Verithic · official data by municipality

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description is not obliged to restate it. It instead adds genuinely useful behavioral detail beyond annotations: a warning below 100 contracts, the first/last reliable year sentence, inclusion of source/period/read date, and null-with-reason for missing years.

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 is front-loaded with the purpose, but the entire description is duplicated verbatim in Spanish and English, effectively doubling its length without adding information. Every sentence is relevant once, yet the bilingual repetition is pure redundancy for an agent consuming this definition.

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 no output schema, the description carries the return-value burden and does it well: it specifies the units (€/month), contract counts, the <100-contract warning, the reliable-year sentence, provenance fields, and null semantics. Only the shape/ordering of the returned series is 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, but the description goes beyond the schema by explaining the semantic effect of omitting municipio (it lists towns with a sufficient series), which the schema only labels 'optional'. The language enum's default is already documented 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 states a precise verb and resource: average rent of registered contracts per full year for one municipality, with the specific dataset cited (qww9-bvhh). It clearly distinguishes a per-year time series from what siblings like comparar_municipios or ficha_municipio would do, though it never names those alternatives 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?

It discloses the fallback behavior when no municipality is supplied ('Without a municipality it lists the towns with a long enough series'), which implicitly tells the agent this tool doubles as a lister. However, it gives no explicit when-to-use versus-when-to-use-something-else guidance, and it does not route the agent to buscar_municipios or listar_municipios for that fallback 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?

Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: what the tool returns (slug plus page link) and a negative scope statement (no figures), which matters because there is no output 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?

Content is front-loaded and the scope-exclusion sentence is well placed, but the entire description is duplicated in Spanish, roughly doubling length without adding information for the reader. It is defensible for a bilingual server but not 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?

With five optional parameters, no output schema, and full annotation coverage, the description supplies the two things that would otherwise be missing: the return shape (slug + page link) and the boundary against figure-returning tools. Only the routing decision against listar_municipios remains unaddressed.

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 five parameters including the zona enum nuance and limite bounds are already documented in the schema. The description only restates that matching is by partial name/county, adding little beyond the field descriptions. 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 (finds municipalities) plus the matching criteria (part of the name and/or county) and the returned fields (slug and page link). The clause 'Does not return figures' cleanly separates it from the analysis/price siblings, though it never distinguishes itself from the closest sibling, listar_municipios.

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?

'to use with the other tools' implies a chaining/lookup role, and 'Does not return figures' implies when-not-to-use-it-for-data questions, but no alternative tool is named and no explicit condition for choosing search over listing is given. Usage is implied 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description still adds real context: the figure is a municipal average excluding taxes and purchase costs, not a specific flat, and transport minutes are door-to-door departing 7–9am on a weekday. It omits pagination/rate behavior, but the data caveats are genuinely useful.

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 sentence is well front-loaded and dense with useful detail, but the entire description is then repeated verbatim in Spanish, roughly doubling its length. For an English-reading agent the second half is pure redundancy, which costs it points on conciseness.

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?

There is no output schema, so the description carries the return-shape burden, and it does so well: it says what each municipality carries (m², public transport minutes, driving minutes) and that results are sorted descending. What is missing is minor — it never states the maximum row cap of 25 or the budget floor/ceiling, though those live in 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 description coverage is 100%, so the schema already documents all six parameters, including the county filter and the two minute limits. The description restates these constraints and adds only marginal nuance (the no-taxes caveat, the door-to-door assumption), so 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: given a budget, compute the square metres of used housing each municipality buys, sorted most-to-least. The formula (budget / average price per m²) and the supplementary transport-minutes payload make the operation unmistakable and clearly distinct from generic sibling tools like buscar_municipios or comparar_municipios.

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 can be constrained (max public transport minutes, max driving minutes, county) but never says when to pick this tool over siblings such as comparar_municipios or ranking_por_perfil. Usage is implied by the operation rather than stated, so it meets the minimum-viable bar without 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 beyond them: every output line carries its type (data/rule/sum/user figure), source and read date, and it explicitly states the tool never concludes whether to move. No rate limits or auth needs are mentioned, but they are irrelevant for a local calculator.

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?

Content is front-loaded with the balance of moving and every clause describes a distinct output line, so little is wasted. However, the identical text is repeated verbatim in Spanish, doubling the length without adding information for the agent.

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 18 params at 94% coverage and no output schema, the description effectively serves as the output description, enumerating return lines and their metadata, and states the tool's non-recommendation boundary. This is nearly complete; only explicit sibling routing 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 94%, so the schema already documents the 18 parameters. The description ties them to the calculation model (user figures override official averages) but adds little per-parameter meaning beyond what the schema provides.

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+resource: it computes the balance of moving between two municipalities in the Barcelona area, enumerating the exact figures produced (rent+IBI, ITP, notary/registry, m² bought, recovery months, commute time). This clearly distinguishes it from generic comparison siblings. It does not, however, explicitly name any sibling (e.g. comparar_municipios) to differentiate.

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: the framing 'Is moving worth it?' and the note that official averages can be replaced by user figures signals the evaluate-a-move scenario. There is no explicit when-to-use vs alternatives guidance and no exclusion rules routing to the 13 sibling 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?

