Gas Quebec: Quebec fuel prices

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

Annotations already declare readOnly/non-destructive/local-world behavior, so the safety profile is covered. The description adds genuinely non-structured context: prices are in ¢/L, results are capped at 10 stations within 30 km, and the precise definition of the 'value' sort (price + 1¢/L-per-km detour penalty). It does not mention rate limits or what fields are returned, but for a read-only lookup this is solid.

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?

Front-loaded with the core action, then scope caps, then the alternative-tool routing, all in three dense sentences with no filler. Slightly packed (the formula parenthetical and the routing clause both compete for attention), but every clause carries information.

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 six-parameter read-only lookup with no output schema, the description covers scope, units, result caps, default ranking, and sibling routing — enough for correct invocation. The only real gap is that it never hints at the shape of the returned station data, which an agent may need to plan a follow-up call.

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 description fills the most important gap: the 'value' enum has no schema description, yet the description defines its formula and calls it the default, which materially affects how an agent sets `sort`. It also clarifies price units. It does not add anything for `limit`, `radius_km`, or `lat`/`lng` beyond what the schema already says.

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?

States a specific verb+resource+scope ('Find gas stations near a coordinate in Quebec') and the ranking modes, and explicitly names the sibling it is not ('for area-wide summaries use get_city_prices instead'), so an agent can distinguish it from get_city_prices without opening any schema.

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 an explicit use case ('sized for one fill-up decision'), an explicit exclusion with the alternative tool for area-wide needs, and even recommends the default ranking mode ('value ... the best default for "where should I fill up"'). When/when-not/routing are all covered.

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

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

Annotations already establish readOnly, non-destructive, and closed-world behavior, so the safety bar is low. The description adds useful behavioral context by enumerating what the response contains (station count, min/avg per fuel type, five cheapest regular stations), which is valuable given there is no output schema.

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?

One front-loaded sentence with no filler; the scope statement and the return payload are packed without redundancy. Every clause earns its place.

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 single-parameter read tool with annotations covering safety and no output schema, the description competently covers the return shape and scope. Only minor gaps remain, such as data freshness or units consistency beyond the stated ¢/L.

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 100% and the schema itself explains the city_slug source ('from list_cities or search_locations, e.g. "montreal"'). The description only confirms a single-city scope, adding no syntax or format detail 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?

States a specific verb and resource ('Current gas price summary for one Quebec city') plus the exact payload (station count, min/average price per fuel type, five cheapest stations for regular). It is clear what the tool returns, though it never names the sibling find_cheapest_stations that overlaps on the 'five cheapest stations' output.

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?

Usage is implied by 'for one Quebec city' and the required city_slug, so an agent can infer this is a city-level summary lookup. However, there is no explicit when-to-use, no when-not-to-use, and no routing to alternatives such as find_cheapest_stations or get_fill_up_verdict.

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

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

Annotations already declare a safe read (readOnlyHint true, openWorldHint false). The description adds real context: reliance on 30-day history and, notably, that fields are null during data gaps — a behavioral trait not in annotations or schema.

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?

One dense sentence front-loads the verdict then qualifies scope and the 30-day basis; the null-fields caveat is tacked on but earns its place. Slightly compressed but not bloated.

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 no output schema, the description covers the core judgment plus a key edge-case (null fields during gaps) and the trend basis. It does not describe the shape/fields of the verdict itself, a modest gap for a computed-judgment tool.

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 100% and the single parameter already documents its source (list_cities/search_locations). The description adds no further parameter detail, so the schema baseline of 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?

States a specific purpose: a fair-price assessment and fill-now-or-wait verdict for a Quebec city, distinct from siblings like get_city_prices or find_cheapest_stations which list prices vs. render a judgment.

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 decision framing for waiting vs. filling is clear, but no explicit guidance on when to prefer this over get_city_prices or find_cheapest_stations, nor prerequisites beyond an implied city_slug lookup.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safe, bounded-read nature is covered. The description adds provenance context (prices come from Régie Essence Québec), but discloses nothing further about result size, ordering, or freshness of the municipality list.

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?

Two sentences with the core function front-loaded and no filler. The trailing sentence on price provenance is context rather than invocation-critical information, so it is slightly beyond strict minimum.

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 zero parameters and no output schema, the description does the work of telling the agent what comes back (municipalities plus their citySlug). It is nearly complete, needing only a note on how the list relates to search_locations.

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?

The tool takes zero parameters, so the baseline is 4. The description correctly adds no parameter syntax and instead documents the returned citySlug identifier, which is the relevant semantic detail for a parameterless tool.

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?

States a specific verb and resource ('List every Quebec municipality tracked by Gas Quebec') and clarifies the key output artifact, the citySlug used by the other tools. It does not explicitly differentiate itself from the closest sibling, search_locations, so it falls short of a 5.

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?

Usage is only implied: the mention that citySlug is 'used by the other tools' hints this is the discovery/lookup step before calling get_city_prices or find_cheapest_stations. There is no explicit when-to-use statement, no exclusion, and no guidance on how it relates to search_locations.

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

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

Annotations already declare readOnlyHint, destructiveHint, and closed-world scope, so safety is covered. The description adds the important behavioral fact that this is a resolver feeding price tools, but it omits result format, ranking, or matching behavior (e.g., fuzzy vs exact, partial names).

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?

Two dense sentences with no waste, front-loading what is searched and then why it matters. Every clause earns its place.

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?

Covers scope, the input concept, and the downstream workflow purpose, which is the key thing an agent needs. No output schema exists, yet the description does not explain return structure or how to use the resulting citySlug, leaving a small gap.

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 100%, with both query and lang already documented including examples, so the schema carries the parameter burden. The description adds no syntax or format detail beyond what the schema provides, making baseline 3 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?

States a specific verb (Search) and resource (Quebec cities, regions, and gas stations) and names the output token (citySlug). It is clearly distinguishable from siblings like list_cities or get_city_prices.

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?

Explicitly says when to use it: to resolve a user-mentioned place to a citySlug before calling the price tools. That sequencing guidance is strong, but it does not name which price-tool sibling to proceed to or mention when not to use it.

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