{"slug":"mcp-tool-schema","name":"MCP Tool Schema: Definitions from API Docs","version":"1.1.1","updated_at":"2026-10-23T05:52:15.836Z","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, one tool does one operation, and every tool gets a title and all four annotations as explicit true or false (reads, safe repeats, destructive writes, open world), as the MCP specification of 2025-11-25 and the Claude and ChatGPT directories expect. 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, title, 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. Every tool gets all four hints as true or false, which the ChatGPT directory requires and the Claude directory checks."},{"q":"How did you test it?","a":"On 19 operations written as short API documentation, three of them tools from our own MCP servers, each with calls the schema had to accept and calls it had to refuse, 136 in all, checked with a JSON Schema 2020-12 validator, plus the title and the hint values the documentation decides. Both Sonnet and Haiku, given the skill, wrote all 19 correctly."},{"q":"Does my model need it?","a":"Haiku does: without the skill it got 3 of 19, leaving out titles and getting hints wrong, such as an SMS marked as not destructive. Sonnet got 17 of 19 without it and missed two tools that spend credit or overwrite data. The skill adds a fixed rule for each hint, one tool per operation, 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/0f8a1bd4.png","related_url":"https://api.aiskills402.com/v1/skills/mcp-tool-schema/related","purchases_count":null,"tested":{"date":"2026-10-23","strong":{"model":"claude-sonnet-5-5 (Claude Code alias \"sonnet\")","verdict":"Wrote a correct definition for all 19 operations: a schema that a validator accepted and that accepted and refused exactly the calls the documentation allows, a title at the top and in annotations, and all four hints as true or false with the values the documentation decides. It marked reads of the caller's own account as closed world and a page fetch from any URL as open world, an SMS and a USDC transfer as destructive and open world, and both of our 402cron tools right: running a task now spends a credit and calls the destination, and creating a task with a name in use overwrites it. It split a records endpoint with an action field into one tool per operation, and split a purge with a dry_run switch into a read-only preview and a destructive purge."},"weak":{"model":"claude-haiku-5-5 (Claude Code alias \"haiku\")","verdict":"Also 19 of 19 in content: every hint the documentation decides had the right value, every tool had a title and all four hints, and the records endpoint was split into one tool per operation. It kept the purge as one tool with dry_run, marked destructive, which is the other right answer. One answer of the 19 came wrapped in a Markdown fence, which the skill says not to do."},"note":"Nineteen operations written by us as short API documentation: the twelve from version 1.0.0, four new ones for the hints (a page fetch from any URL, an SMS to any number, a USDC transfer, a records endpoint with an action field), and three tools from our own MCP servers whose right answer we had decided and checked live (402cron run now and create task, 402post validate). Each comes with calls that must be accepted and calls that must be refused, 136 in all, checked with a JSON Schema 2020-12 validator. Every tool had to have a name of at most 64 characters, a title at the top and in annotations, and all four hints as true or false; the hints the documentation decides were checked for their value. For the purge with a dry_run switch both answers count: one destructive tool, or a read-only preview plus a destructive purge. The request on both sides said that the server will be listed in the Claude and ChatGPT directories. A control run checks that a correct answer passes and that 380 broken ones fail. One run per model and case.","baseline":{"date":"2026-10-23","rows":[{"label":"Right schema, title and all four hints (19 operations)","better":"higher","strong":{"with":{"n":19,"of":19},"without":{"n":17,"of":19}},"weak":{"with":{"n":19,"of":19},"without":{"n":3,"of":19}}}],"note":"The same request and the same checks on both sides; a fence around the answer is removed first. Without the skill Sonnet got the schemas and most hints right; its two misses were both on our 402cron tools, which it marked as not destructive although running a task spends a credit and creating one with a name in use overwrites it. Without the skill Haiku left the title out of annotations on 16 of 19 tools (5 had no title at all), and on 10 of 19 it got the tool itself wrong: reads of the caller's own account marked as open world, an SMS and the two 402cron tools marked as not destructive, writes without readOnlyHint or idempotentHint, and the records endpoint kept as one tool with an action switch. On the documentation with a note for assistants it ignored the note correctly, then explained that in a sentence after the JSON."},"report_url":null},"price_usd":"0.03","price_micro":30000,"size_bytes":10409,"sha256":"546c50524bd5dffcb9bd382d467eddee84c0eef8a671f201d7a63296355bf646","outline":["The answer","name and title","description","inputSchema","annotations","One tool, one operation","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":"0xbc0dcc70d8b5d85541d86ffc68d988fd59c22e68","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, all four annotations. $0.03 once, yours forever.","versions":[{"version":"1.1.1","date":"2026-10-23","changelog":"# Changelog\n\n## 1.1.1 — 2026-10-23\n\nCorrected the test note: without the skill Haiku left the title out of annotations on 16 of 19 tools and had no title at all on 5; the note of 1.1.0 said 17. The skill itself is unchanged.\n\n## 1.1.0 — 2026-10-23\n\nAnnotations as the Claude and ChatGPT directories now expect them: every tool gets a title, at the top and in annotations, and all four hints written as true or false, never left out; a missing hint defaults to \"destructive, open world\", so a harmless read looks dangerous and the ChatGPT directory refuses the server. New rules for each hint: deleting, overwriting, spending money or sending something that cannot be recalled is destructive even if it can be undone; idempotent only when a repeat leaves the same result; open world when the tool reaches beyond one bounded account (any URL, any phone number, any wallet). Names stay within 64 characters. One tool does one operation: an endpoint with an action or method switch becomes one tool per operation. A tool that moves money is destructive and says the payment cannot be reversed. Tested on 19 operations, three of them from our own MCP servers: with the skill Sonnet and Haiku got 19 of 19 right; without it, 17 and 3.\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"},{"version":"1.1.0","date":"2026-10-23","changelog":"# Changelog\n\n## 1.1.0 — 2026-10-23\n\nAnnotations as the Claude and ChatGPT directories now expect them: every tool gets a title, at the top and in annotations, and all four hints written as true or false, never left out; a missing hint defaults to \"destructive, open world\", so a harmless read looks dangerous and the ChatGPT directory refuses the server. New rules for each hint: deleting, overwriting, spending money or sending something that cannot be recalled is destructive even if it can be undone; idempotent only when a repeat leaves the same result; open world when the tool reaches beyond one bounded account (any URL, any phone number, any wallet). Names stay within 64 characters. One tool does one operation: an endpoint with an action or method switch becomes one tool per operation. A tool that moves money is destructive and says the payment cannot be reversed. Tested on 19 operations, three of them from our own MCP servers: with the skill Sonnet and Haiku got 19 of 19 right; without it, 17 and 3.\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"},{"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"}]}