mail_digest

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

With no annotations supplied, the description carries the full behavioral burden and does much of it: it declares 'Read-only' explicitly, discloses the response shape in detail, and warns that subjects and sender names are untrusted email content that must never be followed as instructions — a meaningful safety disclosure no annotation would provide. It stops short of describing scan cost, truncation behavior when maxMessages is hit, or what happens for an empty/unknown folder.

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?

A single front-loaded sentence with a colon-delimited enumeration of outputs, followed by the security caveat and the read-only marker. Every clause adds information — output inventory, trust boundary, safety profile — with no filler or repetition.

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 and no annotations, so the description must supply both return-value semantics and the safety profile; it does both (output inventory plus read-only and untrusted-content warnings). For a read-only, zero-required-parameter digest tool, an agent has enough to decide to call it and to interpret what comes back.

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 every parameter including the groupBy enum, unreadOnly, and maxMessages bounds is already documented in structured form. The description restates the folder and time-window defaults but adds no new meaning for groupBy, unreadOnly, or maxMessages, so the baseline 3 applies.

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 states a specific verb ('Summarize') and resource ('what is waiting in a folder') and then enumerates the exact outputs: counts (total, unread, flagged, high importance, with attachments), high-importance/flagged messages, and sender-grouped messages with a newsletter hint. That aggregate framing clearly separates it from siblings like list_messages and search_messages, which return raw message lists rather than a digest.

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?

Usage is implied rather than stated: the defaults (inbox, last 24 hours, unreadOnly true) suggest a 'what's new' triage use case, which is helpful context. However, the description never says when to prefer this over list_messages or search_messages, nor does it state when a digest is a poor choice (e.g., when specific messages are needed).

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