AI & MCP

Designing an MCP tool: name, schema and citable output

An MCP tool is a public function for a model: a name that states the verb, a narrow schema and output worth citing. These are the choices that matter.

2026-11-01

Key points

The name states the verb and the return type: search, get, list, compose.
Only necessary fields are required; every free-text field carries a description with examples.
A result must be written to be cited: count, identifier, URL and command.

An MCP tool is designed like a public function: a name that states the verb, a schema that rejects ambiguous arguments and output a model can cite without fetching the page again. The rest is decoration.

The name is the interface

search_components searches, get_component reads one record, list_categories lists. A model chooses from the name before reading the schema, so a generic name such as query loses to one that states object and verb.

A narrow schema

In search_components only query is required: the other properties carry a description and an example, such as pricing table or modal with focus trap. The limit is an integer between 1 and 30, so the server never handles impossible values.

A real call

curl -s https://ui.eneawork.it/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_components","arguments":{"query":"pricing table","limit":5}}}'

The answer opens with the number of matches and how many it shows. Each row carries name, library, licence, page URL and install command: four facts a model can paste into an answer without inventing anything.

Fail usefully

When nothing matches, the text says No components matched and suggests list_categories. When the identifier is wrong, it says to call search_components first. An error that names the next step beats a stack trace.

How many tools

Nine are enough for a catalogue: search, read, list, compose and page. list_design_systems and list_categories carry an empty schema because they take no arguments. Every extra tool occupies context on every request, so add one only when it answers a question the others cannot.

The catalogue

A typical result is Magic UI rainbow button, MIT licence and 2,130 stars declared upstream. Blocks live on 1,556 sections and icons on 12,808 icons; the full server is described on /mcp.

The limitation

A tool description is text that lands in the prompt, so it is also an injection surface: a hostile server can hide instructions in a description or a result. A read-only tool limits the damage, but the install command it returns is run by the agent, and the risk moves to the shell.

Where to continue

The protocol and transport are in how to build an MCP server and in what MCP is. For the choice between ready servers read the best MCP servers for frontend work, and for the comparison between copying code and installing a package read copy-paste or headless.

Frequently asked questions

How many tools should an MCP server expose?

Only those covering different questions. EneUI exposes 9 for a catalogue of 111,985 components: search, read, list, compose and page. Every extra tool spends context on every request.

Is a generic tool better than a specific one?

Specific is better. A name such as search_components tells the model what it gets; a tool called query forces it to read the schema and guess. Specificity cuts wrong calls.

How do you describe a text argument?

With a quoted example in the description, such as pricing table or modal with focus trap. A free-text field without an example produces vague searches and empty results.

What should a tool output contain?

The fact the model will use: identifier, URL and command, plus the result count. EneUI also returns licence and library, so the answer can cite the source without a second call.

Is a read-only tool safe?

It lowers the risk without removing it. The server writes nothing, but it returns an install command the agent runs: safety depends on the client permissions, not on the tool.