Bounding Execution Loops & Tool Calling Schemas
Your payment agent invokes an external banking API with a refund amount formatted as "$50.00" (string) instead of 5000 (cents integer). The API fails with an unhelpful 400 error. The agent re-invokes with "50.00 USD", escalating the failure. How do strict JSON Schema contracts prevent argument hallucination before packets ever hit the network?
Author unambiguous tool definitions using strict schema constraints and implement pre-flight argument validation.
Why is it critical to set "additionalProperties: false" on all tool argument schemas passed to language models?
Tool Contracts as Security Boundaries
In an agentic architecture, tools are the boundary where non-deterministic text generation interacts with deterministic production systems.
Every tool definition must treat the model as an untrusted client. The application must validate every argument against an exact schema before executing the handler.
Idempotency and Side-Effect Isolation
Network calls drop. Connections timeout. If an agent calls a payment tool, the network drops before receiving the response, and the agent retries, will it charge the user twice?
Every mutating tool must accept a deterministic idempotency key derived from the conversation ID and step index.
Incident Analysis: Duplicate Order Fulfillment via Unbounded Retry
A fulfillment warehouse agent was processing physical shipment labels.
Developers assumed the model would know whether a label had been created based on the assistant message history.
A transient socket timeout caused the label creation call to return an error observation. The model retried with slightly altered dimensions. Two physical shipping labels were generated and printed for a single customer order.
The tool lacked an idempotency key tied to the order ID.
Duplicate inventory dispatched and unnecessary carrier freight charges.
Added mandatory idempotency keys (`idempotency_key = order_id + "_" + item_sku`) to the tool contract.
All mutating agent tools must be idempotent. Never rely on the language model to manage transaction safety.
What is the most reliable way to generate an idempotency key for an agent tool call?
Exercise: Writing a Zero-Tolerance Tool Contract
Author a tool definition for an automated database query analyzer that prevents destructive SQL execution.
- •Must reject non-SELECT statements at the schema parser level
- •Enforce mandatory execution timeout parameter
- •Set additionalProperties to false
Key Engineering Invariants
- 01Treat the model as an untrusted caller at all tool boundaries.
- 02Enforce strict JSON schemas with additionalProperties: false.
- 03Every state-mutating tool must implement idempotency keys.