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

With no annotations, the description carries the burden and does meaningful work: it discloses the two-stage behavior (domain selection then in-domain series search), that every domain is returned so the caller can retry, and a concrete latency/caching profile ('a few seconds to a minute... cached for a week'). It omits error behavior and what the search does when no domain matches, so not a 5.

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-loads the one-line purpose, then examples, then behavior, then a short Args block — a sensible order with little waste. The trailing 'Args: lang: ...' fragment leaks docstring formatting rather than prose, which slightly hurts structure.

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 values need no explanation. The description covers the search strategy, the domain fallback path, and caching/latency — enough to call the tool confidently. The only real gap is limit, whose effect on results is never described.

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. It explains lang ('PT' or 'EN', with the useful note that PT labels are richer) and domain_id (a filter, and the retry handle), but the required query parameter is only illustrated via examples and the limit parameter is never mentioned at all.

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 ('Find Banco de Portugal statistical series by keyword') and immediately scopes it with six concrete example queries covering different statistical topics. An agent can distinguish this from bpstat_series (which presumably fetches a known series) without inspecting either 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 clear usage context: pass a keyword query, optionally constrain with domain_id, and retry with a specific domain_id after reading the returned domain list. The example queries model the expected input style well. It stops short of explicitly saying when to prefer this over the sibling bpstat_series, so it lands at 4 rather than 5.

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. It does disclose useful constraints — max 10 series, last_n capped at 1-500, and that since overrides last_n — which goes beyond the schema. It does not cover error behavior for invalid ids, rate limits, or whether the call is purely read-only, so the disclosure is helpful but partial.

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 purpose statement is front-loaded and the Args block is compact with one line per parameter. Slightly terse phrasing ('Observations of ...') is the only cost; there is no redundant 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?

An output schema exists, so return values need not be described, and all four inputs are covered. The remaining gap is edge-case behavior (what happens when more than 10 ids are passed, or an unknown id), which matters for a data-retrieval tool but is minor.

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 0%, yet the Args block documents all four parameters: types, example format ([12559924]), numeric ranges (max 10; 1-500), the 'YYYY-MM-DD' format for since, allowed lang values ('PT'/'EN'), and the interaction rule that since overrides last_n. This fully compensates for the empty schema.

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 ('Observations of Banco de Portugal series') and explicitly routes id discovery to the sibling bpstat_search, which is the one sibling an agent could confuse it with. The verb+resource pairing plus the cross-reference makes the tool's role unambiguous.

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 mention of 'ids from bpstat_search' implies the correct call sequence (search first, then fetch), but there is no explicit 'use this when...' or 'do not use for...' statement, and no guidance on choosing between last_n and since beyond the precedence note.

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 supplied, so the description carries the full burden and does well: it discloses distance-sorted results, result contents (lines serving each stop), accent/case-insensitive matching requiring all words, that a 6-digit id is accepted as a query, and the conditional radius default. It omits only edge behavior such as what is returned when nothing matches or when lat/lon is supplied without a query and no stops fall in range.

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?

Purpose and the 'use this first' routing rule are front-loaded, then a compact Args block gives per-parameter detail. The Lisbon/Carris caveat is the only aside, and it earns its place by preventing a false-negative conclusion.

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 values need not be described, and the description still notes that results include serving lines. With five optional parameters, no annotations, and a coordinate-based search, everything an agent needs to call this correctly is present.

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 0%, and the description fully compensates: every one of the five parameters gets concrete semantics (matching rules, WGS84, default 500 m only when no query, default 10 / max 50). The conditional interaction between radius_m default and the presence of query is information available nowhere in the schema.

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 first sentence names a specific verb and resource (find bus stops) and scopes it to a named operator, Carris Metropolitana. It is immediately distinguishable from siblings like bus_next_arrivals and bus_line_info, which are explicitly framed as downstream consumers of this tool's 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?

Explicitly states 'Use this first whenever the user names a place, street, station or gives a location', and names the dependent tool (bus_next_arrivals) that consumes the returned stop_id. It also adds a genuine scope exclusion — Lisbon city buses are Carris, not covered here — which prevents a predictable misfire.

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 at all, the description carries the full burden and does real work: it discloses the free-text fallback (non-exact input lists matching lines rather than erroring), explains that trips_today = 0 means the line does not run today, and warns about past-midnight times written as '24:30'. It doesn't cover behavior on zero matches or result-set size 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?

Front-loaded with the core purpose and the returned fields, then usage examples, then a compact Args block. Every line carries information the agent would not otherwise have; nothing is 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?

An output schema exists, so return values needn't be spelled out, and the description instead spends its budget on edge cases the schema can't express (seasonal/weekday-only lines, midnight rollover, free-text fallback). For a 2-parameter lookup tool this is complete.

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 0%, so the description must compensate and does: 'line' is documented as either a 4-digit number or free text matched against line names, with the divergent behavior for each case, and 'include_stops' is documented as listing every stop id+name in order per direction. This adds meaning well beyond the bare string/boolean types in the schema.

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 opens with a specific verb+resource ('Details of a Carris Metropolitana line') and enumerates the concrete fields returned (name, route ends, directions, municipalities). The follow-up examples ('where does line 4715 go?') make it unmistakable versus siblings like bus_find_stops or bus_next_arrivals.

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 gives clear use cases and even routes an internal decision ('include_stops=True' to check whether a line passes a stop). What it lacks is an explicit exclusion naming the sibling to use instead for stop lookup or arrival times, so the agent must infer that boundary from the sibling names.

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 it well: it explains the realtime vs scheduled distinction and the caveat that a scheduled bus may not have started its trip, that minutes_from_now prefers the real-time estimate, that times are Europe/Lisbon, that only today's operational day is covered, and that the list may be short or empty late at night.

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 purpose, then caveats, then args — no wasted sentences and the operational-day warning is placed where it will be read. The Args block restates parameter names already in the schema, which is slightly redundant, but the format constraints it adds justify its presence.

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 semantics needn't be spelled out here, and the behavioral caveats an agent needs to interpret an empty or short list are all present. Nothing material is missing for a 3-parameter read tool without annotations.

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 does: stop_id is a 6-digit id with an example, line_id is an optional 4-digit line filter with an example, and limit is documented with default 10 and max 50 — the max is not in the schema at all.

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: 'Upcoming buses at a Carris Metropolitana stop, real-time where available.' The real-time qualifier distinguishes it from timetable/schedule siblings, and the tool is clearly not a stop finder (bus_find_stops) nor a vehicle-position feed (bus_vehicle_positions).

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 trigger phrase ('when is the next bus at X?') plus the prerequisite workflow: obtain stop_id from bus_find_stops first. It does not, however, mention when a caller would prefer bus_vehicle_positions or bus_line_info instead, so there is no stated exclusion.

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 carries the behavioral burden. It usefully discloses the likely volume (~100 alerts with no filter), that alerts are mostly Portuguese-only, and how defaults behave, though it does not discuss update frequency or source reliability.

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 front-loaded with purpose and usage, then presents parameters in a compact, scannable block. Every sentence and parameter note adds actionable 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?

