ITBI SP · São Paulo real estate prices

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

Annotations already declare readOnly, idempotent, closed-world, so the safety profile is covered; the description adds real behavioral context beyond that: results are deduplicated per property with the lowest price, q is parsed into rule-based filters and echoes termos_entendidos, and each record carries a 4-level price label, nearest station, feature tags, and building-level counts. It does not discuss pagination limits, response size, or what happens when q parses to nothing, which is why it falls short of a 5.

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

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

The core behavior and the q-first strategy are front-loaded, and the sentences are dense with operational detail rather than filler. The Portuguese and English halves restate largely the same content, which adds length; it is defensible for a bilingual audience but not maximally economical.

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 28-parameter tool with no output schema, the description compensates well: it enumerates what each result contains (price, R$/m², price level, station and distance, features, photo tags, building peers, both links). Combined with 100% schema coverage and read-only annotations, an agent has enough to call it and interpret the response 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 baseline is 3; the description goes further by explaining the relationship between q and the 27 structured fields (structured fields override the natural-language parse) and by noting that the response echoes the interpreted terms. It does not resolve ambiguous interactions, such as which field wins between bairro and a neighborhood mentioned inside q, or how q combines with faixa_avaliacao.

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 verb and resource ('Busca imóveis à venda') and bounds it tightly: São Paulo city only, sale only, deduplicated per property, with the cheapest asking price and links. Scope and exclusions are unambiguous, but no sibling tool (comparaveis_imovel, ficha_imovel, resumo_bairro, para_voce) is named or contrasted, so the agent must infer the routing itself.

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 states clearly when to use which input style: the easiest path is passing the user's request in q in Portuguese, and structured fields 'complete or correct' q and take precedence over it. Exclusions ('Só cidade de São Paulo; não cobre aluguel') prevent misuse. It stops short of naming which sibling to use for comparables, a single property's ficha, or neighborhood summaries.

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/closed-world, so the safety bar is met; the description adds genuine context by disclosing the two authoritative data sources (asking prices vs. ITBI recorded prices) and their geographic granularity (same building vs. district). It does not cover failure behavior, e.g. what happens with an unresolvable address or a building with no comparables, which is the main remaining gap.

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 Portuguese sentence is well front-loaded (input scope first, then outputs, then use cases) and wastes little. However, the English version is a near-verbatim full-length duplicate, roughly doubling the text without adding information, which is frontal-loading preserved but conciseness hurt.

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

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

For an eight-parameter, all-optional tool with no output schema, the description does the important extra work of enumerating what comes back (comparables, median R$/m², estimate, ITBI prices) and constraining geography to São Paulo. It stops short of describing output shape/ordering or the empty-result case, but an agent has enough 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?

With 100% schema description coverage the schema already documents each of the eight parameters, so the baseline is 3. The description adds one thing the schema does not: that endereco and lat/lon are alternative input modes ('Para um endereço ... ou um ponto lat/lon'), which clarifies the mutual-exclusivity relationship; otherwise it only restates area/tipo behavior 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 description names a specific verb and resource — it returns for-sale comparables, median asking R$/m², an asking-price estimate, and ITBI paid prices for a São Paulo address or lat/lon point. It is clearly distinguishable from ficha_imovel or resumo_bairro, but it never explicitly contrasts itself with the closest sibling, comparaveis_imovel, leaving the address-vs-property-id distinction 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?

Concrete question templates ('quanto vale meu apartamento na Rua X, 123?', 'esse preço está caro para essa rua?') give strong positive guidance about the situations this tool serves. What is missing is the negative side: no explicit statement of when NOT to use it, and no named alternative (e.g. use comparaveis_imovel when you have a listing rather than an address).

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

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

With no annotations, the description carries the full disclosure burden, and it does describe the payload in unusual detail (comparables with price, area, R$/m², the median, ITBI sales with date, paid value, area). It omits the behavioral edges that matter for a data-evidence tool: it is implicitly a read-only lookup but never says so, and it does not say what is returned when no comparable or ITBI sale exists.

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

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

The opening clause is well front-loaded — the resource and its evidence are named before the usage cues. However, the entire content is then restated in an English gloss that adds no new information, roughly doubling length for a bilingual reader who needs only one half.

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?

