Build Your First AI Agent: Define the Tool Contract Before the Loop

\n\n## Why the tool contract comes before the loop\n\nThe tool contract stopped being optional the moment you tried to ship an assistant that does real work. Skip it and you get loops that never terminate, tools called with malformed arguments, and a token bill that grows every turn. Most guides on how to build AI agents jump straight to the 

 loop. We start one step earlier.\n\nThe loop earns its keep. A chatbot answers in a single pass. An agent persists across steps, assembling context, choosing an action, running a tool, and reading the result before deciding what comes next. A loop also amplifies whatever you hand it, and it bills you per turn. Coverage of agent architecture has framed that price plainly, describing agent runs as consuming roughly 4x more tokens than standard chat interactions and up to 15x in multi-agent systems. The same write-up makes a structural point worth taping to the monitor: repetition alone does not make a result autonomous, correct, or safe. Permissions and stopping conditions have to be defined by the application itself.\n\n### What a tool contract actually buys you\n\nA tool contract is three things: a name, a description, and a JSON input schema (the typed description of the arguments your function accepts) built from 

 fields. One per tool, written before the loop exists. What comes back is clearer responsibilities, less tool exposure, tighter token budgets, scoped permissions, and failures you can trace to a single call instead of a whole conversation.\n\nThe savings sit exactly where the contract does. Schema-first tool APIs for LLM agents examine this trade-off directly: how the shape of a schema changes what the model has to reason about, and how much selection work can move out of the prompt and into the contract. In practice, the contract does work the model would otherwise burn tokens on.\n\nOne tool, one call, no decisions in between? Skip the phase. A single-step lookup doesn't need a loop.\n\n### How to plan an agent before you write code\n\nOne row per goal. Budget time with explicit timeouts on each LLM call and each tool call rather than guessed runtimes. The table below is an illustrative example.\n\n| Goal | Tool | Contract | Loop Steps | Time Estimate |\n|-|-|-|-|-|\n| Answer a docs question | Search API | 

; approval gate | look up, preview, approve, execute | 4 calls, timeout per call |\n\n## Defining the contract: the three fields the model actually sees\n\nA model never sees your Python function. It sees a name, a description, and a JSON input schema. That trio is the whole interface between the model's reasoning and your code. If you're working out how to build AI agents that behave predictably, most of that question gets settled here.\n\nThe minimal weather contract we hand new builders:\n\n

