# Tools and agents

# Defining a tool

{
  "name": "get_weather",
  "description": "Get the current weather for a city. Use it for any weather question. Returns a short text summary.",
  "strict": true,
  "input_schema": {
    "type": "object",
    "properties": {"city": {"type": "string", "description": "City name"}},
    "required": ["city"],
    "additionalProperties": false
  }
}

• The description decides whether the tool gets used: say what it does, when to use it, what comes back.
• strict: true (on the tool, not on tool_choice) guarantees schema-valid input. It needs additionalProperties: false and every property listed in required.
• Tool inputs are model output. Validate them before acting, and parse with a JSON parser, never with string matching.

# The loop

1. Send messages + tools.
2. If stop_reason is tool_use: append the entire assistant content; run every tool_use block (they may be several — run them in parallel); append one user message holding all the tool_result blocks (is_error: true for failures, never drop one).
3. Repeat until end_turn. Always cap the number of turns.
4. pause_turn means a server tool paused: resend unchanged.

tool_choice: auto (default) and none work everywhere. any and tool are rejected by claude-fable-5-1, claude-fable-5-2, claude-opus-5-5, claude-sonnet-5-5.

# Tool runner (SDK beta helper)

TypeScript: betaZodTool({name, description, inputSchema: z.object({…}), run}) from @anthropic-ai/sdk/helpers/beta/zod, then await client.beta.messages.toolRunner({model, max_tokens, max_iterations, tools, messages}). Python: @beta_tool on a typed function with a docstring, then client.beta.messages.tool_runner(...).until_done(). It validates inputs against the schema and loops for you. Use it unless you need a control flow it cannot express.

# Server tools (run by Anthropic)

Declare them in tools; results arrive as content blocks in the same response.

Server-tool failures come back as HTTP 200 with an error object inside the result block. They are billed per use on top of tokens.

# Client tools defined by Anthropic

{"type": "bash_20250124", "name": "bash"}, {"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}, {"type": "memory_20250818", "name": "memory"} — declared by type, no input_schema; you execute them. A custom tool that you name bash is a different tool.

# Which agent architecture

Before building an agent, check: is the task open-ended, worth the cost, within the model's ability, and are errors recoverable? If not, use a single call or a fixed workflow.