search_flex

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

With no annotations, the description carries the burden. It reveals key behaviors: currency can be inferred from origin, if unknown ask the user, the tool does not convert currency, and unnamed baggage_buffer defaults to 0. It does not disclose the output format or any side effects (though a search is likely read-only by nature). The provided details add value but are not comprehensive.

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 succinct and front-loaded with the central concept. It uses four short sections that each address a distinct point (flex window, sibling usage, currency, baggage default). No filler or redundancy. It is appropriately sized given 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?

For a tool with 37 parameters, no available annotations, and no output schema, the description is incomplete. It does not describe the return format, pagination, or many parameter constraints. The agent is left without crucial context for correct invocation, especially regarding interplay of required parameters like route and around. The few hints provided are insufficient.

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 0%, and the description does not explain the vast majority of the 37 parameters. It mentions only a few: flex (via '±N'), currency (inference and no conversion), and baggage_buffer (default). The required parameters around and route are not explained. With such high parameter count and zero schema descriptions, the description fails to compensate adequately.

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 function: a shopping search with a flexible date window, picking the cheapest day. It distinguishes itself from sibling search_dates by explicitly naming it and contrasting with a calendar view. This is specific and unambiguous.

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?

Provides explicit directive: 'Use search_dates for a cheapest-week calendar' and warns 'Do not brute-force a date matrix.' This tells the agent when NOT to use this tool and when to prefer a sibling. However, it doesn't cover all alternative scenarios or edge cases, but the guidance is clear and actionable.

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