pmus_list_events

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, which cover safety and side-effect transparency. The description adds useful context by stating that each event includes its markets with best bid/ask and implied probability, which is beyond the schema. It also implies the response includes pagination and filtered data. However, it doesn't disclose pagination limits beyond 'offset' or the default response size, but the schema covers defaults.

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, all relevant. It front-loads the primary purpose, then provides a key output detail (each event includes markets with best bid/ask and implied probability), and ends with a useful pagination hint. No waste.

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?

The tool has 12 parameters, all optional, and an output schema. Given the output schema exists, the description doesn't need to explain return values. The description covers the essential behavior (listing events with filters, pagination, and market data). It is incomplete in that it doesn't explain the relationship to pmus_list_markets or detail the pagination mechanics fully, but for a list tool with rich schema, this is adequate.

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 description coverage is 50%, with 6 out of 12 parameters having descriptions (category, order_by, tag_slug, end_date_max, end_date_min, description_chars). The description adds value by naming the tool's core output (markets with bid/ask and implied probability) but does not explain parameters like active, closed, offset, or series_id beyond what the schema titles provide. Since coverage is moderate (50%), the description partially compensates but not fully.

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 a specific verb ('List'), the resource ('events'), and the key capability ('filters and pagination'), which distinguishes it from siblings like pmus_get_event (which retrieves a single event) and pmus_search (which likely searches events). However, it doesn't explicitly differentiate from pmus_list_markets, which could be a sibling with overlapping functionality, and the filtering details are only implied.

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 'filters and pagination' and specifically says to use 'offset to page', which gives some guidance on when to use this tool. However, it doesn't explicitly state when NOT to use it or mention alternatives like pmus_search for more complex queries. The sibling context suggests pmus_search might be the alternative for extensive filtering, but the description doesn't name it.

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