Tool use

Tool use is how agents affect anything outside their own reasoning. A tool is a function, with a name, description, parameter schema, that the LLM can request to call. The orchestrator executes it and returns the result.

Modern tool-use APIs

Every major LLM provider offers native tool-use support:

• Anthropic Claude, tools defined in API call, model emits structured tool_use blocks
• OpenAI, function calling, now "tools" with JSON schema
• Google Gemini, function calling with FunctionDeclaration objects

All three follow the same basic shape: you provide tool definitions, the model returns structured tool calls, your code executes them and feeds results back.

Anatomy of a tool definition

{
  "name": "search_web",
  "description": "Search the web for recent information. Returns top 5 results with snippets.",
  "input_schema": {
    "type": "object",
    "properties": {
      "query": {"type": "string", "description": "search query"},
      "recency": {"type": "string", "enum": ["day", "week", "month"]}
    },
    "required": ["query"]
  }
}

The loop

1. Agent receives user prompt + tool definitions
2. Agent responds with either final answer or tool_use block
3. If tool_use: orchestrator calls actual function with given args
4. Orchestrator sends result back to agent as tool_result
5. Repeat until agent gives final answer

What the LLM sees

The model sees your tool name, description, and parameter schema. That's it. It doesn't see your code. Everything the LLM needs to know about when to call the tool, how to call it, and what it returns must be in the description.

Parallel tool calls

Modern APIs support calling multiple tools in a single step. "Search these three things at once." Saves latency when tools are independent.

The error-return pattern

When a tool fails (network error, invalid args, no results), return a structured error the LLM can reason about:

{
  "error": "rate_limit",
  "message": "Rate limited. Try again in 60 seconds.",
  "retry_after": 60
}

The agent can see the error type and decide whether to retry, pivot, or ask the user.