Tool calling: schema, call and result
A tool call is a proposal with three artefacts: the declaration, the call, the result.

Tool calling — “also known as function calling” — is the mechanism that lets a model reach outside the conversation: “Function calling provides a powerful and flexible way for OpenAI models to interface with external systems and access data outside their training data.” It is a round trip with three artefacts, and pipelines break when they treat the three as one: the declaration you publish, the call the model emits, and the result you send back.
The declaration: a schema with a description
The unit is stated precisely: “A function is a specific kind of tool, defined by a JSON schema. A function definition allows the model to pass data to your application, where your code can access data or take actions suggested by the model.”
Three consequences follow from that sentence:
- The schema is the contract, and it is written in the same JSON Schema vocabulary as structured output
(the L2 sheet): types, required fields, enumerations. Whether it is enforced during generation is a
property of the request — the API examples carry a
strictflag alongside the schema — while validation of what arrives remains the caller’s job. - The description is part of the interface. The model decides whether a tool fits, and it decides from the description: in the other provider’s words, the model “determines when to call a tool based on the user’s request and the tool’s description”. A tool with a vague description is a tool that gets called at the wrong times.
- The schema is a public promise. Once a tool is published to a model-driven pipeline, changing it changes behaviour; versioning it is the same discipline as versioning an API.
The call: a structured message, not prose
The model’s answer to “should I use a tool?” is a structured block, and the round trip is explicit in the
documentation: “the response carries a tool_use block, your code runs the lookup, and a second request”
carries the outcome back, with the first response stopping for a tool call rather than ending the
conversation.
Three properties matter operationally:
- Arguments arrive as data to be parsed, not text to be trusted. Every client example in the provider
documentation parses them before use (
JSON.parse(tool_call.function.arguments)in one,json.loads(...)in another), which is the same discipline as validating a request body. - Several calls can arrive at once. The API description’s request examples carry a
parallel_tool_callsflag, and the client has to handle a list of calls rather than a single one — each with its own identifier. - The tool identifier is the key. The result is matched back to the call through that identifier, which is why the identifier has to be preserved through whatever queueing, retrying or parallel execution the pipeline does between the call and the result.
The result: an observation, including when it is an error
The result goes back as a structured block tied to the call — a tool_result in the provider’s vocabulary —
and the documentation’s own checklist for the client is “parse tool_use blocks, format tool_result
responses, and handle errors”, with error signalling as a first-class part of the format rather than as a
special string.
The design point is easy to miss: an error is a result. A tool that returns “the record was not found” or “the operation was refused” gives the model something to work with; a tool whose failure is reported as an exception in your own logs, with nothing sent back, leaves the model to invent the outcome — which is exactly the confusion the next sheet is about.
Who executes: the boundary that defines the design
The taxonomy is stated in one line: “Tools differ primarily by where the code executes.”
- Client tools “run in your application”: the model asks, your code acts, and the result is returned.
- Server tools “run on Anthropic’s infrastructure, with no handler code in your application” — the provider executes the search or the computation and returns the result inside the same conversation.
- The model protocol for tools that servers publish is described, in the open protocol for model-context
integration, as model-controlled: “Tools in MCP are designed to be model-controlled”, with a declared
capability and a listing operation (“Servers that support tools MUST declare the tools capability” and
“MUST respond to
tools/listrequests”). The same protocol makes the same distinction this sheet makes: the model decides whether to call; something else decides whether the call is allowed and performs it.
What goes wrong, in practice
- Schema drift. The tool changes, the published schema does not, and the model keeps producing arguments for the old shape.
- Unvalidated arguments. The schema constrains structure, not intent: a
pathargument of the right type can still point anywhere. Validation and refusal belong on the receiving side. - A missing error path. If failures are not returned as results, the loop continues on invented information.
- An unbounded loop. A tool-calling conversation is a loop: model calls, you answer, model calls again. Whoever owns the loop owns the stop condition — how many rounds, and what happens when the limit is reached. That stop condition is the subject of L4’s material on agents; at this level the requirement is that it exists.
- Ambiguous tools. Two tools whose descriptions overlap produce inconsistent choices; the fix is in the descriptions, which is a design task rather than a prompt trick.
Level and prerequisites. L3 — integration level: the reader must be able to define a tool, execute it safely and return an honest result. The security architecture of tool permissions, sandboxing and approval is L4. Prerequisites: the L2 sheets on structured output and on error handling, and the retrieval sheets of this layer for the RAG-side analogue.
Where to go next
- Automation & AI — the macro-area this sheet belongs to.
- Applications — the node this sheet sits in.
References
- OpenAI — Function calling — the definition of a function as a tool with a JSON schema, the description of what the model passes to the application, and the client-side parsing examples.
- OpenAI — API description — the
strictandparallel_tool_callsfields visible in the request examples. - Anthropic — Tool use — client versus server tools, the
tool_use/tool_resultround trip, the description-driven choice of tool, and the client checklist including error handling. - Model Context Protocol — Tools — the model-controlled design of the tool capability in the open protocol.