get_room_options

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that no rate is auto-selected or ranked, that missing terms remain unknown, that usePoints supports only regular award inventory, and that government scope defaults to federal-only. It also instructs to review options with the user before choosing an offerId. This is comprehensive for a read-only tool.

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 compact yet information-dense, with the core function stated first and key caveats following. Every sentence adds value, and it avoids redundancy. It is appropriately sized for the tool's complexity.

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 11 parameters, no output schema, and no annotations, the description covers the essential behaviors, defaults, limitations, and workflow. It could be more detailed on the structure of rateResults or how to interpret cancellation terms, but it gives enough to call the tool correctly. The missing details are not critical for invocation.

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 36%, so the description must compensate. It adds meaning to specialRates (categories to search separately), usePoints (regular award inventory only), governmentScope (defaults to federal-only), and corporateCode (implied for corporate_promo). It does not explain rooms, adults, children, dates, or hotelId, but those are self-explanatory and covered by schema patterns. Overall, it adds value 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?

The description clearly states the tool returns all matching room/rate offers grouped in rateResults for each selected specialRates category, including cancellation policy, deadline, deposit terms, and eligibility. It is specific about the resource (room/rate offers) and the action (returning them), and it distinguishes itself from sibling tools like select_room by explicitly noting that no rate is automatically selected or ranked.

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 provides clear context on how to use the tool, including that defaults come from MCP environment config, government scope defaults to federal-only, and that review with the user before choosing an offerId is required. It does not explicitly name alternatives (e.g., select_room) or state when not to use it, but the guidance is strong enough to orient an agent.

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