Annotations already establish read-only, idempotent, non-destructive behavior, and the description reinforces 'Nothing is stored' while adding real substance: data sources (Generalitat/Notariado registrations, Catalonia contracts, Madrid tax declarations), source period, read date, licence, and the ±5% banding rule. It stops short of a 5 only because return shape details border on output documentation the tool lacks elsewhere.

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 English and Spanish versions are full duplicates of the same content, roughly doubling length with no new information. The lead sentence is well front-loaded, but the verbatim bilingual repetition is waste an agent must wade through.

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 no output schema, the description carries the return burden and does so thoroughly: €/m² or rent, municipal figure with source/period/read date/licence, % and euro difference, and the below/in-line/above band. An agent has everything needed to call and interpret it.

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 parameters (m2, modo, zona, precio_eur, municipio, language) are already fully documented in the schema. The description restates the buy/rent and m²-required-for-buy logic without adding format or edge-case detail, 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?

Uses a specific verb (compares) with a precisely bounded resource: one listing's price/rent vs. the published municipal figure, per source. It is clearly distinguishable from siblings like comparar_municipios (town-to-town) or precio_parada because it anchors on a single asking price.

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 context for when the result is appropriate and, importantly, the limits of its meaning ('town average, not a valuation of the flat'; 'rent average mixes all sizes'), which steers correct use. It never explicitly names an alternative sibling or says when not to use it, 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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuine behavioral context beyond that: every figure carries its source, differences are only returned when both sources publish the value, and small municipalities substitute a county average with an explicit label. Minor gap: no note on partial-data cases beyond the county-average rule.

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 metric list is front-loaded and every clause conveys substance. The full Spanish repetition doubles length for readers who only need one language, which is a real cost, though it is a deliberate bilingual-serving choice rather than 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 no output schema, the description steps in to explain the return shape (per-metric value plus source plus difference) and the small-municipality caveat, which is the main thing an agent needs. It is nearly complete; only edge cases like unresolvable municipality names are unaddressed.

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 each property is described with name-or-slug guidance and the language enum, so the schema carries the burden. The description only implies that two municipality identifiers are compared; it adds no format, ambiguity-resolution, or disambiguation guidance 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 concrete verb+resource (side-by-side comparison of two municipalities) and enumerates the exact dimensions compared: price per m², IBI, rent, commute minutes, beach, rent-cap zone, tourist flats, resident satisfaction. The two-input scope implicitly separates it from single-municipality siblings like ficha_municipio, but no sibling is named, so the differentiation is left to inference.

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?

Framed around 'what weighs most when choosing', which hints at the residential-decision use case, but there is no explicit when-to-use, when-not-to-use, or pointer to alternatives such as ficha_municipio for a single town or municipios_similares for discovery. Usage must be inferred from the metric 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is added context — and it delivers: every figure carries source, period and read date; unpublished values come back as null with the reason; the response includes the yearly price series since 2013 and five dimension indices with cut-off dates. That is real disclosure about data provenance and completeness that the annotations do not supply.

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 scope is front-loaded ('Everything Verithic publishes for one municipality'), but the body is a long enumerated list presented twice, once per language, which roughly doubles the length without adding information. The bilingual mirroring is defensible for a bilingual product, yet it is not economical 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?

There is no output schema, so the description carries the burden of explaining returns — and it does so well, spelling out the field catalogue, the null-with-reason convention, provenance metadata, and the included series and indices. What an agent receives is clear; only the absence of any routing to overlapping siblings leaves a 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% and both parameters (municipio with name/slug forms, language enum) are documented in the schema. The description adds nothing about parameter syntax or defaults, so the baseline 3 applies — the schema does the work and the prose neither helps nor hurts.

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 scope: the complete published dataset for one municipality ('Everything Verithic publishes for one municipality'), then enumerates the concrete fields (price €/m², IBI, rent, transport, rent-cap zone, tourist flats, empty homes, satisfaction). 'One municipality' implicitly sets it apart from comparar_municipios or listar_municipios, but no sibling is named explicitly, so differentiation is left partly to inference.

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 when-to-use or when-not guidance, and no alternative is named despite a crowded sibling set with clear overlap (comparar_municipios for multiple, zona_tensionada_2027 for a single dimension, alquiler_ano_a_ano for the rent series, ranking_por_perfil for ranking). The 'everything for one municipality' framing implies usage, but the agent must infer that this is the broad profile rather than a focused lookup.

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 establish read-only, idempotent, non-destructive behavior, and the description adds substantive traits beyond them: per-value provenance (source, period, read date), null-with-reason semantics, and that towns lacking a filtered field are listed separately and 'never estimated'. The 'no cap' note also clarifies pagination 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?

