lineage_list

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

Annotations already carry the read-only safety profile (readOnlyHint=true, destructiveHint=false), so the description nicely layers on the pagination envelope ({items, next_cursor}) and the supersedes-edge retirement mechanic behind current_only — behavior not visible from any structured field. It stops short of stating ordering guarantees or pagination maximums, hence a 4 rather than a 5.

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?

Three dense sentences with clear structure: what's listed, the return envelope, and the boolean flag behavior. The "willow...recorded story" metaphor is the only ornamentation and it's brief; otherwise every clause 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?

For a 4-parameter, no-output-schema list tool this covers the essentials: purpose, field list, return shape, pagination, and the key filter. But the undocumented required app_id and limit bounds are real holes, and since no output schema exists, mentioning ordering or error semantics would have meaningfully improved completeness. Adequate, with clear gaps.

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?

With schema description coverage at 0%, the description must fully carry parameter documentation, but it only addresses current_only (and implies cursor usage via next_cursor). The required app_id parameter is never explained, and limit has no bounds or semantics noted — a significant gap given no fallback help exists in the 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?

"List recorded lineage atoms (id, title, whether current, tags)" is a specific verb+resource statement with an inline field list, immediately telling an agent what result to expect. The "index of what parts of this willow have a recorded story" provides a shorthand mental model, though the product-name metaphor is slightly cryptic and the description never names a sibling for contrast, keeping it from a 5.

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 states when the tool is appropriate: it's "the index" for enumerating recorded lineage atoms, with an explicit pagination contract and a documented boolean switch ("Pass current_only=True to hide atoms that a later supersedes edge has retired"). It gives clear context for common call patterns but doesn't state exclusions or mention alternatives like lineage_why/lineage_link, so it misses the explicit when-not-to-use guidance needed for a 5.

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