Repository Public Research preview
1# Tools and agents23## Defining a tool45```json6{7 "name": "get_weather",8 "description": "Get the current weather for a city. Use it for any weather question. Returns a short text summary.",9 "strict": true,10 "input_schema": {11 "type": "object",12 "properties": {"city": {"type": "string", "description": "City name"}},13 "required": ["city"],14 "additionalProperties": false15 }16}17```1819- The description decides whether the tool gets used: say what it does, when to use it, what comes back.20- `strict: true` (on the tool, not on `tool_choice`) guarantees schema-valid input. It needs21 `additionalProperties: false` and every property listed in `required`.22- Tool inputs are model output. Validate them before acting, and parse with a JSON parser, never23 with string matching.2425## The loop26271. Send `messages` + `tools`.282. If `stop_reason` is `tool_use`: append the **entire** assistant `content`; run **every**29 `tool_use` block (they may be several — run them in parallel); append **one** user message30 holding all the `tool_result` blocks (`is_error: true` for failures, never drop one).313. Repeat until `end_turn`. Always cap the number of turns.324. `pause_turn` means a server tool paused: resend unchanged.3334`tool_choice`: `auto` (default) and `none` work everywhere. `any` and `tool` are rejected by35`claude-fable-5-1`, `claude-fable-5-2`, `claude-opus-5-5`, `claude-sonnet-5-5`.3637## Tool runner (SDK beta helper)3839TypeScript: `betaZodTool({name, description, inputSchema: z.object({…}), run})` from40`@anthropic-ai/sdk/helpers/beta/zod`, then `await client.beta.messages.toolRunner({model, max_tokens, max_iterations, tools, messages})`.41Python: `@beta_tool` on a typed function with a docstring, then42`client.beta.messages.tool_runner(...).until_done()`.43It validates inputs against the schema and loops for you. Use it unless you need a control flow it44cannot express.4546## Server tools (run by Anthropic)4748Declare them in `tools`; results arrive as content blocks in the same response.4950| Tool | `type` | Notes |51|---|---|---|52| Web search | `web_search_20260209` | `web_search_20250305` on Haiku 4.5. Optional `max_uses`, `allowed_domains` |53| Web fetch | `web_fetch_20260209` | `web_fetch_20250910` on Haiku 4.5 |54| Code execution | `code_execution_20260521` | Do not add it next to the 20260209 web tools: they already execute code |55| Tool search | `tool_search_tool_bm25_20251119` | Mark other tools `defer_loading: true`; never all of them |5657Server-tool failures come back as HTTP 200 with an error object inside the result block.58They are billed per use on top of tokens.5960## Client tools defined by Anthropic6162`{"type": "bash_20250124", "name": "bash"}`, `{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}`,63`{"type": "memory_20250818", "name": "memory"}` — declared by type, no `input_schema`; you execute64them. A custom tool that you name `bash` is a different tool.6566## Which agent architecture6768| Approach | You write | Runs where |69|---|---|---|70| Manual loop | The loop and the tools | Your infrastructure |71| Tool runner | The tools | Your infrastructure |72| Managed Agents (beta) | Agent config, optional custom tools | Anthropic sandbox |73| Claude Agent SDK (separate package) | A prompt and options | Your infrastructure, with built-in file/shell tools |7475Before building an agent, check: is the task open-ended, worth the cost, within the model's76ability, and are errors recoverable? If not, use a single call or a fixed workflow.77