envelope_read_discards

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

Annotations already mark the tool read-only and non-destructive. The description adds valuable behavioral context: discards are cleared on process restart, clear_auto_propose_cache() can clear them per-session or globally, and empty session_id returns all discards. No contradiction with annotations.

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 core action is front-loaded, and the later sentences add operational context rather than padding. It is slightly jargon-heavy with references like PR6, ledger.unreadable(), and 'floor', but each paragraph contributes distinct value.

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 one-optional-parameter read tool with strong annotations, the description covers scope, filtering, failure behavior, and cache-clearing semantics. It does not specify an exact return shape, but no output schema exists and correct invocation is well supported.

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 0%, so the description carries the full burden for the single parameter. It explicitly explains that empty session_id returns all discards and a specific session_id filters them.

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 names the operation ('Read'), the resource ('auto-propose discard residue'), and the scope ('current process'). It also clarifies the tool's role as a second walk that exposes both proposed and swallowed entries, distinguishing it from related envelope 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?

It explains the triggering context: PR6 auto-propose is silent on failure, so this tool lets an operator check whether the pending queue is the full picture or a floor. It does not explicitly list exclusions or alternative tools, but the use case is clearly stated.

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