BrokerIA Imoveis

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

Annotations indicate a mutation (readOnlyHint false) but not destructive. The description adds that the tool only creates a request, not a confirmed appointment, and that the agency will follow up. This adds useful context beyond the annotations.

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

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

Three sentences, front-loaded with the primary action, no redundant information. Every sentence adds value: purpose, required inputs, and behavioral caveat.

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

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

Given no output schema, the description adequately explains the workflow: request submitted, agency contacts for confirmation. Parameter descriptions are complete. A minor gap is lack of explicit return value format, but it's not critical.

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%, but the description adds meaning by explaining that property_id comes from a search, contact must be phone or email, and preferred_period includes specific time-of-day options. It also clarifies that notes are optional.

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 it registers a visit request ('Registra uma SOLICITACAO de visita a um imovel'), which is distinct from sibling tools like search, comparison, or detail retrieval. The verb 'agendar' in the title is clarified as requesting, not confirming.

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 explicitly lists required inputs and notes that the request is sent to the agency for confirmation, and crucially states 'NaO confirma visita nem reserva horario por conta propria'—a clear when-not-to-use. While it doesn't explicitly mention alternatives, the context is sufficient.

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 destructiveHint=false. The description adds that it returns a list with photo, address, price, and ID, but does not mention pagination or the full return structure. No contradictions with annotations.

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?

Description is a single well-structured sentence with a follow-up on return value. Every sentence adds value, but slight improvement could clarify the schema inconsistency regarding residential versus commercial.

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

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

Given 14 parameters and no output schema, the description covers basic functionality but misses details like pagination, the fact that 'descricao' is natural language search, and the inconsistency between 'residencial' in description and 'comercial' in 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 79%, so the schema already documents most parameters. The description summarizes filter types but does not add new meaning beyond the schema. Baseline of 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?

The description clearly states it searches residential Brazilian real estate listings, specifying filter criteria and return fields. It distinguishes from sibling tools like 'detalhes_imovel' and 'agendar_visita' which are for details and scheduling respectively.

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 the tool does but does not explicitly state when to use it over alternatives or provide exclusions. It implicitly distinguishes from siblings via its name but lacks direct 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?

The description adds significant context beyond annotations: it states the educational nature, approximate 30% commitment criterion, and that it does not consult credit history or determine approval. The readOnlyHint and destructiveHint are consistent, and no behavioral surprises remain.

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 description is a single paragraph that is front-loaded and contains essential information without excessive verbosity. It could be slightly more structured (e.g., bullet points for disclaimers) but is clear and concise enough.

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

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

