intercom_pending

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

Annotations already declare openWorld, idempotent and destructive behavior; the description adds genuinely new context beyond them, namely the waiting semantics, that the wait does not end the Codex turn, and that plain MCP cannot wake an idle turn. It does not, however, explain that mark_read permanently clears unread state, which is the likely source of the destructiveHint.

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?

Purpose is front-loaded in the first sentence, followed by increasingly specific usage notes; four sentences carry distinct information. Slightly jargon-heavy (Codex turn, coi) but every sentence 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 two-parameter read-with-wait tool and no output schema, the description covers purpose and the waiting workflow well but omits the shape of what is returned (messages vs. asks, counts) and the mutating effect of mark_read. Adequate but with clear gaps given no output schema to lean on.

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 50%: wait_ms is documented in the schema, mark_read is not. The description adds usage intent (wait_ms: 60000 to wait for incoming completion reports, mark_read: true alongside it) but never states what mark_read actually does as a side effect, leaving the undocumented parameter only partially compensated.

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?

Clear specific verb+resource: "Read unread inbound messages and unresolved asks" tells the agent exactly what the tool returns (pending inbox items). It does not, however, differentiate itself from siblings like intercom_list or intercom_status, so an agent must infer why 'pending' is distinct.

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?

Provides explicit situational guidance: use wait_ms: 60000 and mark_read: true when awaiting delegated results, and repeat after a timeout while results are still required. It also names an alternative mechanism (coi for automatic wake-on-message), though it does not mention sibling tools as alternatives or state when not to use it.

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