Server Quality Checklist

Tool Scores

• skills_catalog_statusA
  3.6/5.0
  Behavior4/5

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

  Annotations declare readOnlyHint=true and idempotentHint=false, and the description adds useful behavioral context: refresh=true forces a rescan of skills directories. This goes beyond the schema and annotations by disclosing a potentially expensive or state-changing behavior within an otherwise read-only operation. No contradiction with 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 brief sentences with no filler. The first sentence front-loads the core purpose and returned data, and the second adds the key behavioral option. Every word earns its place.

  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?

  With an output schema present and annotations covering read-only behavior, the description is sufficient for an agent to understand the tool's role. The main gap is the undocumented include_warnings parameter, but given the low complexity and existing output schema, the description is still reasonably complete.

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

  Parameters2/5

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

  Schema description coverage is 0%, so the description must carry parameter meaning. It explicitly explains refresh=true, but it does not explain include_warnings, which is only vaguely implied by the mention of frontmatter warnings. With two parameters and one undocumented, the description only partially compensates for the lack of schema descriptions.

  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 identifies the tool as providing catalog statistics, listing specific data points (libraries, skill count, files, last scan, frontmatter warnings). It is easily distinguished from sibling tools that search, list, or fetch specific catalog items, though it does not explicitly name the verb 'get' or 'retrieve'.

  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 tool is for inspecting catalog health and statistics rather than searching or listing resources, but it does not explicitly state when to prefer it over siblings or provide exclusions. The refresh hint gives one concrete usage scenario, but overall guidance is left to inference.

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

• skills_list_skillsA
  3.9/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds useful behavioral context: results are compact name+description entries, pagination uses a cursor, and filtering is optional.

  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?

  A single, tight sentence that front-loads the core purpose, then states filters and pagination. Every clause adds useful information with no filler.

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

  Completeness5/5

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

  For a read-only listing tool with an output schema, annotations, and a simple parameter set, the description covers output shape, filtering options, and pagination. It is sufficient for an agent to invoke the tool correctly.

  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?

  With only 50% schema description coverage, the description compensates by clarifying that library and category are optional filters and that pagination uses a cursor. It does not add meaning for the limit parameter, though the schema's default/min/max constraints provide partial guidance.

  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 it lists skills as a compact catalog, with name and one-line description, and that filters by library/category are available. It distinguishes itself from get_skill and read_skill_file through the 'catalog listing' framing, though it does not explicitly contrast itself with skills_search_skills.

  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 usage for browsing/enumerating skills and points to skills_list_categories for category context, which is helpful. However, it never explicitly says when to use this list tool instead of skills_search_skills or get_skill, leaving the routing decision partly to inference.

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

• skills_read_skill_fileA
  4/5.0
  Behavior4/5

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

  The annotations already declare readOnlyHint, idempotentHint, and openWorldHint, covering safety. The description adds useful behavioral detail beyond annotations: binary files are returned base64-encoded, which materially affects how an agent consumes the response.

  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 with no filler: purpose, parameter behavior, examples, and special return encoding are all included efficiently. Information is front-loaded and every clause earns its place.

  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 two-parameter read tool with strong annotations and an output schema, the description is nearly complete. The only gap is the exact format or scope of the 'name' param, which keeps it from being fully self-contained.

  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 only 50% and the description partially compensates by explaining relative paths with examples. However, the 'name' parameter remains somewhat ambiguous ('skill name/path'), and the description does not clearly specify whether it accepts a name, a path, or both.

  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 uses a specific verb ('Read') and a clear resource ('a file bundled with a skill'), and explains the addressing scheme with concrete examples. This clearly differentiates it from sibling tools like skills_get_skill, skills_search_skills, and skills_list_skills.

  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 intended use is implied by the description and examples, but there is no explicit guidance on when to use this tool versus alternatives like skills_get_skill. For a small sibling group, an explicit 'when to use' statement would strengthen the definition.

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

