List Cisco Network Icons

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.

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.

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.

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.

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.

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.