Claude Tool Use FAQ & Answers

Add cache_control to tool definition or tool results: tools = [{'name': 'get_weather', 'description': '...', 'input_schema': {...}, 'cache_control': {'type': 'ephemeral'}}]. Minimum cacheable prompt: 1024 tokens for Claude Sonnet 3.5/3.7. Cache duration: 5 minutes default. Extended cache (1 hour): add beta header extended-cache-ttl-2025-04-11 and include ttl in cache_control. Example: {'type': 'ephemeral', 'ttl': 3600}. Tool results caching: messages = [{'role': 'user', 'content': [{'type': 'tool_result', 'tool_use_id': 'id', 'content': 'result', 'cache_control': {'type': 'ephemeral'}}]}]. Benefits: reduces cost/latency for repeated tool schemas. Cache hits charged at 10% of regular input tokens. Use for: large tool catalogs (>1024 tokens), frequently used tools, multi-turn conversations. Models: claude-3-5-sonnet, claude-3-7-sonnet, claude-4-sonnet. Monitor cache efficiency via API usage stats.

Set tool_choice = {'type': 'any'} to force Claude to call any tool (cannot return text-only response). For specific tool: tool_choice = {'type': 'tool', 'name': 'get_weather'}. Options: (1) auto (default, model decides), (2) any (must use some tool), (3) tool (must use specified tool). Example: client.messages.create(model='claude-3-5-sonnet-20241022', messages=messages, tools=tools, tool_choice={'type': 'any'}). Use 'any' for: forcing JSON output via dummy tool, ensuring function call in workflow. Available models: Claude 3+, Claude 4 (all variants). Bedrock syntax: ToolChoice={'Type': 'Any'}. Note: disable_parallel_tool_use parameter controls whether Claude can make multiple tool calls simultaneously. Production tip: combine with tool schema descriptions to guide which tool Claude selects when using 'any'.

Add beta header computer-use-2025-01-24 and use computer tool: tools = [{'type': 'computer_20241022', 'name': 'computer', 'display_width_px': 1024, 'display_height_px': 768, 'display_number': 1}]. Claude captures screenshots, counts pixels to calculate coordinates, and executes mouse_move/left_click/type actions. Example response: {'tool_use': {'name': 'computer', 'input': {'action': 'left_click', 'coordinate': [512, 384]}}}. Critical: keep resolution ≤XGA (1024x768) for speed/accuracy. Claude trained to count pixels vertically/horizontally for precise clicking. Actions: mouse_move, left_click, right_click, middle_click, double_click, screenshot, cursor_position, type, key (keyboard). Use for: browser automation, UI testing, desktop task automation. Warning: may hallucinate coordinates on complex interfaces. Currently beta - production use requires careful error handling. Models: claude-3-5-sonnet-20241022+, claude-4-sonnet+.

Parse content array with multiple tool_use blocks: response = client.messages.create(model='claude-4-sonnet-20250514', messages=messages, tools=tools); if response.stop_reason == 'tool_use': tool_uses = [block for block in response.content if block.type == 'tool_use']; results = [execute_tool(use.name, use.input) for use in tool_uses]; messages.append({'role': 'assistant', 'content': response.content}); messages.append({'role': 'user', 'content': [{'type': 'tool_result', 'tool_use_id': use.id, 'content': result} for use, result in zip(tool_uses, results)]}). Claude 4 excels at parallel execution (~100% success rate with prompting). Claude 3.7 Sonnet less likely to parallelize - enable token-efficient tool use or prompt with . Disable with disable_parallel_tool_use parameter. All parallel calls return single stop_reason: 'tool_use'. Execute tools concurrently (asyncio.gather) then return all results in one message. Alternative stop_reason: pause_turn (web search continuation).

