# Tool Calling

Tool calling lets a model propose a typed request to an external function or service while application code controls execution and returns the result.

- Type: practice
- Domain: Engineering & architecture
- Level: Intermediate
- Last reviewed: 2026-09-26
- Original: [Soroush’s Product Wiki](<https://wiki.soroush.uk/topic/tool-calling/>)

## What it means

Tool calling, also called function calling, gives a model descriptions and input schemas for external capabilities. The model selects a tool and produces arguments; the host application validates permissions and data, executes the function if allowed, and may return its result to the model. The model's call is a proposal, not trusted code or authorization.

## Why it matters

Tools let model-based products access current data, perform exact computation, and take useful actions beyond text generation. They also turn incorrect or manipulated output into potential real-world effects, making interface design, least privilege, confirmation, and auditability essential.

## When to use it

Use tools when a task needs live data, deterministic computation, or an external action and the function can be narrowly specified. Keep simple known sequences in application code. Avoid exposing actions whose worst-case misuse cannot be constrained, detected, or reversed.

## How it works

1. Define one bounded capability with clear semantics, typed parameters, errors, idempotency, and side effects.
2. Expose only tools and data allowed for the current user, task, and session.
3. Treat model-selected names and arguments as untrusted input and validate them deterministically.
4. Confirm consequential actions, execute with least privilege, and return a minimal structured result.
5. Log calls and outcomes, test normal and adversarial sequences, and cap retries, spend, and recursion.

## A practical example

A travel assistant can search trains and draft a booking. Search is read-only, while purchase requires a separate tool with a quoted itinerary, server-side price checks, authentication, and explicit user confirmation immediately before payment.

## Where it breaks

Models can choose the wrong tool, invent arguments, repeat calls, or be manipulated by untrusted results. Schemas cannot encode every business rule. Added round trips increase latency and cost, while overly broad tool sets make selection and security harder.

## Common mistakes

- Executing a model-generated call without server-side authorization and validation.
- Combining read, write, and destructive behavior in one broad tool.
- Describing tools vaguely and then blaming the model for ambiguous selection.
- Letting retries or agent loops create duplicate side effects without idempotency.

## Visualization

[View the visualization on the website](<https://wiki.soroush.uk/topic/tool-calling/#visualization-tool-calling>)

## Sources

1. [Function Calling](<https://developers.openai.com/api/docs/guides/function-calling>) — OpenAI · Official documentation
2. [Building Effective Agents](<https://www.anthropic.com/engineering/building-effective-agents>) — Anthropic · Official engineering guidance

## Related topics

- [AI Agent](<https://wiki.soroush.uk/topic/ai-agent/>)
- [Structured Output](<https://wiki.soroush.uk/topic/structured-output/>)
- [Application Programming Interface \(API\)](<https://wiki.soroush.uk/topic/application-programming-interface/>)
