Tools, seen from the loop

You built the pieces of a tool call in Give your model tools. Here they are in thirty seconds, with the lesson to revisit if one feels shaky.

Describe it. Claude sees a tool's name, description and input_schema, never your code, and the description does most of the work. Revisit Describing a tool and Descriptions Claude follows.

Run it. A reply with stop_reason: "tool_use" holds tool_use blocks. You push Claude's whole reply back unchanged, then one user message with a tool_result per call, matched by tool_use_id. Revisit One round trip.

Fail politely. A failed call still gets a result, marked is_error: true, with a message that says what to try next. Revisit Many calls, some fail.

The weather bot made one round of calls and stopped. An agent doesn't stop: every result becomes the input to Claude's next plan, maybe dozens of times. That changes what your tool code has to get right.

First, your tool layer must never throw. In a loop, an exception doesn't just lose one answer. It ends the run, and Claude never learns what went wrong, so it can't retry or tell the user. Send every call through one function that always returns a tool_result. The loop in the next lesson imports a runTool just like it.

Because strict schemas can't enforce minimum or maximum (as of October 2026). Put the range in the description, so Claude rarely gets it wrong, and check it in code, so a wrong call comes back as an error Claude can fix next turn: “days must be 1 to 7”.

Second, a result is the next turn's input. Write each one to answer the question Claude asks itself next: what can I do now? That means returning the fields the next tool needs, in the names it takes. It means saying what was actually matched, so Claude can catch a wrong match before it builds three more steps on it. And it means staying small, because in a loop every result is re-sent on every later turn.

Anthropic calls this designing the agent-computer interface, and suggests you poka-yoke your tools: shape them so mistakes are hard to make. Their coding agent kept fumbling relative file paths, so they made the tool require absolute paths, and the mistakes stopped. Here, get_forecast takes coordinates rather than a place name, so it can never guess which Portland you meant.

Your turn. Give Claude two tool descriptions that are meant to chain, a question, and ask whether it could get from one to the other. Anything it has to guess is a step your agent would guess at too.