browse_manual

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively communicates that this is a cheap, non-destructive orientation tool ('Cheapest way', 'list sections'). It discloses what it filters by and discloses its return granularity (sections/headings, not full passages). The depth is good given zero annotation coverage.

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 compact, front-loaded with the core purpose, and every sentence earns its place. The strategy framing (cheapest, recovery move) and sibling comparison are woven into two tight lines, followed by a minimal Args block. Zero waste.

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?

For a simple 3-parameter browsing tool with an output schema present, the description is complete. It explains what it does, why to use it, when to prefer it over the key sibling, and clarifies all parameter semantics. The presence of an output schema relieves it from describing return values. Nothing material is missing.

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 0%, so the description must compensate for all three parameters. It does: 'query' gets keyword-filter semantics (section headings and page titles), 'family' gets an operator-family filter with the enumerated options, and 'limit' gets maximum-section semantics. This fully compensates for the 0% coverage, though exact value formats aren't elaborated.

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 clearly states a specific verb+resource ('list page sections') with a defined scope ('to orient before retrieving full passages'). It distinguishes itself from siblings by positioning it as a discovery/browsing tool versus search_manual. The 'L0' prefix and vocabulary-discovery framing make its purpose unmistakable.

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 explicitly compares to search_manual ('Prefer this over search_manual when you need the shape of a topic rather than a specific answer'), giving a clear when-to-use directive. It also states the recovery use case ('best recovery move when a search misses'). It doesn't discuss when NOT to use it relative to read_page, but the when-to-use guidance relative to the key sibling is strong.

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