# ToolGrade

> Grade MCP tool definitions for agent-readiness. Paste a tools/list response (or a tool array) and get a 0-100 score, an A-F grade, per-tool scores, findings with concrete fixes (missing or weak descriptions, untyped parameters, strings without maxLength, missing required / additionalProperties, missing annotations such as readOnlyHint, bad or duplicate names, outputSchema and enum problems, hidden characters and tool-poisoning patterns) and an estimated token cost of the definitions. Free paste tool, JSON API and a remote MCP server for AI agents. Pure parsing: no network calls, and your tool definitions are never stored.

## For AI agents

- [MCP server](https://toolgrade.mike-tusa.workers.dev/mcp): remote MCP over Streamable HTTP (POST only, stateless, JSON responses). Protocol versions: 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05. Tool `grade_tools` (tools: array of tool definitions, or tools_json: raw tools/list JSON text; optional include_raw). Read-only. Client config (most MCP clients accept this; some use a different format, for example VS Code uses a `servers` key): `{"mcpServers":{"toolgrade":{"type":"http","url":"https://toolgrade.mike-tusa.workers.dev/mcp"}}}`
- [OpenAPI 3.1 spec](https://toolgrade.mike-tusa.workers.dev/openapi.json): machine-readable description of the JSON API
- [MCP server card](https://toolgrade.mike-tusa.workers.dev/.well-known/mcp/server-card.json): static description of the MCP server and its tool
- Useful for anyone building MCP servers for AI agents and assistants, for example Muse, Claude, ChatGPT or Cursor. 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.

## JSON API

- `POST https://toolgrade.mike-tusa.workers.dev/api/grade`: body = the JSON output of an MCP tools/list call (the full JSON-RPC response, its result `{"tools": [...]}`, a JSON-RPC batch, or a bare array of tools), application/json. Max 262144 bytes and 200 tools. Response: { score (0-100), grade (A-F), summary { tools, critical, warning, info, source, verdictMeaning }, tokenEstimate { estimated: true, totalTokens, averagePerTool, largestTool, method, note }, tools [ { index, name, score, grade, estimatedTokens, critical, warning, info } ], findings [ { severity (critical|warning|info), code, tool, path, count, paths, message, fix } ], findingsOmitted, meta }. Optional key: `Authorization: Bearer <key>` or `X-Api-Key: <key>`. Response headers: X-ToolGrade-Tier (anonymous|free), X-ToolGrade-Quota-Remaining. Errors: { "error": { "code", "message" } } with 400 invalid_input / invalid_json / too_many_tools, 401 invalid_key, 503 unavailable, 404 not_found, 405 method_not_allowed, 413 too_large, 429 rate_limited / daily_limit / monthly_limit / pool_exhausted.
- Token cost is an ESTIMATE: Estimate only: compact-JSON characters divided by 4. Real token counts vary by model, tokenizer and how each client serializes tool definitions.
- `POST https://toolgrade.mike-tusa.workers.dev/api/keys` (no body, no sign-up, no email): returns 201 { key, plan: "free", monthlyLimit, note } once. Keys look like `tg_live_` + 32 hex. Only a SHA-256 hash of the key and a monthly counter are stored. About 3 new keys per hour per IP (best-effort, counted per server instance) and a global cap of about 200 new keys per day; 429 rate_limited / pool_exhausted, 503 unavailable when today's storage write budget is used.
- `GET https://toolgrade.mike-tusa.workers.dev/api/health`: { ok, version, day }.

## Limits, keys and pricing

- Anonymous (no key): about 20 grades/min per IP and a shared pool of about 5000 grades per UTC day.
- Free key: about 100 grades per key per UTC calendar month, about 20/min per key, not charged to the anonymous pool. All free keys together share a pool of about 20000 grades per UTC day (429 pool_exhausted), and about 200 new keys can be issued per day in total. No paid tier.
- Counts are approximate: counters are batched per server instance before being saved, so a key can occasionally get a few more than 100 in a month and the daily pools can run slightly over.
- The MCP endpoint uses the same keys and counters: each `tools/call` is one grade. Non-grade MCP messages don't count as grades, but are capped at about 120/min per IP (HTTP 429 + Retry-After). Via MCP, tools_json text is capped at 262144 bytes like the JSON API, and the whole MCP request body (including a parsed tools array) at 270336 bytes (about 264 KB).
- Tool definitions you submit are parsed in memory and discarded when the response is sent. They are never written to storage, logs or analytics, and ToolGrade makes no network requests: it never connects to your server.

## Optional

- [Privacy](https://toolgrade.mike-tusa.workers.dev/privacy)
- [Terms](https://toolgrade.mike-tusa.workers.dev/terms)
- Contact: digitalpromohub.support@gmail.com