Claude tool use, a working quickstart

What tool use actually is

Tool use lets Claude call functions you define instead of only producing text — you describe a tool's name, what it does, and the shape of the input it expects, and Claude decides during a conversation whether calling it would help answer the current request. The model doesn't execute anything itself; it returns a structured request to call a specific tool with specific arguments, your code runs the actual function, and you send the result back so Claude can use it to continue. The loop is request, your execution, response, repeat — Claude never reaches outside that loop on its own.

Describing a tool well is most of the work

The single biggest determinant of whether tool use works reliably isn't the calling code — it's how well the tool itself is described. A tool named ambiguously, or with a description that doesn't distinguish it clearly from a similar tool in the same request, gets called incorrectly or skipped when it shouldn't be, not because the model failed at reasoning but because the description didn't give it enough to reason with. Write tool descriptions the way you'd write documentation for a teammate who's never seen the codebase — what it does, when to use it, what it explicitly does not do if that's likely to be confused with something else in your tool list.

The request-response loop, concretely

A turn where Claude decides to use a tool comes back with a stop reason indicating a tool call is pending, along with the tool's name and the arguments it wants to call it with. Your code is responsible for actually running that function — Claude has no side-channel access to execute code itself — and then sending the result back as a new message in the conversation, formatted as a tool result tied to the specific call that requested it. Claude then continues from there, either finishing its answer using that result or, on a task that needs several tools in sequence, making another call.

Parallel tool calls versus sequential ones

A single turn can request more than one tool call at once when the calls are independent of each other — looking up two unrelated pieces of information doesn't require waiting for the first lookup before starting the second. Your code needs to handle that shape explicitly: executing requested calls, collecting all their results, and returning them together, rather than assuming every turn produces exactly one tool call to handle. Code written assuming a strict one-call-per-turn shape breaks the first time a task naturally produces two calls it could reasonably run in parallel.

The failure mode that isn't really a tool-use bug

The most common early problem with a tool-use integration isn't a broken tool — it's a tool that gets called when it shouldn't be, or not called when it should be, because its description didn't clearly separate its purpose from a similar tool nearby in the list, or because the system prompt gave contradictory guidance about when to reach for it. Debug this by reading the tool descriptions as if you'd never seen the code, not by assuming the model reasoned incorrectly.

Where to go from a working quickstart

Once a basic tool-use loop is running, the two things worth hardening next are error handling — what happens when a tool call fails, which is a different problem from the model choosing not to call a tool — and, if your tool surface is large, whether every tool needs to be declared up front or some of it belongs behind on-demand discovery instead. See handling Claude API errors without guessing for the first, and building a tool-search workflow for the second.