python\ntools = [{\n \"name\": \"get_weather\",\n \"description\": \"Get the current weather for a given location.\",\n \"input_schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"location\": {\n \"type\": \"string\",\n \"description\": \"City and state, e.g. San Francisco, CA\",\n }\n },\n \"required\": [\"location\"],\n },\n}]\n

: the identifier the model sends back in its tool call. Your dispatcher routes on it, so keep it explicit.\n- 

: the model picks tools from the user's request plus this text. Vague description, wrong calls.\n- 

: an object with typed fields. The format example inside the field description shows the model what a good value looks like.\n- 

: the fields a call must include. Treat it as a hint, not a guard. Claude's docs note that less capable models may guess a plausible value instead of asking for it, so validate inputs in your own code.\n\n

\n\n### Where timeouts and token costs belong\n\nTimeouts have no home in the schema, because there's no latency field. They go in the execution layer. One durable-workflow recipe runs the LLM call and each tool call inside its own activity, which makes that layer the place to handle limits and failures. It also hands retries to the orchestrator rather than the OpenAI client, since client-side retries can interfere with durable error handling and recovery.\n\nThen budget tokens, the text units you pay for. Every request carries each tool's name, description, and schema, plus 

 blocks. In a loop, each LLM call also receives the accumulated history, earlier tool calls and results included, so that overhead compounds turn by turn. Every tool you expose costs you on every turn. List only what this agent needs.\n\nSix items on the checklist: explicit names, clear descriptions, typed properties, required fields, a minimal tool list, and a defined error path for each tool.\n\n## The loop is the easy part\n\nThe loop you ship to production looks nearly identical to the toy demo. That surprises people. When you're building AI agents, the hard parts live in the tools and plumbing you defined in the contract, not in the 

 statement.\n\nStrip it down and it fits in about six lines: while not done, call the model; if the response contains tool calls, execute them and append the results; otherwise return the response. You own the loop and the tools. The model owns the reasoning.\n\n### Every turn ends in one of three branches\n\nThe documented flow has five steps. Send a request with tools, receive a tool call, execute the code on your side, send the output back. Then you get a final response 

. That last clause is what makes chaining work, because one user question can trigger many round trips.\n\n

python\nwhile True:\n response = client.messages.create(\n model=\"claude-sonnet-5\", max_tokens=1024, tools=tools, messages=messages)\n if response.stop_reason == \"end_turn\":\n break\n elif response.stop_reason == \"tool_use\":\n results = [{\"type\": \"tool_result\", \"tool_use_id\": b.id,\n \"content\": run_tool(b.name, b.input)}\n for b in response.content if b.type == \"tool_use\"]\n messages.append({\"role\": \"assistant\", \"content\": response.content})\n messages.append({\"role\": \"user\", \"content\": results})\n else:\n print(f\"Stopped early: {response.stop_reason}\")\n break\n

\n\nThe minimal weather case stays inside a single round trip: one tool call goes out, one result comes back, and the next turn lands on 

.\n\nThe defensive branch is the one beginners drop. If the model stops for a reason your code did not plan for, exit cleanly instead of treating the turn as usable context.\n\n### Your contract sets the token floor\n\nSupplying tools takes you out of plain chat economics. The overhead starts with the tool definitions you ship, not with the user's question. Then every 

 block rides along in the history on each turn. Each tool you cut at the contract stage pays you back on every iteration.\n\nYou can steer call frequency from the system prompt. "Use your judgment about whether to call a tool or respond directly" keeps calls conservative. "Always call a tool first before responding" pushes harder.\n\nSkip the loop for fixed sequences and latency-critical work. A deterministic pipeline is cheaper than paying for an extra model call per step.\n\n## Handling errors, timeouts, and latency\n\nFailure handling stops being cleanup duty the moment you put a model inside a loop. Walking teams through how to build AI agents, the same gap shows up every time: error handling gets bolted on after the loop already works. Flip the order. Retries, timeouts, and stop conditions are execution-design decisions, made before you write a line of loop code.\n\n### Who owns the retry?\n\nPick one owner and switch the rest off. The durable-execution reference recipe builds its model client with 

 so the orchestration layer owns retry behavior instead of the SDK.\n\nThat matters more than it looks. Client retries left on invite nested attempts that interfere with correct and durable error handling and recovery. Two retry stacks means two sets of backoff timers and no single place to see what actually failed.\n\n### Which stop reasons end the loop?\n\nA production loop should name every stop path it recognizes. Continue only when the response is asking for tool execution. Return the final answer when the model is done. Anything outside those two cases: log the reason and halt, rather than assuming the next turn will repair itself.\n\nTimeouts belong at the execution layer, not in the schema. The same recipe sets a 30-second start-to-close timeout on the LLM activity and on each tool activity, plus a 30-second timeout on the request itself. Bounded latency, without inventing a contract-level max-response-time field nobody validates.\n\n### Do errors reach the agent as recovery instructions?\n\nA 400 tells a developer what broke. An agent needs candidates, corrections, and a next move. That is why the Six-Verb Semantic Protocol gives 

 its own phase, and why enterprise-agent research lists "errors are HTTP status codes" among the CRUD assumptions that collapse when the caller is an LLM planner rather than a rendered UI.\n\nBill cost in the categories the API actually charges for: tool definitions, 

Definition overhead is the one teams forget

, and it recurs on every single turn.\n\nFor a one-shot tool call with no loop, all of this buys you nothing. Skip it.\n\n## 

: build it in one sitting\n\nYour first agent stopped being a demo the moment it could call code you wrote. The smallest honest version is tiny. Lesson 4 of Claude Platform 101 is a clear single-tool walkthrough for building AI agents without a database or UI in the way.\n\nThe run stays predictable because the contract came first. One 

 tool: a name, a description, and a JSON schema that requires 

. Ask what to wear in Austin and you get 

two API calls, one tool execution, one final answer

. Turn one ends with the tool call; your code returns "95F, sunny." Turn two ends with advice to dress light.\n\n### Why the loop needs the contract first\n\nA dispatcher can only route a tool name it already knows. It can only validate input against a schema you already wrote. The 

 is the field that tells you why the model paused, and it drives every branch:\n\n- 

: run the tool, append the result, loop again.\n- 

): stop rather than recycling the same unresolved turn.\n\nThere's no latency figure to hand you here. Operation count is the honest metric for this mini-project, and that count is fixed.\n\n### How to grow it without losing control\n\n- 

 Each schema ships with the request, so every addition costs tokens on every turn.\n- 

 option on supported models. It loads seldom-used tools only when the model needs them.\n- 

 Learned tool-contract research explores showing the model only the tools whose preconditions match the task. Fewer visible tools means less to read and fewer wrong picks.\n- 

 A weather bot doesn't need search. Skip it until the task depends on facts the model lacks.\n- 

 Before anything writes, sends, or refunds, require a check that lives outside the model."}

Does marking a field "required" guarantee the model will supply a real value?

No. Treat schema requirements as routing and formatting guidance, then enforce them in your dispatcher. If a value is missing, malformed, or unsafe, reject the call before the tool runs.

Should I leave the SDK's built-in retries on when my orchestrator also retries?

No. Use a single retry layer so failures, backoff, and logs all live in one place. If the orchestrator is responsible for recovery, configure the model client so it does not create a second retry path.

Use something simpler when the task has no real decision point between steps. Direct calls and deterministic pipelines are easier to debug, cheaper to run, and less exposed to accidental looping.

AUTHOR

Dr. Dipen

{"article":" \n\n## Why the tool contract comes before the loop\n\nThe tool contract stopped being optional the moment you tried to ship an assistant that does real work. Skip it and you get loops that never terminate, tools called with malformed arguments, and a token bill that grows every turn.…

Learn

The newline Guide to Building Your First GraphQL Server with Node and TypeScript

Teach

Amelia Wattenberger

Author of Fullstack D3

Community

Free Tools

Build Your First AI Agent: Define the Tool Contract Before the Loop

Responses (0)

Free AI Career Tools

AI Job Listings

ATS Resume Checker

Startup Perks

Masterclasses

Tutorials

Fullstack React with TypeScript