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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so "Read-only" largely repeats structured data. The description does add one real behavioral fact: proof is optional and, when supplied, additionally returns the caller's own bed — a meaningful distinction about output-dependent-on-auth. It says nothing about the cost of omitting proof beyond that.

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?

Two short sentences with the purpose front-loaded and no filler. The compactness is slightly at odds with clarity — the compressed metaphors cost a little comprehension — but nothing 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?

An output schema exists, so return values need no explanation, and annotations carry the full safety profile. Sibling routing to cite_census and the optional-proof behavior are both covered. The remaining gap is that the domain vocabulary is opaque enough that an agent may not fully grasp what is being returned.

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 100%, so the four auth-related parameters are already fully documented in the schema and the baseline is 3. The description only gestures at them via "proof" and "your own bed," adding no syntax, format, or interaction detail beyond the schema.

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 ("Returns") and resource ("hotel rail") and enumerates what it surfaces: occupancy, guests, terraces, and the caller's own bed. It explicitly distinguishes itself from cite_census, so an agent can route between the two without opening schemas. The metaphorical vocabulary ("rail", "lit and empty terraces") is somewhat cryptic, keeping it just short of a 5.

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?

"Use it to see beds; for the full census use cite_census" gives both a when-to-use trigger and a named alternative with the condition that selects it. That is close to explicit routing guidance. It stops short of a 5 only because the trigger ("see beds") is terse and no when-not condition beyond the census split is stated.

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