Spain Open Data

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

Annotations already declare read-only, idempotent and open-world behavior, and the description adds substantial non-obvious context on top: counts are lower bounds because OSM is volunteer-mapped, an INE cross-check reports regional completeness, and the return is aggregates-only rather than premise lists. That is exactly the kind of data-quality caveat structured fields cannot express.

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 sentence and every later sentence carries distinct information (use cases, ranking intent, OSM caveat, INE check, return boundary). It is somewhat dense with long clauses, but 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?

With an output schema present, return format need not be re-explained, and the description covers the remaining burden: what is counted, how it is normalized, expected use cases, ranking semantics, data-source limitations and the aggregate-only contract. An agent has everything needed to call it 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 coverage is 100%, so the schema carries the parameter detail (baseline 3). The description still adds interpretive value by tying ranking to 'per_10k_residents' for spotting under-served sub-areas and by framing what 'category' means in use ('how many gyms, cafés or dentists'), rather than merely restating the fields.

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 and resource ('Count businesses of a kind in a place in Spain'), plus the two normalizations (per 10,000 residents, per km²) and the data source (OpenStreetMap). This distinguishes it from siblings like market_size, demographics and income without the agent needing to open any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete use cases ('size competition and supply', compare with province/region/Spain, find over- or under-served districts) and an explicit scope boundary ('Returns counts and brands only, never lists of individual premises'). It does not, however, name sibling alternatives such as market_size or compare_areas for overlapping tasks.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, so the bar is lower, yet the description still adds real behavior: addresses are validated against the named municipality and ambiguous ones are refused with suggestions, and supplying a category conditionally adds market size, competitors and an opportunity score. These conditional-output and failure-mode details are exactly what the agent cannot infer from the structured fields.

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?

Roughly three sentences, front-loaded with the verb 'Profile the area', followed by conditional capability, use cases, then a caveat about address validation. Dense but every clause carries information; only the interleaved example quotes make it slightly harder 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?

With an output schema present and annotations covering the safety profile, the remaining burden is purpose, input intent, conditionality and failure handling — all covered. An agent can decide to call this tool and predict the refusal path for ambiguous addresses without opening the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, and the description adds meaning on top: it frames radius_m versus walk_minutes as mutually exclusive ways to define the area ('instead of a circle') and ties category to the extra outputs it unlocks. It stops short of example syntax for coordinates or walk times, which the schema already handles.

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: profile the population, households, income, age and mapped businesses within a radius or walk time of an address, with market size and an opportunity score when a category is given. That scope is clearly distinct from point-topic siblings like income or crime, but the description never names an alternative tool (e.g. compare_areas or demographics), so the differential 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?

Offers concrete trigger scenarios ('who lives within 800 m of this shop', 'is there room for a bakery near Calle X') that make the intended use easy to recognize. It does not say when to prefer a sibling such as market_size or demographics, nor when this tool is the wrong choice, so it stops short of full routing 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?

Annotations already declare read-only, idempotent, non-destructive behavior, so the bar is lower. The description still adds real value: the output is an image plus the underlying text and sources, a source line is stamped on the image, and it degrades gracefully by returning text if drawing fails.

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 action and output type, with the failure-mode caveat last. Every clause earns its place and nothing is padded.

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 a full output schema and 100% parameter coverage, the description need not restate return values or param formats, and it still covers output composition and failure behavior. Only the when-to-use routing is thin, which is a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, including detailed enum semantics and place-code formats, so the schema carries the parameter burden. The description adds no format or syntax detail beyond what the schema already documents; baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Draw a chart (PNG)') and enumerates the exact four chart kinds that match the kind enum, so an agent immediately understands the scope. No sibling tool draws images, so this is clearly differentiated from income, demographics, etc.

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 'of a tool result' implies this wraps/enriches the data tools (income, opportunity), but the description never explicitly says when to prefer a chart over the bare numeric tool, nor names alternatives or exclusions. Usage is inferable but not 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?