Given the tool's complexity (9 parameters, no output schema), the description covers the main purpose, disclaimers, optional catalog count, and usage timing. It does not explain parameter constraints (e.g., age limits) but the input schema handles that. Overall, it provides a solid understanding of the tool's behavior.

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 only 33% schema description coverage, the description should compensate but only minimally explains key parameters (renda_familiar_brl, entrada_brl). It does not clarify dependentes, tipo_imovel, valor_fgts_brl, or fgts_acima_36_meses, leaving room for ambiguity.

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 it estimates an educational property value range based on monthly income, explicitly disclaiming quote, pre-approval, or credit check. It also notes the optional catalog count and advises use before searching properties, differentiating it from siblings like brokeria_buscar_imoveis and brokeria_estimar_parcela_educacional.

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 explicitly says 'Use ANTES de buscar imoveis' and explains it helps define a realistic price range. Negative statements clarify what the tool does not do (quote, pre-approval, etc.). It could name alternative tools but provides sufficient context for correct usage.

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 mark the tool as readOnlyHint=true and destructiveHint=false, indicating safe execution. The description adds behavioral context by stating it 'nao indica qual e o melhor — a decisao e do usuario' (does not indicate which is best – the decision is the user's), which goes beyond annotations. There is no contradiction.

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 description is concise, with four sentences that front-load the main action ('Compara de 2 a 4 imoveis'). Every sentence adds value: range, source, displayed fields, utility, and limitation. No redundant or unnecessary words.

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 tool with one parameter, no output schema, and low complexity, the description covers the core purpose, inputs, outputs (table fields), and behavioral caveat (no best-pick). It does not mention error handling or data source details, but the annotations and schema fill safety and input constraints. Overall, it is complete enough for an agent to use 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 for the single parameter 'imovel_ids' is 100%, with a clear description in the schema. The tool description reinforces that IDs come from searches and that the count is 2-4, matching schema constraints (minItems: 2, maxItems: 4). Since the schema already does the heavy lifting, the parameter semantics are adequate but not enhanced beyond what is already specified, resulting in a baseline score of 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 clearly states the verb 'comparar' (compare) and the resource 'imoveis' (properties), specifying it compares 2-4 properties side by side. It lists the fields displayed (price, area, bedrooms, etc.) and clarifies that it does not judge which is 'best'. This distinguishes it from sibling tools like 'brokeria_detalhes_imovel' (details) or 'brokeria_buscar_imoveis' (search), making its purpose unambiguous.

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 mentions that the tool is 'util pra visualizar trade-offs objetivos' (useful for visualizing objective trade-offs) and that IDs come from searches, implying it is used after searching. However, it does not explicitly state when not to use it or suggest alternatives like 'brokeria_detalhes_imovel' for a single property. Still, the context is clear enough for an agent to infer the appropriate use 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 readOnlyHint=true and destructiveHint=false, but the description goes beyond by detailing what data is returned (photos, characteristics, etc.) and what is not included (financing calculations). This adds valuable behavioral context without contradiction.

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 description is two sentences long with no extraneous words. The first sentence states the core action and source of ID; the second lists contents and exclusions. Information is front-loaded and every sentence contributes meaning.

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

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

Given the tool has one required parameter and no output schema, the description fully covers what the agent needs to know: input (ID from search), output (list of public details), and limitations (no financing). It aligns with sibling tools for a complete real estate workflow.

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

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

The single parameter 'imovel_id' is described in the schema as 'UUID do imovel', but the description adds the critical context that the ID is 'retornado por uma busca' (returned by a search). This clarifies the origin and usage of the parameter, adding value 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?

The description clearly states that the tool returns public details of a specific property by ID, lists included information (photos, description, characteristics, address, price, agency), and explicitly states what it does not do (financing or credit eligibility). This effectively distinguishes it from sibling tools like 'brokeria_estimar_parcela_educacional' and 'brokeria_capacidade_pre_search'.

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 indicates that the ID should come from a search, providing clear usage context. While it does not explicitly list alternatives or exclusions, the context of sibling tools and the specific purpose given (get details after search) is sufficient 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?

The description adds significant behavioral context beyond annotations: it is educational, based on public averages, and not a quote or pre-approval. It also warns against misuse, consistent with readOnlyHint=true.

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 description is front-loaded with key information in Portuguese, followed by an English translation. Some redundancy exists, but it remains clear and reasonably concise for the complexity.

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

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

Given no output schema and 14 parameters, the description covers the essential behavior (educational range estimate), limitations, and expected output format (min-max). However, it lacks guidance on parameter selection and detailed output structure.

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?

Despite low schema description coverage (36%), the description does not explain individual parameters or how they influence the estimate. It only vaguely references prazo and entrada, failing to compensate for the schema gaps.

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 explicitly states it provides an educational estimate of monthly payment range for Brazilian properties, using verbs like 'Apresenta' and specifying the output is an interval. It clearly distinguishes itself from sibling tools which are for searching, comparing, or booking properties.

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 explicitly states what the tool is not (quote, pre-approval, credit check) and that it does not substitute professional analysis, providing clear context for when to use (educational estimation). However, it does not name alternative sibling tools as alternatives.

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 destructiveHint=false, so safety is clear. The description adds detailed behavioral traits: returns up to 20 properties sorted by straight-line distance, includes photo, price, basic characteristics, and distance in km. No contradictions.

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 description is a single, well-structured paragraph. It front-loads the core action, lists output details, and ends with a usage context. Every sentence is relevant and efficient.

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

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

Despite no output schema, the description adequately explains return fields and ordering. Parameters are sufficiently documented. The tool's complexity is low, and the description covers search modes, limits, and use case completely.

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 80%, so baseline is 3. The description adds meaning by explaining that 'referencia' accepts address/CEP/coordinates and that 'raio_km' sets search radius with a default. It slightly contradicts itself by stating 'ate 20 imoveis' while default limit is 10, but overall adds substantial value.

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 the verb 'lista' (list), resource 'imoveis' (properties), and the selection criterion 'proximos a um endereco, CEP ou coordenada geografica'. It differentiates from sibling tools like brokeria_buscar_imoveis by focusing specifically on proximity-based search.

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 provides a clear use case: 'util pra usuarios que priorizam morar perto de um local especifico'. It implies when to use but doesn't explicitly state when not to or name alternative tools. Lacks exclusions but context is clear.

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 indicate readOnlyHint=true and destructiveHint=false. The description adds behavioral details beyond annotations by specifying what aggregate statistics are returned (percentiles, distribution, etc.). No contradictions.

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 description is a single paragraph that quickly states the main function, then lists details. It is front-loaded and concise with no unnecessary words. Could be slightly more structured but effective.

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

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

Despite lacking an output schema, the description fully explains the return values: total properties, price percentiles (25/50/75), distribution by type and number of rooms, and number of partner agencies. This is complete for a stats tool, though it doesn't mention data freshness or scope (partner catalog only).

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 description for both parameters. The description clarifies that 'bairro' is optional and if omitted, returns city-wide stats, but this is already in the schema description. No additional semantic value beyond 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?

Description uses specific verb 'Retorna' and resource 'estatisticas agregadas do catalogo de imobiliarias parceiras' for a city or city+neighborhood. It lists exactly what statistics are returned, distinguishing it from sibling tools that focus on individual properties, visits, or comparisons.

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 states it is useful for guiding the user about typical price range and supply before a search, implying when to use (pre-search) and when not (for individual properties). It does not explicitly list alternatives but sibling tool names suggest differentiation.

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