1
# Bad description — agent might not use it
2
{
3
    "name": "search_docs",
4
    "description": "Search documentation",
5
    "inputSchema": {
6
        "query": {"type": "string"}
7
    }
8
}
9
# Likely agent behavior: rarely calls it. Prefers to guess.

1
# Good description — agent uses it as intended
2
{
3
    "name": "search_docs",
4
    "description": "Search the internal product documentation for technical references, API guides, and implementation patterns. Always call this before writing new code to check for existing patterns. Return up to 10 results ranked by relevance.",
5
    "inputSchema": {
6
        "query": {"type": "string", "description": "The search query. Include domain-specific terms for better results."},
7
        "max_results": {"type": "number", "description": "Number of results (1-10).", "default": 5}
8
    }
9
}
10
# Likely agent behavior: calls it frequently. Follows the "always call before writing code" instruction.

1
# Bad: just describes
2
"description": "Fetches user data from the database"
3

4
# Good: describes AND instructs
5
"description": """Fetches user data from the database.
6
Always call this when you need user information instead of guessing.
7
Returns: user_id, email, role, created_at.
8
Never log the email field — it contains PII.
9
If the user is not found, check the archive database tool instead of reporting an error."""

1
# Before: generic name, agent might not distinguish
2
tools = [
3
    { "name": "query", "description": "Query the production database" },
4
    { "name": "query", "description": "Query the staging database" },
5
]
6
# Agent gets confused about which to use
7

8
# After: explicit names for routing
9
tools = [
10
    { "name": "query_production", "description": "Query the production database. Use for customer-facing data." },
11
    { "name": "query_staging", "description": "Query the staging database. Use for testing and development." },
12
]
13
# Agent can now route correctly based on context

1
{
2
    "name": "process_refund",
3
    "description": "Process a refund for a customer transaction",
4
    "inputSchema": {
5
        "transaction_id": {
6
            "type": "string",
7
            "description": "The transaction ID from the payment system. Must start with 'txn_'."
8
        },
9
        "amount": {
10
            "type": "number",
11
            "description": "Refund amount in cents. Maximum: 50000 ($500). Refunds over $100 require manager approval — do not process without it."
12
        },
13
        "reason": {
14
            "type": "string",
15
            "enum": ["duplicate_charge", "customer_request", "product_return", "service_issue"]
16
        }
17
    }
18
}

1
# MCP resource definition
2
{
3
    "uri": "docs://architecture",
4
    "name": "System Architecture Documentation",
5
    "description": "Architecture docs describing the microservices, data flow, and deployment topology. Read this before making architectural decisions.",
6
    "mimeType": "text/markdown"
7
}

1
tools = [
2
    { "name": "search", "description": "search database" },
3
    { "name": "read", "description": "read document" },
4
    { "name": "write", "description": "write to file" },
5
]

1
tools = [
2
    {
3
        "name": "search_knowledge_base",
4
        "description": "Search the internal knowledge base for documentation, guides, and reference materials. Call this whenever you need technical context about our codebase. Always search before writing new code — there might be an existing pattern or utility function.",
5
        "inputSchema": {
6
            "query": { "type": "string", "description": "Search terms. Be specific." },
7
            "max_results": { "type": "number", "default": 5 }
8
        }
9
    },
10
    {
11
        "name": "read_source_file",
12
        "description": "Read a source file from the codebase. Use this to understand existing code before making changes. Full file path required.",
13
        "inputSchema": {
14
            "path": { "type": "string", "description": "Absolute path to the file in the repository." }
15
        }
16
    },
17
    {
18
        "name": "write_code_change",
19
        "description": "Write or modify a source file. Always read the existing file first. Always run tests after writing. Never overwrite files without reading them first.",
20
        "inputSchema": {
21
            "path": { "type": "string" },
22
            "content": { "type": "string" }
23
        }
24
    }
25
]