No output schema exists, and the description compensates by enumerating the returned fields and the median calculation, which is the main thing an agent would otherwise have to guess. Combined with 100% schema coverage on the two parameters and a read-only operation, the definition is close to self-sufficient.

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 both the required id (pointing at buscar_imoveis output) and the limite cap of 30 are already documented, making the baseline 3 correct. The description reinforces the comparison criteria ('tamanho próximo', same building/street/neighborhood) but adds nothing about what limite controls or how comparables are ranked when truncated.

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: it shows the evidence behind a listing's price label — the comparables used (same building/street/neighborhood, similar size) plus the ITBI registered sales in the same building, including the median. That is concrete enough to separate it from ficha_imovel or resumo_bairro, though it never names comparaveis_endereco, the sibling whose scope (address vs. property id) is closest and most confusable.

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 trigger conditions by quoting the user questions it answers ('esse preço é bom?', 'com o que vocês compararam?', 'por quanto venderam apartamentos nesse prédio?'), which is genuinely useful for routing. It stops short of when-not guidance or naming an alternative when the caller has an address instead of a property id.

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 and openWorldHint=false, so safety is covered. The description adds substantive context beyond that: the payload spans listing history, market comparison and ITBI transaction data, which tells the agent this is a heavy, single-property read rather than a light lookup. No rate limits or failure modes are mentioned, but for a read-only detail tool that is a minor gap.

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 on what the record contains, then the usage clause, then a separator and full English restatement. The bilingual duplication doubles length, but it serves a stated Portuguese/English audience, and no sentence is filler.

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

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

With no output schema, the description takes on the burden of describing returns and does so thoroughly — listings, price history, photos, amenities, fees, transit, price explanation, ITBI comparables. Combined with a single fully-documented required parameter, an agent has everything needed to call and interpret this tool.

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

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

There is one parameter and schema coverage is 100%, with the schema already saying the id comes from buscar_imoveis and giving an example format. The description repeats the same provenance hint without adding format, validation or edge-case guidance beyond the schema. Baseline 3 is appropriate when the schema carries the semantics.

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 ('Ficha completa de um imóvel') and enumerates exactly what the record contains: active listings, price history, photos, amenities, condo fee/IPTU, subway, price label, ITBI sales. It also names the sibling that produces the input (buscar_imoveis), so an agent can place it in the workflow without opening the schema.

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

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

Gives clear trigger conditions: 'Use quando a pessoa quer detalhes, quer comparar imobiliárias anunciando o mesmo imóvel ou perguntar se o preço é bom.' That covers the main intents well. It stops short of routing away from siblings like comparaveis_imovel or comparaveis_endereco, which overlap with the price-comparison intent, so no explicit when-not guidance.

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

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

With no annotations, the description carries the full behavioral burden and mostly succeeds: it declares the operation is a read-only ranking over 'imóveis à venda', describes the return payload as a 0-100 score plus reasons and alerts, and shows example alerts so the agent knows what comes back. It omits any statement about how many candidates are evaluated or whether results are capped, which is where the remaining opacity lies.

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 ranking criteria and the output contract before the trigger example, and every clause earns its place. The full English restatement roughly doubles the length for little new information, which is the only structural cost.

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 15-parameter tool with no annotations and no output schema, the description covers the conceptual model and return shape well, but leaves several levers unexplained — notably limite (how many recommendations, default 8, cap 20) and the filtro params (tipo, area_min, objetivo, quartos_min, vagas_min). An agent can call it, but can't confidently predict result count or how those filters interact with ranking.

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 only 53%, but the description compensates meaningfully: it maps commute modes (transporte, carro, bike, a pé) to modo, 'distância de pessoas importantes (pais, escola)' to pessoas, 'metrô a pé' to metro, 'o que ela não abre mão' to essenciais, and 'regiões que prefere' to bairros. It also explains the two input styles — everything inside q as free text, or pre-resolved points with address or lat/lon — which is genuine added meaning. Undocumented params like limite, objetivo and area_min are left to their names.

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 — it orders/ranks for-sale homes for a person — and enumerates the ranking criteria (commute time, distance to family/school, subway, price vs comparables, must-haves, preferred areas). It also pins the output form ('nota de 0 a 100, motivos e alertas'), which no sibling (buscar_imoveis, ficha_imovel, comparaveis_*) provides.

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 quando a pessoa cita trabalho, escola, família ou rotina' — with a concrete example request, which clearly separates it from a plain listing search. It does not name a sibling or state when NOT to use it (e.g. when the user just wants raw listings, use buscar_imoveis), 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 establish that this is a read-only, idempotent, closed-world operation. The description adds meaningful behavioral context beyond that: the metric is actual price paid rather than asking price, the source is ITBI, the window is the last 12 months, and coverage is all 96 districts. It does not describe the return shape or data limitations, but with annotations covering safety it is reasonably transparent.

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 and the example queries are useful, but the description duplicates the same content in Portuguese and English, which nearly doubles length without adding information. It is not badly structured, but the bilingual repetition reduces 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?

