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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds behavior annotations cannot express: pagination size, sort order, and a nuanced permission model where non-whole-book members see only email linked to their assigned clients plus unlinked email. That access-scoping disclosure materially changes how an agent interprets an empty result set.

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?

Front-loads purpose and scope before the field list and filters, with no filler sentences. The parenthetical field/classification enumeration is dense but each item informs the agent what it can expect back; a tighter phrasing could have cut a few words without loss.

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?

An output schema exists and the description still previews the payload shape adequately, and the permission scoping is covered, which is the main hidden risk here. The gaps are firm_id's role and the exact pagination contract (default page, how to detect the last page).

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 0%, so the description has to carry the load, and it does for most parameters: it supplies the full enum vocabularies for priority and category (which the schema lacks entirely) and explains client_id filtering. It leaves firm_id and the page parameter's mechanics (beyond '25 per page') undocumented, so one of five parameters is unexplained.

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?

Opens with a specific verb+resource ('List email messages synced from your firm's connected mailboxes') and immediately scopes it with ordering and page size. The returned-field list and the filter surface make it clearly distinct from get_email_detail (single message) and link_email_to_client (mutation) among the siblings.

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?

Gives concrete operating context: newest-first ordering, 25 per page, the filters available, and the visibility rule for members lacking the whole-book role. It does not explicitly route the agent to a sibling (e.g. 'use get_email_detail for the full body'), so the when-not/when-alternative half 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.