Tool Definition Patterns

Well-designed tool definitions are the interface contract between an agent and the external world, and their quality directly determines how reliably an agent selects and invokes the right tool for a given task. Effective tools have clear, descriptive names that signal purpose, precise descriptions that explain when and how to use them, and well-typed parameters with constraints that prevent misuse. The most common mistake is writing vague descriptions that leave the model guessing — a tool named "search" with the description "searches for things" will be invoked incorrectly far more often than one named "search_codebase_by_symbol" with a description specifying exactly what it searches and what format results return. This concept is foundational because every agent system, regardless of architecture, depends on tool definitions to bridge the gap between language understanding and real-world action. This connects to function calling for the underlying mechanism, JSON schema for the structural format, and resilient tool contracts for designing tools that handle errors gracefully.