# Lo schema JSON di un tool per agenti: campi, required e limiti

Uno schema di tool è type object, properties e required: il modello legge quella forma, non il codice. Ecco come tenerla stretta e citabile.

> Pagina: https://ui.eneawork.it/blog/agent-tool-schema-json
> Markdown: https://ui.eneawork.it/blog/agent-tool-schema-json.md

*2026-11-01*

Lo schema JSON di un tool per agenti è un oggetto con type: object, una mappa di properties e la lista required: il modello legge quella forma, non il codice del server. Un campo libero senza descrizione è un campo che il modello riempirà a caso.

I 9 tool in backend/mcp.js, letti il 1 novembre 2026, espongono 18 proprietà in totale, di cui 8 obbligatorie, un solo array tipizzato e nessun enum. La stessa lista serializzata in JSON occupa 3.621 byte; l'endpoint EneUI ha risposto a tools/list con 3.655 byte in 218 ms, misurati il 1 novembre 2026. La pagina Tools della revisione MCP 2025-06-18, letta su modelcontextprotocol.io lo stesso giorno, descrive inputSchema come JSON Schema, rende outputSchema opzionale con structuredContent e chiede ai server di validare gli input. Il catalogo dietro conta 111.985 componenti, 1.556 blocchi e 12.808 icone da 1.472 librerie, letti da /api/stats.

## La forma minima

{ "name": "get_component", "inputSchema": { "type": "object", "properties": { "library": { "type": "string" }, "name": { "type": "string" } }, "required": ["library", "name"] } }

Due stringhe, entrambe obbligatorie, nessun campo opzionale. Il server rifiuta una chiamata senza library e suggerisce search_components, perché il modello di solito non conosce l'identificativo esatto. Lo schema dichiara cosa serve, il messaggio d'errore dichiara cosa fare dopo.

## Obbligatorio è una decisione di prodotto

Su 18 proprietà totali, EneUI ne segna 8 come obbligatorie: query per le due ricerche, library e name per la lettura di un componente, source e name per un blocco, intent per la composizione, path per una pagina. Ogni campo obbligatorio in più è una chiamata che il modello può sbagliare, quindi la regola è: obbligatorio solo ciò senza cui il tool non ha senso.

## Vincoli al posto della logica

Il parametro limit di search_components è un intero con minimum: 1 e maximum: 30; compose_page si ferma a 20. Il campo sections è un array con items di tipo stringa. Con questi tre vincoli il server non deve gestire numeri negativi, testi dove serve una lista o valori fuori scala: lo schema li ferma prima.

## La descrizione è parte dello schema

Le nove descrizioni misurate vanno da 61 a 230 caratteri. Quella di search_components dice cosa restituisce e cita esempi tra virgolette, come pricing table o modal with focus trap. Un esempio concreto vale più di un aggettivo: il modello copia il formato dell'esempio quando riempie il campo libero.

## Nessun enum, e non è pigrizia

Un enum sarebbe utile per pageType, che accetta landing, pricing, dashboard, auth, ecommerce e blog. Oggi è una stringa con la lista nella descrizione, perché la lista cambia quando il catalogo cambia e un enum vecchio rifiuterebbe un valore nuovo. La scelta ha un costo: il modello può inventare una categoria che non esiste.

## Input e output sono due contratti

La revisione 2025-06-18 permette anche outputSchema, con il risultato strutturato in structuredContent. EneUI non lo usa: restituisce testo Markdown con conteggio, nome, libreria, licenza, URL e comando di installazione. Il vantaggio è che il modello può citarlo così com'è; il costo è che nessun client valida la forma del risultato.

## La limitazione

JSON Schema valida la forma, non il significato. Non può dire che una libreria deve esistere nel catalogo, che name va cercato prima con search_components o che un URL deve rispondere 200. Quelle regole restano nella descrizione e nel messaggio d'errore, cioè in testo che il modello legge come contenuto non fidato.

## Dove continuare

La scelta di nome e output è in progettare un tool MCP, il trasporto e il montaggio del server in un server MCP con l'SDK Node, il protocollo in che cos'è MCP. Il catalogo dietro gli esempi è in 111.985 componenti e 1.556 blocchi; un record con licenza MIT dichiarata a monte è rainbow button di Magic UI.

## FAQ

### Quale dialetto di JSON Schema devo usare?

La pagina Tools della revisione 2025-06-18 non impone un dialetto. Resta sul sottoinsieme comune a tutti i client: type, properties, required, items, minimum, maximum. Ogni parola in più è compatibilità che perdi.

### Tutti i campi devono essere obbligatori?

No, solo quelli senza cui il tool non ha senso. EneUI segna 8 proprietà obbligatorie su 18: un campo obbligatorio in più è una chiamata che il modello può sbagliare, e un errore di validazione costa un passaggio intero.

### Meglio un enum o una stringa libera?

Un enum quando la lista è stabile e corta, come i sei valori di pageType. Una stringa con la lista nella descrizione quando i valori cambiano con il catalogo, accettando che il modello possa inventarne uno.

### Quanto deve essere lunga la descrizione di un campo?

Una o due frasi con un esempio tra virgolette: le descrizioni dei tool EneUI misurano da 61 a 230 caratteri. Oltre, il testo occupa contesto a ogni richiesta senza cambiare la scelta del modello.

### Serve un outputSchema?

Serve quando un client deve validare o elaborare il risultato. EneUI dichiara solo l'input e restituisce Markdown, perché il consumatore è un modello che cita il testo. Con outputSchema devi anche restituire structuredContent conforme, altrimenti il contratto è rotto.