Core purpose and scope are front-loaded in the first sentence, and every sentence carries information. The bilingual duplication doubles the length but is justified by the audience; it is well-structured though somewhat long.

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?

There is no output schema, so the description carries the return-shape burden, and it does so: it explains that each value includes source, period and read date, how missing values appear, and how filtered-out towns are separated. Complete for an 8-parameter, no-required-params 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% so the baseline is 3, but the description adds the non-obvious no-fields default behavior (returns default fields plus the available field-key list) and reiterates that min/max filters apply to any numeric field and combine conjunctively. It goes modestly 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 and resource ('Returns every published municipality') with explicit scope ('no cap') and operation set (filter, sort, field selection). This distinguishes it from search-oriented siblings like buscar_municipios by emphasizing exhaustive retrieval without a cap.

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 a concrete triggering use case ('which is the cheapest town within 35 minutes of Barcelona?') and a procedural hint ('Call it without fields to get the default fields and the list of available field keys'). It does not, however, name alternatives or state when-not-to-use versus siblings like buscar_por_presupuesto or ranking_por_perfil.

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 safety is covered. The description adds genuine context beyond that: thresholds live in 'Verithic's dated weights file', percentiles are computed 'within the area', and the response carries the three indices plus the figures behind them and the cut-off date. It does not mention result counts or pagination, keeping it out of 5 territory.

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 and the constraint and disclaimer follow logically, so structure is sound. However the entire content is duplicated verbatim in Spanish, roughly doubling the length without adding information for an agent that reads either language.

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?

There is no output schema, so the description correctly carries the return shape (three indices, the underlying figures, cut-off date) and the scoping option. What is missing is result-size/pagination behavior and any signal of ranking order, but for a zero-required-param read tool it is largely 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 100%, so the schema already documents both comarca and language. The description only echoes the county limitation ('Can be limited to a county') and never mentions the language parameter, adding no syntax or format detail beyond the schema. 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 and criteria: towns scoring high on Connections and 'Services nearby' that are cheaper than most, returned with three indices, their underlying figures, and a cut-off date. The verb is implicit (it is a filtered ranking), but the purpose is discernible. It does not differentiate itself from siblings like ranking_por_perfil or buscar_por_presupuesto, 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 only usage-shaped statement is 'Can be limited to a county' and the disclaimer 'Not a recommendation'. There is no when-to-use, no when-not-to-use, and no reference to the obvious alternatives (ranking_por_perfil, buscar_por_presupuesto) that an agent must choose between.

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=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so safety and idempotency are covered. The description usefully adds what the returned content actually contains (sources, missing-value semantics, computation notes, gaps), but says nothing about response format or structure beyond the topic 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?

