Tool Use and Function Calling
The contract
Tools are declared in a tools array. Each entry needs name (snake_case, no spaces), description, and input_schema in JSON Schema. The description is the highest-leverage field: the model selects tools and fills arguments almost entirely from it, so describe when to use the tool, not just what it does, and document every parameter including units and allowed values.
The turn cycle
With tools present, the model may respond with stop_reason: "tool_use" and one or more tool_use blocks carrying id, name, and a parsed input object. Claude never executes anything. Your code runs the function, then sends back a user message of tool_result blocks referencing the matching tool_use_id. Results must be paired with their calls and directly follow the assistant turn; unpaired or reordered results produce an error. Mark failures with is_error: true and return readable error text rather than raising - the model can often recover.
Control knobs
tool_choice accepts auto, any, a specific tool, or none. Disabling parallel tool use forces one call at a time when ordering matters. Use enums and required fields in schemas; loose schemas invite hallucinated arguments, so validate every input before execution.
Worked example
get_weather(city) - the assistant emits two tool_use blocks for Paris and Tokyo. Execute both, return one user message with two tool_result blocks in matching order, then continue the loop until end_turn. If a city is unknown, return is_error: true with "unknown city" instead of inventing weather.
Trap to watch
Confusing a tool-use stop reason with a failure, or putting tool results in an assistant message.