Immediate home report for a building or flat in Spain: 22 checks from official public sources.
Scored across 8 tools
Each tool maps to a distinct step or resource: coverage check, address search, building resolution, report creation, status polling, catalog, and check listing. The only wrinkle is purchase_report, a deprecated stub that overlaps create_free_report, but its description explicitly flags it as unavailable, so confusion is limited.
All eight names use a consistent snake_case verb_noun pattern (check_coverage, create_free_report, get_products, get_report_status, list_checks, purchase_report, resolve_building, search_address). The verb choices are predictable and clearly signal each tool's action.
Eight tools is well-scoped for a report-ordering workflow with distinct pipeline stages. Each tool earns its place, and the single dead tool (purchase_report) is a minor compatibility artifact rather than bloat.
The surface covers the full pipeline from coverage check through address lookup, building resolution, report creation, and status polling, plus catalog and check explanations. Minor gaps exist (no report cancellation/retrieval-content tool), but core lifecycle is complete.
Says whether HOUSINGFAX can produce a report for a province (name or two-digit INE code) and, optionally, finds the municipality in the official street directory. Status covered, not_yet_covered (Navarra: foral adapter pending) or unrecognized; not_yet_covered never means no risk. In the Basque Country (Araba, Bizkaia, Gipuzkoa) the report covers the whole building, not a single flat. municipalityLookup unavailable means the directory did not answer: unknown, not missing. Call it before search_address when you are not sure the place is covered.
| Name | Required | Description | Default |
|---|---|---|---|
| language | No | Language of the texts in the answer (and of the report): es, en, de, nl or fr. Default es. | es |
| province | No | Spanish province by name (Madrid, València, Bizkaia…) or two-digit INE code (28). Omit both fields to list every province. | |
| municipality | No | Optional municipality name; it is looked up in the official street directory of the province. |
| Name | Required | Description |
|---|---|---|
| contract | Yes | |
| language | Yes | |
| provinces | Yes | |
| coverageNote | Yes | |
| municipalities | Yes | |
| municipalityLookup | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, openWorld and non-destructive, but the description adds substantial behavioral context: not_yet_covered never means no risk, Navarra has a pending foral adapter, the Basque Country covers the whole building rather than a single flat, and an unavailable municipalityLookup means the directory did not answer rather than the place being absent. These are non-obvious semantics an agent could not infer from annotations or schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The paragraph is dense but front-loaded with the core purpose before listing statuses and edge cases. Every sentence carries relevant information, though the status and regional caveats make it longer than a typical minimal definition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema is present and annotations cover the safety profile, the description still supplies the domain-specific statuses, regional caveats and the municipalityLookup failure meaning that an agent needs to interpret results correctly. Nothing important for correct invocation appears missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents province names/INE codes, the optional municipality lookup and the language enum. The description largely restates that province can be a name or two-digit INE code and that municipality is checked against the street directory, adding little beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: determines whether HOUSINGFAX can produce a report for a province and optionally looks up a municipality. It distinguishes itself from siblings by naming search_address as the alternative and describing the exact statuses it returns, so an agent can identify it 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?
Explicitly says to call it before search_address when unsure the place is covered, which gives a clear when-to-use rule and names the alternative tool. It also explains the meaning of each status, removing ambiguity about how to act on the result.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Queues the report for the building resolved with resolve_building and returns a private link (previewUrl) and a statusToken for get_report_status. Every report is free: it is the full report with PDF, with the building condition assessment when the building has an IEE/ITE record, generated in minutes. CONSENT: before calling, show the person the consent text returned by get_products (consent.text, same language) with its terms and privacy links, and set consent=true only if the person has explicitly accepted it in this conversation; pass consent.statementSha256 as consentStatementSha256. Never accept on the person's behalf. The email is optional (ready notice with the link and the PDF; at most 2 reports per email every 14 days) and only with the person's permission. The link is private: give it only to the person, never publish it. Always tell the person: it is a preliminary, automated report built from public records, not a technical inspection, valuation, certificate, safety assessment or legal advice; probabilities are given as words (very low to very high), never as percentages; a check without data (○) means unknown, not negative or safe; Navarra is not covered yet; the report is only available as a private link.
| Name | Required | Description | Default |
|---|---|---|---|
| No | Optional email of the person for the ready notice with the link and the PDF, only with their permission. | ||
| consent | Yes | true only if the person explicitly accepted the consent text from get_products. | |
| language | No | Language of the report and of the texts: es, en, de, nl or fr. Default es. Must be the language of the consent text shown. | es |
| resolutionToken | Yes | resolutionToken returned by resolve_building (valid 15 minutes). | |
| consentStatementSha256 | Yes | consent.statementSha256 from get_products for the same language. |
| Name | Required | Description |
|---|---|---|
| jobId | Yes | |
| notice | Yes | |
| status | Yes | |
| contract | Yes | |
| language | Yes | |
| previewUrl | Yes | |
| emailNotice | Yes | |
| statusToken | Yes | |
| pollAfterSeconds | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), and the description adds substantial non-obvious behavior: the returned previewUrl/statusToken, the consent gating contract (never accept on the person's behalf, sha256 binding), the email rate limit (2 reports per 14 days), the private-link-only rule, and the required disclaimers.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action and return values, then organized into consent, email, and privacy blocks. It is long, but for a consent-gated tool most sentences carry compliance weight; a little redundancy exists between the schema and the consent paragraph.
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?
An output schema exists, so return values need not be documented, yet the description still names previewUrl and statusToken. Combined with consent handling, privacy rules, email limits, and coverage caveats (Navarra uncovered, ○ means unknown), an agent has everything needed to call this 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 coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: consent must reflect explicit acceptance in this conversation, email is optional and rate-limited, and language must match the consent text shown. These constraints go past the field-level descriptions, though much of the mechanical semantics is still carried by 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 (queues/creates) and resource (the HOUSINGFAX report) and scopes it to the building returned by resolve_building, with the return artifacts (previewUrl, statusToken) named. An agent can distinguish this free-report tool from purchase_report without opening either 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 explicit preconditions (resolve_building must run first, consent text from get_products must be shown and accepted, email only with permission) and names the follow-up tool get_report_status. It does not explicitly state when to route to the sibling purchase_report instead, so the alternative-selection guidance is implied rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the HOUSINGFAX report for a home in Spain (productMode free): a single product, the full report with web view and PDF, free of charge, with the building condition assessment when the building has an IEE/ITE record. Also returns the report limits and the consent text (with its SHA-256) that the person must accept before create_free_report. Use it when someone asks what HOUSINGFAX offers or before ordering. Always tell the person: it is a preliminary, automated report built from public records, not a technical inspection, valuation, certificate, safety assessment or legal advice; probabilities are given as words (very low to very high), never as percentages; a check without data (○) means unknown, not negative or safe; Navarra is not covered yet; the report is only available as a private link.
| Name | Required | Description | Default |
|---|---|---|---|
| language | No | Language of the texts in the answer (and of the report): es, en, de, nl or fr. Default es. | es |
| Name | Required | Description |
|---|---|---|
| consent | Yes | |
| upgrade | No | |
| contract | Yes | |
| currency | Yes | |
| language | Yes | |
| orderUrl | Yes | |
| products | Yes | |
| priceNote | Yes | |
| disclaimer | Yes | |
| pricingUrl | Yes | |
| checksCount | Yes | |
| productMode | No | |
| vatIncluded | Yes | |
| exampleReportUrl | Yes | |
| freeReportLimits | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), and the description still adds substantial non-obvious context: the consent text must be accepted before create_free_report, the free/private-link delivery mode, the Navarra coverage gap, and the mandatory disclaimers the agent must relay. This goes well beyond what the annotations disclose.
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 purpose and usage in the first two sentences, which is exactly right. The trailing disclaimer block is long and semicolon-dense, but each clause carries a real constraint the agent must honor, so it mostly earns its place despite the bulk.
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?
An output schema exists, so return values need no explanation, yet the description still surfaces the workflow prerequisite (consent acceptance), geographic limits, and mandatory user-facing caveats. For a single-parameter read-only product lookup, an agent has everything needed to call and communicate results 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% for the single optional 'language' parameter, including its enum and default, so the schema does the work. The description never mentions the language parameter or that it also controls the language of the returned report, adding no meaning beyond the schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Returns the HOUSINGFAX report for a home in Spain (productMode free)') and enumerates the payload: the full report with web view and PDF, report limits, and the consent text with its SHA-256. An agent can distinguish this from create_free_report and purchase_report without opening a 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?
Explicitly names the triggering conditions ('Use it when someone asks what HOUSINGFAX offers or before ordering') and ties the consent text to the downstream create_free_report call, which is an actionable alternative/dependency. Nothing about when to reach for this tool is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the status of a report created with create_free_report: queued, in_progress, ready, failed or expired, with the private link when ready. Wait pollAfterSeconds between calls. withLimitations=true means some source did not answer and its check shows ○ no data with the reason (unknown, not negative). Give the link only to the person.
| Name | Required | Description | Default |
|---|---|---|---|
| jobId | Yes | jobId returned by create_free_report or purchase_report. | |
| language | No | Language of the texts in the answer (and of the report): es, en, de, nl or fr. Default es. | es |
| statusToken | Yes | statusToken returned by create_free_report or purchase_report. |
| Name | Required | Description |
|---|---|---|
| jobId | Yes | |
| stage | Yes | |
| notice | Yes | |
| status | Yes | |
| payment | No | |
| contract | Yes | |
| language | Yes | |
| errorCode | No | |
| previewUrl | No | |
| queuePosition | No | |
| withLimitations | No | |
| estimatedSeconds | No | |
| pollAfterSeconds | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, yet the description still adds real behavioral context: polling cadence, the meaning of withLimitations=true, how to interpret '○ no data' (unknown, not negative), and a handling constraint ('Give the link only to the person'). That is well beyond what the annotations convey.
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?
Dense, front-loaded and free of filler; each sentence carries content. Minor cost: pollAfterSeconds is cited without ever appearing in the schema, which could momentarily confuse an agent looking for that parameter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return structure need not be explained, and the description still covers status values, degradation semantics and link-handling safety. Nothing an agent needs in order to call this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so jobId, statusToken and language are already fully documented. The description references the jobId/statusToken provenance but adds no format, constraint or enum detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Returns the status of a report') and ties it to the sibling that creates it (create_free_report). It even enumerates the possible result states (queued, in_progress, ready, failed, expired), so an agent knows exactly what this tool yields 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 operational context: this is the follow-up call for a report produced by create_free_report, and it tells the agent to poll (wait pollAfterSeconds between calls). It never names an alternative tool or an exclusion, so it stops short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists the 22 numbered checks of the report (title, question it answers and whether its source is integrated yet) and the meaning of the ✓ / ⚠ / ○ marks. Use it to explain what the report looks at. Checks marked pending_integration show as ○ no data, never as a negative result. Always tell the person: it is a preliminary, automated report built from public records, not a technical inspection, valuation, certificate, safety assessment or legal advice; probabilities are given as words (very low to very high), never as percentages; a check without data (○) means unknown, not negative or safe; Navarra is not covered yet; the report is only available as a private link.
| Name | Required | Description | Default |
|---|---|---|---|
| language | No | Language of the texts in the answer (and of the report): es, en, de, nl or fr. Default es. | es |
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| checks | Yes | |
| contract | Yes | |
| language | Yes | |
| semaphore | Yes | |
| methodologyUrl | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description goes well beyond that: it defines the mark semantics, warns that pending_integration sources surface as ○ and must never be read as negative, and enumerates the mandatory caveats the agent must relay (preliminary automated report, no percentages, Navarra uncovered, private link only).
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 in the first sentence, and every subsequent clause is functional rather than filler. The disclosure block is dense and runs long, which slightly hurts scanability, but no sentence is wasted.
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?
An output schema exists, yet the description still explains what the listed checks contain and what the marks mean, and it supplies the disclaimers the agent must surface to users. For a read-only listing tool this is fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single, fully documented enum parameter (language with default), so the schema already does the work. The description adds nothing about the language parameter, making the baseline 3 correct.
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 ('Lists the 22 numbered checks of the report') and enumerates the fields returned (title, question, integration status) plus the mark legend. This is clearly distinguishable from siblings like check_coverage and get_report_status, which do different jobs.
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?
'Use it to explain what the report looks at' gives a clear use context, and the note that pending_integration checks appear as ○ (never negative) tells the agent when not to interpret a result as a failure. It does not explicitly name an alternative sibling, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Not available: every report is free; use create_free_report. This tool stays in the contract for compatibility and answers NOT_FOR_SALE without creating anything.
| Name | Required | Description | Default |
|---|---|---|---|
| tier | Yes | Kept for compatibility with contract 1.1.0; not used while every report is free (purchase_report answers NOT_FOR_SALE). | |
| Yes | Kept for compatibility with contract 1.1.0; not used while every report is free (purchase_report answers NOT_FOR_SALE). | ||
| consent | Yes | Kept for compatibility with contract 1.1.0; not used while every report is free (purchase_report answers NOT_FOR_SALE). | |
| language | No | Language of the texts in the answer (and of the report): es, en, de, nl or fr. Default es. | es |
| freeReport | No | Kept for compatibility with contract 1.1.0; not used while every report is free (purchase_report answers NOT_FOR_SALE). | |
| acceptTerms | Yes | Kept for compatibility with contract 1.1.0; not used while every report is free (purchase_report answers NOT_FOR_SALE). | |
| termsVersion | Yes | Kept for compatibility with contract 1.1.0; not used while every report is free (purchase_report answers NOT_FOR_SALE). | |
| resolutionToken | No | Kept for compatibility with contract 1.1.0; not used while every report is free (purchase_report answers NOT_FOR_SALE). | |
| waiveWithdrawalRight | Yes | Kept for compatibility with contract 1.1.0; not used while every report is free (purchase_report answers NOT_FOR_SALE). | |
| consentStatementSha256 | Yes | Kept for compatibility with contract 1.1.0; not used while every report is free (purchase_report answers NOT_FOR_SALE). |
| Name | Required | Description |
|---|---|---|
| name | Yes | |
| tier | Yes | |
| jobId | Yes | |
| price | Yes | |
| notice | Yes | |
| status | Yes | |
| orderId | Yes | |
| contract | Yes | |
| currency | Yes | |
| language | Yes | |
| reportUrl | Yes | |
| priceCents | Yes | |
| checkoutUrl | Yes | |
| statusToken | Yes | |
| vatIncluded | Yes | |
| termsVersion | Yes | |
| pollAfterSeconds | Yes | |
| checkoutExpiresAt | Yes | |
| agentContractingTermsUrl | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, and the description is consistent with them while adding real value: it discloses the returned signal (NOT_FOR_SALE), confirms no side effects ('without creating anything'), and explains why the tool still exists (contract compatibility). This is exactly the kind of context 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?
Two sentences, both front-loaded: the unavailability and the replacement come first, the compatibility rationale second. Zero 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?
For a deprecated no-op with an output schema, this covers everything an agent needs: it is not callable for its nominal purpose, what it returns instead, and what to use instead. Nothing is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3, but the description adds a global semantic the per-parameter text implies only piecemeal: none of the parameters are consumed because the call never creates anything. That tells an agent it need not assemble a valid purchase payload.
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 exactly what this tool is and does: a compatibility stub that answers NOT_FOR_SALE and creates nothing, rather than a purchase tool. It also names the sibling (create_free_report) that replaces it, so an agent can distinguish it without opening any 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?
Explicit routing guidance: 'every report is free; use create_free_report'. The when-not-to-use case is stated directly, leaving nothing to inference about whether this tool should ever be called.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Identifies the building from an address found with search_address (object address) or from a cadastral reference (14 characters = building or plot; 18 or 20 = a single flat). Give either cadastralReference or address, not both. status resolved returns a resolutionToken (valid 15 minutes) for create_free_report, the building's public cadastral data and whether an IEE/ITE record exists (ieeAvailability; unverified means the registry did not answer, not that there is none), which decides whether the report includes the building condition assessment. status select_unit lists the units: ask the person which flat, or repeat with the 14-character reference and scope=building for the whole building. Only non-protected cadastral data is returned. Do not publish the address or reference.
| Name | Required | Description | Default |
|---|---|---|---|
| scope | No | Only with a 14-character cadastralReference: building to report on the whole building. | |
| address | No | Coded address from search_address (provinceCode, municipalityDgcCode, municipalityIneCode, streetTypeCode, streetCode, number; localityId in the Basque Country; optional block, stair, floor, door). Use instead of cadastralReference. | |
| language | No | Language of the texts in the answer (and of the report): es, en, de, nl or fr. Default es. | es |
| cadastralReference | No | Cadastral reference: 14 characters (building or plot), 18 or 20 (a flat). Use instead of address. |
| Name | Required | Description |
|---|---|---|
| notice | Yes | |
| status | Yes | |
| building | Yes | |
| contract | Yes | |
| language | Yes | |
| candidates | Yes | |
| availableTiers | Yes | |
| evaluationScope | Yes | |
| ieeAvailability | Yes | |
| resolutionToken | Yes | |
| availableNumbers | No | |
| resolutionExpiresInSeconds | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/openWorld/no-destructive, so the bar is lower, yet the description still adds real behavior: resolutionToken lifetime (15 minutes), the meaning of ieeAvailability='unverified' (registry did not answer, not absence), that only non-protected cadastral data is returned, and a privacy instruction not to publish the address or reference. These are non-obvious traits an agent could not infer from structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose and input choice before the status/token details, and every clause carries information (token TTL, iee semantics, privacy). It is dense and slightly long, with several parenthetical asides, but nothing is pure 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?
An output schema exists, so return values need not be explained, yet the description still clarifies the two status branches and the downstream token handoff. Combined with the exclusivity rule and reference-length semantics, an agent has everything needed to call this correctly and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents each field and the baseline is 3. The description goes beyond it by stating the mutual exclusion (cadastralReference OR address, not both) and by tying scope=building specifically to the 14-character reference, which is a semantic constraint the schema does not encode.
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 (identifies/resolves) and resource (building) and immediately distinguishes itself from siblings by naming search_address as the upstream source and create_free_report as the downstream consumer. The two possible inputs (coded address vs cadastral reference) are spelled out, so an agent knows exactly what this tool consumes.
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?
Explicit routing rules: use the address from search_address OR a cadastral reference, but not both; the two status outcomes are given with follow-up actions ('ask the person which flat', or repeat with scope=building). It also names the sibling that consumes the token (create_free_report). This is a full when/how/when-not specification.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Two steps to build an address. kind=municipality with provinceCode and q returns municipalities and their codes. kind=street with provinceCode, municipalityDgcCode, municipalityIneCode (from the first step) and q returns streets with streetTypeCode and streetCode (and localityId in the Basque Country). Pass the chosen street, the house number and the codes to resolve_building. Only for places check_coverage reports as covered. Do not store or publish the address.
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | Text to search: municipality name, or street name optionally followed by the number ("Colón, 5"). | |
| kind | Yes | municipality (step 1) or street (step 2). | |
| language | No | Language of the texts in the answer (and of the report): es, en, de, nl or fr. Default es. | es |
| provinceCode | Yes | Two-digit INE province code (e.g. 28 Madrid, 08 Barcelona). | |
| streetTypeCode | No | Only with kind=street, optional: street type code to narrow the search (CL, AV, PZ…). | |
| municipalityDgcCode | No | Only with kind=street: municipalityDgcCode from step 1. | |
| municipalityIneCode | No | Only with kind=street: municipalityIneCode from step 1. |
| Name | Required | Description |
|---|---|---|
| kind | Yes | |
| options | Yes | |
| contract | Yes | |
| language | Yes | |
| numberHint | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent and openWorld, so the safety profile is covered. The description adds genuine behavioral context beyond that: the mandatory two-step sequencing, the dependency of step 2 inputs on step 1 outputs, the Basque Country localityId special case, and a legal/usage restriction on persisting results.
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?
Four compact sentences, front-loaded with the two-step model, each carrying distinct information (mode semantics, code propagation, hand-off to resolve_building, constraints). Slight density but 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?
An output schema exists so return values need not be described, and annotations cover the safety profile. The description supplies everything else an agent needs: the workflow order, the cross-parameter dependencies, the coverage precondition, and the follow-on 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 description coverage is 100% and the schema already specifies each parameter's role, patterns and 'only with kind=street' conditions. The description reinforces which codes flow from step 1 to step 2, adding sequencing meaning, but mostly restates what the schema already establishes, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource (search municipalities or streets in the official directory) and immediately disambiguates the two modes via kind=municipality vs kind=street. It also positions itself in a chain with resolve_building and check_coverage, making it clearly distinguishable from 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?
Gives explicit preconditions and exclusions: only search places that check_coverage reports as covered, do not store or publish the address, and route the result onward to resolve_building with the house number. This is a rare case of clear when-to-use, when-not-to-use, and next-step routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
check_coverage1 field changedOutput schema / properties / contract / constPrevious value: -"agent-api-1.1.0"New value: +"agent-api-1.2.0"create_free_report2 fields changedInput schema / properties / email / descriptionPrevious value: -"Optional email of the person for the ready notice, only with their permission."New value: +"Optional email of the person for the ready notice with the link and the PDF, only with their permission."Output schema / properties / contract / constPrevious value: -"agent-api-1.1.0"New value: +"agent-api-1.2.0"get_products9 fields changedOutput schema / properties / contract / constPrevious value: -"agent-api-1.1.0"New value: +"agent-api-1.2.0"Output schema / properties / productModeAdded value: +{
+ "enum": [
+ "commercial",
+ "free"
+ ],
+ "type": "string"
+}Output schema / properties / products / minItemsPrevious value: -3New value: +1Output schema / properties / upgrade / additionalPropertiesRemoved value: -falseOutput schema / properties / upgrade / anyOfAdded value: +[
+ {
+ "additionalProperties": false,
+ "properties": {
+ "from": {
+ "const": "simple",
+ "type": "string"
+ },
+ "price": {
+ "maxLength": 600,
+ "minLength": 1,
+ "type": "string"
+ },
+ "priceCents": {
+ "maximum": 9007199254740991,
+ "minimum": 1,
+ "type": "integer"
+ },
+ "to": {
+ "const": "complete",
+ "type": "string"
+ }
+ },
+ "required": [
+ "from",
+ "to",
+ "priceCents",
+ "price"
+ ],
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+]Output schema / properties / upgrade / propertiesRemoved value: -{
- "from": {
- "const": "simple",
- "type": "string"
- },
- "price": {
- "maxLength": 600,
- "minLength": 1,
- "type": "string"
- },
- "priceCents": {
- "maximum": 9007199254740991,
- "minimum": 1,
- "type": "integer"
- },
- "to": {
- "const": "complete",
- "type": "string"
- }
-}Output schema / properties / upgrade / requiredRemoved value: -[
- "from",
- "to",
- "priceCents",
- "price"
-]Output schema / properties / upgrade / typeRemoved value: -"object"Output schema / requiredPrevious value: -[
- "contract",
- "language",
- "currency",
- "vatIncluded",
- "priceNote",
- "products",
- "upgrade",
- "freeReportLimits",
- "consent",
- "checksCount",
- "pricingUrl",
- "orderUrl",
- "exampleReportUrl",
- "disclaimer"
-]New value: +[
+ "contract",
+ "language",
+ "currency",
+ "vatIncluded",
+ "priceNote",
+ "products",
+ "freeReportLimits",
+ "consent",
+ "checksCount",
+ "pricingUrl",
+ "orderUrl",
+ "exampleReportUrl",
+ "disclaimer"
+]get_report_status1 field changedOutput schema / properties / contract / constPrevious value: -"agent-api-1.1.0"New value: +"agent-api-1.2.0"list_checks1 field changedOutput schema / properties / contract / constPrevious value: -"agent-api-1.1.0"New value: +"agent-api-1.2.0"purchase_report11 fields changedInput schema / properties / acceptTerms / descriptionPrevious value: -"true: you accept the Terms, including the clause on contracting through an agent (consent.agentContractingTermsUrl)."New value: +"Kept for compatibility with contract 1.1.0; not used while every report is free (purchase_report answers NOT_FOR_SALE)."Input schema / properties / consent / descriptionPrevious value: -"true: you accept the consent text from get_products on the person's behalf."New value: +"Kept for compatibility with contract 1.1.0; not used while every report is free (purchase_report answers NOT_FOR_SALE)."Input schema / properties / consentStatementSha256 / descriptionPrevious value: -"consent.statementSha256 from get_products for the same language."New value: +"Kept for compatibility with contract 1.1.0; not used while every report is free (purchase_report answers NOT_FOR_SALE)."Input schema / properties / email / descriptionPrevious value: -"Email of the person (required): receipt, private report link and withdrawal confirmation."New value: +"Kept for compatibility with contract 1.1.0; not used while every report is free (purchase_report answers NOT_FOR_SALE)."Input schema / properties / freeReport / descriptionPrevious value: -"A ready free report of the same person to buy from: { jobId, statusToken } from create_free_report. Give this or resolutionToken, not both."New value: +"Kept for compatibility with contract 1.1.0; not used while every report is free (purchase_report answers NOT_FOR_SALE)."Input schema / properties / language / descriptionPrevious value: -"Language of the report, the checkout page and the texts: es, en, de, nl or fr. Default es. Must be the language of the consent text shown."New value: +"Language of the texts in the answer (and of the report): es, en, de, nl or fr. Default es."Input schema / properties / resolutionToken / descriptionPrevious value: -"resolutionToken returned by resolve_building (valid 15 minutes). Give this or freeReport, not both."New value: +"Kept for compatibility with contract 1.1.0; not used while every report is free (purchase_report answers NOT_FOR_SALE)."Input schema / properties / termsVersion / descriptionPrevious value: -"consent.termsVersion from get_products (the Terms version you accept)."New value: +"Kept for compatibility with contract 1.1.0; not used while every report is free (purchase_report answers NOT_FOR_SALE)."Input schema / properties / tier / descriptionPrevious value: -"simple (essential report) or complete (only when the building has an IEE/ITE record)."New value: +"Kept for compatibility with contract 1.1.0; not used while every report is free (purchase_report answers NOT_FOR_SALE)."Input schema / properties / waiveWithdrawalRight / descriptionPrevious value: -"true: the person asks for immediate execution and loses the 14-day right of withdrawal once the report is supplied."New value: +"Kept for compatibility with contract 1.1.0; not used while every report is free (purchase_report answers NOT_FOR_SALE)."Output schema / properties / contract / constPrevious value: -"agent-api-1.1.0"New value: +"agent-api-1.2.0"resolve_building1 field changedOutput schema / properties / contract / constPrevious value: -"agent-api-1.1.0"New value: +"agent-api-1.2.0"search_address1 field changedOutput schema / properties / contract / constPrevious value: -"agent-api-1.1.0"New value: +"agent-api-1.2.0"check_coveragecreate_free_reportget_productsget_report_statuslist_checkspurchase_reportresolve_buildingsearch_addressSpanish public property auctions (judicial, AEAT, Social Security): daily data and risk flags.
New-build homes on sale in Spain, buying costs, non-resident tax and local open data.
First-party Spanish and Portuguese property listings with notary-verified prices.
Market sizing, prices, rents, crime and locations in Spain from INE and other public data
Add one secure layer between your agents and this server.
