Immediate home report for a building or flat in Spain: 22 checks from official public sources.
Scored across 8 tools
Each tool targets a distinct step in the report workflow (coverage, address, building, products, checks, free/paid creation, status), and descriptions are detailed enough to steer selection. Only mild overlap exists between get_products and list_checks (both describe offerings) and between create_free_report and purchase_report (both produce reports), but the free/paid split keeps them separable.
All 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 minor extension to verb_noun_noun in get_report_status and create_free_report is predictable and readable.
Eight tools map cleanly onto the service's lifecycle stages without redundancy, and each one earns its place in the coverage→address→building→order→status chain. The count is well-scoped for a report-ordering service.
The surface covers the full ordering lifecycle: coverage check, address/build resolution, product and check listings, free and paid report creation, and status polling with links. Minor gaps like re-delivering a lost report link or explicit refund/cancel handling (only surfaced as statuses) are workable around.
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 cover read-only, idempotent, and open-world behavior, and the description adds domain-specific traits annotations cannot express: 'not_yet_covered never means no risk', the Navarra foral adapter caveat, the whole-building scope in the Basque Country, and the rule that an unavailable municipalityLookup means unknown rather than missing.
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 dense and useful but packed into a single run-on sentence with semicolons, so the routing cue ('Call it before search_address') lands at the very end instead of being front-loaded.
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 tri-state lookup it covers the key behaviors an agent needs, and the output schema carries the return shape. The missing piece is explicit guidance on passing a province alone versus province plus municipality.
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 each parameter already has a description, so the baseline is 3. The description adds the province name-or-INE-code distinction and the 'omit both fields to list every province' behavior, but not enough to raise the score further.
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?
It states a precise verb and resource — deciding whether a report can be produced for a province or municipality — and explicitly names the sibling it precedes (search_address), so an agent can distinguish it from resolve_building and the report tools.
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 an explicit trigger, 'Call it before search_address when you are not sure the place is covered,' but does not say when NOT to use it or name a different alternative for cases that are already known to be covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Queues the free report for the building resolved with resolve_building and returns a private link (previewUrl) and a statusToken for get_report_status. The free report is a blurred web preview without PDF; it is 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; at most 2 free 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, 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 (readOnlyHint=false, idempotentHint=false, openWorldHint=true) only flag this as a non-idempotent write, but the description adds substantial context the annotations cannot: generation time ('in minutes'), the blurred/no-PDF output, the 2-per-email-per-14-days rate limit, private-link handling, and the exact consent contract including 'never accept on the person's behalf'.
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-loads the action, dependency and return values before the consent and disclosure requirements. The mandatory user-facing disclosure sentence is long and reads more like product copy than tool guidance, but each clause maps to a real behavioral constraint, so the size is mostly earned.
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?
Has an output schema, so return values need not be detailed, yet the description still names previewUrl and statusToken and links statusToken to get_report_status. Combined with prerequisites, consent chain, rate limits, coverage gaps (Navarra) and privacy constraints, an agent has everything needed to invoke it correctly and safely.
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 all five parameters and the baseline is 3. The description nonetheless adds decision semantics beyond the schema: consent may only be set after explicit in-conversation acceptance, consentStatementSha256 must match the language of the shown text, and email requires permission. That is real added meaning, not repetition.
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 ('Queues the free report for the building resolved with resolve_building') and names the dependency tool. It also discloses the observable result (previewUrl, statusToken) and distinguishes this free, blurred, no-PDF artifact from the paid variant implied by the purchase_report sibling.
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, and get_products must supply the consent text and statementSha256 for the matching language. It describes when consent may be set (explicit acceptance in this conversation) and when email may be used (with permission). It stops short of explicitly naming purchase_report as the alternative for a full PDF, so it is clear context without full alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the three HOUSINGFAX report types for a home in Spain with prices in EUR, VAT included: Free report (€0), Essential report (€11 VAT included) and Complete report with building condition (€19 VAT included; upgrade from the essential one €8 VAT included). Also returns the free-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, how much it costs, or before ordering. The complete report can only be ordered when the building has an IEE/ITE record. 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 | Yes | |
| contract | Yes | |
| currency | Yes | |
| language | Yes | |
| orderUrl | Yes | |
| products | Yes | |
| priceNote | Yes | |
| disclaimer | Yes | |
| pricingUrl | Yes | |
| checksCount | Yes | |
| vatIncluded | Yes | |
| exampleReportUrl | Yes | |
| freeReportLimits | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, but the description adds behavior beyond them: the free-report limits, the mandatory consent text+hash gate before create_free_report, the IEE/ITE ordering constraint, and a required disclosure script the agent must relay to the person. None of this is derivable 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 what is returned (types and prices), then usage, then constraints. The long mandated disclaimer block is verbose but is arguably load-bearing output content; still, it stretches the entry considerably for a one-parameter read tool.
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 shape need not be explained, yet the description still summarizes the products and prices. Combined with the usage conditions, ordering prerequisite, and disclosure requirements, nothing needed 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?
There is a single optional 'language' parameter with 100% schema description coverage and a five-value enum, so the schema fully documents it. The description adds no syntax or formatting 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?
Names the exact resource (the three HOUSINGFAX report types for a home in Spain) with concrete prices, plus the ancillary returns (free-report limits, consent text + SHA-256). This is far more specific than the generic name 'get_products' and clearly separates it from siblings like create_free_report and purchase_report.
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 ('when someone asks what HOUSINGFAX offers, how much it costs, or before ordering') and routes the agent downstream to create_free_report for the consent requirement. It also states the ordering prerequisite (IEE/ITE record) that gates the complete report.
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 and closed-world, so safety is covered. The description adds genuinely non-obvious behavior: the polling cadence, the meaning of withLimitations (a source that did not answer shows ○ no data with a reason — explicitly unknown, not negative), and a privacy constraint on the returned link. It does not say what happens to expired/failed jobs or how long the statusToken/link remains valid.
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, each carrying distinct payload: what is returned, how to poll, and how to interpret limitations plus the link-sharing warning. Front-loaded with the return value, zero filler or restated boilerplate.
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 re-explained, yet the description still surfaces the statuses, the withLimitations semantics and the link-handling rule. It is complete enough to poll correctly; only token/link lifetime and terminal-state handling are unstated.
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 documents all three parameters with patterns and an enum, so the baseline is 3. The description adds no per-parameter detail — language, jobId format and statusToken provenance are left entirely to 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+resource ("Returns the status of a report"), names the originating sibling (create_free_report) and enumerates the exact status vocabulary (queued, in_progress, ready, failed, expired). An agent can distinguish this from create_free_report, purchase_report and check_coverage 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?
Gives concrete operational guidance for the polling pattern ("Wait pollAfterSeconds between calls") and ties the tool to the create_free_report workflow that produces the tokens. It does not name alternative status/check routes (e.g. list_checks) or state when this tool should not be used, so it stops short of full when/when-not coverage.
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, whether its source is integrated yet and which report types include it) 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds real behavioral context beyond them: pending_integration checks render as ○ no data and never as a negative result, Navarra is not covered, and the report is only distributed as a private link. It adds no auth or rate-limit detail, which keeps it out of 5 territory.
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, with the mark legend immediately after. The second half is a long mandated disclosure block; its sentences are operationally relevant for the agent to relay, but the single packed sentence plus the disclaimer wall makes it dense rather than elegant.
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 an output schema present, return values need no explanation, and the description covers scope, the pending-integration caveat, geographic limitation and distribution constraints. The only gap is any relationship to siblings such as check_coverage, which would help an agent decide between them.
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 `language` parameter is fully described in the schema with an enum and default, giving 100% schema coverage, which sets the baseline at 3. The description never mentions language at all, so it adds nothing beyond the schema and cannot score higher.
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 (Lists) and a specific resource with its exact scope: the 22 numbered checks of the report, plus the fields returned (title, question, integration status, report types) and the mark legend. It is clearly distinguishable from siblings like check_coverage or get_report_status because it describes catalog-level content rather than coverage or status of a specific report.
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 concrete usage context, and it implies this is the explanatory/catalog tool rather than a status or purchase tool. However it never names an alternative or states a when-not-to-use condition, so sibling routing is left partly to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Opens an order for a paid report and returns a Stripe Checkout URL (checkoutUrl) where the person, or you on their behalf, pays: Essential report €11 VAT included or Complete report with building condition €19 VAT included, VAT included, one-off payment, no subscription. Use it only when the person has decided to buy that report type. The complete report can only be bought when resolve_building says ieeAvailability=available. The building comes from resolve_building (resolutionToken, valid 15 minutes) or from a free report that is ready (freeReport with its jobId and statusToken; the paid report then reuses its sources). ACCEPTANCE: by calling it you accept, on the person's behalf, the consent text from get_products (data processing, immediate execution and loss of the right of withdrawal) and the Terms in force, including the clause on contracting through an agent; the person who delegates to you is bound by it, so tell them before calling. Pass consent=true with consent.statementSha256, termsVersion from get_products, acceptTerms=true and waiveWithdrawalRight=true. The email is required: receipt, report link and withdrawal confirmation go there. Nothing is generated until Stripe confirms the payment; then the report is ready in minutes (the AI summary follows) and the link is emailed. Poll get_report_status with the returned jobId and statusToken: awaiting_payment, payment_received, queued, in_progress, ready (or payment_expired, refunded, failed). Never publish the checkout or report link. 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 |
|---|---|---|---|
| tier | Yes | simple (essential report) or complete (only when the building has an IEE/ITE record). | |
| Yes | Email of the person (required): receipt, private report link and withdrawal confirmation. | ||
| consent | Yes | true: you accept the consent text from get_products on the person's behalf. | |
| language | No | 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. | es |
| freeReport | No | A ready free report of the same person to buy from: { jobId, statusToken } from create_free_report. Give this or resolutionToken, not both. | |
| acceptTerms | Yes | true: you accept the Terms, including the clause on contracting through an agent (consent.agentContractingTermsUrl). | |
| termsVersion | Yes | consent.termsVersion from get_products (the Terms version you accept). | |
| resolutionToken | No | resolutionToken returned by resolve_building (valid 15 minutes). Give this or freeReport, not both. | |
| waiveWithdrawalRight | Yes | true: the person asks for immediate execution and loses the 14-day right of withdrawal once the report is supplied. | |
| consentStatementSha256 | Yes | consent.statementSha256 from get_products for the same language. |
| 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?
Far exceeds the annotations (readOnly/openWorld/idempotent/destructive hints). Discloses that nothing is generated until Stripe confirms, the post-payment lifecycle and polling states via get_report_status, the email requirement, the acceptance/consent obligations on the person's behalf, and the 'never publish the link' constraint. This is rich behavioral context 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?
Purpose is front-loaded, which is good, but the body is a single dense block that mixes prerequisites, legal acceptance, lifecycle, and disclaimers without structure. There is also a literal duplication ('€19 VAT included, VAT included'), indicating loose editing. Information is valuable but not well organized.
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 mutating, multi-step purchase flow with 10 params, nested objects, and an output schema, the description covers prerequisites, consent binding, payment gating, follow-up polling, and required consumer disclosures. Nothing critical 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 schema already documents all 10 parameters, including the consent/terms booleans and token formats. The description reinforces the mutual exclusivity of resolutionToken vs freeReport and the 15-minute token validity, but largely restates what the schema already provides. 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 and resource: 'Opens an order for a paid report and returns a Stripe Checkout URL'. It also distinguishes itself from siblings by naming resolve_building and create_free_report as sources and get_report_status as the follow-up, so the agent can route without opening other schemas.
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 when-to-use ('only when the person has decided to buy that report type'), explicit precondition (complete tier requires ieeAvailability=available from resolve_building), and explicit input alternatives (resolutionToken OR a ready freeReport, not both). Exclusion and alternative conditions are all present.
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, whether an IEE/ITE record exists (ieeAvailability; unverified means the registry did not answer, not that there is none) and the report types that can be ordered. 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/non-destructive, and the description goes well beyond them: resolutionToken lifetime (15 minutes), ieeAvailability disambiguation ('unverified means the registry did not answer, not that there is none'), and a data-scope constraint ('Only non-protected cadastral data is returned'). The privacy instruction not to publish the address or reference is a real operational constraint absent 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 identification purpose, then the input rule, then return semantics. Dense but nearly every clause earns its place; it is longer than ideal but not padded, since the token lifetime, status branching, and privacy note all carry weight.
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?
Output schema exists, yet the description still clarifies the two status outcomes and their consequences for the caller, which is the part of the return contract that drives the next action. With annotations and a full schema in place, nothing needed to invoke 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 coverage is 100%, so the baseline is 3, but the description adds semantics the schema cannot: the length-to-domain mapping (14 = building/plot, 18 or 20 = a single flat), the constraint that scope=building is only valid with a 14-character reference, and the mutual exclusivity of the two input paths. This meaningfully reduces wrong-argument calls.
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 ('Identifies the building') and explicitly roots its two input paths in the sibling search_address ('an address found with search_address'), making it distinguishable from search_address at a glance. An agent can tell it resolves, not searches.
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 mutual-exclusion guidance ('Give either cadastralReference or address, not both'), names the downstream consumer (create_free_report via resolutionToken), and prescribes what to do on status select_unit ('ask the person which flat, or repeat with the 14-character reference and scope=building'). This is when/when-not plus alternative routing.
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 readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description still adds real context beyond them: the mandatory two-step dependency between calls, the coverage precondition, and a compliance constraint ('Do not store or publish the address') that no annotation conveys. It stops short of 5 only because it says nothing about result limits or ambiguity handling.
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 short sentences, front-loaded with the core two-step model, then per-step outputs, then the handoff, then the constraints. No filler, no restatement of the name or title, and each sentence adds operational information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter tool with an output schema, the description covers what the schema cannot: call ordering, cross-parameter dependencies, coverage precondition, and data-handling constraint. Return shape can be deferred to the output schema, and nothing an agent needs before invoking the tool 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 goes beyond the per-field text by explaining the inter-call data flow: municipalityDgcCode and municipalityIneCode come 'from the first step' and streetTypeCode is optional narrowing for kind=street, plus localityId appearing only in the Basque Country. That relational meaning is not derivable from the schema alone.
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 ('Two steps to build an address') and enumerates exactly what each kind value returns (municipalities + codes; streets + streetTypeCode/streetCode). It explicitly differentiates itself from the sibling resolve_building, which it hands off to, so an agent can tell the two apart without reading 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?
The description lays out the full two-step procedure (kind=municipality first, then kind=street with codes from step 1), names the next tool in the chain (resolve_building), and states the precondition 'Only for places check_coverage reports as covered'. That is explicit when-to-use, sequencing, and an alternative/precondition all in one passage.
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_coveragecreate_free_reportget_productsget_report_statuslist_checkspurchase_reportresolve_buildingsearch_addressSpanish public property auctions (judicial, AEAT, Social Security): daily data and risk flags.
First-party Spanish and Portuguese property listings with notary-verified prices.
AI legal copilot for foreigners in Spain: immigration and housing rental, cited to Spanish law.
Field-tested Spanish immigration gotchas, procedure guides, and live Madrid padrón availability.
Add one secure layer between your agents and this server.
