Imóveis à venda em São Paulo · itbisp.com

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 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.