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

The description discloses mark_read behavior and the alternative HTTP endpoint, but the annotation readOnlyHint=true directly contradicts the mark_read parameter, which mutates read state. This is a clear annotation contradiction, making the transparency score 1 despite the description being otherwise transparent.

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?

Three sentences, each with a clear purpose: primary action, return payload contents, and filtering/mark_read/alternative access. The description is front-loaded with the verb and object, contains no fluff, and every sentence earns its place.

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 no output schema, the description covers return content (source, citation_uri, raw payload), filtering, mark_read side effects, and provides an alternate HTTP endpoint. Minor gaps like response ordering or default limit are covered by the schema. Overall, it is sufficiently complete for a read-only feed retrieval tool, aside from the annotation contradiction.

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 covers all 5 parameters with basic descriptions, so the baseline is 3. The description adds meaningful value by giving a concrete example for type ('sec_8k'), explaining mark_read's effect on subsequent calls, and clarifying the since parameter as an ISO timestamp.

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 a specific verb and resource: 'Pull fired events from your subscription feed.' It clearly states that it returns recent alerts with source, citation_uri, and raw payload, distinguishing it from sibling tools that manage subscriptions or perform searches.

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?

It explains when to use the tool (pulling fired events from the feed) and provides usage details like filtering by type/since, mark_read, and polling suitability. However, it doesn't explicitly contrast with alternatives, though the context implies this is the go-to for recent alerts from the subscription feed.

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