How to Design Tools That AI Agents Can Use Reliably

This article provides a comprehensive tutorial on designing tools that AI agents can use reliably. It emphasizes that agent tools are contracts between nondeterministic decision-makers and deterministic systems, requiring distinct names, narrow responsibilities, constrained input schemas, useful descriptions, predictable outputs, retry-safe side effects, actionable errors, server-side validation, and evaluations based on realistic tasks. The tutorial builds a production-style change-request tool called 'change.create' and covers naming conventions, descriptions, JSON Schema constraints, idempotency, dry-run validation, structured error results, and tool-specific evaluations for selection, argument quality, recovery, safety, latency, and efficiency. It is framework-neutral and applicable to protocols like Model Context Protocol.