These are my notes on tool calling. I wanted to understand how a call request generated by a model becomes an operation a program actually executes, and why MCP emerged as a way to connect external capabilities to an agent.
Saying that tool calling gives an LLM “hands” is an intuitive starting point. Following that idea further means separating the responsibilities of the model, the host, and the tool implementation, and understanding how results return to the model and shape its next decision. This article starts with what tools do, then works through Function Calling, MCP, execution loops, and practical considerations, before looking at implementations in several products and open-source projects.
If you are working through these concepts too, I hope you will read along and share your own understanding and practical experience.
1 Why Tools Are Needed: Moving LLMs from Conversation to Action
What tools do: connect language reasoning to the environment
An LLM can explain a piece of code, derive a result, or write a command. Generating that text does not mean a file has been read, a calculation completed, or a command run. To act on the current environment, a system needs an entry point that can execute operations.
Tools provide those entry points. Search and reading tools help a model obtain information for a task; code execution tools perform actual computations; file editing tools and service APIs let the system change its environment. The content returned by tools can also help the model check earlier judgments and decide whether to continue. Action here includes querying and observing as well as making changes.
Giving a model “hands” therefore means allowing it to request actions that the system provides and use execution feedback to continue reasoning. The model interprets the task, chooses an action, and generates arguments; a program performs the actual operation. OpenAI’s Function calling guide describes tool calling as a multistep interaction between a model and an application, emphasizing this division of responsibility.
Responsibilities: the model requests, the host organizes execution
The application system running an agent is commonly called the host. It prepares model input, provides the currently available tools, receives call requests, dispatches execution, and assembles the results. Some systems implement these responsibilities in application code; others delegate them to an Agent SDK or a managed service.

Original responsibility diagram: tools connect the model’s decisions to files, programs, and external services. Model-side call requests and service-side MCP integration use different interfaces. Boxes represent responsibilities; they do not imply that every component is deployed separately.
A tool implementation can be a function inside the host, a business service accessed over HTTP, or a capability provided by an MCP server. Both paths in the diagram ultimately lead to execution code. Chapter 3 examines MCP’s specific role.
Tools give an agent available actions; the execution loop organizes those actions, their feedback, and the next decision. A single function call can complete a calculation or query. More complex tasks often require several rounds of observation and action until a stopping condition is met.
2 Function Calling: Expressing Structured Call Requests
Tool definitions: telling the model what it can do and how to request it
Function Calling lets a model express tool call requests in an agreed format. This article uses JSON Schema function tools to explain the mechanism. Other platforms may also support forms such as free-text tools, and their fields can differ.
The following teaching example uses the OpenAI Responses API format to define a document search tool:
{
"type": "function",
"name": "search_docs",
"description": "Search product documentation accessible to the current user and return relevant passages, document identifiers, and sources. Use this when an answer needs to be based on documentation.",
"strict": true,
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "The question or keywords to check"
},
"limit": {
"type": "integer",
"enum": [5, 10],
"description": "The maximum number of results to return"
}
},
"required": ["query", "limit"],
"additionalProperties": false
}
}The name identifies the tool, the description explains its responsibility and when to use it, and the parameter structure defines the fields a request can contain. After seeing these definitions, a model can generate a tool name and arguments for the task. The execution side still needs an implementation registered under that name to search the documents.
Within the supported subset of schemas, strict constrains the argument structure. For example, limit above should be one of the integers in the enum. It cannot ensure that the query is semantically appropriate or that the documents contain an answer, and it does not obtain access permission for the user. Structure, business conditions, and permissions each need their own checks. The Strict mode documentation explains the schema constraints; those requirements should not be applied unchanged to every model interface.
Calls and results: two kinds of messages in execution
When the model requests a call, it may return something like the following. Both the call identifier and query text here are illustrative:
{
"type": "function_call",
"call_id": "call_01",
"name": "search_docs",
"arguments": "{\"query\":\"configuration changes after the upgrade\",\"limit\":5}"
}The application identifies name, parses and checks arguments, then passes the request to a registered execution function. Once retrieval is complete, it returns the result to the model as tool output associated with call_01. The identifier links a call to its result so that responses to multiple requests do not become mixed up.
These objects serve different purposes: a tool definition describes a capability, a call request expresses the current action, and a tool result records execution feedback. When a model outputs a function name, it has made a request. Executing it, collecting the result, and making the next model request still require an external program.
SDK boundaries: interface wrappers and runtime loops
The claim that “the SDK handles tool calls” depends on the library in question.
A standard model API SDK mainly wraps requests, responses, and data types. Developers may still need to identify calls, execute functions, and supply the results themselves. An Agent SDK can go further by providing a Runner that organizes these steps into a loop. OpenAI’s Agents SDK running guide explicitly describes executing tools, appending results, and calling the model again.
To determine which component executes a tool, follow the call chain and executor rather than simply checking whether the code uses an SDK. Tool definitions should also avoid letting the model supply its own execution identity or arbitrary credentials. That information should come from the user and authentication context held by the host.
3 MCP: Origins, Core Components, and Invocation
Why it emerged: reducing repeated integration work
Function Calling can already express “which tool to call and with which arguments,” but developers still have to connect the tools themselves to the application.
A host accessing files, code repositories, and business systems may encounter different catalog structures, request formats, and result conventions. Another host connecting to the same services needs to maintain another set of adapters. As applications and services multiply, this integration work is easily repeated.
In its original MCP announcement, Anthropic proposed an open protocol for connecting AI applications to systems that hold data and tools. The Model Context Protocol provides shared conventions for discovering and accessing capabilities, allowing a service to expose them once and hosts that support the protocol to connect to them.
A common protocol reduces differences between integration interfaces. Each service still needs to implement its business semantics and data permissions, and each host still needs to organize its models and tasks.
Core components: host, client, and server
MCP distinguishes three architectural roles. The host is the application that uses a model and external capabilities, managing context, connection policies, and user interaction. A client is the component inside the host that handles MCP protocol interactions. A server exposes specific capabilities to clients and can be a local process or a remote service.

