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

Annotations only provide readOnlyHint: true, so the description carries most of the behavioral burden. It clearly discloses the tool is read-only (lists, doesn't modify), explains the bounded default to avoid returning thousands of items, describes the recency windows for resolved and shelved rows, and notes cross-agent behavior (shared operator sees only shared agent). This is rich context beyond the annotation's basic hint, but does not mention any external side effects beyond read-only nature, so a 4 is warranted (would be 5 if it explicitly stated no side effects, but readOnlyHint covers that).

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 long but information-dense, with a summary section followed by a detailed returns section. It front-loads the core purpose and use cases. Every sentence adds new information (channels, bucketing, node_id, pagination). The length is justified by the tool's complexity, but it could be slightly more compact without losing key details.

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?

Given the complexity of the output (nested dict, buckets, previews) and the fact there is no output schema, the description thoroughly explains the return structure, including the difference between default mode and drill-down mode, the meaning of `preview_truncated`, and the semantics of `target_provider_id`. It also covers edge cases like cancelled drafts not appearing in recently_resolved. An agent can fully understand how to call and interpret results without additional info.

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 the schema already documents all parameters. However, the description adds significant context: describes when to use `bucket` for drill-down, that `offset` is ignored without `bucket`, and that `as_teammate` requires consent. It also explains the default recency window for `resolved_within_days`. This adds value beyond the schema descriptions, which are brief. Since coverage is high, baseline is 3, but the extra context justifies a 4.

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 explicitly states it lists pending approvals, the same rollup as the home page, and covers four channels. It clearly distinguishes from other tools by focusing on what's waiting on the user, and even mentions related tools like request_user_action and get_outreach_approval implicitly. The verb (list) and resource (pending approvals) are specific.

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 explicit use cases: 'what's waiting on me?', checking if a manual action was handled, whether a draft was shelved. It also explains when to pass `bucket` for drill-down versus using the default preview. It implicitly contrasts with alternative tools like get_outreach_approval or manage_inbox, noting this is the rollup view.

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