AI / LLM Integration
Tool calls: code and schema reading
Crux Read real tool-calling snippets — a tool JSON schema, a parallel-call dispatcher, a loop with timeout/error handling, and an argument validator — and pick the highest-leverage fix.
Your altitude — climbing toward senior
ZeroJuniorMiddleSenior
You are at senior altitude — in orbitTool-calling bugs live in the schema, the dispatcher, and the loop — not in the model. Read each snippet the way you would in review, then choose the fix a senior engineer would make first.
Goal
Practise the diagnosis loop you run on every agent: read the tool schema and the loop code, predict how the model and your handler will behave, and reach for the fix that closes the trust boundary or stops the runaway.
Snippet 1 — the tool schema
{
"name": "cancel_order",
"description": "Cancel an order.",
"input_schema": {
"type": "object",
"properties": {
"order_id": { "type": "string" },
"reason": { "type": "string" }
}
}
} Quiz
Completed
A mutating cancel_order tool ships with this schema. What is the single biggest weakness, and the highest-leverage fix?
Heads-up Adding tools does not fix this one. The defect is that the schema permits a free-form, optional, undescribed order_id, so the model has no constraint and you have nothing tight to validate against.
Heads-up Type alone does not stop hallucination — the model can invent a plausible integer just as easily as a string. The fix is required fields, enums where applicable, a real description, plus runtime existence/authorization checks.
Heads-up The input_schema is what guides the model toward correct calls and gives you a contract to validate. Dropping it removes both the guidance and your validation target — the opposite of the fix.
Snippet 2 — the parallel dispatcher
results = []
for block in response.tool_use_blocks: # may be several this turn
output = TOOLS[block.name](**block.input) # run sequentially
results.append(tool_result(block.id, output))
send(messages + results) Quiz
Completed
When the model emits three independent tool_use blocks in one turn, what does this dispatcher get right and what does it leave on the table?
Heads-up All tool_result blocks for one turn's tool_use blocks go back in a single follow-up request; that is exactly what this code does. The improvement is concurrency of execution, not splitting the response.
Heads-up Each tool_result references its block.id, so matching is by id, not order. The model emitted parallel blocks deliberately; the fix is to execute them concurrently, not to disable parallelism.
Heads-up Spreading model-supplied input straight into the function is the missing trust boundary — arguments can be hallucinated or malformed. Validate against input_schema before calling, regardless of the parallelism question.
Snippet 3 — the loop with no guard
while True:
resp = model.create(messages=messages, tools=TOOLS)
if resp.stop_reason != "tool_use":
break
for b in resp.tool_use_blocks:
out = run_tool(b.name, b.input) # may raise / hang
messages.append(tool_result(b.id, out))
messages.append(resp.message) Quiz
Completed
This loop runs in production against client tools. Which two defects will bite first under failure, and how do you fix them?
Heads-up Message ordering is a real concern but not what bites first under failure. The dangerous gaps are the missing iteration cap (runaway cost) and the missing per-tool timeout (a hanging tool stalls the turn).
Heads-up Breaking when stop_reason is not tool_use already exits on end_turn, max_tokens, etc. The exposure is the unbounded while True on the tool_use path and the lack of a tool timeout.
Heads-up This loop already runs tools sequentially, so parallel safety is not the issue. The failure-mode gaps are the runaway guard and the per-tool timeout.
Snippet 4 — the validator
def handle(block):
args = block.input
try:
validated = ToolArgs.model_validate(args) # pydantic: shape + types
except ValidationError as e:
return tool_result(block.id, f"invalid arguments: {e}", is_error=True)
return tool_result(block.id, run(validated)) Quiz
Completed
This handler schema-validates with Pydantic and returns errors as a tool_result. For a mutating tool against a multi-tenant database, what is still missing?
Heads-up Schema validation only proves the arguments are well-shaped, not that the referenced entity is real or owned by the caller. A validated-but-fabricated id still mutates the wrong record without an authorization/existence check.
Heads-up Returning the error as a tool_result is correct — it lets the model read the error and self-correct on the next turn. Raising out of the loop ends the turn and removes that recovery path.
Heads-up Blind retries on a mutating call risk repeating a destructive action and burning tokens. The missing layer is authorization/existence checking before execution, not retry-on-failure.
Recap
Every tool-calling bug is read in the schema, the dispatcher, the loop, or the validator. A loose schema (no required, no enum, empty description) lets the model guess and gives you nothing to validate. A sequential dispatcher is correct but forfeits the parallel-call latency win for independent calls. while True with no per-tool timeout is a runaway and a stall waiting to happen — cap iterations and time-box each tool. And Pydantic shape-validation is necessary but not sufficient for a mutating call: add the authorization and existence check, and return every rejection as a tool_result so the model can self-correct.