Source: Model Context Protocol, Architecture overview, licensed under CC BY 4.0. Re-rendered from the official Mermaid source, preserving the nodes and connections. The connections in the diagram do not imply that HTTP must maintain a persistent session.
A host can manage multiple clients, with each client connecting to one server. The diagram also shows different clients connecting to the same remote service. A client is a protocol role; the name alone should not be taken to mean a user-facing chat client.
Servers provide more than tools. The server specification distinguishes three main primitives:
| Primitive | What it provides | Intended interaction model |
|---|---|---|
| Tool | A callable query or operation | The model chooses calls based on the task; the host enforces execution policies |
| Resource | Content or context with a URI | The application decides which content to read and use |
| Prompt | A message template that can accept arguments | The user chooses the relevant template |
These forms of control describe interaction design and do not replace permission rules. A resource URI does not have to point to a public web page. A prompt returns a set of messages; that does not mean any corresponding tools have already executed.
Invocation: from the protocol catalog to tools the model can use
The host needs to connect MCP capabilities to the model interface. A common tool path is to obtain tool names, descriptions, and inputSchema through tools/list, then adapt them into definitions the model recognizes. After the model requests a call, the host converts the name and arguments into tools/call, receives the result, and incorporates it into model input.
MCP messages and model API tool objects belong to different interfaces. Even when their structures are similar, adaptation is required. Results may contain text, structured content, images, or resource links, which the host should handle according to the forms supported by its model and API. The Tools specification defines the protocol objects, while the Agents SDK MCP integration guide shows how a particular host makes the connection.
Messages use JSON-RPC encoding, and transport can use stdio or Streamable HTTP. stdio communicates through the standard streams of a local subprocess. Streamable HTTP uses an HTTP endpoint, with responses that can be JSON or request-scoped SSE. MCP therefore does not mean that a remote service must be called over HTTP. Transports
In an interaction mode based on self-contained requests, protocol metadata travels with the request rather than depending on a previously established handshake session. The server provides server/discover so that clients can learn about protocol support and capabilities in advance. A client can also issue a specific request directly and handle incompatibilities, so discovery is not a required step before every tool call. Hosts and SDKs need to match the interaction modes supported by the service. A stateless protocol also does not mean that business objects have no state. Versioning and Compatibility
Authorization has its own scope: the HTTP authorization specification differs from credential handling for stdio, and the execution side still decides permissions for specific data and operations. A successful connection does not mean that the current user can perform every action. Authorization
How the concepts relate: tool calling, Function Calling, and Skills
The following comparison uses the division of responsibilities adopted in this article: tool calling refers to the complete process of requesting, executing, and returning feedback, while Function Calling focuses on how calls are expressed in the model interface. Platforms may use these two names in overlapping ways.
| Concept | Main question it answers | Form and content | How it works with the other concepts |
|---|---|---|---|
| Tool calling | How can external capabilities move a task forward? | An interaction in which the model makes a request, a program performs an operation, and the result returns to the model | Requests can be expressed through Function Calling; execution can use directly integrated tools or MCP |
| Function Calling | How does the model express what to call and which arguments to pass? | A mechanism for call requests in the model interface; this article uses structured function tools as the example | Gives the host a basis for identifying and dispatching requests; a program still performs the actual operation |
| MCP | How does a host discover and access capability services? | A communication protocol between clients and servers; servers can provide Tools, Resources, and Prompts | The host can adapt MCP tools into model-visible definitions, then convert model requests into protocol calls |
| Skill | How should a type of task be performed, and which methods and materials does it need? | A package of instructions and resources with SKILL.md as its entry point, optionally including scripts | Can guide an agent in using directly integrated tools or MCP tools; scripts still depend on an execution environment provided by the host |
Within one task, a Skill can guide the steps, the model can request tools through Function Calling, and the host can execute them directly or access a service through MCP before returning results to the model. Tools can also be integrated without MCP, and a Skill can provide only knowledge and methods. These concepts do not have to form a fixed chain. The Agent Skills format specification describes Skill content and the optional script structure.
4 The Execution Loop: How an Agent Chooses, Executes, and Uses Tools
A worked example: letting one round’s result shape the next step
Once the interfaces are connected, tools enter the agent’s execution loop. The host prepares the current input, the model chooses a tool and generates arguments, the execution side performs the operation, and the host requests the model again after the result returns. Each piece of feedback can change later choices.

