Piso Radar

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

Annotations already declare readOnlyHint and idempotentHint, so safety is covered. The description adds real behavior beyond that: a hard cap of 50 returned results, the inclusion of a per-listing ficha URL, and the fact that descuento, cierre, ocupación and cargas filters apply only to subastas — important because an agent filtering pisos de banco would otherwise expect them to apply. It does not mention pagination or what happens when more than 50 match.

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 what is searched and where, followed by the filter axes and the return contract. No filler, no repetition 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?

For a 13-parameter search tool with no output schema, the description covers the essentials: scope, filter families, result cap and the URL returned per record. Missing only secondary details such as default result count behavior when limite is omitted and how results are ordered when orden is not set.

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 85%, so the schema already explains nearly every parameter, including the enum meanings for tipo and orden. The description only echoes the filter list and restates the 50-result ceiling, adding little semantic detail (e.g. whether precio applies to bank listings as well as auction values, or how descuento is computed) 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?

Names a specific verb (buscar) and precise resources (subastas de viviendas abiertas y pisos de banco en venta) scoped to a Spanish province, plus the filter axes and the return shape. It is clearly not ficha_vivienda (detail lookup) or listar_provincias, but it never explicitly distinguishes itself from subastas_que_cierran or resumen_mercado, which overlap with its cierra_en_dias and market-scope angles.

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 it to find candidate listings in a province with filters. There is no explicit when-to-use versus the siblings, no statement that subastas_que_cierran is the shortcut for closing-soon searches, and no prerequisites (e.g. that provincia must be a valid name obtainable via listar_provincias).

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 and idempotentHint, so safety is covered. The description adds useful behavioral context by explaining that the ITP rate derives from the comunidad autónoma of the province, but it does not clarify what 'coste mínimo resultante' includes or how results are broken down, leaving the calculation's boundary fuzzy.

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, zero filler, with the primary function front-loaded and the scope limitation immediately following. 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 no output schema, the description should say more about what the tool actually returns — the ITP amount, the applicable rate, and what components 'coste mínimo' aggregates. It names the outputs but does not characterize them, which leaves an agent guessing at the response shape for a two-parameter calculation 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 both parameters are fully documented in the schema, including that provincia determines the comunidad autónoma and ITP rate. The description largely restates that relationship rather than adding format, range or edge-case 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 specific verb and resource (calculates ITP for an auction/remate value) and scopes the output to ITP plus minimum cost, explicitly excluding other expenses. It distinguishes itself from a 'calculadora completa', though that target is not among the sibling tools listed, so the routing is slightly ambiguous in this toolset.

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 a clear exclusion with an alternative: for registro, deudas de comunidad, cargas or reforma, go to the full calculator. However, it says nothing about when to use this versus the actual siblings (ficha_vivienda, buscar_viviendas), so cross-tool routing within the listed set is left implicit.

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

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

Annotations already declare readOnlyHint and idempotentHint, so safety is covered; the description adds genuine value by disclosing that the response aggregates the file/listing data, computes a minimum cost with ITP and a municipal €/m² comparison, and includes price history and copies in other sources. It does not cover failure modes (unknown id, malformed URL) or latency, but the aggregation behavior is the key disclosure 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: the first front-loads what the record contains via a compact enumeration, the second gives the accepted identifier forms. It is dense but every clause names a distinct part of the payload; 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 one parameter, no output schema and read-only annotations, the description carries its weight by enumerating the returned sections, so an agent knows what to expect without a response schema. Minor gap: nothing about behavior for nonexistent or malformed ids.

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 id parameter is already documented with its 'fuente:referencia' or URL form. The description reinforces this with concrete examples ('boe:SUB-JA-2026-123456', 'solvia:12345'), which goes slightly beyond the schema by showing real source prefixes an agent can pattern-match.

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 resource precisely ('la ficha completa de una subasta o de un piso de banco') and enumerates exactly what the record contains: expediente/listing data, description, notices, minimum cost with ITP, €/m² bank comparison, price history and cross-source copies. That scope makes it obviously distinct from the search/market siblings without needing to name them.

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 accepting a single id or a pisoradar.es URL, so an agent can infer this is a single-record detail lookup rather than a search. However, it never states when not to use it or points to siblings such as buscar_viviendas for obtaining the id in the first place, which is the natural prerequisite here.

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 and idempotentHint=true, so the safety profile is covered. The description does add value by disclosing what is returned per province (live auction counts, bank flat counts, panel link), but it says nothing about data freshness, whether counts are cached, or the ordering of the returned provinces.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence that front-loads the resource and then lists the returned fields; nothing is redundant. It is slightly convoluted with the nested 'con cuántas... y cuántos... y el enlace' construction, 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?

