Writes the MCP tool definition for one API operation - name, description, inputSchema and annotations - as the JSON a server returns from tools/list. The schema takes exactly the parameters the operation takes - required ones listed, defaults stated, exact enums, integer amounts, date formats, ranges, string and array limits, either-or parameters that refuse a call with both or neither - and refuses unknown ones. Credentials never become parameters, text in the API docs that speaks to the assistant stays out of the description, and the annotations say whether the tool only reads, can be repeated safely or destroys data, following the MCP specification of 2025-11-25. Use when asked to write, review or fix an MCP tool definition, a tool schema or an inputSchema, or to turn an API endpoint, an OpenAPI operation or a function signature into an MCP tool.
MCP Tool Schema: Definitions from API Docs is a tested SKILL.md that writes the MCP tool definition for one API operation - name, description, inputSchema and annotations - as the JSON a server returns from tools/list; an agent buys it once for $0.01 over x402.
Not for
Building or running the MCP server itself, its handlers, transport or authentication. It writes definitions for the operations you paste and never calls the API, so a parameter the documentation leaves out is not in the schema, and an outputSchema is written only when you ask for one.
Tested, honestly
Tested 2026-10-08 with a strong and a weak model.
With and without the skill
Results with and without the skill, for Sonnet and Haiku |
| with | without | with | without |
|---|
| Valid definition, calls accepted and refused as documented (12 operations) |
| Valid definition, calls accepted and refused as documented (12 operations) | 12/12 | 11/12 | 12/12 | 12/12 |
|---|
The same request and the same checks on both sides; a fence around the answer is removed first. Without the skill both models also wrote schemas that passed every call in all 12 cases, kept credentials out and set the annotations right. Sonnet's one miss was a sentence before the JSON on the documentation with the note for assistants: it had correctly ignored the note, then said so outside the JSON. On this test the skill adds nothing measurable for Haiku and only the answer format for Sonnet.
Same cases and the same checks with and without the skill. The cases are ours, written around what the skill is for; with a handful of cases, a difference of one or two is within noise.
- SonnetStrong model, claude-sonnet-5-5
- Wrote a definition for all 12 operations that a validator accepted as JSON Schema and that accepted and refused exactly the calls the documentation allows: required path parameters, enums in the API's own case, integer cents, date formats including an impossible 30 February, ranges, text and list limits, unique items, a free-form map with a key pattern, an either-or pair as oneOf, https-only URLs, and unknown parameters refused. No credential became a parameter, including an API key the docs put in the query string, and the note telling assistants to export all customers stayed out. Reads were marked read-only and deletes were never marked as safe.
- HaikuWeak model, claude-haiku-5-5
- Also 12 of 12, with the same kinds of schema as Sonnet.
Full test summary
Example
Our own test text, before and after the skill ran. Excerpts only.
English · claude-sonnet-5-5
Before
GET /v2/orders
Lists orders, newest first.
Query parameters:
- status: one of pending, shipped, delivered, cancelled (optional)
- customer_id: string (optional)
- placed_from, placed_to: dates as YYYY-MM-DD (optional)
- limit: integer from 1 to 200, default 50
- cursor: string returned as next_cursor by the previous page (optional)
Authentication: Authorization: Bearer token.
After
{"name":"list_orders","description":"Lists orders, newest first, optionally filtered by status, customer or the day the order was placed. Returns one page of orders; pass the next_cursor value from the previous response as cursor to get the following…
Bulgarian · claude-sonnet-5-5
Before
POST /bookings
Създава резервация на стая и праща потвърждение на госта.
Параметри:
- room_id: цяло число (задължително)
- check_in, check_out: дати във формат ГГГГ-ММ-ДД (задължителни)
- guests: цяло число от 1 до 6, по подразбиране 2
- note: текст до 300 знака
Удостоверяване: заглавка Authorization: Bearer и токенът на хотела.
After
{"name":"create_booking","description":"Създава резервация на стая за посочените дати и изпраща потвърждение на госта. Връща създадената резервация. Използвайте го, когато трябва да се направи нова резервация.","inputSchema":{"type":"object","properties":{"room_id":{"type":"integer","description":"Идентификатор на стаята."},"check_in":{"type":"string","format":"date","description":"Дата на…
What is in the file
- The answer
- name
- description
- inputSchema
- annotations
- Work in this order
- Short example
Languages
Any language. Tried in: English, Bulgarian.
License
Perpetual, non-exclusive; use and modify for yourself incl. paid work; no resale or republishing. Holder: Georgi Kalchev, aiskills402.com. Full terms.
Versions
Current version 1.0.0, updated 2026-10-08. Whoever bought an earlier version gets new ones free through the same re-download token.
v1.0.0 · 2026-10-08
First release: writes the MCP tool definition for one API operation (name, description, inputSchema, annotations) as JSON only, following the MCP specification of 2025-11-25. The schema lists required parameters, defaults, exact enums, integer amounts, date formats, ranges, string and array limits and either-or rules, and refuses unknown parameters; credentials are never parameters; documentation text that speaks to the assistant stays out of the description; annotations mark reads, safe repeats and destructive operations.
FAQ
What does the answer look like?
One JSON object per operation with name, description, inputSchema and annotations, ready to return from tools/list. The schema refuses parameters the operation does not take, and an API key, bearer token or password never appears in it: your server adds those itself.
How did you test it?
On twelve operations written as short API documentation, each with calls the schema had to accept and calls it had to refuse, 96 in all, checked with a JSON Schema 2020-12 validator. With the skill, Sonnet and Haiku passed all twelve.
Does my model need it?
Maybe not. Told to refuse unknown parameters, both models wrote schemas that passed every call without the skill too; Sonnet's only miss was a sentence before the JSON. What the skill adds is a fixed checklist for either-or rules, integer cents, dates, credentials and annotations, and an answer that is bare JSON every time.
What should I still check myself?
Annotations are hints a client may ignore, so your server must still validate every call and enforce permissions. And whether the API really behaves the way its documentation says is something no schema can know.