# 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.

> Page: https://ui.eneawork.it/blog/mcp-tool-design
> Markdown: https://ui.eneawork.it/blog/mcp-tool-design.md

*2026-11-01*

Un tool MCP si progetta come una funzione pubblica: un nome che dice il verbo, uno schema che rifiuta gli argomenti ambigui e un output che il modello può citare senza riscaricare la pagina. Il resto è contorno.

Il server EneUI in backend/mcp.js espone 9 strumenti in sola lettura, contati il 1 novembre 2026. search_components accetta fino a 30 risultati (default 10) e compose_page fino a 20; ogni chiamata scrive una riga di telemetria mcp_call con nome del tool e piano, verificato il 1 novembre 2026. Il catalogo dietro conta 111.985 componenti, 1.556 blocchi e 12.808 icone da 1.472 librerie, letti da /api/stats il 1 novembre 2026. Il dataset docs/keyword-data.json non contiene una domanda Stack Overflow su questo tema: i 16 tag campionati il 31 ottobre 2026 non includono un tag MCP.

## Il nome è l'interfaccia

search_components cerca, get_component legge un record, list_categories elenca. Un modello sceglie in base al nome prima di leggere lo schema, quindi un nome generico come query perde contro uno che dichiara oggetto e verbo.

## Uno schema stretto

In search_components solo query è obbligatoria: le altre proprietà hanno una descrizione e un esempio, come pricing table o modal with focus trap. Il limite è un intero tra 1 e 30, quindi il server non deve gestire valori impossibili.

## Una chiamata reale

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}}}'

La risposta comincia con il numero di corrispondenze e quante ne mostra. Ogni riga porta nome, libreria, licenza, URL della pagina e comando di installazione: quattro dati che il modello può incollare in una risposta senza inventare nulla.

## Fallire in modo utile

Quando non c'è nulla, il testo dice No components matched e suggerisce list_categories. Quando l'identificatore è sbagliato, dice di usare prima search_components. Un errore che indica il passo successivo vale più di uno stack trace.

## Quanti strumenti servono

Nove bastano per un catalogo: ricerca, lettura, elenco, composizione e pagina. list_design_systems e list_categories hanno uno schema vuoto perché non prendono argomenti. Ogni strumento in più occupa contesto in ogni richiesta, quindi conviene aggiungerne uno solo se risponde a una domanda che gli altri non coprono.

## Il catalogo

Un risultato tipico è rainbow button di Magic UI, licenza MIT e 2.130 stelle dichiarate a monte. I blocchi stanno su 1.556 sezioni e le icone su 12.808 icone; il server completo è descritto su /mcp.

## La limitazione

La descrizione di un tool è testo che finisce nel prompt, quindi è anche una superficie di iniezione: un server ostile può nascondere istruzioni in una descrizione o in un risultato. Un tool in sola lettura riduce il danno, ma il comando di installazione che restituisce viene eseguito dall'agente, e il rischio si sposta sulla shell.

## Dove continuare

Il protocollo e il trasporto sono in come costruire un server MCP e in che cos'è MCP. Per la scelta tra server pronti leggi i migliori server MCP per il frontend, e per il confronto tra copiare codice e installare un pacchetto leggi copy-paste o headless.

## FAQ

### Quanti strumenti deve esporre un server MCP?

Solo quelli che coprono domande diverse. EneUI ne espone 9 per un catalogo di 111.985 componenti: ricerca, lettura, elenco, composizione e pagina. Ogni strumento aggiuntivo consuma contesto in ogni richiesta.

### Meglio un tool generico o uno specifico?

Specifico. Un nome come search_components dice al modello cosa ottiene; un tool chiamato query lo costringe a leggere lo schema e a indovinare. La specificità riduce le chiamate sbagliate.

### Come si descrive un argomento di testo?

Con un esempio tra virgolette nella descrizione, come pricing table o modal with focus trap. Un campo libero senza esempio produce ricerche vaghe e risultati vuoti.

### Cosa deve contenere l'output di un tool?

Il dato che il modello userà: identificatore, URL e comando, più il conteggio dei risultati. EneUI restituisce anche licenza e libreria, così la risposta può citare la fonte senza una seconda chiamata.

### Un tool in sola lettura è sicuro?

Riduce il rischio, non lo elimina. Il server non scrive nulla, ma restituisce un comando di installazione che l'agente esegue: la sicurezza dipende dai permessi del client, non dal tool.