Annotations already cover safety and idempotency, and the description adds substantial behavioral context: what each area returns (yearly market in euros, estimated competitors, opportunity score with ranges), how areas are ranked (by the cautious low end), and that areas too small are excluded and counted.

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 ranking purpose and moves efficiently through output details and examples. It is appropriately sized, though the middle sentence partially repeats what the output schema likely covers, keeping it just short of maximally concise.

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 rich schema, annotations, and an output schema, the description is nearly complete: it covers purpose, usage, output shape, ranking, and exclusion behavior. It still lacks explicit alternative-tool routing and does not mention the limit parameter's behavior, leaving a small gap for a multi-tool environment.

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 100%, so all four parameters are already documented in the schema. The description adds only contextual phrasing like 'for a category' and does not provide additional parameter syntax, defaults, or constraints beyond what the schema supplies.

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: ranking areas by market per competing business for a category. It identifies the core output as the opportunity score and gives concrete examples, which differentiates it from sibling tools like market_size or catchment.

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 gives clear usage examples ('where in Valladolid should I open a gym') that establish when to use the tool. However, it does not name alternatives or state when not to use it, so the routing guidance is present but incomplete.

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

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

Annotations already declare this a read-only, idempotent, closed-world lookup, so the safety bar is low. The description adds genuinely non-obvious behavior: the 20,000-resident coverage threshold and the province-level fallback, plus the note that the response flags when the fallback occurred. That is meaningful disclosure beyond the structured fields.

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, no filler, with the core content (what data, what measures, what comparisons) front-loaded. The second sentence is slightly halting in construction but carries distinct information about coverage that 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 documentation is not required, yet the description still tells the agent what quantities come back (rates, year-on-year change, YTD) and that fallback provenance is included. Combined with the schema and annotations, nothing needed to call this correctly 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 100% and the single 'place' parameter's schema description already spells out accepted formats (INE codes, municipality/province/community/district/tract, 'Name, Province' disambiguation). The tool description adds nothing about parameter syntax, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific resource (recorded crime from the Interior ministry), enumerates the offence types, the normalization (per 1,000 residents), the time dimension (latest full year, change on prior year, YTD), and the comparison geographies. An agent can distinguish this from demographics, income, rents or businesses without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The second sentence gives real applicability context: coverage starts at municipalities over 20,000 residents, provinces and regions, and smaller places silently fall back to province figures. It doesn't name an alternative tool (e.g. resolve_place for ambiguous names) or state exclusions, so it stops short of 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?

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds real behavioral context beyond that: it discloses the data sources (INE census, official Padrón, INE income atlas) and, critically, that the returned variables differ by place granularity (municipality/province/CCAA vs district/tract), which is not derivable from the annotations.

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 the resource set, and the body is organized by geographic level. It is slightly repetitive in restating 'Municipality, district and tract', but each line carries distinct content about which metrics apply where.

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, return-value explanation is unnecessary, and the description covers scope, sources, granularity-dependent outputs and the sub_areas use case. It is largely complete for a two-parameter read tool, with only sibling-level differentiation left implicit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description goes further by tying place granularity to which metrics come back and by explaining the practical intent of sub_areas, adding meaning beyond the enum/default already 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 names the concrete resources returned (population, sex, five-year age bands, 5-year trend, household size, single-person households, mean age, share under 18/65+) and the geographic scope (a place in Spain), so an agent knows exactly what data this yields. It does not, however, explicitly contrast itself with adjacent siblings such as income, rents or crime, so it stops short of full sibling differentiation.

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 situational guidance for the sub_areas parameter ('Use sub_areas to compare a city's districts or tracts, e.g. to find where young families or older residents concentrate'), which tells the agent when to reach for sub-area breakdowns. There is no explicit when-not guidance or naming of alternative sibling tools (e.g. income or rents) for related 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds the fact that results come from an external national catalogue and that Spanish queries work best, but the enumerated return fields are largely duplicated by the existing output schema rather than adding new behavioral 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?

Two tight paragraphs: purpose first, then return contents, then the usage trigger. Every sentence carries information an agent needs, with no filler or restatement of the 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?

Purpose, usage condition, output shape and the hand-off to read_dataset are all present, and the output schema plus annotations remove the need to dwell on return format. Minor redundancy in re-listing returned fields is the only thing keeping it from a 5.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so query, place and limit are all documented in the schema itself. The description reinforces the query semantics ('Spanish works best') but adds no new meaning for place or limit; baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — searching Spain's national open-data catalogue (datos.gob.es) for datasets on a topic — and names the sibling (read_dataset) that consumes its output. An agent can distinguish it from sibling tools like businesses or demographics without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit trigger: 'Use when a question needs data this server does not hold directly,' with concrete domains (parking, licences, local events, tourist offices, transport). It also names the follow-up tool (read_dataset) and the id needed to call it, so the routing is unambiguous.

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

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

Annotations already declare read-only, idempotent and open-world behavior; the description adds an important freshness caveat ('the atlas runs about two years behind') and the currency basis, which the agent cannot infer from annotations. It does not discuss rate limits or auth, but with annotations covering safety a 4 is warranted.

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 well-structured, moving from purpose to returns to usage to caveats. The lengthy enumeration of return fields is somewhat redundant given the output schema, which keeps it from a 5.

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 handling return values and annotations covering safety, the description supplies the key missing context: data vintage and practical use cases. It does not direct the agent to alternative tools for overlapping needs, a minor gap for a data-retrieval 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 100%, so the schema fully documents all four parameters including formats and enums. The description adds no parameter-specific meaning beyond what is already in the schema, making the baseline 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Starts with a precise resource ('Household income for a place in Spain... down to census tract') and enumerates the returned metrics, so the agent knows exactly what data it retrieves. It does not explicitly contrast itself with sibling tools like demographics or price_band, which keeps it from 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?

Provides concrete use cases ('purchasing power, price positioning and choosing between districts'), giving clear context for when to invoke it. It offers no when-not guidance or named alternatives among the siblings, so it stops short of 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?

With annotations covering safety (readOnly, idempotent, non-destructive), the description goes far beyond by disclosing the computation model (households × INE spend × income adjustment; supply calibrated against the INE directory), the return contract (market per business plus an opportunity score relative to the region), and an explicit non-goal ('not a forecast of openings'). It also notes assumptions are listed and overridable.

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 units, then method, returns, and usage, with every sentence carrying information. Minor redundancy in stating assumptions are listed and then again overridable, and the formula clauses are terse, 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?

For a 5-parameter analytical tool with an output schema and full annotation coverage, the description supplies the missing pieces an agent needs: units (euros), geographic granularity, methodology, the meaning of the opportunity score, and the override-for-scenarios affordance. Nothing essential is omitted.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds purpose-level meaning to the optional parameters: they exist so 'assumptions can be overridden to test scenarios'. It does not add per-parameter syntax (e.g. valid ranges for capture_share), so it is not a full 5.

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 ('Size the yearly market for a business category in a place in Spain, in euros, with a range'), naming the units and geographic scope. This is clearly distinguishable from siblings like businesses, catchment, or income, which compute different quantities.

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 gives the triggering questions: 'how big is the market for X in Y' and 'is Y under-served for X'. It provides clear positive context but no exclusions or naming of an alternative sibling (e.g. when to use income or businesses instead).

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so safety is covered. The description goes further by disclosing the adjustment method (CPI for the category's group, then local median income per consumption unit against the reference place) and the output shape: a range from no adjustment to full adjustment, explicitly labelled an estimate rather than a market price.

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 tight paragraphs: the first states the purpose, the second supplies the rationale and mechanics. Front-loaded and free of filler, though the line-broken mid-sentence formatting is slightly awkward and the second paragraph is dense.

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-parameter analytical tool with an output schema, the description covers the method, the data limitation, and that the result is an estimated range — enough for an agent to decide and call correctly. It could still note whether results are Spain-only or how the returned range should be interpreted, but the gaps are minor given the 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 100%, so baseline is 3. The description adds genuine meaning beyond the schema by explaining how 'category' and 'price_month' feed the CPI uprating and how 'reference_place'/'reference_price' define the base against which local adjustment is applied, clarifying the interaction of the five parameters.

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 names a specific verb (suggest) and resource (price range for a place) plus the two inputs driving it (local purchasing power and inflation). It also states the key scope constraint — public data has no competitor prices — which separates it from data-lookup siblings like rents or income that return observed local figures rather than an adjusted estimate.

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 a clear condition for use: you must already have a price 'from elsewhere or an earlier date' to adjust, which effectively excludes use as a primary price-discovery tool. It does not, however, name alternative siblings (e.g. rents, income, market_size) or say what to do when no reference price is available.

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

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

Annotations already declare read-only, idempotent, non-destructive, open-world behavior, and the description adds genuinely new operational facts: a 20-row sample cap, a 5 MB read limit, and that personal-data-looking columns (names, IDs, emails, phones) are withheld. That privacy-filtering disclosure is exactly the kind of trait annotations cannot express.

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 paragraphs, front-loaded with what is returned before the constraints. Each sentence carries a distinct fact (return shape, file scope and size cap, PII withholding, fidelity of values) with no 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?

With an output schema present, the description need not explain return structure, yet it still summarizes the payload (columns, sample rows, licence). Combined with annotations covering the safety profile and complete schema coverage, an agent has everything needed to call it 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 100%, and both parameters are already documented there (dataset_id from find_datasets, file_index selection with a stated default). The prose adds no parameter-level syntax or format detail beyond what the schema provides, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (read) plus resource (datos.gob.es dataset) and enumerates exactly what is returned: columns, up to 20 sample rows, and the licence. This clearly separates it from the search-oriented sibling find_datasets.

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 establishes the operating context (only CSV and JSON files listed in the catalogue, only the first 5 MB) and the schema ties dataset_id back to find_datasets, so an agent can infer the follow-up-after-search workflow. It stops short of an explicit when-not-to-use statement or naming an alternative 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?

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds genuinely new behavioral context: the index construction (IPVA, 2015=100), that results are relative changes rather than euro amounts, and the hard coverage exclusions (Basque Country and Navarra).

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, then the supporting geographies and caveats in short sentences. The three-line layout is efficient, though the coverage list is slightly list-heavy and the exclusions could be tightened.

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-format explanation is not needed, and the description covers scope, measurement basis and coverage limits. The only gap is that it doesn't hint at using resolve_place when a bare place name is ambiguous, a step the sibling list suggests is available.

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?

With 1 parameter at 100% schema description coverage, the schema already documents accepted formats exhaustively (municipality name/code, province code, community code, district, census tract, and 'Name, Province' disambiguation). The description only restates the entity types covered, adding no syntax beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific resource (INE IPVA rent index, 2015=100) and exactly what the output measures: change over 1 year, 5 years and since 2015, compared against province, region and Spain. It also draws a sharp boundary ('gives changes, not rents in euros'), which separates it from euro-denominated siblings such as price_band or income.

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 rather than stated: an agent can infer this is the tool for rent-trend questions. The geographic eligibility rules (municipalities >10,000 residents, districts of provincial capitals, provinces, regions) function as practical use constraints, but there is no explicit when-to-use-vs-alternative guidance and no reference to resolve_place for ambiguous 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?

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial behavior beyond them: best-match-first ordering with alternatives returned, multilingual/accents handling, and the non-obvious district/tract neighbourhood-name mapping in both directions. This is exactly the extra context an agent cannot get from structured fields.

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 and the 'use first' directive, then uses the remaining lines for genuinely load-bearing detail on matching and neighbourhood resolution. Slightly long with the parenthetical examples, but every clause carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return shape needn't be spelled out, yet the description still explains return semantics (best match first, alternatives follow). Combined with annotations and full schema coverage, an agent has everything needed to invoke and interpret this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single param is already described, so baseline is 3. The description adds real meaning beyond the schema: that the query accepts INE codes, multilingual/English place names, and neighbourhood names ('Parquesol, Valladolid') that resolve to a containing district.

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 (resolve a Spanish place to its INE code and level) and enumerates the level taxonomy (CCAA, province, municipality, district, tract). No sibling tool overlaps with place resolution, so an agent can immediately route here for geographic grounding.

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 'Use this first when a question names a place,' which gives clear priority ordering relative to the sibling dataset tools (income, crime, demographics, etc.) that all need a place code. It does not name a specific alternative or state when-not-to-use, so it falls just short of a 5.

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