For a read-only ranking tool with four optional parameters and no output schema, the description supplies the key context: geography, metric, timeframe, sort modes, and filters. It leaves out details such as the exact response fields or handling of districts with sparse data, but the agent has enough to select and invoke 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 all four optional parameters and their enums are already documented in the schema. The description restates the available filters and sort modes but adds little semantic meaning beyond what the schema provides, making the baseline 3 appropriate.

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

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

The description clearly states a specific resource and scope: a ranking of São Paulo's 96 districts by actual paid m² over 12 months, with sort modes and filters. It is easy to distinguish at a high level from property-level or address-level siblings, but it never names or explicitly contrasts those alternatives.

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

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

The description gives concrete example questions such as 'quais os bairros mais caros de São Paulo?' and 'bairro mais barato da zona leste', which clearly show when to use it. It does not state when not to use it or explicitly route users to siblings like vendas_bairro or resumo_bairro.

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 and openWorldHint=false, so safety and idempotency are covered. The description adds real behavioral context the annotations lack: the data sources (asking prices vs. ITBI registry), the 12-month window, and the fact that comparisons require one call per neighborhood. No rate limits or failure behavior are mentioned.

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 useful, but the entire description is duplicated in Portuguese and English, roughly doubling length without adding information for an agent. The core content is tight; the bilingual redundancy is the main cost.

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 must describe return values, and it does so thoroughly by enumerating every reported metric and its time window. What remains unstated is response shape (structured vs. narrative) and behavior for unknown neighborhoods, which keeps 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 description coverage is 100% and both parameters are documented with bilingual descriptions and an enum for tipo. The description adds only marginal meaning, mainly the example neighborhood names echoed from the schema and the implied default of apartment in its examples. Baseline 3 applies when the schema carries the parameter semantics.

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 (a São Paulo neighborhood) and enumerates exactly what is returned: listing counts, median asking price, R$/m² overall and by bedrooms, below-market share, subway proximity, and ITBI paid prices for the last 12 months. This is far more specific than the title and lets an agent distinguish it from listing-oriented siblings like buscar_imoveis or ficha_imovel.

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 three concrete trigger queries ("quanto custa um apartamento em Moema?", "qual o preço do m² em Pinheiros?", "Tatuapé ou Mooca, qual é mais barato?") plus the operational instruction to call once per neighborhood for comparisons. It does not state exclusions or what to use instead when the agent needs individual listings, 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 declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior context beyond that: the data source is ITBI registry records, the window is a fixed trailing 12 months, and coverage spans 96 districts plus city-level aggregation. It omits error behavior for unknown neighborhood names and any data-lag 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?

The purpose and scope are front-loaded in the first clause before the metric enumeration, and every clause carries substantive information rather than filler. It runs long in a single dense block, and the trailing English restatement partly duplicates the Portuguese text, though for a bilingual tool that redundancy has some justification.

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 closed-world annotations, the tool is simple, and the description compensates for the missing output schema by enumerating the returned indicators instead of leaving returns opaque. Input scope is fully specified. Only edge-case behavior (unknown neighborhood, accent sensitivity) is missing.

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

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

