MCP tool description: what to write and how long it can be

An MCP tool description is the free-text description field on each tool a server lists. The MCP schema calls it a human-readable description that clients can use to improve the model's understanding of available tools, like a hint to the model. The spec sets no length limit for it, only for tool names (1–128 characters), but clients can: Claude Code truncates each tool description at 2,048 characters by default.

The rules come from the MCP 2025-11-25 tools page and schema reference, Claude Code's MCP docs, Anthropic's Define tools and tool use pages, OpenAI's function calling guide, and the Copilot CLI command reference, all read on 2026-09-28. The worked example is Sume's hosted MCP server, from its current code; Sume's basics page says hosted MCP still works but is not the primary path today.

Where does the description go in an MCP tool?

Next to name, title, and inputSchema in each tool that tools/list returns. The schema marks description optional. Parameters get their own description inside inputSchema, as in the spec's weather tool, trimmed:

{
  "name": "get_weather",
  "title": "Weather Information Provider",
  "description": "Get current weather information for a location",
  "inputSchema": {
    "type": "object",
    "properties": {
      "location": { "type": "string", "description": "City name or zip code" }
    },
    "required": ["location"]
  }
}

How long can an MCP tool description be?

As long as you like, as far as the spec goes. The practical limits come from clients and from token cost:

What should an MCP tool description say?

The MCP spec doesn't prescribe the contents; it says tools are model-controlled, so the model discovers and invokes them from context and the user's prompts. Model vendors do give guidance for their own tool formats, and it lines up:

• Anthropic calls detailed descriptions by far the most important factor in tool performance. Cover what the tool does, when to use it and when not to, what each parameter means and how it affects the tool's behavior, and important caveats or limitations. Aim for at least 3–4 sentences per tool, more for complex tools.
• OpenAI says to explicitly describe the purpose of the function and each parameter, including its format, and what the output represents. It suggests examples and edge cases, but notes that examples may hurt performance for reasoning models.
• Claude Code's advice for MCP server authors: keep descriptions concise, and put critical details near the start, since anything past the limit is cut.

What does a production tool description look like?

Sume's hosted MCP server is one example. In current code, a source comment sets the template for the descriptions of its hot create tools: Purpose; When to use and when not; Defaults; Required payload, which generate_image labels Input shape; Aliases and forbidden keys; Safety; Next step; and an optional Skill line. The same comment caps them at about 0.5–2 KB, with longer guidance kept in skills, and tests hold each one between 512 and 2,048 bytes.

MCP tool annotations covers the hints that sit next to a description. Here is part of generate_image's description, trimmed, with line breaks added:

Purpose: Generate a still via POST /v1/images. The default image tool.
When to use: any still, … When not: B-roll (generate_video); BGM (music_create);
  cutout (rmbg_create); enlarging a still (image_upscale_create).
Input shape: { idempotency_key, payload } — every generation field goes INSIDE
  payload. payload.prompt required; …
Safety: paid create bills via wallet/admission. Require idempotency_key.
  Optional dry_run=true for cost; optional max_spend_usd when provided. …
Next step: async create answers in ms — fan out the whole wave, then one
  jobs_wait on job_ids … → jobs_result; no per-still wait mid-wave.