Tools

Not every server needs dynamic tools. But the ones that do need a way to tell the client its cached list is stale.

Example scenario

A server that wraps a project-management API might expose different tools depending on the workspace the user is authenticated into: create_ticket, assign_ticket, and, only for admins, delete_workspace. If the user re-authenticates into a workspace with different permissions, the tool set legitimately changes mid-session.

// Server -> Client, after tools change
{"jsonrpc": "2.0", "method": "notifications/tools/list_changed"}

// Client reacts by re-fetching
{"jsonrpc": "2.0", "id": 12, "method": "tools/list"}

Preconditions for sending it

1. The server must have declared "capabilities": {"tools": {"listChanged": true}} during initialize. Sending the notification without declaring support for it is a spec violation the client isn't obligated to react to.
2. It should only fire on a genuine change, not speculatively or on a timer. Spamming this notification defeats its purpose — the client would end up re-fetching constantly for no reason — and can cause visible UI churn in hosts that refresh a tool picker on receipt.

When you don't need it at all

A server with a static tool set never needs to send this notification. That's the common case for most single-purpose servers, like a Postgres server that always exposes query and list_tables. It shouldn't declare listChanged: true for a capability it never actually uses. Declaring a capability you don't implement is arguably worse than not declaring it, since it invites a client to expect behavior that never arrives.

A tool's description isn't documentation for a human reading your code later. It's the only information the model has at inference time to decide whether and how to use the tool.

A weak vs. strong description

// Weak: vague, ambiguous, no format guidance
{"name": "get_data", "description": "Gets data.",
 "inputSchema": {"properties": {"id": {"type": "string"}}}}

// Strong: specific, states scope, gives format examples
{"name": "get_customer_order_history",
 "description": "Fetch the last 90 days of order history for a single customer. Use this when the user asks about a specific customer's past purchases. Does not include current cart contents.",
 "inputSchema": {
   "properties": {
     "customer_id": {"type": "string", "description": "Internal customer ID, format 'CUST-00000' (not an email address)"}
   },
   "required": ["customer_id"]
 }}

Principles that consistently help

• State the scope explicitly: "last 90 days," "does not include X." This stops the model from assuming broader behavior than the tool actually has.
• Disambiguate near-duplicate tools. If you have search_users and find_user, the model has no reliable way to pick between them unless the descriptions explain the difference — one takes a fuzzy query, say, the other an exact ID.
• Give format examples for anything non-obvious — IDs, date formats, enums — directly in the parameter's description, not just its type.
• Say when not to use it, if there's a common wrong-context call the model might otherwise make.

Why this is worth real design effort

Two functionally identical servers with different tool descriptions can produce very different model behavior. One calls the right tool reliably; the other picks the wrong tool or passes malformed arguments a meaningful fraction of the time. Treating tool descriptions as a first-class design artifact, not an afterthought filled in once the code works, is one of the highest-leverage things you can do when building an MCP server.

Plain-text tool results are easy to hand to a model. They're painful for a host that wants to do something programmatic with the result, not just display it.

Before: text-only result

{"content": [{"type": "text", "text": "Austin: 91F, sunny, 62% humidity"}]}

A host that wants to render a weather widget now has to parse this string. That's fragile against any wording change.

With structured output

// Tool definition declares an outputSchema
{
  "name": "get_weather",
  "inputSchema": {...},
  "outputSchema": {
    "type": "object",
    "properties": {
      "tempF": {"type": "number"},
      "condition": {"type": "string"},
      "humidityPct": {"type": "number"}
    },
    "required": ["tempF", "condition"]
  }
}

// CallToolResult returns both
{
  "content": [{"type": "text", "text": "Austin: 91F, sunny, 62% humidity"}],
  "structuredContent": {"tempF": 91, "condition": "sunny", "humidityPct": 62}
}

Why both, not just structured

