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

Beyond the readOnlyHint and idempotentHint annotations, the description explicitly states that the tool never installs packages, loads plugins, fetches remote instructions, or executes code, and that it only returns curated static metadata. It also advises checking release and verification status, adding actionable behavioral context.

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?

The description is dense but efficient: purpose, output contents, safety boundaries, and a usage caveat are each covered in a single sentence. There is no filler or redundant repetition of schema fields.

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?

There is no output schema, but the description compensates by listing the full range of returned metadata (IDs, descriptions, source links, versions, requirements, installation instructions, examples, citations, share links) and by clarifying execution behavior. Nothing essential is missing for an agent to invoke and interpret this no-arg catalog tool.

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?

The tool has zero parameters, so schema coverage is trivially 100%. The baseline for zero-parameter tools is 4, and the description appropriately focuses on output rather than parameter details.

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?

The description uses a specific action ('Discover') with a clear resource ('Gabriel's catalog of locally run command-line tools') and enumerates the returned content. This clearly distinguishes it from sibling tools like list_publications and list_playgrounds by focusing on local CLI tools.

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?

The description gives clear context: this is for discovering local CLI tool metadata, not for installation or execution. It explicitly states what the tool does not do, even though it does not name specific sibling alternatives or provide an explicit 'use this when...' rule.

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