Schema coverage is 100% and the single parameter already carries a description with examples, so the schema does the heavy lifting. The prose adds marginal value by expanding the accepted vocabulary (Vila Nova Conceição, Vila Olímpia, Brooklin, Higienópolis) and confirming 'São Paulo' as the city-wide value, but does not cover accent/fuzzy matching or invalid-input handling.

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 metric set: actual ITBI-registered prices paid per m² in a São Paulo district over the last 12 months, plus the derived indicators returned. It is clearly not a generic search tool, but it never names the overlapping siblings (resumo_bairro, ranking_bairros, vendas_rua) or states how it differs from them, leaving that differentiation 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?

Concrete trigger questions are given ('quanto custa o m² em Moema?', 'Pinheiros valorizou?', 'Tatuapé ou Mooca?') along with the operational note 'uma chamada por bairro', which tells the agent how to handle comparisons. There are no explicit exclusions or named alternatives for cases better served by another 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, idempotentHint and openWorldHint=false, and the description goes well beyond that: it names the data source and vintage (ITBI, 2019+), the adjustment method (IPCA-corrected m²), and — critically — the failure behavior when a building has no recorded sales. That fallback disclosure is the kind of operational detail annotations cannot carry.

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 Portuguese sentence front-loads the value proposition and the returned fields, then examples, then fallback — a sensible order. The trailing English block is a condensed restatement that partially duplicates the Portuguese text; it is useful for English queries but is not free of redundancy.

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 full burden of describing return values, and it does: m² median, sale count, price range, trend, last sale month, unit estimate, neighborhood comparison and building page link. Combined with the no-data fallback and all-optional params, an agent has everything needed to call it and interpret results.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: it explains that 'area' drives the unit estimate and that when no area is supplied the estimate falls back to the most-sold unit size, and it clarifies that 'endereco' expects street plus number, with 'slug' as the alternate identifier. That is genuine semantic value beyond the field descriptions.

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 — real sale prices paid for a building/house in São Paulo sourced from ITBI records since 2019 — and enumerates the exact outputs (median m² price, sale count, range, trend, estimate, neighborhood comparison). The phrase 'num prédio' scopes it to a single building, distinguishing it in substance from the street- and neighborhood-level siblings.

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

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

Three concrete example queries ('quanto vale meu apartamento na Rua X, 123?', 'por quanto o vizinho vendeu?', 'quanto vale um apê de 80 m² na Alameda Franca, 1633?') make the intended trigger clear. It also discloses the no-data fallback (returns nearby buildings on the same street). It never names vendas_rua, vendas_bairro or comparaveis_endereco as the alternatives for street-wide or comparison queries, so the exclusions are 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, idempotentHint and openWorldHint=false, so safety is covered; the description adds real context on the data source (ITBI registry), temporal coverage (medians since 2024, series since 2006 with IPCA correction) and that links are returned. What is missing is any caveat about data lag, gaps for streets with few transactions, or minimum-sample behavior.

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

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

The first sentence front-loads what the tool returns, followed by use-case examples and the disambiguation hint — a sensible order. The full Portuguese-to-English duplication adds length that does not earn much additional clarity, though it does not obscure the core content.

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 does the necessary work of describing return contents (median m², yearly series, districts, buildings, links) for a fairly rich analytical tool. The only gap is operational caveats about data coverage, freshness, or sparse streets, which an agent would want before quoting numbers.

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 both parameters are already documented, including the 'bairro' disambiguation note. The description restates that same rule ('passe bairro') without adding new syntax or constraints, so it sits at the baseline for a fully documented schema.

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

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

The description names a specific verb and resource ('vendas registradas no ITBI numa rua de São Paulo') and enumerates the concrete outputs — median m², yearly series, districts, top buildings. The street-level scope makes it immediately distinguishable from the bairro and prédio siblings.

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?

Two concrete example questions ('qual o preço do m² na Rua Oscar Freire?', 'a Alameda Olga valorizou?') show exactly when to reach for it, and the disambiguation rule ('Se houver ruas com o mesmo nome em bairros diferentes, passe bairro') is clear. It never names siblings like vendas_bairro or vendas_predio as alternatives, so the routing is implied rather than explicit.

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