Tool Design and Contracts

A tool definition is the interface contract between an agent and the external world: it includes a name, a description the model reads to decide when to call it, and a typed parameter schema that constrains what the model can pass in. The most common failure mode is vague descriptions: a tool named "search" with the description "searches for things" will be invoked incorrectly far more often than one named "search_codebase_by_symbol" that specifies exactly what it searches and what format results take.

JSON Schema is the formal specification language used to define the structure, types, and constraints of the parameters that agents pass to tools, serving as the contract between the model's output and the tool's input. Every major large language model (LLM) provider uses JSON Schema as the standard for defining tool interfaces, making it the universal language for describing what an agent can do.

Function calling is the mechanism through which language models invoke external tools by outputting structured requests that match predefined function signatures, producing a JSON (JavaScript Object Notation) payload specifying the function name and arguments rather than a free-text description of intent. This structured interface is what transforms a language model from a text generator into an agent capable of taking real-world actions like reading files, querying databases, or calling APIs.