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

Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds genuine behavioral context beyond the annotations: newest-first ordering, a default 90-day window, and the fact that the data mirrors the webhook audit trail. There is no contradiction with the annotations.

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 dense but efficient: it front-loads the core purpose ('cross-event change feed, newest first'), enumerates the change kinds in one compact list, states scope and time default, and closes with the polling-vs-webhook usage hint. No sentence or clause is wasted.

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 read-only feed with no required parameters and 80% schema coverage, the description provides enough to call it correctly: scope, change kinds, ordering, default time window, and the intended use case. Minor gaps remain: it does not describe the response shape, pagination behavior (cursor/limit), or explicitly differentiate from get_event_changes, but these are secondary for a tool whose annotations and schema already cover the essential contract.

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 80% (only limit lacks a description), so the schema already documents org, kind, since, and cursor. The description reinforces param meaning by listing change kinds in prose and stating the since default ('default the last 90 days'), and it clarifies org scope ('every covered promotion or one of them'). This is helpful but largely redundant with the schema, so it adds only marginal value.

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 names a specific resource ('cross-event change feed') and a concrete verb ('list'), then enumerates the exact change types covered: bouts added/cancelled/reinstated, opponents swapped, times/venues moved, fighter profiles merged. It also states the scope ('across every covered promotion or one of them'), which distinguishes it from event-scoped siblings like get_event_changes without opening their schemas.

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 gives a clear usage context: it is the change feed for polling agents, explicitly framed as 'the same audit trail webhooks deliver, for agents that poll instead.' It also implies when to use org/kind filters. However, it does not explicitly name alternatives or state when NOT to use this tool versus get_event_changes or list_events, so guidance is strong but not fully explicit.

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