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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds valuable context beyond the schema: availability=null almost always indicates wrong parameter names, a dorm bed is the default, and there is no room_type parameter. This gives the agent actionable diagnostic information, though it doesn't discuss return format or pricing details (mitigated by the output schema).

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 somewhat long but every sentence is informative and relevant. It is front-loaded with the core purpose, then provides parameter usage, a default behavior, and a troubleshooting tip. No filler or redundancy; the structure is logical and efficient.

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 tool's complexity (two provider types, multiple params) and the presence of an output schema, the description covers the critical aspects: required provider_id, parameter mapping, naming pitfalls, and default behavior. It doesn't explain how provider_id is obtained (likely from find_providers) but that is inferable. Overall, it provides enough context for an agent to invoke the tool correctly.

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 covers 67% of parameters, but the description adds substantial meaning: it maps date to doctor and check_in/check_out/guests to hostel, enforces underscore naming, clarifies guests is an integer, states provider_id is required, and labels promo_code as optional. It also explicitly denies the existence of a room_type param, which is not in the schema. This far exceeds what the schema describes and fully compensates for uncovered parameters.

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's purpose as retrieving availability and price for a venue, using a specific verb and resource. It distinguishes itself from sibling tools like book, cancel, and find_providers by being a read-only pre-booking lookup, and it explicitly notes the required provider_id.

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 usage instructions: required provider_id, venue-type-specific parameters (doctor vs hostel), exact underscore naming, no room_type param, and optional promo_code. It doesn't explicitly mention alternatives like 'use this before booking' or 'use find_providers to search providers', but the context strongly implies the tool's role. The troubleshooting hint for null availability further guides correct usage.

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