mcp-tool-design-patternsDesigns effective MCP tools and resources following best practices including clear descriptions, bounded inputs/outputs, proper annotations (readOnlyHint, destructiveHint, idempotentHint), hierarchical resource templates, progressive discovery patterns, and avoiding anti-patterns like tool bloat, vague contracts, and unbounded responses.
Independent GitHub snapshot · Automated classification · Original documentation governs
Designs effective Model Context Protocol (MCP) tools and resources that enable AI models to interact with external systems reliably and safely.
Use this skill when:
Avoid this skill for:
mcp-client-integration instead)mcp-server-fastmcp-python instead)Every MCP tool is a callable unit of work with:
get_stuff, use fetch-customer-invoice)Resources expose data that can be accessed via URIs:
dns://api.example.com/users/{id}/settingstext/plain, application/json, text/html)Does it accept input and perform an action?
→ Tool (call `search-users`, `send-email`, `create-invoice`)
Does it represent structured data accessible via a URI?
→ Resource (access `dns://api.example.com/users/{id}`)
Is it mostly discovery (listing possibilities)?
→ Resource template (let client explore `dns://api.example.com/users`)
Is it a long-running operation?
→ Tool (tools can include status polling hints)
Should the model explore it progressively?
→ Resource + Resource Template (start with core tools, add depth via templates)
Start with 5–10 core tools. Use resources and templates to enable the model to discover additional functionality as needed.
Why? AI models perform better with focused tool sets. Too many tools → lower accuracy and higher latency.
Core Tools (5–10)
↓
Resource Templates
↓
(Model explores templates as needed)
Core Tools:
search-customers — Find customers by name or IDfetch-customer-details — Get full profile for a specific customercreate-invoice — Generate an invoicesend-email — Send notification emailsResource Templates:
dns://crm.example.com/customers — List all customers (auto-discovery)dns://crm.example.com/customers/{customer_id} — Specific customer datadns://crm.example.com/customers/{customer_id}/invoices — Customer's invoicesdns://crm.example.com/customers/{customer_id}/settings — Customer preferencesModel Interaction:
1. Model calls search-customers
2. Gets customer ID from result
3. Model discovers resource template: dns://crm.example.com/customers/{customer_id}/invoices
4. Model reads invoices via resource (no additional tool call needed)
Organize resources using DNS-like hierarchies to reflect the data model:
dns://api.example.com/
/users/{id}/
/settings
/notifications
/billing/
/invoices/{invoice_id}
/payments/{payment_id}
/teams/{team_id}/
/members
/projects/{project_id}
/issues/{issue_id}
Benefits:
/users/{id}/settings clearly belongs to a userNever return unbounded arrays. Always paginate and limit sizes.
from pydantic import BaseModel, Field
from typing import List, Optional
class PaginatedResponse(BaseModel):
"""Paginated results with cursor for next batch."""
items: List[dict] = Field(..., max_items=100)
next_cursor: Optional[str] = Field(None, description="Cursor for next page")
has_more: bool = Field(False, description="Whether more results exist")
from pydantic import BaseModel, Field
from typing import Optional
class ListCustomersInput(BaseModel):
"""List customers with pagination."""
limit: int = Field(10, ge=1, le=100, description="Max results per page")
cursor: Optional[str] = Field(None, description="Pagination cursor from previous response")
filter_status: Optional[str] = Field(None, description="Filter by status: active, inactive, trial")
class ListCustomersOutput(BaseModel):
"""Paginated customer list."""
customers: List[dict] = Field(..., description="Up to 'limit' customers")
next_cursor: Optional[str] = Field(None, description="Pass to next call for more results")
total_available: int = Field(..., description="Approximate total count")
async def list_customers(input: ListCustomersInput) -> ListCustomersOutput:
"""
List customers with optional filtering and pagination.
Always limits results to prevent response bloat.
Use cursor for pagination, not offset (more efficient).
"""
# Enforce max limit even if client requests more
safe_limit = min(input.limit, 100)
# Fetch one extra to detect if more results exist
results = await db.query(
"SELECT * FROM customers WHERE status = ?",
input.filter_status or "active",
limit=safe_limit + 1,
offset_cursor=input.cursor
)
has_more = len(results) > safe_limit
items = results[:safe_limit]
next_cursor = None
if has_more:
next_cursor = items[-1]['id'] # Use last item's ID as cursor
return ListCustomersOutput(
customers=items,
next_cursor=next_cursor,
total_available=await db.count("SELECT COUNT(*) FROM customers")
)
Use Pydantic to enforce constraints at the boundary. Never accept open-ended dicts.
# ❌ NEVER DO THIS
class SearchInput(BaseModel):
filters: dict # Anything goes — model doesn't know constraints
options: dict # Unbounded — server must validate everything
# Problems:
# - Model can pass invalid filters
# - Server has to guess what's allowed
# - No IDE autocomplete or documentation
from pydantic import BaseModel, Field
from enum import Enum
class CustomerStatus(str, Enum):
ACTIVE = "active"
INACTIVE = "inactive"
TRIAL = "trial"
class SearchCustomersInput(BaseModel):
"""Search and filter customers."""
name: Optional[str] = Field(
None,
min_length=2,
max_length=100,
description="Customer name to search for (partial match OK)"
)
status: CustomerStatus = Field(
CustomerStatus.ACTIVE,
description="Filter by account status"
)
country_code: Optional[str] = Field(
None,
regex="^[A-Z]{2}quot;,
description="2-letter ISO country code (US, UK, FR, etc)"
)
limit: int = Field(
10,
ge=1,
le=100,
description="Results per page (1-100)"
)
async def search_customers(input: SearchCustomersInput) -> List[dict]:
"""
Search customers with strict, validated filters.
Benefits:
- Model knows exactly what's allowed
- Constraints enforced before DB call
- Clear error messages if invalid
"""
# All input is already validated by Pydantic
# No defensive checks needed
results = await db.search_customers(
name=input.name,
status=input.status,
country=input.country_code,
limit=input.limit
)
return results
Use annotations to communicate tool behavior to the model:
Indicates a tool doesn't mutate server state.
from mcp.server.models import Tool
read_only_tool = Tool(
name="fetch-customer-profile",
description="Retrieve customer profile information",
inputSchema={...},
readOnlyHint=True # ← Tells model this is safe to call multiple times
)
When to use:
Effect: Models can call these freely without worrying about side effects.
Indicates a tool makes irreversible changes.
destroy_tool = Tool(
name="delete-customer-account",
description="Permanently delete a customer account and all associated data",
inputSchema={...},
destructiveHint=True # ← Tells model this requires careful reasoning
)
When to use:
Effect: Models treat these with extra caution, may ask for confirmation.
Indicates a tool is safe to retry.
idempotent_tool = Tool(
name="create-invoice",
description="Create an invoice. Safe to retry with same inputs.",
inputSchema={...},
idempotentHint=True # ← Tells model retries are safe
)
When to use:
Example Implementation:
async def create_invoice(input: CreateInvoiceInput) -> CreateInvoiceOutput:
"""
Create or fetch an invoice.
Idempotent: calling twice with same input returns same invoice_id.
Model can safely retry on transient errors.
"""
# Check if invoice already exists
existing = await db.query(
"SELECT id FROM invoices WHERE customer_id = ? AND reference_id = ?",
input.customer_id,
input.reference_id
)
if existing:
return CreateInvoiceOutput(invoice_id=existing[0]['id'], created=False)
# Create new invoice
new_id = await db.insert("invoices", {...})
return CreateInvoiceOutput(invoice_id=new_id, created=True)
Indicates a tool or resource supports unbounded discovery.
# Use for resource templates that can explore many possibilities
list_resource = ResourceTemplate(
uriTemplate="dns://api.example.com/items",
description="List all items. Supports dynamic filtering.",
mimeType="application/json",
openWorldHint=True # ← Model can explore unknown items dynamically
)
When to use:
Returns complete results without requiring previous context.
# ✅ GOOD: Stateless, self-contained
class FetchInvoiceInput(BaseModel):
invoice_id: str
class FetchInvoiceOutput(BaseModel):
id: str
customer_id: str
total: float
status: str
items: List[dict]
async def fetch_invoice(input: FetchInvoiceInput) -> FetchInvoiceOutput:
"""Fetch full invoice details. Works regardless of call history."""
return await db.fetch_invoice(input.invoice_id)
Advantages:
Maintains context from previous calls (conversational flow).
# ⚠️ ONLY if necessary: Stateful, context-dependent
class UpdateInvoiceInput(BaseModel):
invoice_id: str = None # Optional if using context
field: str # Which field to update
value: str # New value
async def update_invoice(input: UpdateInvoiceInput, context: Dict) -> dict:
"""Update invoice. Depends on 'current_invoice' in context."""
invoice_id = input.invoice_id or context.get('current_invoice')
if not invoice_id:
raise ValueError("No current invoice in context")
# Update...
When Stateful is OK:
Better Alternative: Use tool parameters instead of context.
Problem: Having 20+ tools in a single server
# ❌ BAD: Too many tools
tools = [
"get_user",
"get_users",
"search_users",
"create_user",
"update_user",
"update_user_profile",
"update_user_settings",
"delete_user",
"ban_user",
"get_user_invoices",
"get_user_payments",
# ... 10 more ...
]
# Model gets confused about which tool to use
# Token usage explodes with tool descriptions
# Response time suffers
Solution: Use Progressive Discovery
# ✅ GOOD: Core tools only (5–10)
tools = [
"search_users", # Find users
"fetch_user_details", # Get full profile
"create_user", # Create new user
"update_user", # Update user (generic)
]
# Add depth via resources
resources = [
"dns://api.example.com/users/{id}", # User details
"dns://api.example.com/users/{id}/invoices", # Invoices
"dns://api.example.com/users/{id}/payments", # Payments
"dns://api.example.com/users/{id}/settings", # Settings
]
# Model can discover and navigate the hierarchy
Impact:
Problem: Unclear tool purposes
# ❌ BAD: Ambiguous descriptions
Tool(
name="get_data",
description="Get data from the system" # What data? Which system?
)
Tool(
name="process",
description="Process something" # Process what? How?
)
Tool(
name="search",
description="Search" # Search where? What fields?
)
Solution: Specific, Actionable Descriptions
# ✅ GOOD: Clear intent and usage
Tool(
name="fetch_customer_invoices",
description="Retrieve all invoices for a specific customer, optionally filtered by date range and status"
)
Tool(
name="create_invoice_from_order",
description="Generate an invoice from an existing order. Links the invoice to the order and sends payment notification"
)
Tool(
name="search_customers_by_email",
description="Search customer database by email address. Returns up to 10 matching customers"
)
Impact:
Problem: Returning unlimited results
# ❌ BAD: No size limit
class SearchInput(BaseModel):
query: str
class SearchOutput(BaseModel):
results: List[dict] # Could be millions of items!
async def search(input: SearchInput) -> SearchOutput:
"""Search without pagination — response could be massive."""
all_results = await db.query("SELECT * WHERE ...")
return SearchOutput(results=all_results) # Disaster!
Solution: Always Paginate
# ✅ GOOD: Bounded, paginated responses
class SearchInput(BaseModel):
query: str
limit: int = Field(50, ge=1, le=100)
cursor: Optional[str] = None
class SearchOutput(BaseModel):
results: List[dict] = Field(..., max_items=100)
next_cursor: Optional[str]
total_available: int
async def search(input: SearchInput) -> SearchOutput:
"""Search with pagination — bounded response size."""
safe_limit = min(input.limit, 100)
results = await db.query(
"SELECT * WHERE ... LIMIT ?",
safe_limit + 1,
cursor=input.cursor
)
has_more = len(results) > safe_limit
return SearchOutput(
results=results[:safe_limit],
next_cursor=results[-1]['id'] if has_more else None,
total_available=total_count
)
Impact:
Problem: Explosion of discovery options
# ❌ BAD: 30+ resource templates → discovery chaos
templates = [
"dns://api.example.com/users",
"dns://api.example.com/users/{id}",
"dns://api.example.com/users/{id}/profile",
"dns://api.example.com/users/{id}/profile/name", # Too granular
"dns://api.example.com/users/{id}/profile/email",
"dns://api.example.com/users/{id}/profile/phone",
# ... many more micro-templates ...
]
# Model gets lost trying to navigate
Solution: Organize by Natural Hierarchy
# ✅ GOOD: Grouped, hierarchical templates
templates = [
"dns://api.example.com/users", # List all
"dns://api.example.com/users/{id}", # User details
"dns://api.example.com/users/{id}/invoices", # Related data
"dns://api.example.com/users/{id}/settings", # Configuration
]
# Client fetches /users/{id} which includes profile info
# No need for micro-templates
Impact:
get_data or processWhen designing MCP tools and resources, your output must include:
| Skill | Purpose |
|---|---|
mcp-server-fastmcp-python | Implement MCP server with FastMCP framework |
mcp-client-integration | Integrate MCP clients to call tools and read resources |