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

Annotations only declare readOnlyHint, so the description carries the rest, and it does add real behavior: 'Instant and free,' a cached 'latest finished' search 'about six weeks out,' refreshed on a rota, with beachWeek refreshed 'every Thursday' and grouped by area at a board URL. That freshness/staleness and cost disclosure is exactly the context annotations cannot provide, though it never states what a returned pick looks like.

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?

A single ~200-word comma-spliced run-on that repeats the same five cities in both the six-adult weekend list and the hotel list. The useful framing ('Instant and free') is front-loaded, but the bulk is undifferentiated enumeration that should live in an enum or reference rather than prose.

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?

There is no output schema, so the description should characterize the return value; it says picks exist and that beachWeek picks are grouped by area, but not how many picks, what fields, or how the default whole-home result is shaped. Coverage of inputs and freshness is strong, return shape is thin, and the two city lists are internally inconsistent about what is covered.

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 coverage is 67% and the two documented params are already explained in the schema, but the description adds substantial meaning: what stayType 'hotel' actually yields (two adults, three nights, and in which cities), what beachWeek yields (a specific January week from 2027-01-14 in three named destinations), and an implicit enumeration of valid city values. The city parameter itself is only defined indirectly via two overlapping lists, one of which omits the beachWeek cities.

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 identifies the tool as returning 'the latest finished standard search for one of the covered cities' and enumerates the covered cities, so the resource and scope are recoverable. It also names the sibling it is not ('For other places or specific dates use search_stays'), which aids disambiguation, though the core purpose is buried under trip-composition detail rather than stated crisply up front.

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?

Explicit routing exists: 'For other places or specific dates use search_stays,' plus conditional guidance for stayType 'hotel' (only where a hotel-room trip exists, with an enumerated city list) and beachWeek (only Playa del Carmen, Cancún, Punta Cana, one January week). No explicit when-not beyond those constraints, and the reader must infer that uncovered cities or custom dates are unsupported.

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