{ "openapi": "3.1.0", "info": { "title": "ToolGrade", "version": "0.1.3", "description": "Grade MCP tool definitions for agent-readiness: 0-100 score, A-F grade, findings with fixes, estimated token cost. Pure parsing; your tool definitions are never stored; no network calls. Anonymous: about 20/min per IP, shared daily pool about 5000. Free key (POST /api/keys): about 100 grades/month. ToolGrade is not affiliated with Meta, Anthropic, OpenAI, Cursor or any other AI or MCP client vendor, and is not endorsed or sponsored by them.", "contact": { "email": "digitalpromohub.support@gmail.com" } }, "servers": [ { "url": "https://toolgrade.mike-tusa.workers.dev" } ], "security": [ {}, { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "paths": { "/api/grade": { "post": { "operationId": "gradeTools", "summary": "Grade MCP tool definitions (tools/list output or tool array)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "tools/list JSON-RPC response, its result {\"tools\": [...]}, a JSON-RPC batch, or an array of tools. Max 262144 bytes, 200 tools.", "oneOf": [ { "type": "object", "properties": { "tools": { "type": "array", "maxItems": 200, "items": { "type": "object" } } }, "required": [ "tools" ] }, { "type": "object", "properties": { "jsonrpc": { "type": "string", "const": "2.0" }, "id": {}, "result": { "type": "object", "properties": { "tools": { "type": "array", "maxItems": 200, "items": { "type": "object" } } }, "required": [ "tools" ] } }, "required": [ "result" ] }, { "type": "array", "items": { "type": "object" } } ] } } } }, "responses": { "200": { "description": "Grade report", "headers": { "X-ToolGrade-Quota-Remaining": { "schema": { "type": "string" }, "description": "Approximate grades left (shared daily pool when anonymous, monthly quota with a key)" }, "X-ToolGrade-Tier": { "schema": { "type": "string", "enum": [ "anonymous", "free" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Report" } } } }, "400": { "description": "invalid_input, invalid_json or too_many_tools (rejected before rate limits or the daily pool are charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "invalid_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited, daily_limit (anonymous), monthly_limit or pool_exhausted (key; counts are approximate, batched per instance)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "string" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "unavailable: key check temporarily failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "string" } } } } } }, "get": { "operationId": "gradeGetNotAllowed", "summary": "Not supported (POST the JSON body)", "responses": { "405": { "description": "method_not_allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/keys": { "post": { "operationId": "issueKey", "summary": "Issue a free API key (no sign-up, no email). The key is shown once.", "security": [ {} ], "responses": { "201": { "description": "New key", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^tg_live_[0-9a-f]{32}$" }, "plan": { "type": "string", "const": "free" }, "monthlyLimit": { "type": "integer" }, "note": { "type": "string" } }, "required": [ "key", "plan", "monthlyLimit" ] } } } }, "429": { "description": "rate_limited (about 3 new keys per hour per IP, best-effort) or pool_exhausted (global cap of about 200 new keys per day)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "string" } } } }, "503": { "description": "unavailable: key issuance paused until the daily storage write budget resets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "issueKeyGetNotAllowed", "summary": "Not supported", "responses": { "405": { "description": "method_not_allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/.well-known/mcp/server-card.json": { "get": { "operationId": "serverCard", "summary": "Static MCP server card (same tools as tools/list)", "responses": { "200": { "description": "Server card", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/health": { "get": { "operationId": "health", "summary": "Health and version", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "version": { "type": "string" }, "day": { "type": "string" } } } } } } } } }, "/mcp": { "post": { "operationId": "mcp", "summary": "Remote MCP server (JSON-RPC 2.0 over Streamable HTTP, stateless)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON-RPC 2.0 request, notification or batch (max 10, at most one tools/call). Max 270336 bytes." } } } }, "responses": { "200": { "description": "JSON-RPC result", "content": { "application/json": { "schema": { "type": "object", "description": "JSON-RPC 2.0 response (or batch array)" } } } }, "202": { "description": "Notification or client response accepted (empty body)" }, "400": { "description": "Parse error, invalid request or protocol/header mismatch", "content": { "application/json": { "schema": { "type": "object", "description": "JSON-RPC 2.0 response (or batch array)" } } } }, "401": { "description": "Invalid API key (data.code invalid_key; no WWW-Authenticate)", "content": { "application/json": { "schema": { "type": "object", "description": "JSON-RPC 2.0 response (or batch array)" } } } }, "403": { "description": "Origin not allowed", "content": { "application/json": { "schema": { "type": "object", "description": "JSON-RPC 2.0 response (or batch array)" } } } }, "404": { "description": "Method not found (2026-07-28 requests)", "content": { "application/json": { "schema": { "type": "object", "description": "JSON-RPC 2.0 response (or batch array)" } } } }, "413": { "description": "Body too large", "content": { "application/json": { "schema": { "type": "object", "description": "JSON-RPC 2.0 response (or batch array)" } } } }, "429": { "description": "Too many MCP requests (Retry-After)", "content": { "application/json": { "schema": { "type": "object", "description": "JSON-RPC 2.0 response (or batch array)" } } } }, "500": { "description": "Internal error" }, "503": { "description": "Temporarily unavailable" } } }, "get": { "operationId": "mcpGet", "summary": "Not supported (no SSE stream)", "responses": { "405": { "description": "Method not allowed", "headers": { "Allow": { "schema": { "type": "string", "const": "POST, OPTIONS" } } } } } }, "delete": { "operationId": "mcpDelete", "summary": "Not supported (no sessions)", "responses": { "405": { "description": "Method not allowed", "headers": { "Allow": { "schema": { "type": "string", "const": "POST, OPTIONS" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Free API key from POST /api/keys" }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-Api-Key" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_input", "invalid_json", "too_many_tools", "invalid_key", "too_large", "rate_limited", "daily_limit", "monthly_limit", "pool_exhausted", "unavailable", "method_not_allowed", "not_found", "internal_error" ] }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "Finding": { "type": "object", "properties": { "severity": { "type": "string", "enum": [ "critical", "warning", "info" ] }, "code": { "type": "string" }, "tool": { "type": [ "string", "null" ], "description": "Tool name from the input (untrusted); null for server-wide findings" }, "path": { "type": "string" }, "count": { "type": "integer" }, "paths": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" }, "fix": { "type": "string" } }, "required": [ "severity", "code", "tool", "message", "fix" ] }, "ToolRow": { "type": "object", "properties": { "index": { "type": "integer" }, "name": { "type": "string" }, "score": { "type": "integer" }, "grade": { "type": "string", "enum": [ "A", "B", "C", "D", "F" ] }, "estimatedTokens": { "type": "integer" }, "critical": { "type": "integer" }, "warning": { "type": "integer" }, "info": { "type": "integer" } }, "required": [ "index", "name", "score", "grade", "estimatedTokens" ] }, "Report": { "type": "object", "properties": { "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "grade": { "type": "string", "enum": [ "A", "B", "C", "D", "F" ] }, "summary": { "type": "object", "properties": { "tools": { "type": "integer" }, "critical": { "type": "integer" }, "warning": { "type": "integer" }, "info": { "type": "integer" }, "source": { "type": "string", "enum": [ "array", "jsonrpc_batch", "jsonrpc_response", "tools_list_result", "single_tool" ] }, "verdictMeaning": { "type": "string" } } }, "tokenEstimate": { "type": "object", "description": "ESTIMATE of definition token cost", "properties": { "estimated": { "type": "boolean", "const": true }, "totalTokens": { "type": "integer" }, "averagePerTool": { "type": "integer" }, "largestTool": { "type": "object" }, "method": { "type": "string" }, "note": { "type": "string" } } }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/ToolRow" } }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/Finding" } }, "findingsOmitted": { "type": "integer" }, "meta": { "type": "object", "properties": { "version": { "type": "string" }, "stored": { "type": "boolean", "const": false }, "networkLookups": { "type": "boolean", "const": false }, "maxTools": { "type": "integer" } } } }, "required": [ "score", "grade", "summary", "tokenEstimate", "tools", "findings", "meta" ] } } } }