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

The annotations already establish that this is a read-only, idempotent, non-destructive search, but the description adds substantial behavioral context beyond them. It discloses that prices are estimates with no inventory hold, that live-check failures can reduce page size below the limit, that nightly-rate filters use indexed average rates rather than final totals, and that pagination counts reflect the search index rather than current public rows. These are meaningful operational caveats an agent needs before interpreting results.

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 description is front-loaded with the core action and then layers only operationally important caveats: workflow, estimates, live-check omission, rate semantics, pagination, and booking handoff. Every sentence carries distinct information, and none is a restatement of the tool name or schema. It is dense but appropriately sized for a search tool with multiple behavioral caveats.

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?

Given the output schema, the description does not need to explain return fields, and it already covers the workflow, sibling tools, booking handoff, estimate semantics, live-check omissions, rate-filter behavior, and pagination discrepancies. Together with the annotations and output schema, it gives an agent enough context to invoke the tool correctly and interpret its results. No critical behavioral gap remains.

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 only 33%, so the description must compensate for several undocumented parameters. It adds useful meaning for location_id provenance, date/guest price estimation, nightly-rate filter semantics, pagination behavior, and filter resending, but it does not explain page, limit, sort, locale, with_pets, min_bedrooms, or num_guests directly. The added context is helpful but does not fully cover the 12-parameter surface.

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 states a specific verb and resource: 'Search public Guestit accommodation using a location_id from resolve_destination.' It also distinguishes this tool from siblings by routing location resolution to resolve_destination and detailed inspection to stay_details or compare_stays. An agent can tell what this tool is for 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 explicit workflow guidance: obtain location_id from resolve_destination, resend the full filter set when refining, and read house rules and cancellation policy with stay_details or compare_stays before recommending. It also says booking happens on the returned Guestit website link, which clearly positions this as a discovery tool rather than a booking tool. Alternatives and sequencing are named rather than left to inference.

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