The content array stays the primary channel the model reads — natural language is still what an LLM reasons over best. structuredContent is additive. It's aimed at the host application and any other non-model consumer that wants to render a chart, populate a form, or feed the value into further deterministic logic without an LLM in the loop. A server that declares outputSchema is also making a validatable promise: hosts can check structuredContent against that schema to catch a malfunctioning tool, the same way inputSchema lets a server catch malformed input.

When to bother

Add structured output when you expect non-model consumers of the result — a UI widget, a downstream automation, a host feature like data visualization. A tool whose result is only ever read by the model in prose form doesn't need it.

The arguments in a tools/call request ultimately came from an LLM's output. That output was shaped by conversation content the model read, and some of that content may be attacker-controlled: a malicious webpage, a poisoned document, a crafted email. Treat tool arguments with the same suspicion as a public API request body.

Concrete failure modes to close off

# Vulnerable: argument interpolated straight into a shell command
def run_lookup(hostname: str):
    os.system(f"nslookup {hostname}")   # hostname="; rm -rf / #" is catastrophic

# Vulnerable: argument interpolated straight into SQL
def get_user(user_id: str):
    db.execute(f"SELECT * FROM users WHERE id = {user_id}")  # classic SQL injection

# Safer: parameterized query, no shell string interpolation
def run_lookup(hostname: str):
    if not HOSTNAME_RE.match(hostname):
        raise ToolExecutionError("Invalid hostname format")
    return subprocess.run(["nslookup", hostname], capture_output=True)

def get_user(user_id: str):
    return db.execute("SELECT * FROM users WHERE id = ?", (user_id,))

A checklist for every tool handler

• Schema-validate first. Reject anything that doesn't match inputSchema before touching business logic.
• Never trust an argument as an authorization decision by itself. If a tool takes account_id, still check server-side that the authenticated caller actually has access to that account. Don't let the model's argument alone decide whose data gets returned or modified.
• Avoid raw string interpolation into shells, SQL, or file paths. Use parameterized APIs, allow-lists of permitted values, and path canonicalization for anything path-like — resolve .. traversal, restrict to a known root directory.
• Bound the blast radius. Rate-limit calls, cap result sizes (a "list all records" tool shouldn't dump an entire multi-million-row table in one call), and set execution timeouts on anything that shells out or hits a slow external system.
• Log tool invocations (arguments and results, redacting secrets) so a suspicious pattern of calls is auditable after the fact.
• Treat the handler as a public-facing API endpoint at all times, even though the "client" calling it is an LLM rather than a browser.

It's tempting to wrap an entire REST API 1:1 into MCP tools — one tool per endpoint. In practice this backfires quickly.

Why more tools isn't free

Every tool's full definition (name, description, JSON Schema) is included in the model's context on essentially every turn where tools are available, whether or not that turn uses them. A server exposing 80 near-identical CRUD tools:

• Burns a meaningful chunk of the context window before the conversation even starts.
• Makes tool selection harder for the model. More semantically overlapping options increase the chance of picking a plausible-but-wrong tool.
• Makes maintaining good, differentiated descriptions much harder at scale. 80 descriptions are far more likely to blur together than 8.

Practical mitigations

• Consolidate around user intent, not API endpoints. Instead of create_issue, create_issue_with_labels, create_issue_in_project, expose one create_issue tool with optional parameters covering all three cases.
• Prefer a small number of general tools over many narrow ones for broad domains. A search(query, filters) plus get_by_id(id) pair often covers what would otherwise be a dozen single-purpose lookup tools.
• Scope servers narrowly by task, and let the host/user choose which servers are active for a given session, rather than one server trying to expose everything the API can do.
• Use tools/list pagination (a cursor in the request, nextCursor in the response) for genuinely large catalogs, so a client isn't forced to load the entire set into one tool-selection prompt.

The rule of thumb

If you can't write a distinct, non-overlapping one-sentence description for every tool on your server, that's usually a sign some of them should be merged into a single, more flexible tool with optional parameters instead.