Given there is an output schema, the description need not explain return values. It covers all five parameters, their formats/defaults, the no-filter behavior, language limitation, and when to invoke the tool, leaving no material gap for correct invocation.

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 0%, so the description must compensate, and it does: line_id is described as a 4-digit line number with an example, stop_id as a 6-digit stop id with an example, include_upcoming and language defaults are explained, and limit is given a default and maximum.

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 resource and scope: service alerts for Carris Metropolitana, including the kinds of disruptions covered. It clearly distinguishes this tool from sibling bus tools such as bus_next_arrivals, bus_line_info, and bus_find_stops.

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 gives explicit usage guidance: use before recommending a trip, or when the user asks whether a line is disrupted. It also explains that filtering by line and/or stop is optional and that no filter returns all current alerts.

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 a fair job: it discloses that each vehicle carries position, heading, speed, current/next stop, and the fix age in seconds, which tells the agent how fresh and how rich the data is. It omits error/no-vehicle behavior and any rate-limit or caching expectations for live data.

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?

Purpose is front-loaded in the first sentence, followed by use cases, payload contents, and then the Args block. Every sentence adds information an agent would otherwise have to guess; nothing is padding.

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 optional, and the description still summarizes the payload shape helpfully. The only real gap is what happens for an unknown or non-operating line (empty result vs. error), which matters for a live-data tool with a free-form string id.

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 line_id has no schema description, so the description must compensate — and it does, specifying a 4-digit line number with the concrete example "3508". That is exactly the format detail an agent needs to construct a valid 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 and resource — live GPS positions of buses on a Carris Metropolitana line — and the qualifier 'currently running' pins down the scope. An agent can distinguish it from bus_next_arrivals or bus_line_info without reading either 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 two concrete usage scenarios ("where is the 3508 right now?" and counting buses out on a line), which clearly frames when to reach for it. It stops short of naming the sibling alternatives that handle other bus questions, so there is no explicit when-not guidance.

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; it does disclose a real constraint (days max 30) and ordering behavior (rows returned newest first), which is valuable. It says nothing about return shape, empty-result behavior, or whether results are cached/live beyond 'recent', leaving gaps for an unannotated tool.

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 purpose sentence is front-loaded and each parameter line is one clause with no filler. The 'Args:' docstring formatting is slightly mechanical but costs almost nothing in length.

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?

All four parameters are explained despite 0% schema coverage, and an output schema exists so return values need not be described. The main residual gap is the absence of any safety/read-only statement, though the tool is self-evidently a read query.

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 largely does: region gets its two allowed values with a parenthetical covering Madeira, days gets a max of 30, min_magnitude is defined as a lower bound, and limit is defined as a row cap with newest-first ordering. It stops short of syntax details (e.g., decimal precision) and does not repeat the schema defaults.

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 first line gives a specific resource and source: recent earthquakes recorded by IPMA. There is no direct sibling conflict among the listed tools, so no cross-tool differentiation is required, but the description does not state geographic coverage limits beyond the region parameter.

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 the parameter list (look back N days, filter by magnitude, cap rows), but there is no explicit when-to-use or when-not-to-use statement and no alternative tool is named. An agent can infer it is a query tool for seismic events, but nothing more.

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 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?

With no annotations, the description carries the full burden and does real work: it discloses the output contents (shortage status, on-duty and open-now pharmacies, help lines, next steps), the nearest-first ordering when lat/lon is supplied, and the critical caveat that stock is not public so it will never claim a pharmacy has the medicine. It omits read-only framing, failure behavior when neither city nor lat/lon is given, and any rate/coverage 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?

Front-loaded with the user question it answers, then composition, then returns, then args — a logical scan order. The returns sentence is a dense run-on listing five outputs, which could be broken up, but no sentence is 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?

