claude-skill-validator

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden. It discloses the read-only nature by saying 'parse and validate' and explicitly mentions return values ('parsed fields and any rule violations'). It could be more explicit about no side effects, but the described actions are inherently non-destructive and output is clarified.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences front-load the purpose, then return behavior, then usage guidance. There is no redundant wording or filler, making it tightly packed and effective.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple (one param, no output schema, no annotations), and the description covers purpose, output, and when to use it. It lacks detail on specific violation categories, but for a linter of this scope, the return summary is adequate and complete enough for an agent to invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the parameter is well-documented. The description adds domain context by specifying 'Claude Skill' frontmatter and clarifying scope ('only'), which enriches the schema beyond raw syntax. It does not add format details beyond the schema, but the additional context earns above baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it 'Parse[s] and validate[s] only the YAML frontmatter of a Claude Skill,' using a specific verb and resource. It also distinguishes itself from siblings like validate_skill by scoping to frontmatter only.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description says 'Use during iterative authoring,' providing a clear usage context. However, it does not explicitly name alternatives or exclusions; the word 'only' implies a narrower scope than full-skill validation but a direct sibling reference would strengthen it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the transparency burden. It discloses that the tool scans for specific security issues and returns findings with excerpts, but it does not explicitly state whether the scan is read-only, requires authentication, or has limitations. It adds some value but not comprehensive behavioral detail.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences front-load the purpose and output. Every piece of information earns its place, with no redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter tool with no output schema, the description covers the main purpose and states that it returns findings with excerpts. It could be more specific about the structure of findings, but it is sufficiently complete for an agent to select and invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single 'skill_md' parameter, so the schema already documents its meaning. The description does not add further semantic detail about the parameter itself, only naming target threats, which is not directly about the parameter's format or usage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Scan') and a clear resource ('Claude Skill') while enumerating precise scan targets (dangerous shell commands, hardcoded secrets, prompt-injection phrases). This clearly distinguishes it from sibling tools like lint_frontmatter, score_skill, and validate_skill.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context for when to use the tool (security scanning of skills) but does not explicitly state exclusions or alternative tools. It is evident that this is for security analysis rather than linting or scoring, but there is no direct 'use this instead of X' guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description must disclose behavior. It states the output (score and gate) but does not explain what 'full validation' entails, whether any side effects occur, or what determines the gate. Given the read-only nature of validation, it leaves users guessing about details like error handling or limitations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences long and front-loaded with the core action and output. Every clause adds value—'0–100 score' and 'ship gate' specify the result, while 'Minimal payload suitable for CI/CD pipelines' provides context. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a relatively complex tool (full validation, multiple parameters, ship gate logic) with no annotations and no output schema. The description covers only the high-level purpose and one usage context, leaving out parameter details, gate criteria, and validation scope, making it inadequate for a complete understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is low (33%), with only skill_md described. The description adds minimal parameter context via 'Minimal payload,' implying skill_md is the key input, but it does not explain the purpose or format of tools and allowed_tools. The description fails to compensate for the schema's gaps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Run full validation and return a 0–100 score plus a ship gate (pass/review/fail).' This uses a specific verb ('run'), names the resource (skill validation), and uniquely identifies the tool among siblings by mentioning the score and ship gate output.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear usage context: 'Minimal payload suitable for CI/CD pipelines.' This implies when to use the tool (in automated CI/CD), though it does not explicitly discuss alternatives or when not to use it. The CI/CD context is a useful signal for selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly describes what the tool does and what it returns (score, gate, structured errors/warnings), which is transparent. It does not disclose scoring thresholds or potential side effects, but validation is inherently read-only, so this is a minor gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence leading with 'Fully validate' and then enumerating the checks and outputs. There is no redundancy or extraneous information, making it highly concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that there is no output schema, the description does a good job of explaining what the tool returns (score, gate, errors/warnings) and what it validates. It could be more complete by explaining the gate logic or noting that the tool does not modify the file, but overall it provides sufficient context for a validation tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already provides 100% description coverage for all three parameters (skill_md, tools, allowed_tools), so the description does not need to add parameter-specific detail. The description adds context about the tool's overall purpose but does not enhance understanding of individual parameters beyond what the schema provides, matching the baseline for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: to fully validate a SKILL.md file, and specifies the exact checks it performs (frontmatter rules, body quality, security scan, tool collision) as well as the return format (score, gate, errors/warnings). This distinguishes it from sibling tools like lint_frontmatter or scan_security, which focus on isolated aspects.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies this is the comprehensive validation tool ('Fully validate') while siblings handle specific checks, giving clear context on when to use it. However, it does not explicitly state when not to use it or mention alternatives, so it stops short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.