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

Annotations only declare readOnlyHint=false and openWorldHint=true. The description adds rich behavioral detail beyond them: an asynchronous session-ID model requiring polling, multi-provider price aggregation (Agoda/Booking.com/Traveloka/direct partner rates), the default party of 2 adults in 1 room with defaulting flagged in the result, and the fallback of returning a question rather than a search when city or dates are missing.

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?

Front-loaded with the core action and kept to a handful of dense sentences; each sentence carries distinct information (purpose, providers, async polling, filters, party defaults, missing-input behavior). Slightly longer than strictly needed but with no 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?

For a 13-parameter tool with an output schema, the description covers the essential behavior: the async session/polling model, provider sources, defaulting and its flagging, and edge-case handling for missing city/dates. Return values are delegated to the output schema, which is appropriate, leaving only minor unstated details.

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 schema already documents each parameter (baseline 3). The description adds cross-parameter semantics the schema does not: filters narrow by hotel name/area/total price, the party defaults to 2 adults/1 room and defaulting is flagged in the output, and missing city/dates produce a clarifying question — meaningful value above the schema text.

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 ('Starts a live hotel search') with scope ('for a city and date range'), and distinguishes itself from siblings by naming poll_search_results as the companion for results. An agent can identify it as the hotel counterpart to search_flights_live without opening the schema.

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 clear workflow context: start a search, then poll_search_results to retrieve arriving results, and states what happens when city/dates are omitted (the result asks the user). It does not explicitly contrast against search_flights_live or get_hotel_detail, so the alternative-selection guidance is implied rather than stated.

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