Tool Definition

What is a tool definition?

A tool definition is the machine-readable description of a capability available to a model or AI agent. It tells the model what the tool is called, what it does, and what input it expects. The definition helps the model decide whether the tool is relevant and how to request it.

A tool can represent an API, database query, calculator, search service, file operation, browser action, or another controlled capability.

What a tool definition contains

A practical tool definition normally includes:

• a unique, descriptive name;
• a concise explanation of the tool’s purpose;
• guidance about when it should or should not be used;
• an input schema with fields, data types, and requirements;
• sometimes output expectations or important limitations.

For example, a search_orders tool description should explain which orders it searches and whether it returns summaries or full records. Its schema might require a customer ID and allow optional date filters.

Tool definition versus tool schema

The tool definition describes the capability as a whole. The tool schema is the structured contract for its inputs. A perfect schema cannot fix an unclear purpose: the model may produce valid arguments for the wrong tool.

A definition also differs from [agent instructions](/glossary/agent-instructions/). The definition explains what one tool can do. Agent instructions establish broader behavior, such as requiring approval before using any tool that changes customer data.

Why wording matters

Models use names and descriptions during tool selection. Overlapping descriptions can make two tools difficult to distinguish. Vague wording such as “handles data” gives little guidance. Definitions should state the specific capability, relevant boundaries, and meaningful differences from similar tools.

Definitions should not include secrets or rely on the model to enforce authorization. The execution layer must still verify identity, access, and business rules.

Common failure modes

A tool definition can become stale when the underlying service changes. Missing required fields can lead to repeated failed calls. Excessive descriptions consume context tokens and may distract the model, while overly short descriptions create ambiguity.

Builders should version definitions with their implementations, test realistic tool-selection cases, and return structured errors when inputs or execution fail.

Why it matters

Tool definitions are the interface between model reasoning and external capabilities. Clear definitions improve selection accuracy, argument quality, and safe behavior. They also make tools reusable across multiple agents without embedding implementation details in every prompt. See [Tool Use in AI Agents](/tool-use-in-ai-agents/) for how definitions, selection, execution, and results work together.