MCP Tool Schema: Definitions from API Docs

A newly published MCP tool schema guide specifies how to write a single API operation as an MCP tool definition — name, description, inputSchema and annotations — in the JSON a server returns from tools/list. The guide requires the schema to take exactly the parameters the operation takes, with required parameters 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 rejection of unknown parameters; credentials never become parameters, and each tool covers one operation with a title and all four annotations set as explicit true or false (reads, safe repeats, destructive writes, open world). The guide states these requirements align with the MCP specification of 2025-11-25 and the expectations of the Claude and ChatGPT directories.

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.