programmatic-tool-calling-ptclisted

# Programmatic Tool Calling (PTC) ## When to activate User wants to reduce API token usage for tool-heavy workflows, mentions programmatic tool calling, or has a pattern where the same tool is called more than 3 times in a single inference pass. ## When NOT to use - Tools with side effects that need human review between calls (write, delete, deploy) - Tools requiring re-authentication per call or with per-call authorization prompts - Single tool calls — PTC overhead is not worth it below ~3 calls - Non-Python execution environments — PTC sandbox is Python only ## Instructions ### What PTC Does Standard tool use: Claude calls one tool → result returned → Claude calls the next tool. Each round trip is one API inference pass. With PTC: Claude writes Python orchestration code that calls multiple tools in a loop, executes in a sandbox, and only the final stdout enters the context. Three tools = 1 inference pass instead of 3. **Measured token reduction: ~37% fewer tokens for multi-tool workflows.** ### Enabling PTC Add `code_execution_20250825` as an allowed caller in your tool definition: ```python tools = [ { "name": "read_file", "description": "Read a file from the filesystem", "input_schema": { "type": "object", "properties": { "path": {"type": "string", "description": "File path to read"}, }, "required": ["path"], }, "allowed_callers": ["code_execution_20250825"],