Best Practices

The most common source of AI tool problems is not a bug — it’s a vague description, a poorly structured schema, or a misconfigured parameter mapping. This guide covers the patterns that consistently produce accurate, reliable AI tool use.

1. Write Descriptions That Actually Work

Your tool description is the single most important thing you configure. The AI reads it to decide:

Whether to call this tool at all
Which tool to call when multiple options exist
What arguments to supply

Bad description:

Gets customer data

Good description:

Retrieve a single customer record by their unique customer ID. Returns name, email,
billing address, subscription plan, and account status. Use this when you need
to look up a specific customer's details. Do not use this to search by name or
email — use search_customers for that.

The good description tells the AI: what the tool returns, when to use it, and when NOT to use it. That last part — explicitly ruling out incorrect use cases — dramatically reduces wrong tool calls. Rules for good descriptions:

Start with a verb: Retrieve, Create, Search, Send, Update, Delete
State what the tool returns (not just what it does)
Include when to use it vs when to use a similar tool
Keep it under 200 words — models truncate very long descriptions
Avoid vague words like “handles”, “manages”, “processes”

2. Name Tools in snake_case with a Verb

Tool names follow a verb_noun or verb_noun_noun pattern. The AI’s reasoning will often include the tool name, so make it readable:

Good	Bad
`get_customer`	`customer`
`create_invoice`	`newInvoice`
`search_products`	`products_search`
`send_email`	`email`
`list_open_orders`	`orders`
`update_subscription_plan`	`editSub`

Use the same verb convention consistently across your server: if you use get_ for retrieval, don’t also use fetch_ or retrieve_ — pick one.

3. Design Schemas for the AI, Not the API

Your input schema describes what the AI should provide — not necessarily what the underlying API needs. Map the gap in parameter mappings, not in the schema. Don’t expose internal IDs as required inputs when names work better:

// Bad — AI has to somehow know the numeric category ID
{ "category_id": { "type": "integer" } }

// Good — AI can use the name, you map it server-side
{ "category": { "type": "string", "description": "Product category name (e.g., 'electronics', 'clothing')" } }

Use enums when there are fixed choices:

{
  "status": {
    "type": "string",
    "enum": ["pending", "active", "cancelled", "refunded"],
    "description": "Filter orders by this status"
  }
}

Mark only truly required fields as required. Optional parameters with defaults should be optional — the AI will omit them when not needed. Add description to every parameter. The AI uses these to understand what values to pass:

{
  "limit": {
    "type": "integer",
    "description": "Number of results to return. Default is 20, maximum is 100.",
    "default": 20
  }
}

4. One Tool = One Action

Keep tools focused. A tool that does six different things depending on which parameters you pass produces inconsistent AI behavior.

Don’t do this	Do this instead
`manage_customer` (with `action: create/update/delete`)	`create_customer`, `update_customer`, `delete_customer`
`order_tool` (fetches or updates depending on params)	`get_order`, `update_order_status`

Focused tools have clearer descriptions and are called more accurately.

5. Use Caching for Read-Only Data

Enable Cache TTL on tools that return data that doesn’t change frequently. This is one of the easiest performance wins:

Tool type	Suggested TTL
Product catalog	300–900 seconds
Reference / lookup data	600–3600 seconds
User-specific data	0 (no cache)
Real-time status	0 (no cache)
Documentation content	3600+ seconds

Cached responses are served from WordPress object cache and don’t count against your upstream API rate limits.

6. Set Appropriate Timeouts and Retries

Timeout — default is 30 seconds. Adjust based on your API:

Fast internal APIs: 5–10 seconds
Slow report generation, file exports: 60–120 seconds
Third-party APIs (Stripe, GitHub, etc.): 15–30 seconds

Retry Count — only enable retries for idempotent operations (GET requests, read-only tools). Never set retries > 0 on tools that create or delete data — a retry after a network timeout could create duplicates.

get_order          → retry: 3, timeout: 15s  ✓ safe to retry
create_order       → retry: 0, timeout: 30s  ✗ don't retry writes
search_products    → retry: 2, timeout: 10s  ✓ safe to retry
send_email         → retry: 0, timeout: 20s  ✗ don't retry sends

7. Organize Servers by Domain and Access Level

One server per logical group — not one server for everything:

stripe-payments       (finance team only — high-value credentials)
github-tools          (engineering team)
customer-support      (support team — read-only tools only)
internal-admin        (admin team — create/update/delete tools)

Benefits:

Limit blast radius if a URL is shared accidentally
Different inbound auth credentials per team
Cleaner tools/list — the AI only sees the tools relevant to the current task
Independent rate limits per domain

8. Keep Parameter Mappings Clean

Use the right mapping type for each parameter — don’t send everything in the body:

Parameter type	Mapping
Record ID in the URL	Path (`/customers/{id}`)
Filters, pagination	Query (`?status=active&page=2`)
Data to create/update	Body (POST/PUT only)
API keys (if user-supplied)	Header

Avoid query parameters on POST requests when the API uses a request body — some APIs ignore query params on POST.

9. Test Before You Ship

Use the built-in Test panel on every tool before sharing the server URL with anyone. What to verify:

Tool returns the expected data shape
Required parameters produce an error when missing
Error responses from the API are handled gracefully
Response size is reasonable (very large responses slow AI clients)

For a full protocol-level audit, connect MCP Inspector and test every tool interactively.

10. Security Checklist

Enable inbound authentication for production servers (not none)
Use HTTPS on your WordPress site — required for credentials in transit
Store API keys only in Custom Headers — never embed them in endpoint URLs where they appear in logs
Set a rate limit appropriate for your upstream API’s own limits
Configure webhooks to alert on tool.error events so you catch auth failures fast
Rotate test credentials independently from production keys
Review call logs periodically for unexpected clients or unusual patterns

Getting Started

Concepts

Guides

Use Cases

Best Practices

1. Write Descriptions That Actually Work

2. Name Tools in snake_case with a Verb

3. Design Schemas for the AI, Not the API

4. One Tool = One Action

5. Use Caching for Read-Only Data

6. Set Appropriate Timeouts and Retries

7. Organize Servers by Domain and Access Level

8. Keep Parameter Mappings Clean

9. Test Before You Ship

10. Security Checklist

​1. Write Descriptions That Actually Work

​2. Name Tools in snake_case with a Verb

​3. Design Schemas for the AI, Not the API

​4. One Tool = One Action

​5. Use Caching for Read-Only Data

​6. Set Appropriate Timeouts and Retries

​7. Organize Servers by Domain and Access Level

​8. Keep Parameter Mappings Clean

​9. Test Before You Ship

​10. Security Checklist

1. Write Descriptions That Actually Work

2. Name Tools in snake_case with a Verb

3. Design Schemas for the AI, Not the API

4. One Tool = One Action

5. Use Caching for Read-Only Data

6. Set Appropriate Timeouts and Retries

7. Organize Servers by Domain and Access Level

8. Keep Parameter Mappings Clean

9. Test Before You Ship

10. Security Checklist