MCP Tool Schema Auditor — AgentReady

Check your MCP tool metadata before your next release.

Catch broken schemas, vague tool descriptions, risky permissions, and token bloat before production. AgentReady returns a 0–100 readiness score, prioritized findings, and concrete remediation guidance in seconds.

• Catch tools that agents cannot reliably discover or call.
• Surface destructive side effects and permission risks before users do.
• Find oversized schemas and the tools consuming the most context.
• Use stable finding codes in CI to block risky releases.
• Export machine-readable JSON and a human-readable Markdown report.

No LLM calls. No upstream tool execution. Metadata only.

Try it in 10 seconds — no input required

1. Click Try for free.
2. Leave all three sources empty and start the audit.
3. Inspect the default dataset for JSON and the key-value store for REPORT.md.

The built-in read-only sample makes this a zero-setup preview; it does not inspect your server. When you are ready, use a public HTTPS endpoint, an authorized connector, or your tools/list array below.

Check your own server

Use this when you add or change MCP tools and want to review schema mistakes, unclear descriptions, side-effect hints, or schema size. You receive a JSON report and, by default, a Markdown report with findings and suggested fixes.

1. Open Try for free and choose the JSON input editor.
2. Replace the input with the following example, changing the URL to your public HTTPS Streamable HTTP MCP endpoint:

{
  "mcpServerUrl": "https://mcp.deepwiki.com/mcp",
  "includeMarkdown": true
}

3. Start the audit. Open the output dataset for JSON, or the run's key-value store for REPORT.md.

Use exactly one source: a URL, an authorized connector, or a tools array. If you have a previously saved input, remove its sample tools array before entering a URL. For local/stdio servers, paste their tools/list array into tools; do not expose a local service just to audit it. An empty input runs the built-in demonstration and does not inspect your server.

The hosted price is $0.05 per completed audit; the Store's trial button does not mean unlimited free audits. A 100 score means no current rule was triggered, not a runtime safety certificate.

What it checks

Area	Checks
Contract	MCP-safe names, object input schemas, valid required, parameter descriptions, numeric bounds, categorical enums, array limits
Discoverability	Ambiguous tool names, weak descriptions, semantically overlapping tools, oversized tool surfaces
Context cost	Per-tool and whole-server character-based token estimates, top context consumers, high-overhead warnings
Authority	Read-only, write, destructive, and credential-sensitive classification
Safety	Side-effect disclosure, read-only conflicts, destructive-tool escalation
Permission design	MCP annotation coverage and recommended runtime policy

Public server snapshots — September 8, 2026

We queried tools/list on two public MCP services and ran AgentReady locally against their returned metadata. No upstream tools were executed.

Service / reported version	Tools	Score	Findings	Estimated schema tokens
DeepWiki 2.14.3	3	100/100	0	379
Context7 4.0.5	2	100/100	0	1,215

A clean report means these metadata snapshots triggered none of the current rules. It does not certify runtime safety, correctness, or model performance. Token counts use four characters per token; the two services expose different capabilities and this is not a quality ranking. These are independent observations, not customer endorsements.

To audit the current DeepWiki metadata, use this input (a hosted audit uses the pricing below):

{
  "mcpServerUrl": "https://mcp.deepwiki.com/mcp",
  "includeMarkdown": true
}

Endpoint references: DeepWiki documentation and Context7 project. Live results can change as the services evolve.

Deliberately flawed fixture — finding and fixing issues

The bundled two-tool fixture scores 59/100 and produces 2 critical, 2 high, 4 medium, and 1 low finding. The highest-priority fixes are immediately actionable:

• DESTRUCTIVE_HINT_MISSING — mark the destructive tool and require human approval.
• SIDE_EFFECT_UNDECLARED — state what the operation changes and whether it is reversible.
• REQUIRED_PROPERTY_UNKNOWN — define the required id property or remove it from required.
• TOOL_NAME_AMBIGUOUS — replace delete with a specific verb-resource name such as delete_calendar_event.

This example is generated from examples/input-tools.json, not a mocked marketing score.

How it works