• skills_get_skillA
  4.3/5.0
  Behavior4/5

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

  Annotations already mark the tool read-only and idempotent, so the description's main behavioral addition is the directive to 'follow the instructions as if the skill were installed,' which is important context for how the returned content should be treated. It also discloses that the tool returns both SKILL.md content and a bundled file list.

  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?

  Three short sentences, each earning its place: the core action, the behavioral directive to follow the instructions, and the sibling-tool routing. No filler or redundancy.

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

  Completeness5/5

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

  For a two-parameter tool with a full output schema and read-only/idempotent annotations, the description covers the essential behavior, the instruction-following expectation, and the only likely workflow question (how to read referenced files). Nothing critical is missing.

  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%: both name formats and include_frontmatter semantics are documented in the schema. The description adds no extra parameter detail beyond naming the bundled file list, so the baseline of 3 is appropriate.

  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 opens with a specific verb and resource: 'Load a skill's full SKILL.md instructions and its bundled file list.' This clearly identifies the tool's function and distinguishes it from siblings like skills_read_skill_file by noting that referenced files are handled separately.

  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 usage context—load the full skill content and follow it as if installed—and explicitly routes referenced-file access to skills_read_skill_file. It does not spell out when to prefer this over search or list tools, but the distinction is implied well enough.

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

• skills_list_categoriesA
  4.3/5.0
  Behavior4/5

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

  The description adds useful behavioral detail beyond annotations: it returns all categories, includes skill counts, and also includes value chains. The read-only and idempotent annotations already cover safety, so the description's additional output-scope details are valuable without contradicting 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?

  The description is compact and front-loaded: it states the primary output immediately, then adds the optional scoping. Every sentence earns its place with no redundancy or filler.

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

  Completeness5/5

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

  For a simple list operation with one optional parameter, a strong output schema, and annotations covering read-only/idempotent behavior, the description fully covers what an agent needs 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.

  Parameters3/5

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

  Schema description coverage is 100% for the only parameter, library, and the schema already explains it as an optional filter with a single-library-server caveat. The description's mention of optional library scoping adds nothing beyond the schema, so baseline 3 is appropriate.

  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 the tool lists all categories with skill counts and value chains, with optional library scoping. This distinguishes it from sibling tools like skills_list_skills or skills_search_skills by focusing on category-level aggregation rather than individual skill retrieval.

  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 makes the context clear: use this tool when you need a category overview with counts and value chains. It does not explicitly name alternatives or provide exclusionary guidance, but the distinction from siblings is evident from the resource type it targets.

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

• skills_list_librariesA
  4.3/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, idempotentHint, and openWorldHint: false. The description adds useful context by specifying the output contents (namespace, root directory, skill counts) and explaining that namespaces are the first segment of skill:// URIs. No contradiction with 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?

  A single sentence conveys the resource type, scope, output details, and a useful naming convention. There is no filler, and every phrase adds meaning.

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

  Completeness5/5

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

  For a parameterless, read-only tool with an output schema, the description fully covers what the tool returns and how namespaces relate to URIs. An agent has enough information to select and invoke this tool correctly without additional details.

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

  Parameters4/5

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

  With zero parameters and 100% schema description coverage, the baseline is 4. There are no parameter semantics to document, so the description does not need to compensate for any parameter gaps.

  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 uses a specific verb ('List') and resource ('skill libraries') and clearly indicates what the result contains: namespace, root directory, and skill counts. This distinguishes it from sibling tools like skills_list_skills, which would list individual skills rather than libraries.

  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 intended use is implied: call this when you need an inventory of skill libraries and their namespaces/root directories. However, there is no explicit statement of when to prefer this over alternatives such as skills_list_skills or skills_list_categories, nor any when-not-to-use guidance.

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

• skills_search_skillsA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds meaningful behavioral detail: results are ranked, and the return surface is name/description/category. This is useful context beyond the structured annotations and schema.

  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 carry the core purpose, query semantics, return fields, and the recommended workflow. There is no filler, and the most important information is front-loaded.

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

  Completeness5/5

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

  For a read-only search tool with an output schema, rich parameter descriptions, and readOnly/idempotent annotations, the description is complete. It tells the agent what to search on, what will be returned, and how to proceed to the next step. No critical missing context prevents correct invocation.

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

  Parameters4/5

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

  Schema coverage is high (80%), so the schema already documents parameters well. The description adds value by clarifying what kinds of query terms are expected ('task, keyword, or trigger phrase'), which is a semantic cue not fully captured by the schema's 'What you need to do' phrasing. It does not need to repeat every parameter.

  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 states a specific verb ('Ranked search'), a clear resource ('the skills skill library'), and the input modalities ('by task, keyword, or trigger phrase'). It also differentiates from siblings by prescribing the follow-up flow to skills_get_skill. The awkward title does not undermine the clarity of the description.

  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 clearly tells the agent when to use this tool first in a workflow ('Call this first, then skills_get_skill to load one'). It provides clear context for using search as an entry point, but it does not explicitly state when to prefer a sibling like skills_list_skills instead, so it stops short of full when/when-not guidance.

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