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

Annotations already declare readOnlyHint/idempotentHint/openWorldHint, and the description adds value well beyond them: the PENDING status semantics (paid, awaiting confirmation, must not be paid again), the auth model (user_key supplied by a trusted local Skill, never pasted into chat), and retry policy on failures. It also warns against rephrasing errors or empty results as success, which is a real agent failure mode.

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 purpose and the user_key handling rule are front-loaded, but the same user_key / trusted-client instruction appears in the English text, again in the Chinese text, and a third time in the schema, making the block noticeably redundant. The language mixing also adds parsing overhead without adding information.

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 the description covers everything else an agent needs: ownership restriction on the order number, auth sourcing for user_key, status interpretation, and failure/retry handling. Nothing required to call it correctly is missing.

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% and both parameters are fully documented in the schema, including that user_key may be omitted for ToC queries and that agent_ref_id is not a hotel confirmation or third-party payment number. The description restates rather than extends that information. Baseline 3 is appropriate when the schema carries the parameter burden.

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+resource (query a booking) and scopes it to bookings owned by the authenticated account, identified by the agent_ref_id returned from create_booking. It also implicitly separates itself from pay_order by declaring PENDING means already paid. It stops short of naming sibling alternatives (create_booking, cancel_booking, query_room_rates) explicitly, so differentiation is only partial.

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?

Gives clear context for when user_key is optional (anonymous ToC hotel search) versus mandatory (ordering, order query, cancellation, payment), and instructs using this tool to verify payment and hotel confirmation. Error handling guidance — distinguish param/auth errors from transient upstream failure, retry only the latter — is concrete and actionable. No explicit 'use X instead of this tool' routing is given.

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