AI & MCP
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.
In sintesi
- Lo schema è un contratto che il modello legge prima di chiamare: tre campi obbligatori, non dieci.
- I vincoli numerici e gli array tipizzati sostituiscono la validazione scritta a mano.
- Le descrizioni sono prompt: vanno corte, con un esempio tra virgolette e senza istruzioni nascoste.
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.
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
| Tool | Proprietà | Obbligatorie | Array |
|---|---|---|---|
| search_components | 4 | 1 | 0 |
| get_component | 2 | 2 | 0 |
| search_blocks | 3 | 1 | 0 |
| get_block | 2 | 2 | 0 |
| get_design_system | 1 | 0 | 0 |
| list_design_systems | 0 | 0 | 0 |
| compose_page | 5 | 1 | 1 |
| list_categories | 0 | 0 | 0 |
| get_page | 1 | 1 | 0 |
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.
Domande frequenti
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.