get_pending_events

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

Without any annotations, the description carries the full burden of behavioral disclosure. It explicitly says 'Return and clear', revealing that calling this tool consumes/destroys the events. It also explains the empty-array behavior for missing extension or no new mail. This is transparent about the side effect and edge cases, though it could go further to mention whether clearing is atomic or per-user.

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 description is three sentences long, front-loaded with the core action, and contains no redundant or filler text. Every sentence adds critical information: the action, the empty-array condition, and the event fields. This is an appropriately sized and well-structured description.

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 zero-parameter tool with no output schema, the description is complete: it explains the return value (list of events with fields), covers the edge case of no extension/no mail, and clearly conveys the tool's purpose. There is no missing information that would prevent correct invocation or interpretation.

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?

The tool has zero parameters, so the input schema provides no additional meaning. According to the rubric, baseline for 0 params is 4. The description appropriately adds no unnecessary parameter details and instead focuses on the return value structure, which is more relevant here.

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 clearly states a specific action ('Return and clear') on a distinct resource ('real-time incoming mail events') pushed by the MailKit extension. This distinguishes it from siblings like list_emails or search_emails, which operate on regular email messages rather than event streams.

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 clear context: it is for polling real-time events from the MailKit extension, with an explicit statement about the empty-array case when the extension is missing or no new mail arrives. It does not explicitly mention alternatives, but the resource type (events) is sufficiently distinct from the sibling email/rule tools, making the usage context clear.

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