mcp-patterns

MCP Patterns Skill

MCP Specification (2025-06-18)

Core Concepts

Concept	Description
Server	Exposes tools, resources, prompts to clients
Client	Connects to servers, invokes tools
Transport	Communication layer (stdio, HTTP, SSE)
Tool	Executable function with JSON Schema
Resource	Read-only data (files, URLs)
Prompt	Reusable prompt template

---

Tool Definition Pattern

// TypeScript with @modelcontextprotocol/sdk
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [{
    name: "search_kb",
    description: "Search the knowledge base",
    inputSchema: {
      type: "object",
      properties: {
        query: {
          type: "string",
          description: "Search query"
        },
        limit: {
          type: "number",
          description: "Max results",
          default: 10
        }
      },
      required: ["query"]
    },
    annotations: {
      readOnlyHint: true,      // Doesn't modify state
      idempotentHint: true,    // Same input = same output
      openWorldHint: false     // Bounded result set
    }
  }]
}));

Tool Annotations

Annotation	Meaning	Use When
readOnlyHint	No side effects	Read operations
destructiveHint	Deletes/modifies data	Write operations
idempotentHint	Safe to retry	GET-like operations
openWorldHint	Results may change	External API calls

---

How to Write a Tool Description

The description is the only signal the model uses to route a request. The schema constrains the call; the description decides whether the call happens at all. Treat it as a routing contract, not API prose. A good one has five parts, in this order:

1. One-line purpose — what the tool does, in plain terms. Lead with a verb. Search indexed knowledge-base documents and return ranked passages. Skip the HTTP verb and endpoint; calls GET /v2/search tells the model nothing about intent.
2. WHEN TO USE — concrete trigger phrasings the user might say, not abstract categories. List the actual shapes: "find docs about X", "what does the KB say about Y", "look up the runbook for Z". Models match on surface form, so give them surface forms.
3. WHEN NOT TO USE — the section that does most of the disambiguation work. Name the near-miss tools and the boundary that separates them. This is where you prevent the model from firing the wrong tool on a request that looks similar. Empty WHEN NOT TO USE = the tool is under-specified.
4. CRITICAL — one line for the single non-obvious failure mode. The constraint a reader would not guess from the schema: a required ordering, an ID that must come from another call, a cost/irreversibility warning. One line, not a checklist.
5. Self-test — close with a question the model can apply to itself to decide fit. Ask: is the user looking up existing content, or asking me to create new content? This tool is read-only — if they want to create, stop.