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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds substantial behavioral context beyond them: defaults are derived from the trip, location must be a city, amenity filtering is enum-only, and on an 'unavailable' status the agent must not retry but surface a prefilled fallback URL. That failure-handling guidance is genuinely non-obvious.

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-loads the core purpose, then stacks constraints in tight imperative sentences with no filler. Every clause carries a distinct operational instruction (derivation, location rule, filter limit, failure handling).

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 15-parameter, output-schema-less tool, it covers the trip-derivation model, the key input constraints, and even references return fields (structuredContent.status, fallback_search_url) that would otherwise be opaque. Not exhaustive on the less-critical numeric params, but complete enough to invoke 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?

With schema coverage at only 47%, the description compensates on the parameters that matter most: it clarifies trip-derived defaults, the city-vs-country constraint for location, and the enum-only limitation on amenities. The remaining parameters (price, room_type, min_beds, currency) are self-descriptive from their names, so the gap is modest.

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 (Search) plus resource (Airbnb listings) and scopes it to an existing Tineo trip. This cleanly distinguishes it from the sibling assistant_airbnb_search_user, which lacks the trip anchor.

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 operating context: derive location/dates from the trip unless overridden, require a city not a country, and use only the amenities enum (no free-text). It even offers fallbacks (hotel search, support ticket) on failure. It stops short of explicitly naming the sibling alternative (assistant_airbnb_search_user) and when to use that instead.

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