audit
/audit
Audit MCP server tool definitions against design quality criteria. Use when: 'audit MCP tools', 'check MCP tool descriptions', 'review MCP server quality', 'tool annotations', 'readOnlyHint missing', 'parameter descriptions missing', 'check the _meta annotations', 'maxResultSizeChars', 'requiresUserInteraction', 'alwaysLoad', 'are my server instructions too long', 'mcp audit', or before shipping MCP server changes. Optional path argument targets a single server directory; omit to audit the whole project. Produces per-tool PASS/WARN/FAIL scorecard covering description completeness, parameters,
- Author
- melodic-software ↗
- Repository
- claude-code-plugins ↗
- Licence
- MIT
- Last repository change
- 26.10.2026
Assessment and security
- Files in this package
- 12
- Scripts
- 2
- HTML comments
- 0
- URLs in SKILL.md
- 5
No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 2 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/discover.sh, scripts/discover.test.sh
What it does and when to use it
Audit MCP server tool definitions against design quality criteria. Use when: 'audit MCP tools', 'check MCP tool descriptions', 'review MCP server quality', 'tool annotations', 'readOnlyHint missing', 'parameter descriptions missing', 'check the _meta annotations', 'maxResultSizeChars', 'requiresUserInteraction', 'alwaysLoad', 'are my server instructions too long', 'mcp audit', or before shipping MCP server changes. Optional path argument targets a single server directory; omit to audit the whole project. Produces per-tool PASS/WARN/FAIL scorecard covering description completeness, parameters,
Triggers from the description
Arguments
/audit [path]
Original author description
Audit MCP server tool definitions against design quality criteria. Use when: 'audit MCP tools', 'check MCP tool descriptions', 'review MCP server quality', 'tool annotations', 'readOnlyHint missing', 'parameter descriptions missing', 'check the _meta annotations', 'maxResultSizeChars', 'requiresUserInteraction', 'alwaysLoad', 'are my server instructions too long', 'mcp audit', or before shipping MCP server changes. Optional path argument targets a single server directory; omit to audit the whole project. Produces per-tool PASS/WARN/FAIL scorecard covering description completeness, parameters,
How it works
- Purpose
- Server discovery configuration
- Arguments
- Track progress
- Workflow
- What this skill does NOT do
SKILL.md preview
---
description: "Audit MCP server tool definitions against design quality criteria. Use when: 'audit MCP tools', 'check MCP tool descriptions', 'review MCP server quality', 'tool annotations', 'readOnlyHint missing', 'parameter descriptions missing', 'check the _meta annotations', 'maxResultSizeChars', 'requiresUserInteraction', 'alwaysLoad', 'are my server instructions too long', 'mcp audit', or before shipping MCP server changes. Optional path argument targets a single server directory; omit to audit the whole project. Produces per-tool PASS/WARN/FAIL scorecard covering description completeness, parameters, naming, annotations, and the Claude Code `_meta` annotations, plus a server-level result for the server `instructions` size budget. Language-agnostic: Python (`mcp`), TypeScript, .NET. Not for: whether configured MCP servers are safe to run (/mcp-tools:audit-posture), or MCP config correctness and connection issues (/harness-config:audit)."
argument-hint: "[path]"
user-invocable: true
disable-model-invocation: false
context: fork
background: false
metadata:
workflow-stage: review
summary: Audit MCP tool definitions against design quality criteria
---
**Arguments.** `[path]`. A directory to scope the audit to (e.g. a single server dir), or omit for the whole project.
## 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 2026-07-28: Tools](https://modelcontextprotocol.io/specification/2026-07-28/server/tools). The normative protocol (MUST / SHOULD / OPTIONAL requirements for names, schemas, annotations); why this revision is in reference/checklist.md, "Spec revision record".
- [Define tools: best practices for tool definitions](https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools#best-practices-for-tool-definitions). Tool-design guidance for descriptions, parameters, namespacing, and workflow-shaped granularity (correlate with [Anthropic: Writing effective tools for AI agents](https://www.anthropic.com/engineering/writing-tools-for-agents)).
- [Claude Code: Connect Claude Code to tools via MCP](https://code.claude.com/docs/en/mcp). Claude-Code-specific client behavior: `_meta` annotations and result-size limits. The dated pointer records for the values C4 and C17-C19 turn on are in reference/checklist.md, "Client-behavior record" and "Description length record".
Produces a per-tool scorecard with actionable findings. Catches description gaps, missing annotations,
and naming issues before they degrade LLM tool selection accuracy.
This skill runs as a **blocking fork** (`context: fork`, `background: false`; what that changes is
owned by the
[invocation-context rubric](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/conventions/invocation-context/README.md)).
`$ARGUMENTS` (an optional path) and the working tree are the whole input.
## 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](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; check each
subagent's evidence before accepting its verdicts, then consolidate them into the one Phase 3 report.
## 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](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. Also record each parameter schema's `x-mcp-header` value, if any (C20). Load the detailed checklist from [reference/checklist.md](reference/checklist.md).
Once per server, also resolve its `instructions` field. See **Server instructions** in
[reference/server-discovery.md](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:
```markdown
# 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 rather than 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"`, so 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). Likewise an absent `x-mcp-header` passes, and only a
declared one that breaks the spec's constraints can FAIL (C20).
## 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.
- Does not judge whether the servers in your Claude Code configuration are safe to run (floating
versions, publisher provenance, local stdio versus remote). Use `/mcp-tools:audit-posture` for that.
Files in this package (12)
- SKILL.md 8 KB
- evals/evals.json 10 KB
- evals/fixtures/meta-annotations.md 3 KB
- evals/fixtures/over-length-description.md 7 KB
- evals/fixtures/server-with-resource.md 1 KB
- evals/fixtures/tools-with-defects.md 2 KB
- evals/fixtures/well-designed-tool.md 1 KB
- evals/fixtures/x-mcp-header.md 3 KB
- reference/checklist.md 19 KB
- reference/server-discovery.md 6 KB
- scripts/discover.sh 8 KB
- scripts/discover.test.sh 7 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · melodic-software/claude-code-plugins | 84 | MIT |
| marcel-bich/marcel-bich-claude-marketplace | 100 | MIT |
| jeremylongshore/tons-of-skills-marketplace | 100 | MIT |
| friendlyinternet/nuxt-crouton | 100 | MIT |
| userKael/rastro | 100 | MIT |
| Archont561/qgis-agent-harness | 100 | MIT |
| lilly-logic-labs/lll-skills | 100 | MIT |
| Come-In-Labs/agent-skills | 100 | MIT |
| minanyang/10x-agent | 100 | MIT |
Database snapshot: 13.11.2026 · package version ca564777d5f1 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100tool-design-checker
Grades MCP tool definitions the way a model reads them: a clear purpose, described parameters, safe annotations such as readOnlyHint, and the token size of every tool. Use when an author wants to lint, grade, or review an MCP server's tools, tool descriptions, or input schemas… - 90audit-discoverability
Audit whether agents would find and pick an AI plugin or MCP server when a user asks: how its listing and MCP tool descriptions answer target prompts, with a labelled simulated pick against rivals. Use when asked to audit a plugin or MCP server, when agents ignore a plugin, to… - 100mcp-tool
Optimize the tool surface of an EXTERNAL MCP server — one the agent talks to but does not implement. Use when an agent wired to an MCP server mis-selects tools, fills arguments wrong, or is offered a noisy 40-tool set it mostly ignores. Covers MCP tool descriptions,… - 100eval-mcp
Measures whether Claude uses an MCP server's tools correctly — tests tool selection accuracy, analyzes schema quality, and iteratively optimizes descriptions. Triggers when the user asks to "evaluate MCP tools", "test tool selection", "improve tool descriptions", "check MCP… - 100mcp-tool-naming-description-design
Use this skill when designing intuitive tool names, trigger-rich descriptions, and parameter contracts so LLMs select tools accurately. - 100tool-design
Design tool interfaces for LLM agents — descriptions, parameter schemas, error messages, granularity, and composition. Use when creating function calling tools, building MCP servers, designing agent tool interfaces, writing tool descriptions, or debugging why a model calls the…