For a zero-parameter, read-only listing tool with no output schema, the description covers the essential question of what comes back per item. Adding freshness or ordering details would make it complete, but nothing critical to invoking 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?

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. The description correctly implies the call is unfiltered and returns the full province list.

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

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

The description names a specific resource (the provinces covered by Piso Radar) and enumerates what comes back for each: open housing auctions, bank-owned flats, and a link to the panel. That is concrete enough to distinguish it from search tools like buscar_viviendas, though it never explicitly contrasts itself with the sibling resumen_mercado, which could plausibly overlap.

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 guidance at all: nothing says this is the entry point for discovering coverage, nor when to prefer it over resumen_mercado or buscar_viviendas. The agent must infer from the return contents alone that this is a browsing/overview 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 readOnlyHint and idempotentHint, so safety is covered. The description adds genuinely useful behavior beyond that: the data source is the latest monthly report, and it is supplemented with live 'abierto ahora mismo' figures, which tells the agent about data freshness and the mixed vintage of the numbers.

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 dense sentence, front-loaded with the source and scope, then the metric list, and closes with the live-data caveat. It is slightly run-on laundry-list prose, but every clause maps to a real returned figure and 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 one optional parameter, no output schema, and annotations covering the safety profile, the description carries the remaining burden well by enumerating essentially every metric the report returns. An agent knows what it will get and how scope works before calling 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% and the provincia parameter is already documented as falling back to all of Spain. The description restates the same Spain-or-province scoping without adding format, casing, or matching rules beyond what the schema provides, so the baseline of 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?

The description names a specific resource and verb: aggregate figures from the latest monthly Piso Radar report, scoped to Spain or one province, and enumerates the metrics returned (open auctions, discount, occupancy, liens, deposits, bank flats, price/€/m², top entities). It is clearly an aggregate-report tool rather than a listing search like buscar_viviendas or a detail lookup like ficha_vivienda, though it never names those siblings 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?

Usage is implied by the content: it says it covers 'toda España o una provincia' and mixes monthly report data with what is open right now, which hints at when to reach for it. However, there is no explicit statement of when to use it instead of buscar_viviendas or subastas_que_cierran, nor any exclusions, so the agent must infer the routing.

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

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

Annotations already declare readOnlyHint and idempotentHint, so safety and repeatability are covered. The description adds genuinely new behavioral context: the default 7-day window, the hard 30-day cap, and the guaranteed sort order by closing date and time, which the 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?

A single sentence that front-loads the resource and scope, then the geography, then the ordering. Every clause carries information; there is 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?

For a read-only, parameter-light listing tool with no output schema, the definition covers the essentials an agent needs to call it: window semantics, geographic scope, and result ordering. The only real gap is the undocumented 'limite' parameter, which affects how many results come back.

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 only 33%, so the description must compensate. It does explain 'dias' (7 default, up to 30) and 'provincia' (province or all Spain), but the 'limite' parameter is never mentioned in either the schema or the description, leaving one of three parameters opaque.

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

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

The description states a specific resource and scope: home auctions closing within the next N days, in a province or across Spain, sorted by closing time. This clearly separates it from siblings like buscar_viviendas (general search) or ficha_vivienda (single listing), though it never names those siblings 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?

The 'closing soon' framing implies when to use it (deadline-driven queries), and the province/Spain scope hints at the geographic choice, but there is no explicit when-to-use/when-not guidance and no routing to alternatives such as buscar_viviendas for non-deadline searches.

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