Server Quality Checklist

Tool Scores

• cisco_list_categoriesA
  4.5/5.0
  Behavior4/5

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

  Annotations already convey readOnlyHint, idempotentHint, and destructiveHint=false, so the description doesn't need to repeat those. It adds value by describing the return JSON structure and the total catalog size (308 icons), which gives the agent useful context beyond annotations. No contradiction exists.

  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 concise and well-structured: a clear opening sentence, a usage note, and an example return JSON. It front-loads the purpose and uses compact formatting without unnecessary fluff. Every sentence earns its place.

  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 zero-parameter, read-only catalog listing tool, the description is complete. It explains the output structure (JSON with categories, labels, icon counts), the catalog's scope (308 icons), and its role relative to sibling tools. The inline JSON example compensates for the lack of an output schema.

  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?

  This tool has zero parameters, and the description explicitly states 'Args: none.' The schema is empty with 100% coverage, so there is nothing more to document. The baseline for zero-parameter tools is 4, and the description meets that adequately.

  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 lists every category from the Cisco corporate iconography catalog, including a human-readable label and icon count. It explicitly names the resource ('categories') and the verb ('list'), and it distinguishes itself from sibling tools by indicating it should be used first before calling filtered icon tools.

  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?

  Usage guidance is explicit: use this tool first to understand the catalog organization before calling cisco_list_icons or cisco_search_icons with a category filter. It provides a clear prerequisite context but does not explicitly state when not to use it, which would be a stronger when-not clause.

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

• cisco_get_iconA
  4.6/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: the image is pre-converted from CMYK to RGB (addressing rendering issues in Miro/Figma), the icons are not square (affecting scale mode), and the error message format. This goes beyond annotations without contradicting them.

  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?

  The description is well-structured with clear sections (Args, Returns, Error Handling) and is front-loaded with the core purpose. It's slightly verbose in the Returns section but every sentence adds value (e.g., the FIT vs FILL scale mode warning is important). No wasted words, but could be tightened slightly.

  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 single-parameter tool with 100% schema coverage and strong annotations, the description is complete. It covers the return format (image + metadata), the image characteristics (PNG, RGB, non-square), error handling, and usage flow. No output schema exists, so the description appropriately explains the return structure. Nothing critical is missing.

  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 100% and the schema already describes the id parameter with examples and guidance to get it from search/list. The description reinforces this with the same examples and adds the case-sensitivity note, which is a small but useful addition. Since the schema does the heavy lifting, a 4 is appropriate for the slight extra value.

  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 fetches a Cisco network icon by id, returning both metadata and the image as PNG/RGB. It distinguishes itself from siblings by specifying it's the retrieval step after search/list, and explains the image conversion from CMYK to RGB, which is unique to this tool.

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

  Usage Guidelines5/5

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

  Explicitly instructs to use after cisco_search_icons or cisco_list_icons to get the exact id, and warns not to guess ids. It also provides error handling guidance (call search first, don't retry with variations), which is clear when-to-use and when-not-to-use context.

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

• cisco_list_iconsA
  4.6/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, which the description aligns with. Description adds critical behavioral context beyond annotations: explicitly states the tool does NOT return image bytes, explains pagination mechanics with has_more/next_offset, and documents the default curated_only=true behavior. 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.

  Conciseness4/5

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

  Well-structured with purpose in the first sentence, followed by behavioral notes, args, and return format. The Args section partially duplicates the schema's parameter definitions, but each line adds small value: curated_only gets real-world examples, category gets a cross-reference, and pagination params give defaults inline. The return JSON example is valuable since there's no output schema. Slightly long but every section earns its place.

  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?

  Comprehensive for a moderate-complexity list tool. With 100% schema coverage, strong annotations, and no output schema, the description fills the gaps: it provides the return shape, pagination behavior, sibling connections, and the critical 'does not return image bytes' note. The only minor gap (missing error handling/rate-limit info) is acceptable for a read-only list operation, and the description covers all decision-relevant context the agent would need.

  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 description coverage is 100%, so baseline is 3. The description goes beyond the schema by explaining what the 29 curated icons represent (teaching/enterprise equipment with pedagogical context), clarifying the category parameter is a cross-reference to cisco_list_categories, and reinforcing default values. This adds meaningful context, particularly for curated_only where the schema's phrasing is expanded with concrete examples.

  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?

  Clearly states 'List icons from the 308-icon Cisco Systems Corporate Iconography catalog' with specific verbs (list), resource (icons from catalog), and scope (optional category filter, pagination). Distinguishes from siblings by mentioning the curated_only behavior and pointing to cisco_get_icon for image retrieval, which differentiates it from related operations.

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

  Usage Guidelines5/5

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

  Provides explicit guidance on when to use curated_only=true (teaching/enterprise network diagrams, 29 icons) vs false (full catalog). Cross-references cisco_get_icon for fetching actual images and cisco_list_categories for valid category ids, giving the agent clear routing between alternatives without ambiguity.

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

• cisco_search_iconsA
  4.7/5.0
  Behavior5/5

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

  Beyond the readOnlyHint/idempotentHint annotations, the description discloses non-obvious behavior: it never returns image bytes, returns an empty results array rather than an error on no match, includes a truncated flag, and distinguishes full catalog vs curated 29-icon scope. This is richer than the annotations alone and does not contradict them.

  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 organized into clear sections (purpose, args, returns, examples, error handling) and every sentence contributes value. The core behavior is front-loaded and the JSON return contract is useful given there is no output schema.

  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 search tool with no output schema, this description is fully self-sufficient: it explains the return JSON shape, the empty-match behavior, fallback suggestions, parameter interactions, and the relationship to sibling tools cisco_get_icon and cisco_list_categories. No critical operational detail appears to be 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 coverage is 100%, so the baseline of 3 applies. The description's Args section mostly restates schema-provided details (search term examples, default limit, category guidance, curated_only meaning). It adds convenient multilingual examples like 'roteador' and 'pedagogically-annotated' phrasing, but the schema already carries most semantic load.

  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 ('Search'), a concrete resource ('the 308 official Cisco Systems Corporate Iconography icons'), and a clear matching behavior over id, name, and description. It also distinguishes itself from cisco_get_icon by positioning itself as the metadata-search step before actual image retrieval.

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

  Usage Guidelines5/5

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

  Usage guidance is explicit: use it when the user asks what icon represents X or before assembling a diagram; don't use it when the exact id is already known since cisco_get_icon should be called directly. It also directs users to cisco_list_categories for valid category ids and clarifies the tool returns metadata rather than image bytes.

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