envelope_pending_read

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

Annotations already cover read-only and non-destructive safety, so the description adds real behavioral value: oldest-first FIFO draining, expansion of precedent_ids into precedents_expanded, and the notable edge case that unresolved precedent IDs are 'silently dropped from the expansion' while precedent_ids 'stays intact as tamper evidence.' This discloses behavior an agent could not infer from annotations or schema.

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 front-loaded with the core purpose in the first two sentences, then moves to usage context and parameter detail. The third paragraph is substantive but slightly ornate ('two-hop dance', 'that's what turns a ratify into one glance'), and the design-doc pointer adds minor navigational value. It earns its length given the non-obvious include_precedents behavior, but a sentence or two could be trimmed.

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 read-only list tool with annotations covering safety, the description covers purpose, ordering, the complex parameter's behavior, an edge case, and a design-doc reference. With no output schema, a brief statement of the overall return shape would tighten completeness, and limit semantics are absent. These are minor gaps against an otherwise thorough definition.

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 carries the full burden for parameters. It richly explains include_precedents (default True/PR10, what the expansion produces, and the silent-drop caveat) and implicitly covers oldest_first via the FIFO ordering statement. However, the limit parameter is never mentioned or justified, leaving one of three parameters undocumented.

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 first sentence states a specific verb and resource: 'List envelope PROPOSALS awaiting operator ratification.' It distinguishes itself from the sibling envelope_list by framing this as the operator's queue view and by referencing the 'two-hop dance through envelope_list' that this tool avoids. The FIFO ordering and read-only nature are also stated upfront.

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 gives clear context: this is 'the operator's queue view for the accrual loop' and points to a design doc. It implicitly contrasts with envelope_list (the two-hop alternative) and explains when the include_precedents expansion matters ('turns a ratify into one glance'). However, it never explicitly states when NOT to use it or which sibling to prefer for other listing needs, so the routing guidance is strong but implicit.

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