> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Tool Calling How Models Touch the World
> Explains tool calling where models request actions and an application validates and executes them, enabling safe integration of model plans with external systems.
Models are powerful at reasoning and generating text from their context, but they cannot directly affect external systems. Tool calling is the pattern that lets a model request actions and lets your application (the harness/runtime) perform them. This separation — model as planner/requester, application as executor — is central to safely integrating models into real-world workflows.
Core idea: the model proposes structured requests (which look like function calls). The surrounding application validates and executes those requests against external systems (APIs, databases, filesystems, cloud services).
## How the model knows which actions are available
You provide the model a “menu” of tools. Each tool entry should include:
* a `name` (used in structured requests),
* a human-facing `description` (helps the model choose the right tool),
* and an `input_schema` that describes expected arguments.
Well-written descriptions and strict schemas reduce malformed requests and make the model’s choices more reliable.
Example tool definition (JSON):
```json theme={null}
{
"name": "get_weather",
"description": "Get the current weather for a city.",
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "City & state, e.g. Boston, MA"
}
},
"required": ["location"]
}
}
```
## Execution flow (step-by-step)
1. Model decides it needs external data or an action, and returns a structured request: a tool `name` plus `arguments`.
2. The application (harness/runtime) validates the request against the declared schema and permission rules.
3. If valid, the harness executes the corresponding operation (API call, DB query, local file read, etc.).
4. The harness returns the execution result to the model, injecting it into the model’s context.
5. The model runs again and either produces a final answer or requests additional tools. Repeat as needed.
## Example: model request and tool response
Model's structured request:
```json theme={null}
{
"tool": "get_weather",
"arguments": {
"location": "Denver, CO"
}
}
```
Result returned by the tool execution:
```json theme={null}
{
"tempF": 41,
"rain": true
}
```
This request → execute → response loop is the runtime agent pattern: the model plans and requests, the harness executes, and the model updates its plan with fresh data.
## Risk considerations: read vs write tools
Different tool types carry different risks and operational requirements. Use the table below to quickly compare them.
| Tool Type | Typical Behavior | Main Risks | Typical Safeguards |
| - | - | -: | - |
| Read / Retrieval | Returns external data without changing state | Incorrect or stale data; hallucination from malformed inputs | Input validation, provenance, caching, data freshness checks |
| Write / Action | Changes external state (send email, modify DB, place order) | Irreversible or costly side effects; unauthorized actions | Authorization, permission checks, argument validation, approval workflows |
Write-capable tools can cause irreversible effects (financial transactions, data deletion, email sends). Always add strong validation, authorization, audit logging, and human approval gates where appropriate.
## Tool chains and multi-step agent workflows
Agents often perform multi-step flows where each tool's output feeds the next tool. Example customer-service workflow:
Execution chain (example):
```text theme={null}
query_orders(4821)
-> { status: "LATE", customer_id: "C-5617" }
get_customer(C-5617)
-> { email: "alex@customer.com" }
send_email(to="alex@customer.com", subject="Order #4821 delayed", body="...")
-> { status: "SENT" }
```
Notes:
* Each tool result becomes part of the subsequent model context.
* The harness should validate outputs, perform permission checks, and handle retries/error cases between steps.
## Operational considerations
* Cost & latency: Each tool call usually requires another model invocation plus network or I/O. Longer chains increase cost and response time.
* Failure modes: Every additional step increases the chance of partial failure. Plan retries, backoffs, and compensating actions.
* Observability: Log structured requests, responses, and authorization decisions. Correlate logs across model calls for traceability.
* Security: Enforce least privilege for tools; isolate sensitive actions; redact secrets from logs.
## Best practices for tool design
* Keep tool descriptions concise and explicit.
* Use strict input schemas (JSON Schema or equivalent) to prevent malformed requests.
* Provide examples in the tool description to clarify expected formats.
* Differentiate read-only vs write-capable tools and apply stricter controls for the latter.
Example short table of recommended tool fields:
| Field | Purpose | Example |
| - | - | - |
| `name` | Identifier used in structured requests | `get_weather` |
| `description` | Human-facing guidance for the model | "Get the current weather for a city." |
| `input_schema` | Machine-validated argument types and required fields | see `input_schema` in the JSON example above |
## Summary
* Models generate structured requests (tool calls) but do not execute side effects.
* The application/harness is responsible for validating, executing, and returning results to the model.
* Carefully design tool descriptions and input schemas to improve reliability.
* Treat write-capable tools with strong safeguards: validation, authorization, logging, and human review if needed.
* Monitor cost, latency, and failure modes for multi-step agent workflows.
## Links and References
* [OpenAI — Function calling](https://platform.openai.com/docs/guides/gpt/function-calling)
* [Agent patterns and architectures](https://en.wikipedia.org/wiki/Software_agent)
* [JSON Schema Overview](https://json-schema.org/)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.