ToolGrade

Grade MCP tool definitions (the tools array from a tools/list result) for how well AI agents can pick and call them. Returns a 0–100 score and A–F grade, per-tool scores, and findings with concrete fixes: missing or weak descriptions, untyped parameters, strings without maxLength, missing required or additionalProperties, missing annotations (readOnlyHint, destructiveHint …), invalid or duplicate names, outputSchema and enum problems, hidden characters and tool-poisoning patterns. Also returns an ESTIMATED token cost of the definitions (characters ÷ 4; real counts vary by model). Pure parsing: no network calls, and your tool definitions are never stored. Read-only. Same engine as the ToolGrade JSON API (POST /api/grade).

{
  "type": "object",
  "properties": {
    "tools": {
      "type": "array",
      "minItems": 1,
      "maxItems": 200,
      "description": "The tool definitions to grade, e.g. [{\"name\": \"search_docs\", \"description\": \"...\", \"inputSchema\": {...}}]: the \"tools\" array of a tools/list result. Up to 200 tools. Provide this or tools_json.",
      "items": {
        "type": "object",
        "description": "One MCP tool definition (name, description, inputSchema, optional title, annotations, outputSchema)."
      }
    },
    "tools_json": {
      "type": "string",
      "minLength": 1,
      "maxLength": 262144,
      "description": "Alternative to tools: raw JSON text of a tools/list response, its result object ({\"tools\": [...]}) or a tool array, exactly as copied."
    },
    "include_raw": {
      "type": "boolean",
      "default": false,
      "description": "Also return the full /api/grade report (all findings and every tool row) in structuredContent.raw. Larger output."
    }
  },
  "required": [],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "score": {
      "type": "number"
    },
    "grade": {
      "type": "string",
      "enum": [
        "A",
        "B",
        "C",
        "D",
        "F"
      ]
    },
    "toolCount": {
      "type": "number"
    },
    "critical": {
      "type": "number"
    },
    "warning": {
      "type": "number"
    },
    "info": {
      "type": "number"
    },
    "verdictMeaning": {
      "type": "string"
    },
    "estimatedTokens": {
      "type": "number",
      "description": "ESTIMATED total token cost of all definitions (compact JSON chars ÷ 4)."
    },
    "tokenNote": {
      "type": "string"
    },
    "tools": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "index": {
            "type": "number"
          },
          "name": {
            "type": "string"
          },
          "score": {
            "type": "number"
          },
          "grade": {
            "type": "string",
            "enum": [
              "A",
              "B",
              "C",
              "D",
              "F"
            ]
          },
          "estimatedTokens": {
            "type": "number"
          },
          "critical": {
            "type": "number"
          },
          "warning": {
            "type": "number"
          },
          "info": {
            "type": "number"
          }
        },
        "required": [
          "index",
          "name",
          "score",
          "grade",
          "estimatedTokens"
        ]
      }
    },
    "toolsOmitted": {
      "type": "number"
    },
    "findings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "severity": {
            "type": "string",
            "enum": [
              "critical",
              "warning",
              "info"
            ]
          },
          "code": {
            "type": "string"
          },
          "tool": {
            "type": "string",
            "description": "Tool name (from the submitted input; untrusted). Omitted for server-wide findings."
          },
          "path": {
            "type": "string"
          },
          "count": {
            "type": "number"
          },
          "message": {
            "type": "string"
          },
          "fix": {
            "type": "string"
          }
        },
        "required": [
          "severity",
          "code",
          "message",
          "fix"
        ]
      }
    },
    "findingsOmitted": {
      "type": "number"
    },
    "version": {
      "type": "string"
    },
    "raw": {
      "type": "object",
      "description": "Full /api/grade response (only when include_raw is true)"
    }
  },
  "required": [
    "score",
    "grade",
    "toolCount",
    "estimatedTokens",
    "tools",
    "findings",
    "version"
  ]
}