It is a single content-list sentence, front-loaded with the primary subject ('The official sources behind Verithic's figures'). The bilingual duplication doubles the length, but that repetition is a deliberate localization pattern rather than verbal 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?

For a zero-required-parameter, read-only reference tool with no output schema, the description thoroughly enumerates the categories of information returned. An agent knows what asking for methodology documentation yields; little beyond response structure 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 (language) exists, and its schema description already documents the enum and default at 100% coverage. The description adds nothing about the language parameter, so the schema fully carries the burden — baseline 3.

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 enumerates exactly what content the tool returns: official sources (publisher, link, licence, period, read dates), meanings of missing-value reasons, computation methods for sentences/similar towns/dimension indices, and current gaps. This is a clear content-coverage statement for a documentation resource. It does not, however, distinguish itself from the many data-oriented siblings (e.g., municipios_similares, ficha_municipio), which compute or return the figures this tool only explains.

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 content list: an agent should call this when it needs provenance or methodology explanations rather than data. There is no explicit 'when to use this vs. X' statement and no exclusions, so the routing guidance is left to inference.

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-openWorld, so the safety bar is low. The description adds genuinely useful behavior: the similarity inputs (price, rent, minutes to Barcelona, size, property tax), the geographic constraint (50 km or same county), that the method is returned with the answer, and the 'not a recommendation' caveat.

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 output before the methodology caveats, and every clause carries information. The bilingual duplication doubles the length, but that is deliberate for the target user base rather than 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?

There is no output schema, and the description compensates well by enumerating the returned fields (similarity index, €/m², distance) and explaining the computation and geographic limits. An agent has enough to call and interpret the tool, though edge-case guidance when fewer than five matches exist is absent.

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% with only two well-documented parameters, so the schema does the heavy lifting. The description confirms the 'given municipality' input conceptually but adds no syntax, format, or slug guidance beyond what the schema already provides.

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 ('five municipalities most similar to a given one') plus the secondary cheaper-variant output, distinguishing it clearly from siblings like comparar_municipios or buscar_por_presupuesto. The scope, output fields and computation basis are all named up front.

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 description – you use this when you want alternatives to a given municipality – and 'Not a recommendation' sets a boundary on how the result should be treated. However, it never explicitly says when to prefer this over comparar_municipios or buscar_municipios, so routing is left to inference.

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 establish readOnly/idempotent/non-destructive, but the description adds genuinely useful behavior beyond them: price and rent belong to the town, never the station; source, period and read date are included; a missing figure is null with its reason. That null-with-reason contract is valuable since there is no output 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 and well-ordered within each language, but the content is delivered twice (English and Spanish) for an evaluator that only needs one, roughly doubling length without adding information. The claims themselves are tight, but the duplication is wasteful.

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 no output schema present, the description carries the return-value burden and does so fully: per-stop fields, the town-vs-station caveat, provenance fields, null handling for missing figures, and the no-line fallback. An agent has everything needed to call and interpret it.

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 real semantic value by spelling out what happens when the optional linea is omitted (lists available lines). The language parameter is left to the schema/default, which is acceptable at full coverage.

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: it returns the stops of a given Rodalies/FGC line, ordered from Barcelona outwards, each with price per m², rent and travel minutes. No sibling tool covers line/stop data, so an agent can distinguish it immediately from ficha_municipio or ranking_por_perfil.

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 condition for use ('For a Rodalies or FGC line with a read stop order') and explains the zero-argument fallback ('Without a line it lists the available lines'), which is important given linea is optional. It does not name or exclude specific sibling alternatives, 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds real substance beyond them: what is returned (five indices by dimension with figures, profile weights, cut-off date, town count) and the edge-case behavior that towns missing a dimension are listed apart, unranked, with a reason. That edge-case handling is exactly the kind of behavior an agent cannot infer elsewhere.

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 output content, then the unranked-towns caveat, then the disclaimer – a sensible order. The one cost is the fully duplicated Spanish translation, which doubles length without adding information for a given call, though it is consistent with the tool's bilingual language parameter.

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?

There is no output schema, so the description carries the return-value burden, and it does describe the returned structure and the unranked-edge case. With 4 params at full schema coverage, the remaining gap is minor: pagination or result-size behavior beyond the 'limite' cap is not discussed, but nothing an agent needs to invoke 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 coverage is 100%, so the baseline is 3. The description earns above that by decoding the enum values the schema only labels as 'Profile id' (family = Family with children, relocation = Moving from abroad, calm = Calm and space) and by explaining that comarca narrows the ranking to one county. It adds semantic meaning the schema does not carry.

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 ('Orders the municipalities') plus the exact input dimension (one profile) and the three concrete profile values. It also signals the output shape (five indices, weights, cut-off date, town count) and explicitly says 'Not a recommendation', which separates it from advisory siblings like calcular_mudanza or comparar_municipios.

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: use this when you want towns ranked for a given profile, optionally narrowed to one county. The 'Not a recommendation' note is a useful boundary, but no sibling alternative is named and there is no explicit when-not-to-use condition, so guidance stays at the minimum-viable level.

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, closed-world), so the description is not obligated there. It adds genuine behavioral context by clarifying that it separates what is in force from what is merely proposed, and flags a data limitation (the source does not fix the exact expiry day).

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, but the full bilingual restatement roughly doubles the length without adding new information. Efficient per language, yet redundant 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?

With no output schema and a simple read-only, two-parameter surface, the description adequately conveys what an agent will receive (status, resolution/BOE, proposal, expiry). It is nearly complete, lacking only explicit output-field naming and sibling routing.

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% with only two simple parameters (municipio, language enum), so the schema carries the burden and the baseline is 3. The description adds no syntax or format detail for municipio and does not mention the language option.

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 (rent-cap / stressed residential market zone status for a municipality) and enumerates what the result includes: in-force status, resolution/BOE reference, proposed changes, and expiry. It does not name or distinguish itself from siblings like ficha_municipio, 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?

There is no when-to-use or when-not-to-use guidance and no named alternative, even though siblings such as ficha_municipio and comparar_municipios plausibly overlap. Usage is only inferable from the purpose statement.

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