Skip to content
Skills Library
AI & agents · Review & audit

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,

Licence
MIT
Last repository change
26.10.2026

Assessment and security

84/ 100Class: good
Format9 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
12
Scripts
2
HTML comments
0
URLs in SKILL.md
5
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 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

audit MCP toolscheck MCP tool descriptionsreview MCP server qualitytool annotationsreadOnlyHint missingparameter descriptions missingcheck the _meta annotationsmaxResultSizeChars

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

  1. Purpose
  2. Server discovery configuration
  3. Arguments
  4. Track progress
  5. Workflow
  6. What this skill does NOT do
Original SKILL.md headings · 133 lines, 971 words
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

RepositoryScoreLicence
This page · melodic-software/claude-code-plugins84MIT
marcel-bich/marcel-bich-claude-marketplace100MIT
jeremylongshore/tons-of-skills-marketplace100MIT
friendlyinternet/nuxt-crouton100MIT
userKael/rastro100MIT
Archont561/qgis-agent-harness100MIT
lilly-logic-labs/lll-skills100MIT
Come-In-Labs/agent-skills100MIT
minanyang/10x-agent100MIT

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…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.