Search and Verify Top Itineraries

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

Annotations already declare readOnlyHint=true, so the read-only safety profile is established. The description adds the pipeline stages and the notable Playwright verification step, but it does not explain what verification entails, potential latency, or whether browser automation could have observable side effects. With annotations covering the main safety burden, this is adequate but not rich.

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 extremely compact, with no filler words, and the arrows convey a clear execution order. It is front-loaded and efficient, though the internal jargon makes it less immediately readable than a plain-language sentence.

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 complexity of the request object and the existence of an output schema, the description provides only a pipeline synopsis. It omits when to call the tool, what 'verification' actually validates, and how results are returned. Annotations and schema fill some gaps, but the description is incomplete for a tool this rich.

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 100%, and the request object is described as a Google Flights search with ranking controls. The tool description adds no parameter-level meaning beyond the schema; 'top 1-3' maps loosely to top_n, but the schema already documents that. Baseline 3 is appropriate.

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 names a concrete pipeline—protobuf to HTTP to pairing/ranking to top 1-3 to Playwright verification—and the title clarifies the resource: top itineraries. It is specific enough to distinguish this from the siblings at a high level, though it does not explicitly contrast with discover_and_rank_complete or state the final return value.

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?

There is no explicit statement about when to use this tool versus build_protobuf_search_url or discover_and_rank_complete. The 'top 1-3' mention weakly implies small result sets, but no when/when-not conditions or alternative routing are provided.

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