Audit

Purpose

Evaluate MCP server tool definitions against design quality criteria drawn from three upstream authorities, cited (not recapped) so the current text always governs:

• MCP specification 2025-11-25 — Tools. The normative protocol (MUST / SHOULD / OPTIONAL requirements for names, schemas, annotations).
• Anthropic — Writing effective tools for AI agents. Engineering guidance for descriptions, parameters, namespacing, and workflow-shaped granularity.
• Claude Code — Connect Claude Code to tools via MCP. Claude-Code-specific client behavior: _meta annotations and result-size limits. The dated record for the values C17 and C18 turn on is in reference/checklist.md, "Client-behavior record".

Produces a per-tool scorecard with actionable findings. Catches description gaps, missing annotations, and naming issues before they degrade LLM tool selection accuracy.

Server discovery configuration

Phase 1 enumerates MCP servers and their tool source files by scanning the project for the per-language tool markers. The tool-marker, name-extraction, description-extraction, and meta-extraction rules are upstream MCP-SDK conventions, stable across repos. See reference/server-discovery.md for the per-language discovery rules and how servers are grouped.

Arguments

Parse $ARGUMENTS:

• <path>. Audit a single scope. A directory to narrow the scan to (typically one server's directory).
• (empty). Audit every tool discovered under the project root.

Track progress

For multi-server audit runs (Phases 1-3 across ≥2 servers), keep an in-response checklist of the three phases and tick each as it completes. Phase 2 may run subagent fan-out for ≥5 tools.

Workflow

Phase 1: Discover servers and tools

Run bash "${CLAUDE_PLUGIN_ROOT}/skills/audit/scripts/discover.sh", adding --path <dir> when $ARGUMENTS supplies a directory, to scope the scan to that directory.

Phase 2: Evaluate against checklist

Read each Tool file: from Phase 1. Per the language rules in reference/server-discovery.md, extract descriptions, parameters, wire-level annotations (C12-C14), and the tool's _meta object (C17-C19). The last via meta-extraction, recording each key's JSON type and not merely its presence, because C18 turns on it. Load the detailed checklist from reference/checklist.md.

Once per server, also resolve its instructions field. See Server instructions in reference/server-discovery.md and evaluate C4's per-server clause against it. Phase 1's records are per-tool, so this is the only step that reaches it; its result lands in the server-level row of the Phase 3 report, not in any tool's table.

Evaluate every criterion in the checklist against each tool, and C4's per-server clause once per server. Record each result as:

• PASS. Criterion met
• WARN. Criterion partially met or could be improved
• FAIL. Criterion not met
• info. An optimization opportunity rather than a defect; the severity reference/checklist.md assigns to C8, C11, C14, and by default to C17-C19
• n/a. The criterion has no subject here, so it cannot pass: a server whose construction site declares no instructions gives C4's per-server clause nothing to size
• undetermined. The subject was not reachable in the scanned scope (no server construction site found), which is not the same as its being absent

Phase 3: Report

Output a markdown report with this structure:

# MCP Tool Audit Report

**Date:** YYYY-MM-DD
**Servers audited:** N
**Tools audited:** N
**Overall:** X pass, Y warn, Z fail, W info

## Summary by server

| Server | Tools | Pass | Warn | Fail | Info |
|--------|-------|------|------|------|------|
| <server-name> | N | ... | ... | ... | ... |

## Findings by server

### Server: <server-name> (<language>)

Server-level criteria — the outcomes that belong to the server, not to any one tool:

| Criterion | Authority | Result | Details |
|-----------|-----------|--------|---------|
| C4 Server `instructions` within size budget | OPINION | n/a | Construction site declares no `instructions` |

#### Tool: <tool_name>

| Criterion | Authority | Result | Details |
|-----------|-----------|--------|---------|
| C1 Description has "what" | ANTHROPIC | WARN | Missing "when to use" context |
| C9 Name charset/length valid | SPEC-SHOULD | PASS | |
| C12 readOnlyHint set | SPEC-OPTIONAL | WARN | Read-only tool lacks the hint |
| C18 requiresUserInteraction is JSON `true` | OPINION | FAIL | Declared as the string `"true"` — silently ignored |
| ... | ... | ... | ... |

(repeat for each tool)

Prioritize FAIL items. Highest-value improvements. WARN items are suggestions and info items are optimizations. The Overall line and the summary table count every outcome recorded for a server: its tools' criterion rows and its server-level rows, across the four severity buckets. n/a and undetermined are not severities: they record that a criterion had no subject, or none reachable, so they appear only in the server-level criterion table and never count as a pass. A missing annotation is never FAIL. Annotations are OPTIONAL in the spec (C12-C14) or Claude-Code-specific advisories (C17-C19); only a declared value Claude Code silently ignores can FAIL (C18).

What this skill does NOT do

• Does not modify tool definitions. It reports. Use findings to guide manual improvements.
• Does not test tool functionality. Use MCP Inspector for that.
• Does not evaluate MCP resources. Only tools.