How does it call a function it can’t run?
Tool calling (function calling) · Builder · 5 min · agents, format · after Structured output (constrained decoding)
Tool calling lets a model ask your code to run a function. You send each tool’s name, description and JSON schema; the model replies with a name and JSON arguments, your code runs it and returns the result.
1 Guess first
2 Look
One tool call, four messages
1 / 4your app sends · request 1: question + tools
user: “What’s the weather in San Francisco?”
tools: [{ "name": "get_weather", "description": "Get the current weather for a given location.", "input_schema": { "type": "object", "properties": { "location": { "type": "string", "description": "City and state, e.g. San Francisco, CA" } }, "required": ["location"] } }]
Sent on every request, called or not. Claude Haiku 5.5 also adds a hidden 286-token tool prompt.
requests and replies quoted from Anthropic’s tool-use docs (claude-opus-5-5 example) · checked 2026-10-23
Your app sends the question and a menu of tools: a name, a description and a JSON schema each.
The model only writes: first a call for your code to run, then, once the result is pasted back, the answer.
The model still only writes text. When the request lists tools (functions described by a name, a description and a JSON schema), it can write a call in a fixed shape instead of an answer. The API hands it back as its own block and stops, with stop_reason "tool_use". Whether it runs is up to your code.
4 You are the model
You are the model, with one tool: get_weather. For five turns, choose what to write: an answer, a question, or a tool call.
you are the model · your one tool: get_weather (location: string, required) · what do you write next?
turn 1 of 5 · the user writes
“What’s the weather in San Francisco?”
requests and replies quoted from Anthropic’s tool-use docs (claude-opus-5-5 example) · checked 2026-10-23
You are the model. Answer, ask, or write a tool call?5 Check
Where it goes wrong. Bad arguments: a missing city, a wrong type. Validate before running, or set strict: true (Anthropic, OpenAI) or Gemini’s validated mode; send errors back with is_error, and Claude retries 2–3 times. Needless calls: vague descriptions, too many tools; Gemini advises 10–20 at most. Calls chained in a loop make an agent.
7 Say it back
8 Mission · 5 min
With a free Gemini API key, follow Gemini’s function-calling docs: declare get_weather (location: string, required) and ask gemini-3.8-flash “What’s the weather in Hanoi?”. You get a functionCall with a name and args, not an answer. Send back a functionResponse you make up, {"temp_c": 31}, and read the answer. Then ask “What is a cold front?”: does it call the tool?
Three quick ones
Drawn at random from this lesson's pool; different next time.
Done?
Go deeper
Sources
- https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview (checked 2026-10-23; no update date): the get_weather round trip on claude-opus-5-5 (tool with input_schema, location required; output “Claude called get_weather with {"location": "San Francisco, CA"}”; result “15 degrees Celsius, partly cloudy”; answer “The current weather in San Francisco is 15 degrees Celsius with partly cloudy skies.”); client tools stop with stop_reason "tool_use"; with tool_choice auto Claude “responds directly for stable knowledge”; with no location, Claude Opus “is much more likely to recognize that a parameter is missing and ask for it”, Claude Sonnet might guess {"location": "New York, NY", "unit": "fahrenheit"}; strict: true guarantees schema conformance; tool use system prompt tokens: Claude Haiku 5.5 286 (auto, none), 406 (any, tool); the tools parameter counts as input tokens
- https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls (checked 2026-10-23): example id toolu_01A09q90qw90lq917835lq9; tool_result with tool_use_id and is_error; tool_result blocks must immediately follow the tool_use; error “ConnectionError: the weather service API is not available (HTTP 500)” and Claude’s reply “I’m sorry, I was unable to retrieve the current weather because the weather service API is not available. Please try again later.”; “Claude will retry 2–3 times with corrections before apologizing”; server tools such as web_search run on Anthropic’s infrastructure
- https://ai.google.dev/gemini-api/docs/function-calling (updated 2026-09-23, checked 2026-10-23): “The model doesn’t execute the function itself”; modes auto, any, none, validated (“Model ensures function schema adherence”); “Keep active set to 10-20 tools maximum”; examples on gemini-3.8-flash
- https://developers.openai.com/api/docs/guides/function-calling (checked 2026-10-23): five steps from a request with tools to a final response “(or more tool calls)”; “Setting strict to true will ensure function calls reliably adhere to the function schema”
- https://ai.google.dev/gemini-api/docs/pricing (updated 2026-10-22, checked 2026-10-23): Gemini 3.8 Flash free tier, input and output “Free of charge”; aifree.dev catalog google-gemini-developer-api-free-tier (verified 2026-10-12)
Published Oct 23, 2026 · updated Oct 23, 2026