For a five-param aggregator with an output schema and no annotations, the definition covers composition, output shape, ordering, and the key stock caveat. Gaps are minor: no statement of what happens if neither city nor lat/lon is supplied, and no bounds guidance for limit beyond the default.

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: all five parameters are explained with format examples ('quetiapina', 'Brufen 400', 'Lisboa'), the default for limit, and the city-vs-lat/lon alternative. This adds meaning well beyond the bare typed properties.

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 composite action — running medicine_availability + pharmacies to answer one question — and names both underlying sibling tools. An agent can tell immediately this is an aggregator rather than a raw lookup, distinct from medicine_availability and pharmacies alone.

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 framing sentence ('I need medicine X in city Y — what do I do?') gives a clear trigger condition, and naming the two sibling calls it composes implies the alternative of calling those directly. It stops short of explicitly saying 'use the lower-level tools when you only need shortage status or pharmacy hours.'

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 carries the full burden. It does disclose the meaning of the returned scale (1 reduzido through 5 máximo), which is genuinely valuable, but it says nothing about data source/freshness, behavior for unknown or ambiguous municipality names, or whether tomorrow's value can be unavailable. For a lookup tool the risk is low, so a 3 is fair.

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-liner followed by compact Args and Scale blocks; every line carries information the agent needs. The format is efficient, with only minor redundancy between the title term and the parenthetical Portuguese name.

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 description need not describe return shape, and both parameters are documented, so the essentials for correct invocation are covered. Gaps are secondary: no note on data freshness or handling of invalid municipality names, which matter more for a lookup whose failures may be silent.

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 largely does: municipality is defined as a concelho name with two concrete examples ('Sintra', 'Monchique'), and day is mapped to explicit values (0 = today, 1 = tomorrow). It stops just short of stating what the default is or what happens for out-of-range day values, which the schema's default hint only partially covers.

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 first sentence names a specific resource (wildfire danger / RCM / risco de incêndio rural), its geographic scope (municipality), and its temporal scope (today or tomorrow), with the Portuguese term in parentheses for disambiguation. No sibling tool covers this domain, so the agent can route to it unambiguously.

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 the domain (ask about fire danger, get the level) but there is no explicit when-to-use or when-not guidance, and no reference to adjacent siblings like weather_forecast or weather_warnings that an agent might otherwise pick. The day parameter hints at the two supported timeframes but that is a parameter rule, not usage routing.

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.

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

With no annotations, the description must carry the behavioral burden, and it does disclose useful traits: default geography resolution ('Portugal when present, otherwise all geographies'), the periods range 1-24, and substring-matching filter semantics for category. It says nothing about error behavior for an invalid varcd, unknown place names, or result ordering across geographies, which matters for a 6-parameter retrieval tool.

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?

A single front-loaded summary sentence followed by a compact Args block; no filler and each line carries information. The docstring-style layout is slightly mechanical but appropriate given six undocumented parameters.

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 shape need not be described, and the description covers all six parameters plus default-resolution behavior for the riskiest one (place). Remaining gaps are edge-case behavior (invalid codes, ambiguous place names) and the periods/limit interaction, which are modest for a read-only statistics 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%, so the description carries parameter meaning, and it does so for all six parameters with worked examples ('0008074', 'Portugal', 'Total', 'Mulheres') and the PT/EN enum that the schema itself does not declare. Minor shortfalls: limit is only 'max rows' with no mention of its default of 40 or how it interacts with periods, and units for periods are implied, not stated.

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 the resource (INE indicator values) and the ordering guarantee ('latest periods first'), which is genuinely informative. It does not name a specific sibling to differentiate from, though it does point back to ine_search as the source of varcd, and the verb phrase 'Values of' is slightly passive.

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 varcd entry ('7-digit indicator code from ine_search') implicitly tells the agent this is a second-step tool after ine_search, which is useful routing. However there is no explicit when-to-use/when-not statement, no mention of when to prefer bpstat_series or open_data_search, and no guidance on when a wider or narrower query is appropriate.

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 burden; it usefully discloses that it searches the 'catalogue of key indicators' (a scope limit) and returns varcd codes. However, it omits pagination behavior and what the limit parameter controls, and gives no auth/rate context.

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 and examples, then the return/next-step guidance. The raw "Args:" block is slightly informal but each sentence carries useful 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?

An output schema exists, so return-value explanation is not required, and the description correctly points to ine_indicator as the follow-up. Yet with three parameters at 0% schema coverage, the undocumented limit and thin behavioral detail leave a gap for full completeness.

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. It explains lang well ("PT" more complete wording, "EN") and conveys query semantics via keyword examples, but leaves the limit parameter entirely undocumented.

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 ("Find") and resource ("INE indicators") with keyword-based scope and concrete example queries. It explicitly distinguishes itself from sibling ine_indicator by noting it returns varcd codes to pass to that tool, so an agent can route correctly.

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?

