Definition
An MCP tool is a named capability that an AI client can call through an MCP server.
A tool is not just a button for the model. It has a name, a description, an input schema, and an execution path. The client uses the catalog to decide whether a tool is relevant, then sends structured arguments when it calls the tool.
Good tools are specific. A tool called search_orders with clear filters is usually safer and easier for a model to use than one broad tool that accepts arbitrary instructions.
The tool description helps the model choose. The server-side implementation decides whether the call is allowed.
Anatomy of an MCP tool
A production tool needs more than a name and a function.
| Part | Purpose | Production note |
|---|---|---|
| Name | The identifier the client uses when calling the tool. | Use short, task-oriented names such as search_orders or create_ticket. |
| Description | The model-facing explanation of when to use the tool. | State the use case, constraints, and expected result. |
| Input schema | The structured arguments accepted by the tool. | Constrain types, required fields, enums, limits, and unsafe free-text fields. |
| Execution path | The server-side handler, API operation, database executor, or workflow. | Map to known backend actions instead of trusting client-supplied routes or SQL. |
| Policy | The rules that decide whether the call can run. | Check identity, ownership, publication state, scope, limits, and permissions before execution. |
| Result shape | The structured output returned to the client. | Return enough context for the task without leaking secrets or unnecessary internal detail. |
Description quality
Tool descriptions are part of the product surface because the model reads them when choosing a tool.
| Weak | Better | Why |
|---|---|---|
| Gets data. | Search approved orders by customer, status, or date range. Use limit to keep the result small. | The better version explains task, filters, and result control. |
| Updates ticket. | Add an internal note to an existing support ticket after the user confirms the ticket ID and message. | The better version defines a confirmation expectation for a write action. |
| Run SQL. | Validate a structured QueryPlan against the published sales scope before execution. | The better version describes the safe boundary instead of a broad capability. |
| Customer lookup. | Read customer status and account flags for a known customer ID; do not use for broad customer search. | The better version prevents confusing lookup with search. |
What makes a good MCP tool
The best tools are narrow, well-described, and easy to validate.
- The name should describe the action or resource.
- The description should say when to use the tool, when not to use it, and what it returns.
- The input schema should be structured and constrained.
- The execution path should validate inputs before touching the source system.
- The result should be useful without leaking secrets or unnecessary internal details.
- The tool should be observable by name, source, caller, latency, and success or error state.
OpenAPI operation tools
OpenAPI operations can map naturally to MCP tools, but the generated catalog should still be curated.
An operation like GET /orders/{id} can become a tool with schema-aware arguments and an editable description. The MCP server can then route the call to the upstream REST API or another executor.
The description matters because AI clients use it to choose the right tool. Agent-ready descriptions reduce guesswork and make tool use more predictable.
Not every operation should be published. Admin, token-management, destructive, broad, or low-signal endpoints should stay hidden until a reviewed AI workflow needs them.
Database tools
Database MCP tools should separate metadata from execution.
Schema tools should describe approved tables, columns, keys, relationships, and permissions without returning row payloads. Executor tools should run only after trusted server-side validation.
For database scopes, a schema tool helps the assistant understand what exists. QueryPlan or SqlScript executor tools are separate and must enforce scope, table, column, relationship, limit, and mode policy before data is returned.
Tool risk levels
Different tools deserve different review levels.
| Tool type | Example | Review expectation |
|---|---|---|
| Read-only lookup | get_customer_status | Check scope, returned fields, and logging. |
| Search or list | search_orders | Add filters, limits, and result-size controls. |
| Write action | create_ticket or update_case_note | Require clear arguments, logging, and confirmation expectations. |
| Database executor | execute_query_plan | Require scope, column permissions, row limits, and audit redaction. |
| Admin operation | rotate_token or delete_user | Hide by default unless there is a narrow reviewed workflow. |
Sources and further reading
Common questions
Is an MCP tool the same as an API endpoint?
Not exactly. An MCP tool can wrap an API endpoint, database executor, local function, or other capability. The tool is the AI-facing interface.
Why do tool descriptions matter?
AI clients use descriptions to decide which tool to call. A vague description can cause wrong tool selection or poor arguments.
Should one tool do many jobs?
Usually no. Narrow tools with clear schemas are easier to validate, observe, and explain.
Can a tool description enforce security?
No. A description guides model selection. Security must be enforced by trusted server-side validation before execution.
What is an agent-ready tool?
An agent-ready tool has a clear name, explicit description, constrained input schema, predictable result shape, and server-side validation around the real system it touches.
Should database schema tools return sample data?
No. Schema tools should return metadata only. Row data should come only from validated executor tools inside the published scope.