Server Quality Checklist

Tool Scores

• inventory_skillsA
  3.5/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description redundantly restates 'Read-only' but adds useful context about what the tool reports (duplicate names, read errors). It doesn't contradict annotations.

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

  Conciseness4/5

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

  Two concise sentences that efficiently convey the tool's purpose and outputs. The 'Read-only' clarifying note is slightly redundant given the annotations but harmless. No wasted words.

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

  Completeness4/5

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

  For a single-parameter, read-only, idempotent tool with a fully-covered schema, the description covers the essential behavior adequately. It describes what gets indexed and what summaries are produced. Could mention the format of the summary output, but given zero params required and no nested objects, this is complete enough for an agent to use confidently.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the single parameter (includeDuplicatePaths) is fully documented in the schema itself. The description mentions 'duplicate names' as an output, which loosely relates to the parameter, but the schema already explains it clearly. Baseline 3 is appropriate when the schema handles parameter documentation.

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

  Purpose4/5

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

  The description states a specific verb ('Index') with a clear resource ('installed SKILL.md files') and enumerates the specific outputs (roots, invocation modes, duplicate names, read errors). This distinguishes it well from sibling tools like search_skills and recommend_skills, though it doesn't explicitly name them.

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

  Usage Guidelines3/5

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

  The description implies this is an administrative/inspection tool and states it is 'Read-only,' but it doesn't explicitly say when to use it over alternatives like search_skills or explain_skill. The context is clear enough for an agent to infer it's for inventorying installed skills vs searching/recommending, but no explicit exclusions are given.

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

• recommend_skillsA
  3.6/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds value by disclosing the advisory-only semantics and that additional candidates are retained (not filtered out or hidden), which is a meaningful behavioral trait. However, it doesn't describe return format, ordering, or how limits interact across sections beyond the schema's param descriptions.

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

  Conciseness4/5

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

  Two sentences, both earning their place. The first states the core purpose and the second clarifies the critical advisory/non-hiding behavior. No filler or repetition of what schema/annotations already provide. Loses one point only for not front-loading a strong verb phrase more prominently.

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

  Completeness4/5

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

  For a non-destructive, advisory tool with excellent annotations and 100% schema coverage, the description is appropriately complete. It covers purpose, scope (installed skills), and key behavioral caveat (advisory only, candidates not hidden). No output schema exists, so return values aren't specified, but for a recommendation tool the structure is reasonably inferable from the schema coverage. Complete enough for safe invocation.

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

  Parameters3/5

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

  Schema coverage is 100%, so the schema already documents all three parameters (task, primaryLimit, candidateLimit) with descriptions. The description adds marginal value by clarifying these are installed skills and that candidates aren't hidden. Baseline 3 is appropriate since the schema carries the parameter documentation burden adequately.

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

  Purpose4/5

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

  The description clearly states the verb 'recommend' with specific resources (primary, complementary, additional skills) for a task. It differentiates from siblings like inventory_skills (listing) and search_skills (finding specific skills) by framing the deliverable as a curated recommendation flow rather than raw enumeration. Could be slightly stronger by naming that it works across 'installed skills' explicitly versus search across all.

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

  Usage Guidelines4/5

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

  The description provides clear context of when to use this tool (for a task needing skill recommendations) and importantly clarifies the advisory nature — the agent retains final decision and candidates aren't hidden. It implicitly distinguishes from siblings (inventory lists skills plainly, search finds specific ones) though it doesn't explicitly name alternative tools. A clear when-to-use context with implied exclusions merits a solid score.

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

• explain_skillA
  4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds valuable context beyond annotations by clarifying the tool does not execute the skill or dump its full prompt, and that it requires an exact match. This effectively communicates key behaviors without contradicting the annotations. It doesn't address error behavior for non-existent skill names or exact-match failure cases, which would push it to a 5.

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

  Conciseness5/5

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

  The description is a single concise sentence front-loaded with the primary purpose, followed by two clarifying exclusions. Every word earns its place, with zero filler. This is an exemplar of efficient, well-structured tool documentation.

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

  Completeness4/5

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

  For a read-only metadata lookup tool with a single parameter, strong annotations, and no output schema, the description is largely complete. It covers the core function and what it deliberately avoids (execution, full prompt dump). Minor gap: it doesn't describe what a failed lookup (nonexistent name) returns, which could matter for an agent handling errors. With simple tool complexity, this is near-complete but not exhaustive.

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

  Parameters3/5

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

  Schema description coverage is 100% (the single 'name' parameter is documented as 'Exact skill name' in the schema itself). The description adds marginal value by reinforcing the 'exact' constraint on the name, but since the schema already documents the parameter fully and there's only one trivial string parameter, the baseline 3 is appropriate.

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

  Purpose4/5

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

  The description uses specific verb+resource ('Return metadata and duplicate locations for an exact installed skill name') and clearly distinguishes behavior from related operations by stating 'without executing it or dumping its full prompt.' This effectively differentiates from sibling tools like search_skills which imply broader search. However, 'metadata' is somewhat vague about what specific attributes are returned, and the exact distinction from siblings like inventory_skills could be sharper.

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

  Usage Guidelines4/5

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

  The description implies usage context by specifying 'exact installed skill name' and clarifying it does NOT execute or dump full prompts, which guides an agent toward when this tool is appropriate versus inventory (listing all) or search/recommend (finding). However, it doesn't explicitly name alternative sibling tools or give explicit 'when/when-not to use' guidance, 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.

• search_skillsA
  4.2/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds 'deterministically' (implying stable, reproducible results) and 'scored candidates and reasons' (informing the agent about output shape), which enriches behavioral understanding beyond the annotations.

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

  Conciseness5/5

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

  Two sentences, zero waste. Each phrase earns its place: 'deterministically' conveys behavior, 'scored candidates and reasons' conveys output, and 'without choosing for the agent' conveys role boundary.

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

  Completeness4/5

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

  For a simple 2-param read-only search tool with 100% schema coverage and no output schema, the description adequately covers purpose, behavior, and output shape. It could mention return format expectations (e.g., result ordering) but is largely complete for the tool's complexity.

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

  Parameters3/5

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

  Schema description coverage is 100%, so both query and limit parameters are already well documented in the schema. The description doesn't add semantic detail beyond what the schema provides, but it does clarify the deterministic scoring/reasons output. Baseline 3 is appropriate given full schema coverage.

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

  Purpose5/5

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

  The description clearly states it searches installed skills 'deterministically by task terms.' It emphasizes that it returns 'scored candidates and reasons without choosing for the agent,' which defines its scope precisely. This distinguishes it from siblings like recommend_skills (which presumably chooses/recommends) and inventory_skills (which lists).

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

  Usage Guidelines4/5

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

  The phrase 'without choosing for the agent' implies the tool returns candidates for agent review rather than auto-selecting, which gives a clear usage context. However, it doesn't explicitly state when to prefer this over recommend_skills or inventory_skills, nor provides any when-not-to-use exclusions.

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