Clearly says to use this to discover indicators by keyword and names the alternative (ine_indicator) when you already know a code, including that codes can be sourced from www.ine.pt. It gives a clear usage context and alternative but stops short of explicit when-not guidance beyond the known-code case.

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 behavioral burden and does well: it discloses the source (www.infarmed.pt), the three lists checked, automatic latest-version behavior, supported status values, and the important limitation that Infarmed's full shortage search is not queried. It does not explicitly state read-only behavior or error handling, keeping it from a 5.

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 front-loaded with the core question and then structured into source details, status values, and arguments. It is somewhat long, but for a multi-list availability check most sentences earn their place; the structure is clear and scannable.

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 complexity, the description is complete enough to call it correctly: it explains sources, checked lists, status semantics, important limitations, and both parameters. Since an output schema exists, it does not need to document return structure in detail.

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 0%, but the description fully compensates with an Args section. It explains that 'medicine' accepts brand name or active substance, optionally with strength/form, and gives useful examples; it also clarifies that 'limit' caps rows per list.

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 question and verb ('Is a medicine in shortage in Portugal? Checks Infarmed's published availability information'), making the resource and scope clear. It does not explicitly distinguish itself from nearby-stock or pharmacy-finding siblings such as find_medicine_near, which keeps it at 4 rather than 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?

It gives clear usage triggers ('when someone can't find a medicine, or asks whether X is in shortage') and even lists Portuguese synonyms like 'rutura', 'esgotado', and 'falta'. It also warns that a 'no issue' result does not prove availability, but it does not name alternative sibling tools for locating stock nearby.

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 carries the burden: it discloses that the content is verified reference data, that each record contains number, purpose, hours 'where published', and the source page it was checked on. That provenance and the hours-availability caveat are genuinely useful behavioral context for a read-only lookup; it stops short of stating outright that it performs no writes or that data is static.

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-loads the resource and its contents in one sentence, then immediately gives the usage triggers. No filler, no restatement of the name or title.

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 zero-parameter reference lookup with an output schema, so the description only needs to convey scope and content shape — both are covered, including the caveat that hours are only published for some lines.

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, which is the baseline-4 case; nothing about the call can be mis-specified. The description adds no parameter detail because none is needed.

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 (verified Portuguese help lines for medicine problems) and enumerates the actual entries returned: 112, SNS 24, Linha 1400, Infarmed. This clearly separates it from siblings like medicine_availability, find_medicine_near and pharmacies, which are about medicines/stock rather than who to call.

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 three concrete activation triggers: can't find a medicine, needs urgent advice, or asks who to call. There is no explicit exclusion or named alternative (e.g., 'use medicine_availability to check stock instead'), so it stops short of full routing guidance but the context 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 carries the full burden of behavioral disclosure. It does not say whether this is a read-only lookup, how matching works, whether errors occur for unknown names, or any other operational trait; the field list is the only substantive context.

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 very short and front-loads the resource, but it is a fragment rather than a structured statement of what the tool does. It avoids waste but omits essential framing.

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?

Although an output schema exists and can explain return values, the description still needs to state the operation and clarify input semantics. With no annotations and no parameter documentation, the definition is not complete enough for an agent to confidently select and invoke the 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?

The single required parameter 'name' has 0% schema description coverage, and the description never explains what 'name' means or its expected format. It only implies that a municipality name is involved through the tool title and the parenthetical '(concelho)'.

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 is a noun phrase defining what a municipality is and listing data fields, but it never states an action such as 'get' or 'look up'. An agent can infer retrieval, but the purpose is largely a restatement of the tool name rather than a clear verb+resource statement.

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?

There is no guidance on when to use this tool versus siblings like ine_search or where_is, nor any mention of prerequisites or expected input context. The description gives no usage conditions at all.

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 carries the full behavioral burden. It implies a read-only lookup and mentions downloadable files, but it does not describe authentication needs, rate limits, whether files are URLs or embedded content, or other operational 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?

The description is a single, front-loaded sentence with no wasted text. It states the resource, the returned content, and the parameter source efficiently.

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 simple one-parameter lookup with an output schema available, the description provides enough to call the tool correctly and understand the parameter source. It is slightly incomplete in not distinguishing this tool from open_data_preview, but the core context is present.

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 0%, so the description must explain the single parameter. It does so by saying the argument is a dataset 'id or slug from open_data_search', which adds meaningful expected-value guidance beyond the bare schema type.

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 resource and operation: details and downloadable files for one dados.gov.pt dataset. It also clarifies that the dataset argument comes from open_data_search, which helps distinguish it from the search tool, though it does not explicitly contrast with open_data_preview.

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 phrase 'id or slug from open_data_search' implies the intended workflow: first search, then fetch dataset details. However, it does not explicitly say when to use this tool versus open_data_preview, nor does it state any exclusions or prerequisites.

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 behavioral burden. It usefully discloses the 512 KB read limit and the 1-100 row constraint, but omits error behavior for oversized or unsupported files and does not clarify whether the full file is fetched or truncated.

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 short and front-loaded: the first sentence states what it does and the main constraint, followed by concise parameter notes. Every sentence 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?

An output schema exists, so return-value explanation is unnecessary. For a simple two-parameter read preview, the description covers format, host restriction, size cap, and row limits. Error handling on unsupported or oversized files is the main omission.

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 0%, so the description must compensate. It explains that url must be a resource URL from open_data_dataset and hosted on dados.gov.pt, and that rows must be between 1 and 100. It does not mention the default of 20, but otherwise adds real meaning beyond the bare schema.

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 operation: return the first rows of a CSV or JSON file hosted on dados.gov.pt. It also ties the url input to open_data_dataset, which distinguishes it from sibling tools. It is clear, though it does not explicitly frame itself as a preview-before-download step.

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 through 'a resource url from open_data_dataset', which tells the agent this follows dataset discovery. However, there is no explicit when-to-use/when-not-to-use guidance and no named alternative for full downloads.

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 carries the burden; it does establish a read-only, non-mutating search and adds the limit ceiling of 1-50, which is useful context. It says nothing about result ordering, pagination, or whether the query matches titles vs. metadata fields, leaving behavioral gaps for a no-annotation tool.

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 purpose sentence is front-loaded and the Args block adds concrete value through examples. Slightly listy but nothing is padded or redundant.

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 values need not be described, and all three parameters are documented despite zero schema coverage. What is missing is guidance on the natural follow-up (open_data_dataset / open_data_preview), which would complete the workflow picture.

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 0%, so the description does the work: it defines query as a topic keyword with concrete examples, organization as an optional publisher filter with examples ('INE'), and limit as a bounded 1-50 range with a default. Only the semantics of how query matching works is left unstated.

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 plus the exact data source ('Search the datasets of Portugal's national open-data portal (dados.gov.pt)'), which lets an agent separate it from generic search tools. It does not, however, distinguish it from its own siblings like open_data_dataset or open_data_preview, which an agent could easily confuse it with.

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 example queries ('acidentes rodoviários', 'escolas') imply the intended use for topic discovery, and the organization param hints at narrowing by publisher. There is no explicit when-to-use or when-to-prefer-a-sibling statement, so an agent must infer that this is the discovery step before open_data_dataset.

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 carries the burden. It usefully discloses the output content (party, constituency, status, seats per party) and the include_inactive default, but omits behaviors like pagination/limit handling and what 'inactive' filtering entails.

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 overview sentence and compact Args list are front-loaded and waste-free. The example values add practical value without bloat.

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 values needn't be explained, but with 0% schema coverage the undocumented limit and legislature parameters leave gaps an agent would need to guess at.

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. It documents name, party, constituency, and include_inactive with helpful examples, but omits limit and legislature entirely, leaving two of six params unexplained.

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 clear resource (Members of Parliament/deputados) and the fields returned (party, constituency, status, seats per party). It is clearly distinguishable from siblings like parliament_votes and parliament_initiative, though it doesn't explicitly name which sibling to prefer.

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 Args section implies how to narrow results (name, party, constituency), but there is no explicit guidance on when to use this versus parliament_search or when not to use it. Usage is inferable rather than stated.

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 exist, so the description carries the disclosure burden. It usefully characterizes the returned content (full phase history, per-group vote breakdown, text link), implying a read-only detail fetch, but says nothing about authentication, rate limits, or behavior for an invalid/missing initiative 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?

The content summary is front-loaded in a single dense clause, then the args block. No filler, though the prose-style 'Args:' block mixed into a description is slightly awkward for an agent parsing intent.

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 the description needn't explain return structure, and it still gives a useful preview of what the record contains. The one incompleteness is the undocumented `legislature` parameter for a tool whose id may need session scoping.

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 there is no description of `legislature` anywhere, which is a real gap since it likely scopes which parliamentary session the id refers to. The `initiative_id` param is well served though: format example ("356403") plus the accepted free-text reference form adds meaning beyond the bare string type.

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 and enumerates exactly what the record contains (phases with dates, per-group vote positions, text link), which distinguishes it from the search-style siblings. It doesn't explicitly name parliament_search as its complement in the purpose line, only in the args block, so it stops 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?

The args section explicitly states where the identifier comes from ("the `id` from parliament_search"), giving the agent a concrete entry path and an alternative accepted form ("Proposta de Lei 3"). No when-not-to-use guidance is given, so it isn't a full 5.

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 behavioral burden and does add useful context: it specifies that results are newest-first, that legislature defaults to the current one, and that 'result' filters on the latest vote outcome. It does not discuss pagination or error behavior, but for a read-only search tool this is largely sufficient.

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 purpose is front-loaded in a single clear sentence, followed by a compact parameter list with no filler. Every argument line delivers actionable detail without repetition.

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 values need not be explained. For a 7-parameter search tool the description covers all parameters and key behaviors; it lacks only minor details such as whether filters are combined with AND logic or whether results beyond limit can be paginated.

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 0%, so the description must compensate, and it does so thoroughly: it gives examples for query terms, valid type strings, party acronyms, result values ('aprovado'/'rejeitado'), date format for since, the Roman-numeral default for legislature, and the meaning of limit. Every parameter gains concrete meaning beyond the bare schema.

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 ('Search initiatives in the Portuguese Parliament') and clarifies the scope with examples of initiative types (bills, resolutions, inquiries). It does not explicitly contrast with sibling tools like parliament_initiative or parliament_votes, so sibling differentiation is left implicit.

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 explains what the tool does and how to fill in parameters, but never states when to use it versus alternatives such as parliament_initiative (for a single initiative) or parliament_votes. No exclusions or prerequisites are given, leaving the agent to infer usage context entirely.

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 behavioral burden. It discloses useful behavior such as newest-first ordering, party filtering only where recorded, and result values, but it does not cover permissions, pagination beyond limit, or the omitted legislature parameter.

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 front-loaded and compact, with a clear Args list that avoids repetition. It is appropriately sized for a retrieval tool, though the Args formatting is slightly mechanical.

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?

The tool has six parameters, no annotations, and an output schema. The description covers purpose and most filters, but it omits legislature and provides no usage alternatives, leaving clear gaps for an agent selecting and invoking the 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 description coverage is 0%, so the description must compensate. It documents five of six parameters with examples and formats, but it completely omits the legislature parameter, leaving a meaningful gap.

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 resource and content: recent plenary votes with each parliamentary group's position. It is clear what the tool returns, but it does not explicitly distinguish itself from sibling tools such as parliament_search or parliament_initiative.

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 explains what each filter does but gives no guidance on when to use this tool versus alternatives. There are no exclusions, prerequisites, or named sibling tools to route the agent.

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 discloses the returned fields, the sort order (on-duty, then open-now, then distance), the duty-day boundary definition (09:00–09:00), that on_duty comes from an official roster, and the lat/lon-without-city fallback behavior. These are non-obvious traits an agent could not infer 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 purpose, then uses cases, then return shape and caveat, then args — a sensible order with no filler. The Args block is long but justified at 0% schema coverage; minor duplication with the earlier field list is the only waste.

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 optional-everything seven-parameter tool with no annotations and no schema descriptions still leaves no ambiguity: all params, their interactions, the sort order, and the correctness caveat about stock are covered. The output schema means the return-value enumeration is a bonus rather than a necessity.

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 is the sole documentation and it fully compensates: every one of the seven parameters is explained, city includes disambiguation examples, radius_km is tied to lat/lon availability, and limit states the default 20 / max 100. The dependency rules (radius requires position) are stated explicitly.

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?

Opens with a specific verb+resource+scope: pharmacies within a Portuguese municipality, with duty status and open-now status. It is clearly distinguishable from stock-oriented siblings (medicine_availability, find_medicine_near) because it explicitly states stock is not public.

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 phrases ("farmácia de serviço em X", "pharmacy open now near me", "list pharmacies to call") and an explicit when-not: never claim a pharmacy stocks a medicine. That exclusion routes the agent away from the wrong use without needing the sibling list.

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 exist, so the description carries the full behavioral burden. It discloses the accepted input formats and enumerates returned fields, but the returned fields are already declared by the output schema, and it says nothing about error handling or whether the 4-digit short form returns a single match or many.

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 action and resource, with the format guidance and return contents following in order of need. Nothing is wasted.

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 one-parameter read lookup with an output schema, this covers what an agent needs: the action, the input format, and a preview of the result shape. The only real gap is behavior for invalid or ambiguous code prefixes.

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 0% and the single 'code' parameter is undocumented in the schema, so the description must compensate. It does so by specifying the exact formats 'XXXX-XXX' and 'XXXX', which is the key semantic detail needed to call the tool correctly.

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 ('Look up a Portuguese postal code') and even gives the accepted code formats. The resource is unambiguous, but the description never differentiates itself from nearby geo siblings such as municipality or where_is.

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: an agent can infer this is for resolving a postal code into district/municipality/locality/streets. There is no explicit when-to-use or when-not, and no alternative tools are named.

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 behavioral burden: it discloses the default year, the '2012 onwards' lower bound, the default sort ('value' = largest first), and that limit caps rows. It does not state read-only nature, result pagination, or what happens when filters match nothing, leaving gaps for an unannotated tool.

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 states purpose and scope, followed by a compact per-argument list where each line adds real information. The 'Args:' docstring formatting is slightly programmer-flavored but costs nothing in length.

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 values need not be explained, and the description fully specifies the 9-parameter filter surface including units, formats, defaults and enumerated sort values. An agent has everything needed to construct a call correctly.

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 0%, so the description carries everything: it explains each of the 9 parameters, gives realistic example values including Portuguese terms, clarifies that buyer/supplier accept either a name or a 9-digit NIF, gives the price units (euros), and enumerates the sort modes.

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 ('Search Portuguese public contracts') plus the data source (Portal BASE) and a scope constraint ('for one year'). It does not distinguish itself from the sibling public_contracts_summary, so an agent must infer that this returns individual contracts rather than aggregates.

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 by the parameter list and query examples ('software', 'limpeza'). There is no explicit when-to-use/when-not-to-use guidance and no mention of the sibling summary tool as an alternative for aggregate questions.

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 carries the full burden; it implies a read-only aggregation and discloses the shape of the summary (counts, totals, procedure breakdown, top counterparties). It does not state the underlying data source or coverage, whether entity names are fuzzy-matched, or how the ranking in 'top partners' is computed (by value or by count).

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 summary sentence is front-loaded and wastes no words, followed by a tight per-argument block. Slightly telegraphic phrasing ('by procedure, top partners') but nothing extraneous.

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 four parameters at 0% schema coverage and an output schema present, the description does cover the calling surface adequately. What it leaves out is the routing question an agent actually faces: how this differs from `public_contracts`, and how ambiguous entity names are handled.

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 carry all parameter meaning — and it largely does: `entity` accepts a name or 9-digit NIF, `role` takes buyer/supplier/any (values the schema does not enumerate), `year` defaults to the current year, `top` is the count of counterparties to list. The only gap is a small inconsistency: the schema default for `year` is null while the description says 'this year', without confirming null means current year.

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 concrete resource (public contracts) and an aggregate operation (totals for one entity in a year), and enumerates the output dimensions: count, total value, breakdown by procedure, top partners. That is enough to distinguish it from a raw listing tool. It stops short of naming the sibling `public_contracts` explicitly, so the differentiation is inferred rather than stated.

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 the word 'totals' versus the sibling `public_contracts`, which presumably returns individual contract records, but the description never says when to prefer one over the other. There is no guidance on prerequisites, entity-name resolution, or what happens when a name matches multiple bodies.

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 burden and does disclose important behavioral caveats: default year is the current year, weekdays are included, Carnival is optional, and municipal holidays are excluded. It could say more about valid year ranges or read-only nature, but the behavioral context is solid for a simple lookup tool.

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 short, front-loaded, and every sentence adds useful scope information. The exclusions are clearly separated and no wording is wasted.

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 values need not be explained. However, the description omits the upcoming_only parameter and any guidance on valid year ranges, which leaves a noticeable gap for a tool with 0% schema description coverage.

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 0%, so the description must compensate for both parameters. It clarifies the year parameter's default ('this year') but does not mention the upcoming_only parameter at all, leaving one of two parameters semantically undocumented.

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 that this returns Portugal's national public holidays for a year, including weekday, and distinguishes the scope from Carnival and municipal holidays. It is specific but does not explicitly contrast with a sibling tool, so 4 is appropriate.

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 gives useful scope guidance: Carnival is optional and municipal holidays are excluded, which helps an agent know when this tool is and is not appropriate. It stops short of naming an alternative or giving explicit when-to-use instructions, so it is not a 5.

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 exist, so the description carries the full disclosure burden. It usefully reveals the provider (IPMA) and the covered measures, implying Portuguese coastal coverage, but says nothing about units (metres vs feet, °C), whether place or lat/lon wins when both are supplied, or what happens for an unknown spot.

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-loads the purpose in one sentence and then gives a compact Args block; there is essentially no filler. The Args formatting is slightly redundant with the schema but remains easy to scan.

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 detail is not required, but for a tool with four undocumented-schema parameters and no annotations, the description should also cover units and place/lat-lon precedence. It is adequate to call the tool but not fully complete.

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 0%, so the description must compensate, and it largely does: it gives example place values ('Nazaré', 'Peniche', 'Faro', 'Funchal'), explains the lat/lon fallback to the nearest spot, and decodes day (0=today, 1=tomorrow, 2=day after). Only the precedence between place and lat/lon and the neither-provided case are left unstated.

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 (coastal sea forecast) plus the exact quantities returned: wave height and period, wave direction, sea temperature, with the data source (IPMA) named. This distinguishes it from the land-oriented weather_forecast sibling, though it never explicitly contrasts the two.

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: an agent must infer that this is the tool for sea/beach conditions rather than general weather. There is no explicit when-to-use, when-not, or named alternative (e.g. weather_forecast) to disambiguate the two forecast tools.

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 well: it discloses data provenance and freshness ('official monthly statistics, latest month usually 2-3 months back, provisional'), a hard coverage limit (no specialty breakdown), and the precedence rule that region is ignored when institution is supplied. It does not cover failure modes (unknown institution names, out-of-range periods) or behavior when data is missing.

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?

Well front-loaded: purpose, then triggering questions, then caveats, then args — an agent can stop reading after sentence one and still act. Slight redundancy in restating 'for the month and year-to-date' and a longer-than-needed list of returned fields given an output schema exists.

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 four-optional-parameter statistics tool with no annotations, everything needed to call it correctly is present: scope, data lag/provisionality, coverage gaps, period semantics, and the institution-vs-region precedence rule. An output schema exists, yet the description still summarizes returned fields as a bonus.

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 0%, yet the Args block fully compensates: institution is mapped to its ULS, region enumerates all five values, period specifies the "YYYY-MM" format and default, and months gives default 6 with a max of 24. The critical precedence rule ('region ignored if institution is given') is stated explicitly and is not derivable from the schema.

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 opening sentence states a specific metric set (monthly hospital outpatient consultations plus % of first specialist consultations within the guaranteed maximum time) and a specific scope (TMRG/CTH/SIGA referrals). This is clearly distinguishable from siblings like sns_surgery_wait_stats and sns_emergency_stats, which cover different event types.

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?

Three concrete user-question templates ('how long is the wait for a first hospital appointment at X?', 'is hospital Y on time…', 'how many consultations did the Centro region do?') make the triggering context unambiguous. It also sets a boundary ('no breakdown by specialty in the open data'), but it never names or routes against a sibling tool.

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 well: it warns the latest month is usually 2-3 months back and provisional, explains that a hospital name is mapped to its ULS (check `scope`), and notes region is ignored when institution is given. It does not say what happens on an unknown institution name or an out-of-range period, which is the main remaining gap for a data-lookup tool.

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?

Well front-loaded: purpose, then use-cases, then scope, then output fields, then args. It is on the long side and some content (enumerating what red/orange/yellow mean, the 112/SNS 24 disclaimer) sits beyond what is needed to call the tool, especially since an output schema exists.

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 zero-required-parameter statistics tool with an output schema, nothing essential is missing: scope semantics, data lag, defaults, and unit/format conventions are all covered. An agent could invoke it correctly from the description alone.

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 0%, so the description must compensate and it does: `institution` is accent-insensitive with worked examples, `region` enumerates the five accepted values, `period` specifies the YYYY-MM format and default of newest available, and `months` gives default 6 and max 24. Every parameter is fully specified in prose where the schema is bare.

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 precise verb+resource: monthly emergency-department visits broken down by visit type and Manchester triage colour. It immediately distinguishes itself from the live-queue alternative by declaring 'OFFICIAL MONTHLY STATISTICS ONLY' and pointing live waiting times elsewhere, so an agent can route correctly 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 example queries it answers ('how busy is the ER at X?', 'what share of ER visits are green/blue?') and explicit exclusions ('not the live queue', send the user to tempos.min-saude.pt for waiting times). It also states the scope rule: one institution, one region, or all mainland SNS hospitals.

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 enumerates each returned field, explains that `stats_entity` is a ULS/group-level name rather than a building-level one, and discloses a non-obvious quirk ('Without `query`, umbrella ULS entries are skipped (they duplicate a hospital's location)'). It also warns about the absence of live wait times, preventing a likely misuse.

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 purpose, then usage, then return shape, then args — a logical order with no filler sentences. It is on the long side (~200 words): the important 'umbrella ULS skipped without query' caveat is buried inside the lat/lon sub-bullet rather than surfaced earlier.

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 5-param, zero-annotation, zero-schema-documentation tool, the description supplies everything an agent needs to select and call it correctly, plus the hand-off contract to the three stats tools. An output schema exists, so return values need not be re-explained, and the field enumeration is justified anyway because it clarifies `stats_entity`.

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 five params: `query` is accent-insensitive with examples, `lat`/`lon` are WGS84 and sort by distance with a sample coordinate, `emergency_only` filters to emergency-reporting sites, and `limit` gives default (10) and max (50). It also explains the interaction between `lat/lon` and `query`, 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?

Opens with a specific verb and resource: 'Find SNS hospitals / local health units (ULS) by name, or the nearest ones to a coordinate.' It explicitly separates this lookup role from the statistics siblings (sns_emergency_stats, sns_surgery_wait_stats, sns_consultation_wait_stats) that consume its `stats_entity` 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?

States a clear trigger ('Use this first when the user names a hospital or a place') with two concrete example queries, defines the follow-up step (pass `stats_entity` to the stats tools), and gives an explicit when-not with a redirect ('This list does NOT contain live waiting times; for live emergency waits send the user to https://tempos.min-saude.pt').

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 zero annotations the description carries the full burden, and it delivers real behavioral context the agent could not otherwise know: results are "official statistics, not live data", and hospital-activity datasets store year-to-date cumulative values so a single month must be differenced. It also discloses the limit ceiling (max 100) and paging via offset. It stops short of stating read-only semantics or failure behavior for a bad dataset_id, which keeps it off a 5.

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 opening sentence front-loads purpose and API version, then bullets keep the clause reference scannable. The cumulative-values warning is the longest block, but it is high-value domain context rather than filler. Slightly dense, yet no sentence is expendable.

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 shape needs no explanation, and the description covers the query dialect, field conventions (tempo, regiao, instituicao/entidade), and result-size controls. The main remaining gap is error/empty-result behavior and whether the call requires any auth, which for a 7-parameter free-form query tool would help.

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 0%, so the description must compensate entirely, and it does: every parameter is explained with concrete ODSQL syntax (where with `like` and date'YYYY-MM-DD', select with aggregates, group_by, order_by), dataset_id gets a real example, and limit is given a default and max. This is meaningfully more than the schema's bare titles and defaults.

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: "Run an ODSQL query on any SNS Transparency portal dataset (Opendatasoft Explore API v2.1)". It immediately distinguishes itself from the curated siblings (sns_emergency_stats, sns_surgery_wait_stats) by framing itself as the general-purpose escape hatch, and even names the upstream API so the query dialect is unambiguous.

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 sns_search_datasets for anything the curated tools don't cover" gives both the prerequisite tool and the exclusion condition that routes the agent here. The dependency on sns_search_datasets for dataset_id is reinforced in the Args section, so an agent knows the entry path.

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 carries the behavioral burden and does well: it discloses Portuguese-language titles/descriptions, accent-insensitive matching, empty-query listing behavior, and that limit is ignored when listing all. It does not cover error behavior or rate limits, but the key search semantics are clear.

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 purpose, followed by usage guidance, workflow, and parameter notes. The examples and formatting earn their place by making search behavior and follow-up steps immediately actionable.

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 an output schema exists, the description need not explain return values in detail, and it still explains the important listing behavior. It also connects the tool to sns_query_dataset, making the overall workflow complete for an agent.

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 0%, but the description fully compensates by explaining query as Portuguese keywords with examples, empty query as list-all returning id and title, and limit as default 10, max 50, ignored when listing all. This adds substantial meaning beyond the bare schema.

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: search the ~150 datasets of the SNS Transparency portal. It also distinguishes itself from curated tools and names the follow-up sibling sns_query_dataset, so an agent can place it precisely.

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: when curated tools do not cover the question, with concrete examples such as hospital bed occupancy, births, INEM calls, and cancer screening. It also states the next step: call sns_query_dataset with the returned dataset_id and field names.

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 well: it discloses that figures are official monthly statistics, usually lagging 2-3 months, provisional, and lacking specialty/procedure breakdowns. It also clarifies metric definitions such as LIC, TMRG, and that mean days before surgery is not time on the waiting 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?

The description is front-loaded with purpose, use cases, and limitations, then organizes metric definitions and arguments into clearly labeled sections. Despite its length, every part earns its place by compensating for the absent annotations and undocumented schema parameters.

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 four parameters, 0% schema coverage, no annotations, and the presence of an output schema, the description is complete enough for correct invocation. It covers input semantics, data freshness, limitations, and metric meanings without needing to duplicate return-structure documentation.

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?

Although schema description coverage is 0%, the Args section fully explains all four parameters: institution mapping to ULS, region values and precedence, period format and default, and months default/max. This adds clear semantics beyond the bare schema types.

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 resource and scope: monthly surgery access indicators including waiting list, TMRG compliance, mean days to surgery, and surgeries performed. It distinguishes itself from sibling tools like sns_consultation_wait_stats by focusing explicitly on surgical waiting statistics.

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 gives concrete usage examples for wait times, regional list sizes, and hospital operation volumes, and it explicitly notes the lack of specialty/procedure breakdown. However, it does not name alternative tools or state when to use another sibling instead, leaving routing slightly 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?

With no annotations, the description carries the burden and does disclose a genuinely important behavior: with lat/lon 'the nearest IPMA forecast location is used', so the agent knows results may be snapped to a nearby station rather than the exact point. It also lists the returned fields. It does not cover failure behavior for unknown place names or non-Portuguese coordinates.

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 core purpose is front-loaded in the first clause, followed by a compact parameter block and a one-line return summary. No sentence is 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?

An output schema exists, so the return-value sentence is a bonus rather than a necessity, and the location-snapping behavior is well covered. The gap is the all-optional parameter set with no statement of the valid call combinations or error conditions.

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 0%, but the description compensates well: 'place' is defined as a district capital or island town with four concrete examples, and lat/lon is framed as an alternative input mode. It does not state that at least one of the three optional parameters must be supplied, which is a real ambiguity given all params are optional.

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 (5-day weather forecast) with explicit scope: Portugal, IPMA as the official source. The scope statement alone separates it from siblings like sea_forecast and weather_warnings, which cover different domains.

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 place-vs-lat/lon argument split implies the usage pattern, and 'use instead of place for anywhere else' gives a selection rule between the two modes. But there is no guidance on when to pick this over weather_warnings or sea_forecast, and no note on what to do when a location is outside IPMA coverage.

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 carries the full burden. 'Active' implies only currently-in-effect warnings are returned and include_green clarifies what is excluded by default, which is useful. It does not mention data freshness, source update cadence, or any auth constraints, leaving some behavioral gaps for a tool with zero annotation coverage.

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 purpose is front-loaded in one line, followed by a compact args list where each entry earns its place. Slightly list-heavy but no wasted prose.

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 values need not be described, and both parameters are explained with defaults and examples. Complete enough for a two-param read tool; only minor gaps around data freshness remain.

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: area is given concrete examples ('Lisboa', 'Madeira', 'Açores') plus the omit-for-country semantics, and include_green is explained with its default. This adds real meaning beyond the bare schema types.

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 (active IPMA weather warnings) and enumerates the warning categories covered, which lets an agent distinguish it from weather_forecast or sea_forecast. It stops short of explicitly naming those siblings as alternatives.

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 area parameter documentation implies when to scope down ('omit for the whole country') and include_green clarifies the default behavior. However, there is no explicit guidance on when to prefer this tool over weather_forecast or sea_forecast, so selection relies on the agent inferring from names.

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?

Since there are no annotations, the description must bear the full burden. It provides excellent behavioral context by listing the rich data returned, including 'altitude, land use and hazard maps,' which informs the agent about the depth of the output beyond simple location 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?

The definition is a single, highly effective sentence that gets straight to the core functionality and scope without any extraneous detail.

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 minimal input schema and lack of annotations, this description is exceptionally complete. It informs the AI exactly what the tool does and what types of data the user will receive upon invocation.

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 only defines 'lat' and 'lon' as basic numbers. The description significantly adds value by defining the semantic context of those parameters—that they are lookup points for detailed geographic and environmental analysis.

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 defines the function as coordinate resolution (finding parish, municipality, and district) based on the input coordinates. While highly specific, it does not explicitly contrast itself against every related sibling tool, which prevents a perfect score.

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 tool implies usage when detailed geographic and environmental context (like land use and hazards) is required for a given point. However, it provides no explicit guidance on when *not* to use it, nor does it route the agent to alternatives like `municipality`.

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