1. Run once with no input to see the built-in sample, or provide one source: an Apify MCP Connector, a public HTTPS MCP endpoint, or a raw tools/list array.
2. AgentReady statically audits schema quality, discoverability, context cost, authority, safety, and permission design.
3. Review the score, five dimension scores, severity-ranked findings, evidence, and remediation suggestions.
4. Save the JSON or Markdown report for CI, baselining, or release review.

Input modes

Choose one source, or leave all three empty for the built-in sample:

1. mcpConnector — an authorized Apify MCP Connector. This is the preferred option for OAuth or private credentials because AgentReady only receives the connector ID; Apify injects the credential at its proxy.
2. mcpServerUrl — a public HTTPS Streamable HTTP endpoint. Optional headers are accepted as encrypted Actor input. Localhost, private IP ranges, URL credentials, and redirects are blocked.
3. tools — the raw tool array returned by MCP tools/list. This is ideal for local/stdio servers and CI fixtures.

For a zero-setup preview, leave all three sources empty. AgentReady audits one built-in read-only sample tool so the default Store run always produces a report.

Use from an MCP client

Expose AgentReady directly as a tool through the official Apify MCP server:

{
  "mcpServers": {
    "agentready": {
      "url": "https://mcp.apify.com?tools=matdavis/agentready-mcp-tool-auditor"
    }
  }
}

The MCP client will request Apify authentication before it can run the Actor or read its output.

Minimal inline input:

{
  "tools": [
    {
      "name": "get_weather",
      "description": "Return the current weather for one city without changing external state.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string",
            "description": "City name and optional country code."
          }
        },
        "required": ["city"],
        "additionalProperties": false
      },
      "annotations": {
        "readOnlyHint": true,
        "destructiveHint": false,
        "idempotentHint": true
      }
    }
  ]
}

A deliberately flawed example is available at examples/input-tools.json.

Output shape

{
  "schemaVersion": "1.0",
  "source": { "kind": "inline", "label": "Inline tools" },
  "summary": {
    "score": 72,
    "tools": 23,
    "critical": 2,
    "high": 4,
    "estimatedSchemaTokens": 12400,
    "contextOverhead": "HIGH"
  },
  "scores": {
    "contract": 85,
    "discoverability": 64,
    "tokenEfficiency": 51,
    "safety": 68,
    "permissionDesign": 71
  },
  "risks": [],
  "tokenUsage": [],
  "findings": []
}

The default dataset and REPORT key contain the complete JSON report. REPORT.md contains the human-readable report when includeMarkdown is enabled.

Pricing

$0.05 per completed server audit. The charge is emitted only after the audit reports have been saved successfully.

Scoring model

Each finding deducts points from one dimension according to severity. The overall score uses:

Dimension	Weight
Contract	25%
Discoverability	20%
Token efficiency	15%
Safety	25%
Permission design	15%

The rules are intentionally explainable. Every deduction has a stable code, severity, evidence/location where available, and a concrete remediation.

CI usage

Set failOnSeverity to critical, high, medium, or low. AgentReady writes the report first and then fails the run if the selected threshold is met, allowing a pipeline to retain evidence while blocking a release.

Stable rule codes make the report suitable for baselining and diffing.

Security boundaries

• AgentReady requests metadata only; it never calls upstream tools.
• Connector credentials remain behind the Apify MCP proxy.
• Direct URL mode accepts HTTPS only and blocks obvious SSRF targets and redirects.
• Header values are never copied into reports or logs.
• Risk labels are static heuristics, not a substitute for runtime authorization, approval, sandboxing, or audit logs.
• Tool annotations are untrusted hints. A runtime policy engine must independently enforce authority.

Current MVP limits

• Token estimates use configurable characters-per-token rather than a model-specific tokenizer.
• Risk detection is English-oriented and based on names, descriptions, and MCP annotations.
• The Actor audits contracts only; it does not execute test calls or verify real-world reversibility/idempotency.
• OAuth is supported through Apify MCP Connectors, not a custom interactive OAuth flow.
• DNS checks reduce SSRF risk but should be reviewed and hardened before exposing unrestricted direct URL mode at scale.

Local development

Requirements: Node.js 22+.

npm install
npm test
npm run build

To run as a local Actor, place an input document in the local default key-value store or use the Apify CLI, then run:

$npm start

License

MIT