Find conversations awaiting a reply

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses the exclusion rules (automatic replies, mailing lists, self-only mail), the closing condition (human replies), the fact that results carry evidence and may report incomplete coverage, and that snapshots expire after five minutes. It also states explicitly that no message is sent and no reminder is created, which preempts the most likely misreading of a 'follow-up' tool.

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 purpose leads, followed by the important caveat and then operational constraints, so the front-loading is correct. The prose is dense and slightly telegraphic ('Results name their evidence and incomplete coverage'), but every clause carries operational information; nothing is padding.

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 heuristic detection tool this covers the essential ground: what counts as a conversation, what is excluded, what the results signify, that coverage may be partial, and that snapshots are short-lived. The existence of an output schema removes any need to describe the return shape. The only real hole is account_id and the absence of any guidance on what to do when coverage is reported incomplete.

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% across five parameters, so the description must carry the load; it does so for four of them by mapping the 30-day default to lookback_days, the seven-day default to waiting_days, and explaining that continuation uses only cursor and limit. account_id is never mentioned, leaving one parameter entirely undefined in both schema and prose, which keeps this below 5.

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 opening sentence names a specific verb and resource ('Find possible follow-ups') and explains the detection basis (outgoing mail plus indexed reply headers), which is far more informative than the title alone. No sibling tool is named as an alternative or contrast, so it stops short of the 5 bar, but no sibling in the list overlaps this function so the agent will not confuse it with mail_search or search_conversation.

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 states the default operating window (last 30 days, waiting at least seven days) and issues a clear caution that a candidate is not proof a reply is required, which sets the correct expectation for use. The closing line 'Continue with only cursor and limit' tells the agent how to paginate. It does not explicitly route to alternatives for related tasks (e.g. mail_search for a specific thread), so 4 rather than 5.

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