tool-use

What it does

A comprehensive guide to implementing tool use with Claude, detailing how to design tools with JSON Schemas, choose when and how to call tools, manage multi-turn conversations, handle errors, and integrate extended thinking while ensuring strict schema conformance.

How it works

The skill instructs when to apply it: for defining custom tools with JSON schemas, building agentic workflows that use tools, implementing tool result handling, orchestrating parallel versus sequential tool calls, ensuring guaranteed schema conformance, implementing error recovery, and combining tools with extended thinking. It specifies core concepts including the Tool Definition Schema with fields such as name, description, input_schema, and optional input_examples. It provides best practice JSON examples for tool definitions and lays out modes for tool_choice (auto, any, tool, none) with YAML-like and Python snippets. It enforces extended thinking constraints: it only supports tool_choice types auto or none when used with extended thinking, and recommends using a separate think tool for complex reasoning. It includes sections on strict schema conformance (strict: true) and shows how to define tools with strict input schemas. It outlines single-tool and multi-turn patterns for invoking tools, including how Claude should handle tool results, how to structure tool_result blocks, and how to marshal results in parallel (single user message, tool results first). It provides detailed formats for tool results (text, images, documents) and error formats (is_error flag, messages about missing parameters or connection errors). It also covers error recovery patterns, max-tokens handling, and how to obtain structured JSON output using a tool like record_summary with beta features. Finally, it includes parallel tool use best practices, measurement helpers, and prompts to encourage parallel tool calls.

When to use it

Use this skill when:

• Defining custom tools with JSON schemas
• Building agentic workflows with tool use
• Implementing tool result handling
• Building parallel vs sequential tool orchestration
• Requiring guaranteed schema conformance
• Implementing error recovery patterns
• Combining tools with extended thinking

What it can touch

Tool usage patterns reference: Bash, Read, Write, Edit, Glob, Grep. The skill demonstrates usage of structured JSON tool outputs and tool definitions, but does not specify executing any actual commands itself. It defines how Claude should serialize tool inputs and results and how to respond after tool invocations.

Caveats

• The guide emphasizes strict schema conformance and error handling, including the use of strict: true in tool definitions. It notes potential limitations such as token truncation and safety overrides in strict mode. It requires specific input_schema structure, including name, description, and input_schema with additionalProperties set to false. It also mentions that extended thinking is limited to certain tool_choice modes and recommends a separate think tool for complex reasoning. The material includes several code blocks and examples, but these are illustrative and require integration with an actual tool execution environment.