Original execution flow diagram: the host assembles the tool result on the right into the next round’s input. The diagram shows the normal loop; termination caused by budgets, cancellation, and failures is handled by runtime rules.
Consider this teaching task: “Use the product documentation to determine whether this upgrade requires configuration changes.” Assume that the system provides search_docs and read_doc, which reads original text by document identifier. The document identifiers in the table are illustrative, not records of actual execution.
| Round | Basis for the model’s choice and request | How execution feedback affects what follows |
|---|---|---|
| Round 1: search | No retrieved material is available yet. Using the user’s question and tool definitions, the model chooses search_docs and generates a query and result limit | The executor returns relevant passages, sources, and identifiers such as doc_17. From these, the model finds potentially relevant configuration guidance |
| Round 2: read | The retrieved passages are incomplete. The model asks read_doc to read the relevant parts of doc_17 | The original text and sources enter subsequent input, allowing the model to check applicable versions and conditions |
| Round 3: answer or continue | The model decides whether the available material supports a conclusion | It answers if the evidence is sufficient. If gaps remain, it queries further or explains what it cannot confirm |
This sequence follows from the task and its feedback. The host does not need to hard-code “always read after searching,” and the model is not guaranteed to follow the same path every time. It needs to choose actions using tool descriptions, argument requirements, existing material, and the task objective. The host decides which tools to expose in the current round and constrains actual execution.
Discovering a service catalog should also be distinguished from selecting tools within the loop. A catalog can be fetched and cached during integration, then refreshed when needed. On-demand tool search may instead happen during a task. Neither has to be repeated in full before every tool execution.
A minimal loop: how the program handles model requests
The following Python pseudocode shows the execution skeleton. model.generate, to_input_items, and the other helpers are teaching interfaces; in practice, they need to correspond to the chosen model API and SDK. The example does not implement a retrieval service and is not a complete, directly runnable program.
history = [user_message]
registry = {"search_docs": search_docs, "read_doc": read_doc}
for _ in range(max_rounds):
response = model.generate(input=history, tools=tool_definitions)
history.extend(to_input_items(response))
calls = get_tool_calls(response)
if not calls:
return get_final_answer(response)
for call in calls:
try:
tool = registry.get(call.name)
if tool is None:
raise ToolError("Unregistered tool")
args = parse_and_validate(call.arguments, schemas[call.name])
check_permission(user_context, call.name, args)
value = tool(**args)
except ToolError as error:
value = {"status": "error", "message": error.safe_message}
history.append(make_tool_result(
call_id=call.call_id,
value=value,
))
raise RoundLimitReached()The registry maps names to concrete implementations, and argument and permission checks happen before execution. Here, ToolError represents a tool failure that can be reported to the model. The illustrated check functions and execution adapters convert such failures to that type according to their agreed convention; other exceptions remain the host’s responsibility. call_id associates the result with the original call. The next round’s input preserves the model output that needs to be carried forward, then appends the tool results. Interfaces with reasoning state or special message items require those items to be passed on as specified; keeping only the final text is insufficient.
This code executes tools sequentially to make the control flow clear. Supporting parallel execution also requires checking dependencies and execution capabilities. Reading unrelated materials can happen in parallel, while reading a document’s full text may depend on an identifier returned by an earlier search. Multiple requests from the model in one response do not establish that they can all execute safely at the same time.
Real frameworks encapsulate many of these steps. The official Claude Agent SDK example follows a sequence of inspecting a failure, reading files, making changes, and verifying them to show how tool results drive the next round. Developers can observe the message lifecycle without rewriting the entire loop themselves.
Feedback and completion: what remains to be decided after execution
An empty list may mean that no relevant material was found. A business error may mean that arguments fail domain-specific conditions, while a permission error means that the current identity cannot access the resource. This information shapes the next step: revise a query, adjust arguments, handle authorization, or stop and explain the limitation.
MCP also distinguishes JSON-RPC protocol errors from tool execution errors expressed through isError. Receiving no response may instead mean that the transport was interrupted or that the execution state is unknown. These situations cannot all be reduced to “try again.” Tools error handling
Likewise, a successful tool execution establishes only that the action completed. A successful search does not ensure that the material is sufficient, and a successful write does not automatically establish that the task objective has been met. Whether to continue depends on the evidence and task requirements. Whether continuation is allowed also depends on runtime rules for rounds, time, cost, cancellation, and other limits.
5 Practical Considerations: Context, Execution, and Cost Control
Tool descriptions: enough clarity without repetition and bloat
A tool description is an important basis for the model’s choice of tools. It should explain the capability, when to use it, key limitations, and what it returns. Names and parameters should also make similar tools easy to distinguish. Overlapping responsibilities and descriptions filled with background material give the model more similar entry points to weigh.
When shortening a description, keep the information that affects selection. Reducing “search documents accessible to the current user and return passages and sources” to “search” saves words but loses both the target and the result format. Field requirements clearly expressed by the parameter schema do not need lengthy explanations repeated in several places. Ken Aizawa’s Writing effective tools for agents discusses these trade-offs through tool responsibilities, namespaces, and result design.
Tool descriptions and schemas occupy model input. To control this cost, first distinguish three sets: the capabilities a server provides, those the host can discover, and the definitions actually shown to the model in the current round. These sets can be identical, or filtering and on-demand loading can produce smaller ones.

