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

The description transparently explains the mark_read behavior: 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' This adds context about state modification that is not captured by the annotations (readOnlyHint, openWorldHint, etc.). However, this disclosure contradicts the readOnlyHint annotation (which implies no state changes), so a contradiction flag is triggered.

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 concise (four sentences) and front-loaded with the main purpose. Every sentence provides unique information (fields, filtering, mark_read, poll advice). Minor casual phrasing ('Polls work fine') could be tightened, 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?

Given the 100% schema coverage, no output schema, and read-only+idempotent annotations, the description adequately covers output semantics (source, citation_uri, raw payload), filtering parameters, and the mark_read/unread_only behavior. It also mentions an alternative HTTP endpoint. It could more explicitly describe default behavior for 'limit' (schema says 50), but that is minor.

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 input schema covers 100% of parameters with descriptions, but the tool description adds meaningful usage context: for 'type' it gives an example ('sec_8k'), for 'since' clarifies format (ISO timestamp), and for 'mark_read' explains the side effect. This goes beyond the schema, though the schema already does a good job.

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 opens with 'Pull fired events from your subscription feed,' clearly stating the verb ('Pull') and the resource ('fired events from subscription feed'). It also specifies returned fields (source, citation_uri, raw payload) and filtering options, making the purpose distinct from sibling tools like 'list_subscriptions' which would list subscriptions rather than their events.

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 mentions that 'Polls work fine' and points to an HTTP endpoint for scripts/dashboards, implying lightweight polling use. However, it lacks explicit guidance on when not to use this tool (e.g., for complex queries or historical search) and does not compare it to siblings like 'search_within' or 'subscribe'.

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