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

Beyond the annotations (readOnlyHint, idempotentHint, openWorldHint=false, destructiveHint=false), the description discloses real behavior: it enumerates the fields returned, explicitly states that guest name, email and full phone are withheld, and explains that well-formed-but-incorrect references yield 'no reservation found' rather than an error. It also adds a rate-limit nuance that only failed lookups count toward the per-reference limit, which annotations cannot convey.

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 dense sentences, each doing distinct work: what it returns and the key, what it withholds, and the failure/limit semantics. The returned-fields clause is front-loaded and no sentence is filler.

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 correctly takes on the burden of describing return content, both included and excluded fields, plus the negative-result behavior. The only gap is that 'the per-reference limit' is referenced without stating its value or reset window, leaving an agent unable to reason about retry budgets.

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, but the description adds meaning by framing phone_last4 as a verification factor combined with the reservation number — incorrect details produce no result rather than a partial match. It does not add format or validation detail beyond the schema's pattern constraint, so it stops short of a 5.

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 ('Reads a reservation status, property, room type, dates and total') and names the exact lookup key. That key (reservation number + phone last4) clearly separates it from siblings such as find_rooms, get_rates, quote_stay and list_properties, which operate on availability or pricing rather than an existing booking.

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?

Usage is only implied: an agent can infer this is for retrieving an existing reservation, but the description never states when to prefer it over siblings or what prerequisites exist (e.g. whether the reservation must be confirmed). It focuses on lookup mechanics and failure behavior rather than routing guidance.

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