{"slug":"mcp-tool-schema","name":"MCP Tool Schema: Definitions from API Docs","version":"1.0.0","updated_at":"2026-10-08T07:53:40.250Z","use_when":"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.","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.","languages":["any"],"tags":["mcp","json-schema","tool-definition","api","openapi","agent-tools"],"category":"agents","category_url":"https://aiskills402.com/categories/agents","keywords":["MCP tool definition","tool schema","OpenAPI operation"],"faq":[{"q":"What does the answer look like?","a":"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."},{"q":"How did you test it?","a":"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."},{"q":"Does my model need it?","a":"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."},{"q":"What should I still check myself?","a":"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."}],"examples":[{"lang":"en","model":"claude-sonnet-5-5","input_excerpt":"GET /v2/orders\nLists orders, newest first.\nQuery parameters:\n- status: one of pending, shipped, delivered, cancelled (optional)\n- customer_id: string (optional)\n- placed_from, placed_to: dates as YYYY-MM-DD (optional)\n- limit: integer from 1 to 200, default 50\n- cursor: string returned as next_cursor by the previous page (optional)\nAuthentication: Authorization: Bearer token.","output_excerpt":"{\"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…"},{"lang":"bg","model":"claude-sonnet-5-5","input_excerpt":"POST /bookings\nСъздава резервация на стая и праща потвърждение на госта.\nПараметри:\n- room_id: цяло число (задължително)\n- check_in, check_out: дати във формат ГГГГ-ММ-ДД (задължителни)\n- guests: цяло число от 1 до 6, по подразбиране 2\n- note: текст до 300 знака\nУдостоверяване: заглавка Authorization: Bearer и токенът на хотела.","output_excerpt":"{\"name\":\"create_booking\",\"description\":\"Създава резервация на стая за посочените дати и изпраща потвърждение на госта. Връща създадената резервация. Използвайте го, когато трябва да се направи нова резервация.\",\"inputSchema\":{\"type\":\"object\",\"properties\":{\"room_id\":{\"type\":\"integer\",\"description\":\"Идентификатор на стаята.\"},\"check_in\":{\"type\":\"string\",\"format\":\"date\",\"description\":\"Дата на…"}],"page_url":"https://aiskills402.com/skills/mcp-tool-schema","markdown_url":"https://aiskills402.com/skills/mcp-tool-schema.md","image_url":"https://cdn.aiskills402.com/og/skills/mcp-tool-schema/8d6f41c6.png","related_url":"https://api.aiskills402.com/v1/skills/mcp-tool-schema/related","purchases_count":null,"tested":{"date":"2026-10-08","strong":{"model":"claude-sonnet-5-5 (Claude Code alias \"sonnet\")","verdict":"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."},"weak":{"model":"claude-haiku-5-5 (Claude Code alias \"haiku\")","verdict":"Also 12 of 12, with the same kinds of schema as Sonnet."},"note":"Twelve operations written by us as short API documentation, in English and one in Bulgarian, each with calls that must be accepted and calls that must be refused (96 in all). The model's inputSchema was compiled with Ajv for JSON Schema 2020-12 with formats, and every call was checked against it; the name had to follow the MCP specification of 2025-11-25, the answer had to be JSON only, no property could be a credential, and annotations were checked only where the documentation decides them. The request on both sides already said that unknown parameters must be refused. One run per model and case.","baseline":{"date":"2026-10-08","rows":[{"label":"Valid definition, calls accepted and refused as documented (12 operations)","better":"higher","strong":{"with":{"n":12,"of":12},"without":{"n":11,"of":12}},"weak":{"with":{"n":12,"of":12},"without":{"n":12,"of":12}}}],"note":"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."},"report_url":null},"price_usd":"0.01","price_micro":10000,"size_bytes":7765,"sha256":"e2241b7e45cf7f38d3b66a8f3f0a018442e7455dbe47db2dc3298f6ba130a457","outline":["The answer","name","description","inputSchema","annotations","Work in this order","Short example"],"license":{"summary":"Perpetual, non-exclusive; use and modify for yourself incl. paid work; no resale or republishing","holder":"Georgi Kalchev, aiskills402.com","url":"https://aiskills402.com/docs#license"},"buy_url":"https://api.aiskills402.com/v1/skills/mcp-tool-schema/file","redownload_url_template":"https://api.aiskills402.com/v1/purchases/{token}","mcp_tool":null,"payment":{"protocol":"x402","scheme":"exact","asset":"USDC","selling":true,"network":"base","network_caip2":"eip155:8453","pay_to":"0x8e37022edcf0f21cf3c9f93fee9d4d32519f36f4","facilitator":"cdp"},"seo_title":"API Docs to MCP Tool Schema: Agent Skill","seo_description":"A SKILL.md that turns one API operation into an MCP tool definition: name, description, strict inputSchema and annotations. $0.01 once, yours forever.","versions":[{"version":"1.0.0","date":"2026-10-08","changelog":"# Changelog\n\n## 1.0.0 — 2026-10-08\n\nFirst 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.\n"}]}