Add beta header fine-grained-tool-streaming-2025-05-14 and enable streaming: async with client.messages.stream(model='claude-4-sonnet-20250514', messages=messages, tools=tools, stream=True) as stream: async for event in stream: if event.type == 'content_block_delta' and event.delta.type == 'tool_use_delta': partial_input = event.delta.partial_input; update_ui(partial_input). Event types: message_start, content_block_start, content_block_delta, content_block_stop. Warning: fine-grained streaming sends parameters without JSON validation - may receive incomplete/invalid JSON if max_tokens reached mid-parameter. Handle with try-except json.loads() or buffer until complete. Benefits: real-time UI updates, faster perceived latency. Models: claude-4-sonnet, claude-4-haiku (2025). Alternative: standard streaming buffers complete tool_use before emitting. MCP servers support streamable HTTP (SSE alternative to stdio). Production: validate/repair partial JSON on client side.

Set is_error: true in tool_result content when tool fails: messages.append({'role': 'user', 'content': [{'type': 'tool_result', 'tool_use_id': 'toolu_123', 'content': 'Network timeout connecting to database server', 'is_error': True}]}). Claude understands failure context and can retry with different parameters or inform user. Example: network errors, invalid parameters, permission denied, resource not found. Provide clear, informative error messages not generic failures. Full flow: tool raises exception → catch → return descriptive error with is_error=true → Claude receives error → adjusts strategy or reports to user. Alternative: omit is_error (defaults False) for successful results. Recent issues (July 2025): MCP tools called without required parameters returned isError responses - check parameter validation. Best practice: include error type, what failed, why it failed. Models: all Claude 3+, Claude 4. Use for: graceful error handling, better debugging, improved user experience.

Add beta header interleaved-thinking-2025-05-14 for Claude 4 models: client.messages.create(model='claude-4-sonnet-20250514', messages=messages, tools=tools, max_tokens=4096, extended_thinking=True). Extended thinking allows Claude to reason between tool calls. Critical: pass thinking blocks back unmodified in assistant message during tool use loops. Prefill example: messages = [{'role': 'user', 'content': 'Analyze data'}, {'role': 'assistant', 'content': 'Breaking down the problem: first check data quality, then...'}]. Multishot prompting: provide examples with or tags to guide reasoning patterns. Constraints: cannot toggle thinking mid-turn, entire assistant turn must use single thinking mode, final turn must start with thinking block if enabled. Models: claude-4-sonnet, claude-4-opus, claude-3-7-sonnet. Use for: complex multi-step tool workflows, sophisticated reasoning after tool results. Toggle in Claude.com UI or via API.

Use enum in input_schema with descriptive field descriptions: tools = [{'name': 'convert_temperature', 'description': 'Convert temperature between units', 'input_schema': {'type': 'object', 'properties': {'value': {'type': 'number', 'description': 'Temperature value to convert'}, 'unit': {'type': 'string', 'enum': ['celsius', 'fahrenheit', 'kelvin'], 'description': 'Source temperature unit: celsius for metric, fahrenheit for imperial, kelvin for scientific'}}, 'required': ['value', 'unit']}}]. Enum strongly guides model to valid inputs. Best practices: (1) add description explaining each enum value's meaning/usage, (2) use clear, unambiguous enum strings, (3) include when/why to use each option. Claude constructs system prompt from tool definitions - detailed descriptions improve selection accuracy. 2025 features: fine-grained tool streaming, automatic tool result clearing near token limits (claude-4-sonnet). Alternative: for large enums, use string type with example values in description. Models: all Claude 3+, Claude 4 variants.

Common causes: (1) Unclear tool description - add explicit examples, (2) Missing required fields in input_schema, (3) Model version issues (July 2025 MCP parameter bugs), (4) Complex nested schemas without field descriptions. Fix: (1) Mark all required fields in schema required array: 'required': ['param1', 'param2'], (2) Add detailed descriptions: {'type': 'string', 'description': 'User ID (required): unique identifier from database'}, (3) Provide few-shot examples in system prompt showing correct parameter usage, (4) Use schema validation on tool execution and return is_error=true with descriptive error explaining missing parameter. For MCP tools: verify tool definition exports correct schema. Recent issue (July 23, 2025): Claude Desktop called tools without required params - check for service instabilities. Validate tool_use.input contains all required fields before execution. Models: claude-3-5-sonnet+, claude-4 improved parameter accuracy. Test tools thoroughly with edge cases.