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 (readOnly, idempotent, non-destructive), but the description adds real behavioral detail beyond them: the scoring basis (ranked by the cautious/low end), the outputs per area (yearly market in euros, competing businesses, opportunity score with ranges), and the exclusion rule with counting. Only latency/cost behavior is unaddressed.

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 in sentence one, then ranking mechanics, then examples. Sentence two is a dense run-on ('all with ranges') but every clause carries information; no 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?

Despite an output schema existing, the description still conveys the shape of results (market estimate, competitors, opportunity score) and the ranking/exclusion semantics an agent needs to interpret them correctly. Nothing material is missing for a read-only analytics 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 all four parameters are already documented in the schema. The description adds marginal meaning, only implicitly linking 'towns' vs 'districts' to the level parameter and mentioning the small-area exclusion that relates to limit.

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 (rank) and resource (areas) plus the exact metric framing: 'most market per business'. This is clearly distinguishable from siblings like market_size or catchment, which do not rank areas against a category.

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 usage triggers via two natural-language example questions ('where in Valladolid should I open a gym', 'which towns in Málaga province lack pharmacies'). It does not, however, explicitly state when to prefer a sibling such as market_size or catchment 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 cover read-only, idempotent, non-destructive, closed-world behavior. The description adds genuine non-annotation context: only municipalities over 20,000 residents have their own figures, smaller places return the province's data, and the result itself indicates this fallback. That is exactly the kind of reliability caveat an agent needs.

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 data content and ending with the coverage caveat. Dense but every clause (offence types, unit, comparison levels, publication threshold) adds information; only the long enumeration in the first sentence slightly taxes readability.

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 a single fully documented parameter, rich annotations, and an output schema that handles return values, the description supplies everything else needed: what is measured, the unit, comparison geographies, and the fallback for small places.

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 the single 'place' parameter is thoroughly documented in the schema (INE codes, format variants, disambiguation with 'Name, Province'). The description adds no parameter-level detail beyond that, 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 (Interior ministry recorded crime) with the exact metric (offences by type, per 1,000 residents, YoY change, YTD), so an agent immediately knows what data it returns. No sibling tool covers crime statistics, so it is inherently distinguished from businesses, income, rents, 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?

Usage is only implied by the data domain; there is no explicit 'use this when… / not for…' statement or named alternative. The coverage note (smaller places fall back to province figures) hints at scope but is a behavior caveat rather than 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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuine context beyond that: which official source backs each geography level (census/Padrón vs INE census-tract file vs income atlas) and that figures are latest-1-January and cross-checked, which tells an agent what the numbers actually represent.

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 deliverable in the first sentence, then organized as a geography-to-dataset mapping, which is easy to scan. It is slightly repetitive in re-listing the same geography triples, but every clause carries substantive 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?

