Agents & Protocols

MCP Tool Schema: Definitions from API Docs

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.

MCP Tool Schema: Definitions from API Docs is a 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.03 over x402.

Tested 2026-10-23No code, no hidden instructionsv1.1.1 · 10.2 KB · perpetual license

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-23 with a strong and a weak model.

With and without the skill

Results with and without the skill, for Sonnet and Haiku
SonnetHaiku
withwithoutwithwithout
Right schema, title and all four hints (19 operations)19/1917/1919/193/19

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.

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 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.
HaikuWeak model, claude-haiku-5-5
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.

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 and title
  • description
  • inputSchema
  • annotations
  • One tool, one operation
  • 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.1.1, updated 2026-10-23. Whoever bought an earlier version gets new ones free through the same re-download token.

  1. v1.1.1 · 2026-10-23

    Corrected 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.

  2. v1.1.0 · 2026-10-23

    Annotations 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.

  3. 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, 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.

How did you test it?

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.

Does my model need it?

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.

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.

Read more

Share

Read this page as Markdown: /skills/mcp-tool-schema.md.

  • SKILL.md Review: Safe and Within the Limits

    Agents & Protocols

    SKILL.md · v1.0.1 · 6.7 KB

    Reviews a SKILL.md file before you install, buy or publish it and lists every problem with a fixed code, the place and a fix, then gives one verdict. It checks the front matter against the published limits (name up to 64 characters in lowercase, hyphens and digits, no reserved words; description present, up to 1,024 characters, naming both its job and the requests that should trigger it, in the third person), and it reads the body for hidden orders to the agent, credentials pasted into the text, commands that download and run remote code, Windows-style paths, a body over 500 lines and the lack of any example. Use to review a SKILL.md, audit a Claude or agent skill before installing it, check a skill file for prompt injection, or lint a skill before publishing it to a marketplace.

    $0.05once

    • x402
    • USDC
    • Base
    Get skill

    Tested with Sonnet and Haiku, 8 Oct 2026

  • JSON Repair: Fix Broken JSON, Keep Every Value

    Data & Analysis

    SKILL.md · v1.0.1 · 6.9 KB

    Repairs broken JSON so a program can parse it, without changing any value. Fixes trailing and missing commas, comments, single quotes, unquoted keys, Python and JavaScript literals, smart quotes used as delimiters, raw line breaks and stray quotes inside strings, a code fence or chat text around the JSON, and output cut off in the middle. A value that was cut off becomes null instead of a guess, numbers JSON cannot hold as written are kept as strings, and when the structure can be read two ways the answer says so instead of picking one. Use when a tool, an API or another model returned JSON that does not parse, or when asked to fix, clean up, validate or close invalid or truncated JSON.

    $0.05once

    • x402
    • USDC
    • Base
    Get skill

    Tested with Sonnet and Haiku, 7 Oct 2026

  • Text to JSON: Extract Data Without Guessing

    Data & Analysis

    SKILL.md · v1.0.2 · 7.5 KB

    Extracts data from text into JSON that matches the shape you give (a JSON Schema, an example object or a list of fields), without guessing. Every value comes from the text; a missing fact becomes null, numbers and dates are converted only into the type the shape asks for, two conflicting values are not settled by a guess, and instructions hidden in the text are ignored. Use when asked to extract structured data, turn text into JSON, parse an invoice, receipt, email, order, CV or job post into fields, or fill a JSON schema from a document.

    $0.05once

    • x402
    • USDC
    • Base
    Get skill

    Tested with Sonnet and Haiku, 3 Oct 2026

More in Agents & Protocols

  • Parallel Agent Worktree Review

    Agents & Protocols

    SKILL.md · v1.0.0 · 6.4 KB

    Reviews a plan or shell script that lets several coding agents work in parallel, each in its own git worktree, and lists only the five mistakes that make the agents collide, one line each with a fixed code, the place, why it breaks and the fix - or exactly No findings. It catches one branch checked out in two worktrees or forced onto a second one, two agents started on the same fixed port, an untracked secret file missing in a new worktree or written by two agents, a build folder or database file written by more than one agent, and worktrees that are never removed. It leaves out the safe look-alikes, such as two worktrees on different branches cut from one commit or a shared folder that every agent only reads. Use before launching parallel agents, to audit an orchestration script, or to debug agents that overwrite each other.

    $0.01once

    • x402
    • USDC
    • Base
    Get skill

    Tested with Sonnet and Haiku, 19 Oct 2026

  • Prompt Caching Review

    Agents & Protocols

    SKILL.md · v1.0.0 · 8.8 KB

    Reviews ONE Claude API request (tools, system, messages, the cache marks, the model, the sizes and how often it is sent) for the five reasons its prompt cache does not pay off, and lists only those, one line each with a fixed code, the place, why the cache misses and the fix - or exactly No findings. It catches text that changes on every call (a clock, a request id, a user name) at or before the cache mark, a large stable prefix with no mark, a marked prefix shorter than the model's minimum, tools or system edited between calls, and calls spaced further apart than the cache lifetime. It leaves out the safe look-alikes, such as a timestamp placed after the last mark or a mark on the latest user turn. Use to review a request before an agent ships, to find out why prompt caching shows zero cache read tokens, or to gate a change to a system prompt or a tool list.

    $0.01once

    • x402
    • USDC
    • Base
    Get skill

    Tested with Sonnet and Haiku, 19 Oct 2026

  • Agent Loop Review: Repeats, Caps, Self-Grading

    Agents & Protocols

    SKILL.md · v1.0.0 · 11.8 KB

    Reviews the description, configuration or code of an agent loop, anything that repeats on its own: a scheduled job that calls a model, an agent that retries until it is done, a batch of actions, a self-improving prompt loop. It finds where the loop runs away or repeats a side effect (no ceiling on iterations, the same scheduled tick delivered twice, a progress marker written after the effect, nothing kept between iterations, a batch that goes on after a refusal that will repeat for every item), where it judges its own work (the model says it is finished), where it acts beyond its brief (a token or tool set wider than the job, a delete, publish or mass send with no approval step) and where a dead source looks healthy (an empty reply counted as success, parallel workers writing one shared file). Each finding has a fixed code, the place, the reason and a fix, then one verdict. Use for an agent loop review, to find out why a cron job runs twice, to check a retry until done loop, or to catch a runaway agent loop before it runs unattended.

    $0.01once

    • x402
    • USDC
    • Base
    Get skill

    Tested with Sonnet and Haiku, 18 Oct 2026

  • Claude Session Saver: When to Clear or Compact

    Agents & Protocols

    SKILL.md · v1.0.0 · 12.6 KB

    Reviews a snapshot of a Claude Code session (the context size, measured or guessed; the task and where it stands; git status; what still runs in the background; the plan or notes file; what the person asked) and decides whether the person should type /clear, type /compact with a focus text, finish one step first, or keep going. Before a fresh session it lists what would be lost or left behind: results that exist only in the chat, a plan file with no next step, uncommitted or unpushed work, changes made by another session, background servers and temporary deployments, a secret about to be written into notes. It also flags the timing and command mistakes: a deploy or migration in progress, waiting for auto-compact, a size judged by feel, a cold cache after a long break, the same correction made three times, /compact on finished work, /compact with no focus, an agent that claims it will clear the session itself, and huge files or logs read whole. Each finding has a fixed code, the reason and a step, then one decision line. Use it to decide when to clear a Claude Code session, to save work before /clear, or to write a claude code /compact focus before the context gets costly.

    $0.03once

    • x402
    • USDC
    • Base
    Get skill

    Tested with Sonnet and Haiku, 16 Oct 2026