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

With no annotations, the description carries the full burden and does so well: it discloses the cache-first/live-search hybrid ('Cached prices answer at once; weekends not priced yet are searched live during the call'), realistic latency bounds, and a degraded-mode contract ('the answer says which weekends are still open and to call again'). It also states the auth prerequisite (Pro session cookie) for non-default filters. Read-only nature is implicit in a price-query tool and nothing contradicts it.

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?

Three tight sentences that front-load the return shape, then latency/partial-result behavior, then filters and entitlements — a sensible order with little waste. It drifts slightly into restating schema-level filter info, which is the only redundancy.

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 13-parameter, no-output-schema tool, the description covers everything an agent needs: what is returned (cheapest round-trip per weekend + as_of), how long it may take, what happens on timeout, and what credentials unlock which filters. Nothing critical is missing.

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%, so the schema already documents every parameter's meaning, format, defaults and entitlements; the description only adds a summarizing list ('trip shape, cabin, stops, passengers, departure and return time windows, currency'). That framing is mildly useful but introduces no semantics beyond the schema, so the baseline 3 applies.

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?

Opens with a concrete verb and resource: 'Every weekend of the next 12 months for one origin-destination pair, with the cheapest round-trip price per weekend' — an agent immediately knows this returns a per-weekend price series plus an as_of timestamp. It does not, however, distinguish itself from the sibling 'cheapest_weekends', which sounds like it covers very similar ground, so the agent is left to guess which one to pick.

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 entitlement-based conditions for use: the free tier covers fri-sun/economy/any stops/any passenger mix/no time window, while other combos, cabins and time windows need a Pro session cookie. It also sets latency expectations (10-40 s, at most ~55 s) and tells the agent what to do on a partial result. What's missing is any tie-break against 'cheapest_weekends' — it never says when to prefer a sibling instead.

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