With an output schema present, return-value documentation is unnecessary, and the description covers the remaining concerns: data provenance, per-geography coverage, the required place identifier, and the optional sub-area expansion. Only an explicit sibling-comparison rule (demographics vs income/market_size) 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%, so the baseline is 3. The description earns a notch above that by tying data availability to the geography argument: municipality/province/CCAA yield census plus Padrón, district/tract yield census age bands and sex, and household metrics exist only at municipality/district/tract — context the schema does not state.

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 the exact resource set (population, sex, five-year age bands, trend, household profile) and the exact scope (a place in Spain). The enumerated geography levels and data sources make it unmistakable against siblings such as income, rents, crime, or businesses, which cover entirely different subject matter.

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 one concrete usage example ('use sub_areas to compare a city's districts or tracts, e.g. to find where young families or older residents concentrate'), which is implied guidance rather than an explicit when-to-use rule. It never states when to prefer demographics over income, market_size, or catchment, nor any exclusions.

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 the safe read-only, idempotent profile, so the bar is lower. The description adds meaningful context beyond them: the data lag (~two years behind), that figures are euros of the data year, and the benchmark scope (province, region, Spain). It doesn't discuss pagination or output shape, but with annotations and an output schema those matter less.

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 core identity (income for a place, source, granularity) in the first sentence, then enumerates returns and use cases without waste. Dense but every clause 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?

With an output schema present, return values need no prose explanation, and the description still covers source, granularity, benchmark scope and a key freshness caveat. Nothing an agent needs to call it 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 description coverage is 100%, so the schema already fully documents place, years, rank_by and sub_areas with enum values. The description touches the trend and sub-area ranking conceptually but adds no syntax or format detail beyond the schema, so 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+resource (household income for a place in Spain) with source (INE income atlas) and resolution (down to census tract). It clearly distinguishes from siblings like rents, crime or demographics by naming the exact dataset and granularity.

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 explicit use cases (purchasing power, price positioning, choosing between districts), which tells the agent when this tool is appropriate. However, it never names an alternative sibling (e.g., compare_areas or rents) or draws an exclusion boundary, so it falls 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 cover the safety profile (readOnly, idempotent, openWorld, non-destructive), but the description adds real behavioral context: the underlying model (households × INE spend × income adjustment), supply calibration against INE's directory, that every assumption is listed, and that assumptions can be overridden for scenarios. It stops short of noting data recency or geographic 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 core purpose in the first sentence, followed by methodology and return summary. Three short paragraphs with little waste, though the final paragraph blends usage triggers with output description rather than keeping them separate.

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 output schema exists and the input schema is fully documented, the description supplies the model mechanics, assumption-override capability, and usage triggers an agent needs. Nothing required to invoke or interpret the tool 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 description coverage is 100%, so the baseline is 3, but the description adds meaning by framing competitors, spend_per_household, and capture_share as overridable assumptions for scenario testing, which contextualizes why those optional params exist. It doesn't add unit or format detail beyond 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?

States a specific verb (size), resource (yearly market), scope (business category in a place in Spain), unit (euros) and output shape (with a range). It is clearly distinguishable from siblings like demographics, income, or businesses because it names the market-sizing operation explicitly.

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 explicit trigger phrases: '"how big is the market for X in Y"' and '"is Y under-served for X"', plus a scenario-testing note via overrides. It gives clear context but doesn't name alternative siblings (e.g., demographics, businesses) or state when not to use it.

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 the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds meaningful context beyond that: the two-stage adjustment mechanism, the fact that no competitor price data exists, and that output is a range 'labelled as an estimate'. It does not discuss pagination, latency, or failure modes, but for a read-only computed estimate those are minor.

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?

Three sentences, front-loaded with the purpose and followed by the rationale and the return shape. Well-structured and mostly waste-free, though the second sentence is dense enough that a reader must work through it.

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 detail return fields, and it still supplies the key epistemic caveat (estimate, range from no adjustment to full adjustment) plus the data limitation. Combined with full schema coverage and clear annotations, an agent has what it needs 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%, so the schema already defines every parameter including place formats and defaults. The description adds only the conceptual role of price_month and reference_place (uprating vs. comparison) which the schema largely conveys; 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 and resource: 'Suggest a price range for a place' from purchasing power and inflation, with the method (CPI uprating plus median income per consumption unit) spelled out. It does not, however, contrast itself with siblings such as rents, income, or market_size, so an agent must infer the boundary.

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 a clear usage context: it applies when public data has no competitor prices, so you supply a price you already know 'from elsewhere or an earlier date' and it adjusts it to the place today. No explicit exclusions or named alternative tools are provided, 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 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 this a read-only, idempotent, open-world read, so the safety profile is covered. The description adds behavioral substance beyond that: geographic coverage limits, the exclusion of two regions, and the crucial unit caveat that outputs are index changes rather than euro rents. It doesn't state update frequency or the reference period granularity.

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, front-loaded with the core purpose before coverage caveats. Coverage of provinces and regions is mentioned in both paragraphs, a minor redundancy, but nothing is wasted overall.

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 documented — and the description still adds the key interpretive context that values are changes, not euro amounts. Combined with the full parameter documentation and geographic scope, 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?

The single `place` parameter has 100% schema description coverage, including the accepted code formats and disambiguation syntax, so the schema does the heavy lifting. The description adds nothing about parameter syntax or format beyond what the schema already says.

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 — how housing rents have changed — and names the exact data source (INE's IPVA, 2015 = 100) plus the measures returned (1/5-year and since-2015 change). The line 'Gives changes, not rents in euros' sharply differentiates it from sibling tools like income or price_band that might otherwise be confused with rent costs.

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?

Coverage is spelled out precisely (municipalities over 10,000 residents, districts of provincial capitals, provinces, regions) and exclusions are stated (not the Basque Country or Navarra), which functions as implicit when-not guidance. It stops short of naming an alternative tool to use for excluded areas or for different geographies.

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, closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: best match returned first with alternatives for ambiguous names ('Valencia'), and multilingual/accent handling. It doesn't discuss rate limits or result counts, but with an output schema present that gap is minor.

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?

Three short sentences, front-loaded with the core action, then usage, then the ambiguity/unsupported-input caveats. No filler and every sentence carries distinct 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 values need not be restated, annotations cover the safety profile, and the single parameter is fully documented. The description covers entry conditions, ambiguity behavior, and an unsupported input class — nothing an agent needs 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?

Only one parameter and schema coverage is 100%, including examples ('A Coruña', 'Mérida, Badajoz', '08'), so the schema already carries the semantics. The description's mention of ambiguity is about results rather than the query parameter itself, so it adds little param-level detail. 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 and resource: 'Find the INE code and level (CCAA, province, municipality, district, tract) for a place in Spain.' It even enumerates the output level taxonomy, so an agent can distinguish this geocoding/resolution tool from data-fetching siblings like demographics 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?

Explicitly says 'Use this first when a question names a place', and names the when-not case with an alternative: neighbourhood names are unsupported, use districts or tracts from `demographics` or `income` with `sub_areas`. That is a direct routing rule to specific siblings.

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