fuel_find_cheapest

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well-covered. The description adds useful context: official Fuel Finder data source and 30-minute freshness window. However, it doesn't disclose behavior about edge cases (no stations found, unknown fuel type, invalid postcode) or what the response structure looks like. With strong annotations, this is acceptable but not exceptional.

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 a compact single sentence that packs in purpose, ranking behavior, median comparison, unit, data source, and freshness into an efficient package. It's front-loaded with the core function ('Find the cheapest fuel') immediately. Slightly dense but well-organized; the information-to-word-count ratio is excellent.

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?

With an output schema present, the return-value format is handled structurally. The description covers data source, freshness, pricing unit, ranking, and median comparison — all the key semantics. Given 4 params, 50% schema coverage, rich annotations, and an output schema, the description is reasonably complete. Could mention edge cases or failure behavior, but overall it's adequate for reliable tool selection.

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 50%: 'location' and 'fuel' have descriptions, but 'top_k' and 'radius_miles' do not. The description clarifies the pricing unit (pence per litre) and data provenance, which adds value. However, the top_k (default 10, max 25) and radius_miles bounds are only discoverable from the schema, not reinforced in the description. Baseline 3 is fair since half the params are documented in schema and the description adds the freshness/data-source context.

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 what the tool does: 'Find the cheapest fuel near a location, ranked by price', with each station's price compared to the local median. The verb 'find' + resource 'cheapest fuel' + clear ranking criterion distinguishes this from siblings like fuel_nearby_stations (which likely lists stations without the cheapest-ranking emphasis) and fuel_area_summary (which summarizes an area).

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?

The description implies the tool is for cost-conscious fuel searches by ranking by price and comparing to local median. It doesn't explicitly name alternatives or exclusion criteria, but the 'ranked by price' framing and the sibling context (fuel_nearby_stations for general listing, fuel_data_status for data freshness) gives reasonable usage guidance. No explicit when-not-to-use, but the purpose is clear enough to differentiate.

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