# Gemini — Function calling (tools[].functionDeclarations)

Status: DOCUMENTED + LIVE_VERIFIED (2026-09-18 run — see "Live verification" section at the end)

Sources:

• https://ai.google.dev/gemini-api/docs/generate-content/function-calling (generateContent flavour) · https://ai.google.dev/gemini-api/docs/function-calling (Interactions flavour)
• https://ai.google.dev/gemini-api/docs/generate-content/thought-signatures · https://ai.google.dev/gemini-api/docs/thinking#signatures
• https://ai.google.dev/gemini-api/docs/tool-combination · https://ai.google.dev/gemini-api/docs/live-tools · https://ai.google.dev/api/live
• https://ai.google.dev/api/generate-content (#Tool #FunctionDeclaration #FunctionCallingConfig #FunctionCall #FunctionResponse #FunctionResponsePart #Behavior #Scheduling)
• SDK: https://github.com/googleapis/python-genai (README: AFC, MCP) · https://github.com/googleapis/js-genai

Last verified: 2026-09-18 (docs only)

# 1. Flow

1. Declare functions in tools[].functionDeclarations[].
2. Model answers with functionCall parts {name, args, id} — Gemini 3 always returns an id; the first functionCall of each step carries a thoughtSignature.
3. You execute the function(s) and append a content (role user — the reference also mentions role function) with functionResponse parts {name, response, id}.
4. Model produces text or further calls (compositional). Repeat.

Check candidates[].finishReason: STOP, MALFORMED_FUNCTION_CALL, UNEXPECTED_TOOL_CALL (tool called but none enabled), TOO_MANY_TOOL_CALLS, MISSING_THOUGHT_SIGNATURE.

# 2. Declaration fields (FunctionDeclaration)

Max 512 declarations per request (SDK docstring). Best practice: 10–20 active tools; low temperature; strong typing/enums; validate high-impact calls with the user.

# 3. Modes (toolConfig.functionCallingConfig)

Interactions API twin: generation_config.tool_choice: "auto"|"any"|"none"|"validated" or {"allowed_tools":{"mode":"any","tools":[...]}}.

# 4. Parallel and compositional calls

Supported per the guide table: Gemini 3.8/3.7/3.6/3.5 Flash, 3.5 Flash-Lite, 3.1 Pro Preview, 3.1 Flash-Lite, 2.5 Pro/Flash/Flash-Lite (function, parallel and compositional all ✔).

# 5. Thought signatures (mandatory on Gemini 3)

# 6. Function responses

# 7. Live API (BidiGenerateContent)

• Declare tools in setup.tools; server sends toolCall {functionCalls[{id,name,args}]} and may send toolCallCancellation {ids[]} on interruption; client answers toolResponse {functionResponses[]} (session.send_tool_response). No automatic tool handling.
• behavior: NON_BLOCKING = asynchronous calling: default on gemini-3.8-live (BLOCKING still allowed), only mode on gemini-3.8-live-extended-thinking (BLOCKING = hard error, scheduling unsupported), unsupported on gemini-3.1-flash-live-preview (sync only), sync + async on gemini-2.5-flash-native-audio-preview-12-2025.
• Only googleSearch can be combined with function declarations in Live.

# 8. Multi-tool (built-in + custom) — Gemini 3, Preview

Set toolConfig.includeServerSideToolInvocations: true; response contains toolCall/toolResponse (server tools), executableCode/codeExecutionResult (code execution) and functionCall parts, each with id and thoughtSignature. Echo every part unchanged, then append your functionResponse. Mode is VALIDATED. See index.md §4.

# 9. SDK conveniences

# 10. Minimal examples

curl -s "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash-lite:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" -H "Content-Type: application/json" \
  -d '{"contents":[{"role":"user","parts":[{"text":"Weather in Paris?"}]}],
       "tools":[{"functionDeclarations":[{"name":"get_weather","description":"Weather for a city.",
         "parameters":{"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}}]}],
       "toolConfig":{"functionCallingConfig":{"mode":"ANY","allowedFunctionNames":["get_weather"]}}}'

from google import genai
from google.genai import types
client = genai.Client()  # GEMINI_API_KEY
decl = types.FunctionDeclaration(name="get_weather", description="Weather for a city.",
        parameters_json_schema={"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]})
r = client.models.generate_content(model="gemini-3.5-flash-lite", contents="Weather in Paris?",
        config=types.GenerateContentConfig(tools=[types.Tool(function_declarations=[decl])]))
fc = r.candidates[0].content.parts[0]
# echo the model part (with thought_signature) then reply:
follow = client.models.generate_content(model="gemini-3.5-flash-lite", contents=[
    types.Content(role="user", parts=[types.Part(text="Weather in Paris?")]),
    r.candidates[0].content,
    types.Content(role="user", parts=[types.Part(function_response=types.FunctionResponse(
        name=fc.function_call.name, id=fc.function_call.id, response={"temp_c": 18}))])],
    config=types.GenerateContentConfig(tools=[types.Tool(function_declarations=[decl])]))

import { GoogleGenAI } from '@google/genai';
const ai = new GoogleGenAI({});
const r = await ai.models.generateContent({ model: 'gemini-3.5-flash-lite', contents: 'Weather in Paris?',
  config: { tools: [{ functionDeclarations: [{ name: 'get_weather', description: 'Weather for a city.',
    parametersJsonSchema: { type: 'object', properties: { city: { type: 'string' } }, required: ['city'] } }] }] } });
console.log(r.functionCalls);

# Live verification (2026-09-18)

gemini-3.5-flash-lite, raws tmp-live/gemini-tools/a*.json (all HTTP 200 unless stated):

• Forced call (toolConfig.functionCallingConfig.mode: ANY + allowedFunctionNames) → one part {functionCall:{name:"get_weather", args:{city:"Paris"}, id:"call_356059"}, thoughtSignature:"…"}, finishReason: STOP.
• Round trip: appending the model turn verbatim + {functionResponse:{name, response:{…}}} → text answer. Stripping thoughtSignature → 400 Function call is missing a thought_signature in functionCall parts. This is required for tools to work correctly… function call default_api:get_weather, position 2.
• Parallel: two declarations, mode ANY → parts [functionCall+thoughtSignature, functionCall] (call_243490, call_243491) — only the first carries a signature, exactly as the docs describe.
• parametersJsonSchema (plain JSON Schema with an enum) → args {city:"Rome", unit:"C"}.
• mode: NONE → text only; mode: VALIDATED → accepted (functionCall returned).
• behavior: NON_BLOCKING in generateContent → 400 FunctionDeclaration.behavior is only supported by the BidiGenerateContent method. In the Live API the same declaration produced toolCall{functionCalls:[{name,args,id:"function-call-11967657623789764093"}]} and the model kept talking (audio) — non-blocking behaviour confirmed; setup.toolConfig is rejected (close 1007), so the mode cannot be forced in Live.
• Interactions API twin: tools:[{type:"function",…}] + generation_config.tool_choice{allowed_tools{mode:"any", tools:[…]}} → status:"requires_action", step {id:"call_297992", type:"function_call", name, arguments}; top-level tool_choice → 400 Unknown parameter 'tool_choice'; reply with input:[{type:"function_result", name, call_id, result:[{type:"text", text}]}] + previous_interaction_id.

Examples: examples/gemini/tools/function-calling/{function_calling.py,forced_call.sh,function_calling.ts}, examples/shared/tool-loop/gemini_tool_loop.{py,ts} (all executed). Tests: tests/gemini/test_tools.py.