get_messages_summary

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

With no annotations provided, the description carries the full behavioral disclosure burden, and it delivers: declares non-mutating behavior, states it never marks messages read, discloses on-the-fly decryption under RELAY_ENCRYPTION_KEY, and lists auth requirements (agent token, own mailbox only). It even documents the content_truncated flag behavior. The only minor gap is that it doesn't describe pagination behavior for large result sets, but it defines count and limit semantics.

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?

Every sentence earns its place. The description is organized into clear labeled sections (When to use, Behavior, Returns, Errors) with zero filler. It front-loads the core purpose in the first sentence and packs behavioral and error info efficiently without redundancy. At roughly 140 words, it is dense but scannable.

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?

Considering this tool has no output schema, the description compensates fully by specifying the exact return shape (summaries array with field names, count, agent, filter, since, since_bound), the errors list, auth requirements, and behavioral guarantees. For a 5-parameter tool with no output schema and no annotations, this is about as complete as a description can be.

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 100% with rich param descriptions already (limit bounds, since format enumeration, status enum semantics, token resolution chain). The description adds value by explaining the 'same status + since filter surface as get_messages' consistency guarantee and reiterating correct when/trade-offs. While the schema does heavy lifting, the description ties the params to the preview use-case meaningfully rather than merely listing them.

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 'Cheap, non-mutating mailbox preview' with a specific verb+resource (preview mailbox) and then elaborates on exactly what it returns and when to use it. It clearly distinguishes this from the sibling get_messages tool ('which CAN mutate') and positions it as a preview vs. consumption tool. The scope is explicit: headers + 100-char content preview, never marks read.

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 provides an explicit 'When to use:' section naming orchestrators scanning multiple inboxes, dashboards rendering backlog counts, and read-only inspection flows. It also gives a clear when-not and alternative: 'After picking interesting IDs, expand them with get_messages (which CAN mutate) or read them by ID.' This directly instructs the agent on sibling selection.

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