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

With no annotations at all, the description carries the full disclosure burden. It reveals the richness of the payload (live status, pricing, auth methods), which implies a read, but never states permissions, rate limits, or what happens with a malformed or unknown id.

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, front-loaded with the payload description, then the sequencing hint, then the argument formats. No filler and no repetition of structured fields.

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?

An output schema exists so return-value explanation is unnecessary, and the single required parameter is fully disambiguated. The only gap is error behavior for unresolvable ids, minor for a one-parameter lookup.

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% — the sole parameter 'site_or_point_id' is bare in the schema. The description fully compensates by naming all three accepted id forms and giving a concrete example of each ("EZC-AMD-00051", "AMD-00051-1", "PT*EZC*E*AMD*00051*1"), which is exactly what an agent needs to build the call.

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: retrieve everything about one MOBI.E charging site, enumerating the returned facets (points, live status, power, connectors, price, operator contact, hours, auth methods). This clearly separates it from the list-oriented sibling ev_chargers without either schema being opened.

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?

"Use after ev_chargers" gives explicit sequencing relative to the sibling that produces the ids this tool needs. It stops short of stating when NOT to use it or when to prefer fuel_station_detail, so it is clear context rather than a full routing rule.

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?

With no annotations, the description carries the full burden and does so: it warns that the first call of the day downloads ~220 MB and may take 1-3 minutes (a real latency/side-effect trait), discloses data staleness via data_freshness, and flags that published fees may not be the whole bill, instructing the agent to relay price_note. These are exactly the non-obvious behaviors an agent cannot get from the 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?

Front-loaded with the one-line purpose, then Args and a return summary — a structure an agent can scan. It is somewhat long, and the enumeration of return fields overlaps with the existing output schema, though the 'tell the user about price_note' instruction justifies part of that restatement.

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 7-parameter tool with an output schema and no annotations, the description covers what the schema cannot: geographic coverage, cold-start cost, live-status semantics, freshness, and the pricing disclaimer. Nothing needed to call it correctly or to interpret results responsibly 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 coverage is 0% and the schema has no enums, so the description must compensate — and it does, documenting units (WGS84), defaults and caps (radius 5/100, limit 10/50), the semantics of min_power_kw with a concrete example (50 for fast DC), and the accepted connector values (CCS2, Type 2, CHAdeMO, CEE, DC/AC). The value list is the single most important addition since the schema types connector as a bare string; only minor ambiguity (e.g. how 'DC' interacts with min_power_kw) remains.

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 resource (public EV charging sites on the MOBI.E network), the geographic scope (mainland Portugal, Azores, Madeira) and the ordering (nearest first with live status and prices). It is clearly distinguishable from the fuel_* siblings and from ev_charger_detail, which the 'each site' summary implicitly frames as the bulk-listing counterpart.

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 concrete trigger phrasings ('where can I charge near X?', 'fast chargers near me') and the prerequisite that coordinates are required, with a fallback instruction if the user supplies a place name. It stops short of explicitly naming ev_charger_detail as the tool for drilling into a single site, so routing to the sibling is left implicit.

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?

No annotations, so the description carries the full burden and does well: it discloses sort order (cheapest first), data source (official DGEG), price units (per litre vs per kg/m3 for gas), the last_update freshness field, and the instruction to always cite source and update time. It stops short of stating read-only character, caching/update cadence, or failure behavior.

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 one-line summary followed by a usable Args block and a short returns paragraph. The "Each station: ..." enumeration partly duplicates the output schema, but the closing instruction to always cite DGEG and last_update 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 an 8-parameter, annotation-free lookup tool this is essentially complete: input forms, defaults, geographic precedence, units, ordering, provenance, and the sibling that enumerates legal fuel_type values. Return details being duplicated is harmless given an output schema exists.

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%, so the description must compensate and it does for all eight parameters: fuel_type accepts DGEG names, numeric ids, or plain words like "diesel"/"lpg"; district vs municipality with precedence; lat/lon triggering distance_km within radius_km; brand as a substring match; limit default 10 max 50. It also notes case/accent-insensitive name matching, which the schema cannot express.

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?

Names a specific resource and operation (cheapest fuel stations in Portugal, cheapest first, DGEG source) and distinguishes scope from siblings by directing agents to fuel_types() for the full fuel list. An agent can tell this is the search-a-price tool, not the detail tool, without opening the 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 concrete trigger phrasings ("where is diesel cheapest in Lisboa / near me / in Braga") and states the default when no area is given (searches all of Portugal), plus the municipality-overrides-district rule. It doesn't explicitly say when to prefer fuel_station_detail or fuel_types instead, so routing is implied rather than fully enumerated.

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?

No annotations are present, so the description carries the burden; it implies a read-only lookup and tells the agent what the response contains, which is useful. It does not state behavior for an unknown/invalid station id, coverage limits, or any rate/auth considerations.

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 short sentences, front-loaded with the resource and its contents, followed immediately by the call condition. No redundant restatement of the tool name or filler.

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?

A read-only single-parameter detail lookup with an output schema, so return values need not be spelled out; the description still summarizes them well. Only the error/edge-case behavior for a bad id is left unaddressed, which is minor here.

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 schema only types station_id as an integer. The description compensates by explaining where the id comes from (results of fuel_prices), which is real added meaning, but it does not clarify id format or validity constraints.

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?

Names a specific resource and scope ('Full details of one fuel station') and enumerates the payload (prices with last update, opening hours, services, payment methods). This is clearly distinguishable from the sibling fuel_prices (list of prices) and ev_charger_detail (different resource).

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?

'Use after fuel_prices, with a station id from its results' gives an explicit sequencing rule and the source of the required argument, which implies fuel_prices is the discovery step and this is the follow-up. It stops short of stating when not to use it (e.g., browsing all stations), but the dependency guidance is clear.

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?

No annotations are provided, so the description must carry the behavioral burden. The verb "List" clearly implies a read-only reference lookup with no mutation, and the description identifies what is returned (fuel type ids/names/units and accepted districts), though it does not discuss authentication, caching, or rate limits.

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 two short sentences with no filler. The core list purpose is front-loaded, followed immediately by the usage caveat and alternative.

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 an output schema present, the description does not need to explain return values in detail. It provides enough context about what the tool lists, when to use it, and which sibling handles common fuel names, making it complete for this simple reference lookup.

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 there are no parameter semantics to explain. The baseline for a zero-parameter tool is 4, and the description appropriately does not invent parameter details.

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 states a specific verb and resource: it lists DGEG fuel types with their id, name, and unit, and also lists the districts accepted by fuel_prices. It clearly distinguishes itself from the sibling fuel_prices tool by explaining that fuel_prices accepts common fuel names directly.

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?

It explicitly says it is only needed when the agent is unsure which fuel name to pass, and it names fuel_prices as the primary alternative that understands "diesel", "petrol", "95", "98", and "lpg". This gives a clear when-to-use and when-not-to-use rule.

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