Context & Metadata
Write effective tool and parameter descriptions that help AI agents choose the right tool.
Context & Metadata
AI agents decide which tool to call based on the tool's name, description, and parameter descriptions. Well-written metadata dramatically improves how reliably agents use your tools.
How Agents See Your Tools
When an AI agent connects to your MCP server, it receives a list of tools as JSON Schema. Here is what a tool looks like from the agent's perspective:
{
"name": "get_customer_orders",
"description": "Look up recent orders for a specific customer by their ID. Returns at most 100 rows.",
"inputSchema": {
"type": "object",
"properties": {
"customer_id": {
"type": "string",
"description": "Unique customer identifier (e.g., cust_abc123)"
},
"status": {
"type": "string",
"description": "Filter by order status: pending, shipped, delivered, or cancelled"
},
"limit": {
"type": "number",
"default": "25",
"description": "Maximum number of orders to return"
}
},
"required": ["customer_id"]
}
}The agent uses every field to decide when and how to call the tool.
Tool Descriptions
The tool description is the single most important piece of metadata. It tells the agent when to use this tool and what it returns.
Good Descriptions
| Tool Name | Description |
|---|---|
get_monthly_revenue | Get total revenue broken down by month for a date range. Returns month, revenue, and order count. |
search_customers | Search customers by name, email, or company. Supports partial matching. Returns name, email, company, and plan. |
get_ticket_details | Look up a support ticket by its ID. Returns ticket subject, status, priority, assignee, and full conversation history. |
Bad Descriptions
| Tool Name | Description | Problem |
|---|---|---|
query1 | "Runs a query" | Name and description are meaningless |
get_data | (empty) | Agent has no idea what data this returns |
customer_report | "Customer report" | Repeats the name without adding information |
Writing Tips
- Start with a verb: "Get", "Search", "Look up", "List", "Calculate"
- Mention what is returned: "Returns name, email, and plan" helps the agent know if this tool answers the user's question
- Include constraints: "Returns at most 100 rows" or "Only includes active accounts"
- Mention the entity: "for a specific customer" vs "for all customers" clarifies scope
Parameter Descriptions
Parameter descriptions act as a business glossary for the AI agent. They define what values are valid and what they mean.
Good Parameter Descriptions
| Parameter | Description |
|---|---|
region | "Two-letter region code: US, EU, AP, or SA" |
status | "Order status. One of: pending, shipped, delivered, cancelled" |
start_date | "Start of date range (ISO 8601, e.g., 2025-01-01)" |
granularity | "Time bucket for aggregation: day, week, or month" |
Bad Parameter Descriptions
| Parameter | Description | Problem |
|---|---|---|
region | "The region" | Does not explain the format or valid values |
status | (empty) | Agent will guess values, often incorrectly |
date | "Date" | No format guidance |
Listing valid enum values in the description is one of the most effective ways to improve tool accuracy. Agents cannot guess that your status column uses "shipped" rather than "in_transit".
Naming Conventions
Tool names become the function names that agents call. Follow these conventions:
- Use
snake_case(e.g.,get_customer_orders, notGetCustomerOrders) - Start with a verb:
get_,list_,search_,count_,calculate_ - Be specific:
get_order_by_idis better thanget_order - Keep names under 50 characters
Iterating on Descriptions
After deploying a tool, monitor how agents use it in the execution logs. Common issues:
- Agent never calls the tool — description does not match user intent, or the tool name is too generic
- Agent calls with wrong parameter values — add enum values or format examples to parameter descriptions
- Agent calls the wrong tool — two tools have overlapping descriptions; make them more distinct