practiceEngineering & architecture

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.

Download Markdown (.md)

01What 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.[1][2]

Model proposal, host-controlled execution The model proposes a call; the application validates and executes it
HostModelTool
  1. 01Host ModelCapability descriptions + schemasOnly tools allowed for this user and task
  2. 02Model HostProposed tool name + argumentsStructured but untrusted
  3. 03Host ToolValidate, authorize, confirm, executeLeast privilege and deterministic checks
  4. 04Tool HostMinimal structured resultOutcome or bounded error
  5. 05Host ModelContinue with resultCap retries, spend, and recursion

Tool arguments are untrusted input, and a model proposal is never authorization for a consequential action.

02Why 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.

03When 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.

04How 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.

05A practical example

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.

06Where 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.

07Sources

  1. Function CallingOpenAI · Official documentationFunction Calling
  2. Building Effective AgentsAnthropic · Official engineering guidanceBuilding Effective Agents
View saved topics

Start typing to search titles, definitions, categories, and frameworks.