fuel_prices

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

No annotations are provided, so the description carries full burden for behavioral disclosure. It does not mention read-only vs. write behavior, data freshness (DGEG data likely has update schedules), rate limits, or pagination (though no output schema is given). The description is too brief to adequately cover behavioral traits for a tool interacting with an external data source.

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 single, concise sentence that front-loads purpose and context (data source, use case). Every word adds value; there is no fluff. However, it could slightly improve by mentioning the optional parameters limit and fuelType, but overall it is well-structured.

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?

Given the tool's moderate complexity (3 parameters, no output schema), the description covers the basic purpose and data source. However, it misses completeness regarding return format (list of stations with prices? just names?) and any limits on results other than what is in the schema. Without output schema, the description should hint at what the agent will receive. It is adequate but not exhaustive.

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 input schema has full coverage (100%) with descriptions for all three parameters, including defaults and the list of fuel types. The description adds context by connecting the 'fuelType' parameter to Portuguese terms (gasolina, gasóleo) mentioned in the use case, which semantically clarifies the parameter. The description and schema together provide strong parameter semantics.

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 the tool's purpose: finding the cheapest fuel stations in a Portuguese district. It specifies the data source (DGEG) and the use case (questions about gasolina, gasóleo, GPL prices near a place). However, it could more directly differentiate from siblings like reverse_geocode or municipality, though the domain is distinct enough.

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 usage for fuel price queries in Portugal, but does not explicitly state when not to use it or mention alternatives among siblings. The mention of 'data: DGEG' provides context, but there is no guidance on when other tools like open_data_search might be more appropriate.

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