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

Annotations already declare readOnly/openWorld/non-destructive, and the description layers on genuinely new operational facts: a required ReservationReport (Read) role, the underlying GET endpoint, a hard 31-day span per period, PIN codes being withheld from output, and truncation being signalled in the reply. That is exactly the context annotations cannot carry.

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 tight sentences: resource and scope first, then returned fields, then constraints and auth. The field enumeration is list-like but each item is informational; nothing is redundant with the schema or annotations.

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 no output schema, the description carries the return shape (types, courts, times, players, balances, PIN exclusion) and adds the access prerequisite and span limit an agent needs to call successfully. For a 7-parameter read tool, nothing material is left unexplained.

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 100%, so the baseline is 3; the description earns more by grouping the parameters into two distinct concepts — 'the dates played' vs 'created/updated period' — which the terse schema fields (reservations_from/to vs created_or_updated_from/to) do not make obvious. It stops short of explaining date formats or how the two groups combine.

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?

States a specific verb and resource (list active court reservations) and enumerates the payload an agent gets back (type, courts, start/end, players, amounts owed/paid), which goes well beyond the title. It implicitly distinguishes itself from the cancelled-reservation siblings via 'active', but never names them, so an agent must infer the routing.

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?

'Give at least one period' is a real usage constraint that the schema does not encode (required=0), and the 31-day-per-period cap tells the agent how to shape a call. However, there is no explicit when-to-use/when-not language and no reference to alternatives such as courtreserve_list_cancelled_reservations or courtreserve_get_member_reservations.

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