list_docs

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

There are no annotations, so the description carries the burden. It discloses that this is a comprehensive listing operation ('List every'), how the output is organized by section, and that passing the source parameter filters to one half. It also explains the provenance of the webpage and Rust API docs, which is useful behavioral context. The description does not mention side effects because it is inherently read-only, and that is reasonably inferred from the verb 'list.'

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 concise: one clear first sentence and one short paragraph providing the corpus organization details. Every sentence adds meaningful information about what the tool lists and what the source parameter controls. No filler or redundant phrasing is present.

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?

With one optional parameter and no enums, the description covers the tool's purpose, the parameter semantics, and the default behavior. The presence of an output schema means return value details need not be documented in text. The only minor gap is that the set of accepted source values is not given as an explicit enumerated list, but it is clearly inferable from the prose, so overall the context is complete enough for an agent to call the tool correctly.

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 schema provides only a string parameter named 'source' with no description or enum, and schema description coverage is 0%. The description fully compensates by naming the two possible halves ('website' and 'rust-api'), explaining that the default combines both, and instructing 'Pass source to see one half alone.' This gives the agent concrete parameter values and semantics beyond the raw schema.

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 explicitly states the tool's function: 'List every Apache Iggy documentation page, organised by section.' This is a specific verb and resource, and the detail about the two corpus halves ('website' and 'rust-api') clarifies the scope. The strong contrast with sibling tools like get_doc or search_docs is evident, so an agent can distinguish it without looking at others.

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 explains how to use the tool, especially the source parameter and that the default lists all pages. It gives clear context about the two subsets of the corpus, but it does not explicitly name alternative tools or state when not to use this one. Still, the guidance is sufficient for a listing operation where no heavy alternative-picking logic is required.

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