get_new_events

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

The description reveals cross-process deduplication via a global cursor and mentions default profile filtering. However, it does not clarify if the tool is destructive (draining may consume/delete events), nor does it discuss rate limits or auth requirements. Annotations are absent, so description carries full burden but leaves gaps.

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 two sentences, front-loading key info. Version history could be omitted or shortened, but overall efficient.

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?

With 7 parameters, no output schema, and no annotations, the description is incomplete. It does not explain what events are, how since_seconds works, what peek does, or return format. Agent lacks sufficient info to use the tool correctly.

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 14% (only profile described). The description adds context only for profile, not for other 6 parameters (event_type, event_types, chat_id, since_seconds, max_events, peek). With low schema coverage, description should compensate but fails.

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 it drains real-time events from a machine-level shared event log, distinguishes from version v1.3.8, and mentions default profile behavior. It differentiates itself from sibling tools by focusing on real-time event draining rather than CRUD operations.

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 implies usage for real-time events and hints at profile filtering ('pass profile="*" to see all'), but does not explicitly state when to use this tool vs alternatives like read_messages or list_*. No exclusion criteria or context of non-use.

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