ev_chargers

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.