How to Write MCP Tool Descriptions That AI Agents Actually Understand

Connecting an AI assistant to your API is the easy part. Getting it to pick the right tool, with the right inputs, at the right moment is where most MCP servers fall short. The difference is almost never the code. It is the words: tool names, descriptions and instructions.

An assistant has no intuition about your product. It reads your tool list the way a new hire reads a menu in a language they half know. If the wording is vague, it guesses. If two tools sound alike, it picks the wrong one.

This guide shows what to write, with before and after examples, and where to set each piece in DocStar.

Every time a user asks for something, the assistant looks at the tools you expose and decides which one fits. It only has your names and descriptions to go on. Three things go wrong when they are weak:

• Wrong tool. "Get data" and "Fetch records" look identical, so the assistant flips a coin.

• Wrong inputs. A field called amt with no unit gets filled with dollars when your API expects cents.

• Missed tool. A useful endpoint is never called because its description says what it is, not when to use it.

The same lesson shows up in agent research: tool schemas that agents can read clearly get called correctly more often. We covered that in Tool-call accuracy is a docs problem too.

Users say "create an invoice", not "POST /v2/invoice-resource". Name your tools the same way.

Use a verb first, then the thing. Keep names short and consistent. In DocStar, endpoint tool names can be up to 45 characters.

Most descriptions restate the name: "Creates an invoice." That tells the assistant nothing it did not already know. Add the situation, and the order of calls.

Before: Creates an invoice.

After: Creates a draft invoice for an existing customer. Use when the user wants to bill a customer. Call list_customers first to get the customer_id. The invoice is not sent until send_invoice is called.

That second version answers three questions the assistant would otherwise guess at: when to use it, what it needs first and what happens next.

For each field, write what it means, the unit or format, and whether it is optional.

• amount: "Amount in cents, as an integer. 1000 means $10.00."

• due_date: "ISO 8601 date, for example 2026-12-31. Optional. Defaults to 30 days from today."

• currency: "Three-letter ISO code, such as USD or EUR."

Also include one full example request body. A complete example removes more ambiguity than a paragraph of prose.

Assistants should feel free to look things up and careful about changing things. Make that distinction explicit:

• Mark safe lookups as read-only so assistants can call them without asking.

• Mark anything that deletes or overwrites as destructive, so assistants confirm first.

• Mark calls that are safe to repeat as idempotent.

DocStar's MCP server already splits reads and writes into separate tools, and lets you set these safety hints on your named tools.

By default, an assistant reaches your API through a general "call any API" tool: it searches your docs, finds the endpoint and calls it. That works, but it takes more steps. For the 5 to 10 actions users ask for most, give each a dedicated, named tool. DocStar lets you turn up to 20 published endpoints into named tools. Everything else stays available through the general tool.

Each DocStar MCP server ships with a skill: a short quickstart the assistant reads before it uses your API. DocStar generates one from your docs, and you can replace it with your own. A good skill covers:

1. What your API is for, in two or three sentences.

2. The usual order of calls, for example "list projects, then create a task".

3. Rules and limits, such as required fields and rate limits.

4. Which endpoints are safe to call freely and which to confirm.

For rules that apply to every call, add short instructions, such as "Always ask for the account ID before creating anything."

Before you share your MCP URL, check that:

• Tool names start with a verb and match how users talk.

• Each description says when to use the tool and what to call first.

• Every field has a meaning, a unit or format, and an optional or required note.

• Read tools are marked read-only and destructive tools are flagged.

• Your top actions have their own tools.

• The skill explains the main workflows in plain language.

Connect Claude, ChatGPT or Cursor to your MCP URL and try the requests your customers would actually make. Watch which tool gets picked. Every wrong pick points to a description that needs rewriting.

If you are just getting started, read How to Connect Your API to ChatGPT, Claude and Cursor, then OpenAPI to MCP Server to generate the server itself. For the full setup, see the MCP server guide.

Ready to try it? Start with DocStar and give your API an MCP server your users' assistants can actually use.