catalog

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

Annotations already indicate readOnlyHint=true; description reinforces 'Read-only, no side effects' and adds return format (JSON grouped by priority). No contradictions. Adequate but does not disclose additional traits like rate limits or authentication, which are likely irrelevant for this simple listing tool.

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?

Four sentences, front-loaded with purpose and safety, then output format, usage guidance, and alternatives. Every sentence adds value; no 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?

Covers all essential aspects: what it does, what it returns, when to use, and alternatives. No output schema or parameters exist, so no gaps remain.

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?

No parameters exist (schema coverage 100% with empty schema). Description does not need to add meaning. Baseline 4 for zero-parameter tool.

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 the tool lists commands organized by priority categories. Uses specific verb 'list' and resource 'commands', and distinguishes from sibling tools like 'tool-list' by noting it returns human-readable priority groupings.

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?

Explicitly tells when to use (discover full command surface by functional area) and when not to (LLM function-calling context, recommending 'tool-list' instead). Also references sibling tools 'tool-list' and 'coreutils'.

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