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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is settled. On top of that the description discloses grouping, sort order, the per-group fields returned and the scope switch, and notably explains that the response carries `asOf`, which tells the agent the read-state picture is a point-in-time snapshot rather than a live count — a real behavioral fact not present in the 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?

Three sentences, no filler, and the key identity of the tool is front-loaded before the scope and exclusion clauses. The closing sentence about `asOf` is short and earns its place, though it could have been folded into the first sentence's description of the result.

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?

There is no output schema, so the description carries the burden of describing the return, and it does so adequately: grouping key, ordering, per-group fields and the `asOf` timestamp. Pagination semantics are left entirely to the schema and no total-count or empty-state behaviour is mentioned, which is a minor gap rather than a blocking one.

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 100%, so limit, offset and jobDescriptionId are already documented with defaults, bounds and purpose. The description restates the two scopes (whole account vs. one job position) that jobDescriptionId already expresses, and says nothing about paging behaviour or limits. With the schema doing the heavy lifting, this sits at the baseline.

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 a specific verb and resource ("List the unread email replies from candidates") and immediately fixes the shape of the result: grouped by candidate, most recent first, with unread count, latest subject and preview. It also carves out an explicit scope (whole account or one job position) and an explicit exclusion (WhatsApp messages carry no read state), so an agent can distinguish it from the other listing and search tools without opening the schema.

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 for use: it returns unread candidate replies only, and it states the channel restriction ("Only email replies have a read state; WhatsApp messages are not included"), which prevents a plausible misuse. It does not, however, route the agent to a companion tool such as mark_messages_read for the follow-up action, so the sibling relationship is left to inference.

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