list_refinements

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile needs no restating. The description adds genuinely new behavioral context: a prohibition on ambient polling and a gating rule requiring an unambiguous user decision before the accept/reject siblings are invoked. It stops short of describing ordering or what an empty queue looks like.

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 sentences, front-loaded with the primary rule and the anti-polling prohibition before the mechanics. Dense and nearly waste-free, though the 'filter by action and bound with limit' clause largely duplicates schema text.

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 two-param read-only list tool with no output schema, the description supplies the missing return-value hint ('typed actions and payloads, including vocab_promote') and the critical workflow gating. Only the empty-result and ordering semantics remain unstated, a minor gap given how much annotations and schema already carry.

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 coverage is 100%, so both parameters are already fully documented, including the accepted action values and the 500 default/max. The description only restates 'Filter by action and bound the result with limit' and adds no syntax or format detail beyond the schema, making baseline 3 appropriate.

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?

States a specific verb and resource ('List pending daemon refinement proposals') plus the payload shape ('typed actions and payloads, including vocab_promote'). It does not explicitly name the confusable siblings (list_pending, list_pending_revisions, list_pending_imports), so differentiation relies on the word 'refinement' alone.

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 says when to use ('only when the user explicitly asks to inspect or review the proposal/refinement queue'), when not to ('never poll this queue ambiently'), and what to pair it with afterwards ('accept_refinement or reject_refinement only after an unambiguous item-level user decision'). This is a full when/when-not/next-step specification.

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