Module 8 of 11 · Expert · 10 min read

Tool use and function calling

How models call tools, how to describe tools so they're used well, and how to keep tool use safe.

Key takeaways

1The model never runs a tool itself: it requests a call, your code runs it and returns the result.
2Tool names, descriptions and parameter docs are prompts. Write them carefully.
3Return useful errors so the model can recover.
4Confirm before any irreversible or external action.

01How function calling works

You describe the available tools to the model with a name, a description and a JSON Schema for the parameters. When the model decides a tool would help, it returns a structured call, such as get_weather with {"city": "Lisbon"}, instead of text. Your code executes it and sends back the result, and the model continues, possibly calling more tools, until it can answer. Research such as Toolformer (Schick et al., 2023) explored teaching models when to call tools; today it is a standard API feature.

Standards such as the Model Context Protocol (MCP) let you package tools once and connect them to many AI apps. The Agent Builder path covers tool design and MCP in more depth.

02Describing tools well

The model reads tool descriptions every time, so they deserve the same care as the prompt.

Name tools by what they do: search_orders, not tool_3.
Say when to use it and when not to: 'Use for order status. Do not use for refunds; use create_refund_request.'
Document every parameter, its format and an example value.
Keep the tool set small and distinct; overlapping tools cause wrong choices.
Describe what the tool returns, including what an empty result means.

Example

{ "name": "search_orders", "description": "Look up a customer's orders by email. Use before answering any question about order status or delivery. Returns up to 10 recent orders; an empty list means no orders were found for that email.", "parameters": { "type": "object", "properties": { "email": { "type": "string", "description": "Customer email, e.g. [email protected]" }, "status": { "type": "string", "enum": ["any", "processing", "shipped", "delivered", "returned"] } }, "required": ["email"] } }

03Errors the model can recover from

When a tool fails, return a clear, specific message rather than a stack trace or nothing: 'No customer found with that email. Ask the user to confirm the address they ordered with.' Models recover well from good error messages and flounder with bad ones.

04Prompting for good tool use

The system prompt should explain the strategy, not just list the tools.

Example

You can look up orders, check stock and create refund requests. - Always look up the order before discussing it; never guess order details. - If several lookups are independent, request them together. - Before creating a refund request, summarise what you will submit and ask the customer to confirm. - If a tool returns an error twice, apologise and offer to connect the customer with a person.

05Safety

The model decides what to call; your code decides what is allowed.

Read-only tools are low risk; tools that write, send, pay or delete need confirmation.
Validate every argument in your code, and never pass model output straight into a database query or shell command.
Scope credentials to the minimum each tool needs.
Treat tool results as untrusted content that may contain injected instructions.