Original information flow diagram: the upper half controls definitions; the lower half controls results. Filtering, search, trimming, and moving content out of context depend on the particular host and tool implementations. The MCP integration protocol does not perform these optimizations automatically.
Loading definitions: direct inclusion, filtering, and on-demand discovery
For a small set of stable, frequently used tools, providing complete definitions directly is easy to understand and avoids an extra discovery step. With many tools, the system can first narrow the catalog by business domain, then search for and load definitions relevant to the task.
The deferred loading provided by OpenAI Tool search has specific boundaries. An individual deferred function’s name and description remain visible; its parameter schema is the main part deferred. When tools are organized by namespace or MCP server, the initial input can contain only a group-level overview, with internal definitions loaded after search. It also distinguishes platform-hosted search from search executed by the application.
Anthropic’s Tool search documentation explains that the complete definitions of deferred tools are still submitted with the API request; what happens on demand is their inclusion in model context. What an HTTP request body contains and what the model currently sees therefore need to be examined separately.
On-demand discovery also has costs. Additional searches take time, and failing to select a needed tool can affect later actions. Returning many candidates at once and injecting all of them into context may merely postpone full loading by one step. Benefits should be assessed against task completion rather than initial token counts alone.
These are implementation strategies in model interfaces or hosts. MCP provides conventions for capability discovery and invocation. It does not require a host to put the entire catalog into context, nor does it automatically select the most economical loading strategy.
Results: providing evidence the agent can keep using
Oversized results are a different problem from long descriptions. A log query with few arguments can still return a large amount of irrelevant content. Interfaces should support filters for scope, count, fields, or time where possible. Larger results can be paginated, or the tool can first return a summary and identifiers for reading on demand.
Trimming must preserve what the next step needs. Document queries generally need sources, applicable versions, stable identifiers, and relevant passages. Paginated results should tell the model that more pages remain. When content is truncated, the result should make the scope and method for continuing clear, so that partial material is not mistaken for complete evidence.
Another option is to process intermediate data inside the execution environment. Adam Jones and Conor Kelly’s Code execution with MCP demonstrates wrapping capabilities in code interfaces, composing calls and filtering data within the execution environment, and returning only the necessary results. This requires an additional execution environment and runtime constraints. Connecting MCP does not supply it automatically, and it should not be applied indiscriminately to every small task.
Tool results also have a trust boundary. Web pages, documents, and comments can contain text that looks like operational guidance, but they remain external data. The host and model need to use that content according to its source and the task, rather than granting it greater instructional authority simply because it appears in a tool result.
Execution boundaries: validation, permissions, and side effects
Valid formatting is only part of validation. A path that conforms to a schema may still lie outside the allowed directory, and an existing document identifier may still refer to data the user cannot access. User identity and permission checks belong on the execution side; they cannot depend on the model declaring its own identity in arguments.
Reads and writes also have different consequences. Repeating a failed query carries different risks from resubmitting a write whose outcome is unclear. If an acknowledgment is lost, the original action may already have completed. Before continuing, the system should check a business receipt or current state to avoid repeating the action.
These constraints should correspond to actual capabilities. Narrowing the visible catalog helps control the range of actions, but cannot replace server-side data permissions. A tool’s read-only indication also needs support from its implementation and credential permissions; text alone cannot guarantee it.
Total cost: observe the whole task rather than one call
Tool costs include at least model inference, actual tool execution, and any fees charged by external services. Returned content may also continue consuming budget across subsequent rounds of input. Caching can reduce some processing or billing costs for repeated input, but it does not mean that the content no longer occupies context.
End-to-end latency likewise includes discovery, model generation of arguments, networking, service execution, and result feedback. A tool function can run quickly while the overall task remains slow because of repeated searches or large results.
Decisions about revising descriptions, changing interfaces, or adjusting loading strategies should therefore consider task completion alongside call counts, tokens, total duration, and error types. Round and cost limits also need to fit the task. For example, the Claude Agent SDK exposes round and budget controls. Limits bound execution; they do not replace judging whether the results are sufficient.
6 Implementation Observations: How Products and Open-Source Projects Organize Tool Calling
Codex: from tool routing to returning execution results
In Codex, the harness organizes user input, model reasoning, and tool execution. Each request supplies the current context and available tools to the model. Tools can come from Codex’s built-in capabilities, the model platform, or MCP services. Execution results enter subsequent input and the loop continues. The available tool set also depends on model capabilities, the runtime environment, and configuration. Unrolling the Codex agent loop
The routing layer’s ToolRouter stores the tool execution registry separately from model_visible_specs. Registering execution implementations and deciding which definitions the model can see are related but distinct tasks. After receiving a model call, the router converts it into an internal request containing a name, argument payload, and call identifier, then passes it to the registry for dispatch.
ToolCallRuntime checks whether a tool supports parallel execution, constrains execution with shared or exclusive locks, and calls the router. When execution finishes, it converts the output into a response item associated with the original call identifier for later model requests. The model may request multiple calls, but the runtime still schedules execution according to tool capabilities. The number of requests alone does not determine whether they run in parallel.
Claude Code: letting the product manage the loop and tool context
Claude Code’s architecture guide describes the process as gathering context, taking action, and verifying results. It explicitly identifies the component outside the model that manages tools and context as the Agent Harness. Each tool result can change the model’s judgment about the next step.
Its Agent SDK gives developers the same execution loop: the model requests tools, the SDK executes them and returns results, and reasoning continues until a final answer without tool calls is produced or a runtime limit is reached. Developers can observe model messages, tool results, and completion messages, and configure execution policies through the interface.
Claude Code also provides examples of the two information flows discussed in Chapter 5. Under supported configurations, it discovers MCP tool definitions on demand by default, while still loading tool names and server instructions initially. Models, deployments, or configurations without support may preload definitions; the precise behavior depends on tool search configuration. MCP tool search
For successful text results without images that exceed the relevant limits, the product can save the content to a file and provide a path in the conversation for later reading. Error results have separate handling rules. MCP output limits explains these conditions. Loading definitions on demand and moving results to files control different content. Both are Claude Code implementations, rather than capabilities automatically provided by the MCP specification.
DeepSeek Harness: combining tools and the loop through plugins
DeepSeek Harness (dsh) is DeepSeek’s official open-source Agent Harness. Its architecture uses Cordis plugins to compose model adapters, tool registration, session records, and the agent loop.
The ToolsService source stores tool definitions with their execution functions and selects tools by scope and the current step. schemas() then projects the fields needed for a model request. Execution functions and UI display callbacks are not sent directly to the model as tool schemas, following the distinction between what the model sees and what the program actually executes.
The built-in executor’s tool pipeline includes pre-execution policies and checks, the tool implementation, result processing, and session recording. The subsequent loop builds input from session records so that call results can inform the next decision. Custom executors are also supported, so the full details of the built-in pipeline should not be treated as a universal protocol that every extension must follow.
This example shows how a product architecture brings tools and the loop together. It is distinct from function calling support in the DeepSeek model API and from third-party frameworks that integrate DeepSeek.
Open-source approaches: studying specific designs in SDKs and servers
Alongside complete products, smaller projects are useful for examining how individual responsibilities are organized:
| Implementation | Parts worth reading | Connection to the earlier discussion |
|---|---|---|
| OpenAI Agents SDK | The Runner, tool execution, and MCP integration | Compare with Chapter 4 to understand which loop responsibilities the SDK encapsulates for an application |
| GitHub MCP Server | Toolsets organized by business domain, selection of individual tools, and read-only filtering | Observe how a server controls its exposed catalog, as distinct from on-demand loading on the model side |
| Microsoft Playwright MCP | Browser state, accessibility snapshots, local observations, and interaction tools | Observe how result formats affect later choices and context consumption |
GitHub’s configuration guide allows business groups and individual tools to be combined, with read-only filtering taking precedence. Local arguments and remote request headers are different configuration entry points. This shows that catalog organization comes from the implementation and still needs to work with access credentials and permissions.
Playwright MCP’s browser_find can return snippets around matching nodes, and snapshots support limiting their target and depth. These interfaces help an agent choose the scope of its observations. Using snapshots as the primary interaction method also does not mean that screenshots are unavailable. In its comparison of MCP and CLI, the maintainer notes that coding agents with command execution capabilities can consider CLI + Skills, while persistent state and inspection of page structure are use cases for the MCP approach. The choice should reflect the host’s existing capabilities; this comparison should not be turned into a universal verdict on the relative merits of the protocols.
For a look at how Tools, Resources, and Prompts can be exposed together, Everything in the MCP Reference Servers repository is another teaching entry point. Its role as a reference implementation matters: inclusion in an official repository alone does not establish production readiness.
Tools let an agent read and change its environment, Function Calling expresses call requests, MCP standardizes integration with capability services, and the host organizes execution feedback into the next round’s input. When reading an implementation, follow the tool definitions, call requests, execution functions, and returned results through the code to see what the model, runtime system, and capability services each do.

