Building Agents
Designing Tools That Agents Can Use Reliably
Principles for tool names, parameters, responses, errors, idempotency, and safe execution.
Make the purpose unmistakable
Use a specific action-oriented name and describe when the tool should and should not be used. Avoid several overlapping tools that force the model to guess among nearly identical choices.
Keep inputs narrow
Prefer enums, required identifiers, and small structured objects over free-form blobs. Validate every field and return errors that explain how the request can be corrected.
Design for retries
Network and model failures make repeated calls inevitable. Use idempotency keys for writes, expose the resulting state, and distinguish safe retries from actions requiring fresh approval.