# Fixando public price MCP > Read-only structured access to the same service price estimates published on Fixando. No account, API key or OAuth is required. ## Connection - Endpoint: `https://www.fixando.live/mcp` - Transport: stateless Streamable HTTP, JSON responses. - Method: POST. GET on the MCP endpoint returns 405. - Content-Type: `application/json` - Accept: `application/json, text/event-stream` - Supported protocol versions: 2025-11-25, 2025-06-18, 2025-03-26. - No session ID or persistent SSE channel is required. - Human guide: [/mcp/docs](/mcp/docs) - Website retrieval guidance: [/llms.txt](/llms.txt) - Server version: 1.4.0. - Registry metadata: [/mcp-server.json](/mcp-server.json), identity `com.fixando/prices`. Publication in an external registry is separate from serving this metadata file. This reference is for agents with an MCP client. Standard HTTP crawlers can read public HTML price pages and sitemaps; they do not execute MCP tools automatically. The MCP is for public price data, not a general website crawler or access to private marketplace data. Creating service requests through an approved partner integration uses the separate [partner request API](https://connect.fixando.com/developers). Its approval and authentication flow does not apply to public price retrieval. ## Current coverage This matrix is generated from `get_markets`. It is the public price MCP's coverage, independently of the wider marketplace. A listed market does not guarantee a price for every service, place or billing type. ```json { "markets": [ { "site_code": "pt", "name": "Portugal", "default_lang": "pt", "languages": [ "pt", "en", "de", "es", "fr" ], "currency": "EUR", "endpoint": "https://www.fixando.pt/mcp" }, { "site_code": "es", "name": "España", "default_lang": "es", "languages": [ "es", "en", "pt" ], "currency": "EUR", "endpoint": "https://www.fixando.es/mcp" }, { "site_code": "de", "name": "Deutschland", "default_lang": "de", "languages": [ "de", "en", "es", "fr" ], "currency": "EUR", "endpoint": "https://www.fixando.live/mcp" }, { "site_code": "ch", "name": "Schweiz", "default_lang": "de", "languages": [ "de", "en", "pt", "es", "fr" ], "currency": "CHF", "endpoint": "https://www.fixando.ch/mcp" } ] } ``` ## Client recipes ### OpenAI Responses API Use your own OpenAI API key and an API model supporting remote MCP. No Fixando account, partner credentials or OAuth token is needed. This known-URL profile exposes only `get_prices`: ```sh curl https://api.openai.com/v1/responses \ --header "Authorization: Bearer $OPENAI_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "model": "gpt-6.1-sol", "store": false, "tools": [{ "type": "mcp", "server_label": "fixando_prices", "server_url": "https://www.fixando.pt/mcp", "allowed_tools": ["get_prices"], "require_approval": "never" }], "input": "What reference prices are shown at https://www.fixando.pt/en/capoto/preco/Lisboa/Sintra? Preserve billing units and cite the source." }' ``` Expected: an imported `mcp_list_tools` item, a successful `mcp_call`, and an answer citing the returned canonical page while retaining separate billing types. Values change with publication; do not copy an old example's amounts. Verified on 4 November 2026 with gpt-6.1-sol against public server 1.2.0: the known apartment-cleaning URL for Sintra returned separate hourly and negotiable EUR entries and a canonical citation, in both minimal and full tool profiles. No Fixando credentials were supplied. For service/place questions, use `allowed_tools: ["get_service_price_answer"]` and include the country. On 4 November the minimal profile selected one business call for painting per square metre in Lisbon municipality and for a successful CHF interior-painting reference in Switzerland. The full profile also retrieved matching evidence, but the Lisbon example needed additional location discovery. Single-call selection therefore remains dependent on the wording and imported alternatives. During evaluation, keep tool choice automatic and record the actual trace rather than forcing a Fixando call. After a server upgrade, start a new response context or refresh imported tools. Old `mcp_list_tools` items can keep an old schema in the conversation. See the [official OpenAI MCP guide](https://developers.openai.com/api/docs/guides/tools-connectors-mcp) for filtering, approvals and client-owned conversation state. `require_approval: never` here covers this anonymous, read-only profile; do not copy that setting to tools performing writes. ### Official Node.js MCP client This programmatic profile uses Node.js 20 or newer and `@modelcontextprotocol/client@2.4.0`. Install the client in your own application: ```sh npm install @modelcontextprotocol/client@2.4.0 ``` Save the following as `prices.mjs` and run `node prices.mjs`: ```javascript import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client'; const client = new Client({ name: 'my-price-client', version: '1.0.0' }); try { await client.connect(new StreamableHTTPClientTransport(new URL('https://www.fixando.pt/mcp'))); const tools = await client.listTools(); const reply = await client.callTool({ name: 'get_prices', arguments: { site_code: 'pt', lang: 'en', catid: 1591, dd: 11, cc: 11 } }); if (reply.isError) throw new Error('Price lookup failed'); const result = reply.structuredContent; console.log(result.url, result.prices); } finally { await client.close(); } ``` Expected: the current tool definitions and a structured result containing the canonical price-page URL, currency, billing types and published values. A subsequent user-facing answer must cite that URL and keep each billing type distinct. Verified on 4 November 2026 with Node.js 20.11.0 and `@modelcontextprotocol/client@2.4.0` against public server 1.2.0: an anonymous known-URL call retrieved the apartment-cleaning Sintra page with separate hourly and negotiable EUR entries. This SDK call verifies protocol retrieval; automatic model selection is tested separately. For API details see the [official MCP client connection guide](https://ts.sdk.modelcontextprotocol.io/v2/clients/connect). ### Research retrieval and ChatGPT Deep Research The optional research workflow uses `search` and `fetch` on the same endpoint. Existing custom price tools remain available. `search` returns canonical public source pages; it does not promise that a page currently has prices. `fetch` rechecks the source and returns current evidence from the same provider as the website and `get_prices`. A source with no published prices produces a tool error rather than a zero or an invented price. Connect the public endpoint with no Fixando authentication, refresh the imported tools and confirm that `search` and `fetch` are present. For ChatGPT, follow the [official connection instructions](https://developers.openai.com/plugins/deploy/connect-chatgpt); adding a custom MCP and using it in Deep Research depend on account and workspace policies. Enable the connection as a source in a new research task where supported. Test a question such as “What reference prices does Fixando publish for apartment cleaning in Sintra, Portugal? Cite the source and distinguish billing types.” Check the actual tool trace and final citation. A successful SDK call alone does not verify ChatGPT Deep Research support or natural tool selection. For a research-only API profile, restrict the imported tool names to `search` and `fetch`. For direct SDK clients, use the connection setup above and replace the price call with: ```javascript const found = await client.callTool({ name: 'search', arguments: { query: 'site:pt lang:en apartment cleaning location:"Sintra"' } }); if (found.isError) throw new Error('Source search failed'); const source = found.structuredContent.results[0]; if (!source) throw new Error('No matching public source'); const fetched = await client.callTool({ name: 'fetch', arguments: { id: source.id } }); if (fetched.isError) throw new Error('This source has no current published prices'); const document = fetched.structuredContent; console.log(document.title, document.url, document.text); ``` Expected: search records with stable `id`, descriptive `title` and canonical `url`; fetch returns `id`, `title`, `text`, `url` and `metadata.price_result`. The latter is the unchanged complete `get_prices` object, including separate `request_url` and `request_context`. Text is source evidence, with billing types and temporal fields retained; the canonical `url` is the citation, not the request action. Unknown observation boundaries stay null. The client must preserve the difference between the requested destination and the origin of observations. Queries accept service/topic text and recognised places. Add `site:pt lang:en` for an explicit market/language; otherwise the endpoint's market and default language apply. Use quoted `location:"Sintra"` for an exact place, or `dd:11 cc:11` from location discovery to disambiguate. Equal place names need an explicit selection. `dd:0` selects national source discovery. An entire canonical HTTPS Fixando price-page URL is also accepted and is resolved locally. Fetch accepts only IDs returned by search, never arbitrary URLs. IDs remain stable while the source identity and server signing secret remain unchanged; prices are reloaded on every fetch through the shared provider. Verified on 4 November 2026 with gpt-6.1-sol, public server 1.2.0 and only `search`/`fetch` imported: an ordinary apartment-cleaning question for Sintra selected `search`, fetched a returned source ID and produced a final answer citing the canonical page with separate hourly and negotiable prices. This is a Responses API research-profile check. Actual ChatGPT Deep Research remains unverified. Local tests also cover schema, privacy, withdrawal and cross-market evidence. See the [official search/fetch compatibility guide](https://developers.openai.com/api/docs/mcp). ### Refresh and troubleshooting - Changed tools or schemas: refresh `tools/list` and restart cached client conversations. - HTTP 405: use the MCP client's POST transport; a browser GET is not a connection test. - HTTP 429: honour Retry-After. HTTP 503: back off and check endpoint/market availability. - Unsupported country, language or ambiguous service/place: use the clarification response; do not switch silently to the endpoint's country. - no_data: report no published reference for that selection; never use zero or convert another unit. - Connection works but there is no model call: confirm the tool is imported, the model supports remote MCP, and the profile permits the needed tool. General model selection remains an evaluation concern. - Report problems with the endpoint, client version, server version and X-Request-ID, without API keys or personal data. ## Protocol sequence 1. POST `initialize` with a supported version, client capabilities and clientInfo. 2. Read the negotiated protocolVersion from the response. 3. Send `notifications/initialized` without an id; successful notifications have HTTP 202 and no body. 4. Send `MCP-Protocol-Version` with the negotiated version on subsequent requests. 5. Call `tools/list` for the current public tool definitions. 6. Call `tools/call` with a tool name and its arguments. Initialization: ```json {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"example-agent","version":"1.0"}}} ``` Notification: ```json {"jsonrpc":"2.0","method":"notifications/initialized"} ``` Tool discovery: ```json {"jsonrpc":"2.0","id":2,"method":"tools/list"} ``` ## Price retrieval workflow For a service-price question, call `get_service_price_answer` directly with the known site_code, service phrase, location, lang and optional billing_basis or billing_type_id. Omit location only for national references. No preliminary market, category or location discovery call is required. A missing or unsupported country returns needs_clarification rather than inheriting the endpoint's country. ```json {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_service_price_answer","arguments":{"site_code":"pt","service":"cleaning","location":"Sintra","lang":"en","billing_basis":"hour"}}} ``` The task response contains status, a short localised answer and result. result is the unchanged get_prices response, including prices, currency, canonical citation url, request_url and request_context. Cite result.url. If status is needs_clarification, result is null: ask the single clarification.question and use the relevant candidates. For a subsequent selection, use catid instead of service, or dd/cc instead of location. location_type can distinguish a named canton from its municipality. Do not silently select a candidate. New question text falls back to English until translated; resolved answer labels and prices use the selected language. Use the lower-level workflow for catalogue browsing, precise integrations or an already known price-page URL: 1. Use `get_markets` to discover supported market codes, languages, currencies and endpoints. Do not assume every country has price data. 2. Use `search_price_categories` to discover root, parent or service price-page candidates for the selected market. Search reuses website keyword matching, connecting-word normalisation and aliases in the selected language. Exact category names rank first; root, parent and service candidates remain distinct. Do not invent category IDs or page slugs. 3. For a location-specific query, use `search_price_locations`. Retain the dd/cc pair and inspect location_type, display_name and parents to distinguish equal names. dd represents the parent administrative region; cc represents its local area. Germany uses districts and urban districts at cc level; other current markets use municipalities. Açores and Madeira are autonomous regions. dd=0 means no region restriction for discovery. 4. Use `get_prices` with a returned canonical page URL, or with site_code, catid and optional dd/cc. A URL cannot be combined with category/location IDs. A URL and optional explicit market/language must agree. To select one price kind, supply billing_basis OR an exact billing_type_id. Never convert an unavailable unit into a different one. 5. For search pagination, pass next_offset as the next offset and keep the same filters. Stop when next_offset is null. Fetch only the pages needed for the query; do not enumerate every category/location combination without a reason. 6. Cite the canonical url returned by get_prices as the public source. 7. If the user wants tailored quotes, offer request_url. It opens the existing request form or service-selection step. Confirm the service and postcode with the user; opening the link never submits a request. The requested location is not automatically prefilled. Market discovery: ```json {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_markets","arguments":{}}} ``` Example service search in Portugal: ```json {"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"search_price_categories","arguments":{"site_code":"pt","query":"limpeza","limit":5}}} ``` When a canonical public price-page URL is already known, get_prices can resolve it directly; a prior search is not required. ## Calendar comparisons Use `get_service_price_answer` with the usual service/place arguments plus `year` and `period`, or `get_price_history` for known IDs or a canonical price-page URL. Omit `period` from the answer tool when the user's choice is unclear: it asks whether to use complete calendar years or matching completed-month YTD periods. Current `get_prices` results remain unchanged. `year` compares a completed calendar year with its predecessor. `ytd` compares January through the last completed month in the selected year with the same months in the preceding year. YTD is partial, recalculated monthly and usable for at most 35 days after calculation. Daily and arbitrary date windows are unsupported. The history tool optionally accepts all four `current_start`, `current_end`, `previous_start`, `previous_end` boundaries together, only when they match the selected calendar windows exactly. Period starts are inclusive; ends are exclusive in the recorded timezone. Both periods use one common private reference per billing type. Only individual comparisons marked `comparable` have a percentage, computed before display rounding. Missing, stale or incompatible evidence has no percentage. Changes describe reference estimates based on quotes and eligible customer-reported prices, not inflation or a verified paid-price index. `data_as_of` remains null. Calendar comparisons are available through MCP only. The returned `url` identifies the canonical public price page for the service and location; that page shows current prices and rolling history, without the calendar comparison. Attribute historical values to the MCP result and preserve its `period`, calculation times and comparison status. Supply `year` and `period` again when using the canonical page URL as history-tool input. ## Interpret and cite the response Successful tools return structuredContent plus the same JSON serialized in a text content block. Price lookups include status, resolved market/language, currency, canonical url, category, location and a prices array. - Preserve currency, billing_type_id and the localised unit. billing_basis supplies a language-independent quantity basis where established: hour, day, word, session or square_metre. A null basis denotes an unspecified quantity basis or a pricing condition; negotiable is not per project. Do not assume quantity multiplication is appropriate without confirming the scope. - minimum, central and maximum are the rounded values published on the website. - central_statistic is median for request-based calculations and mean for legacy data. - range_statistic is p10_p90 for request-based calculations and legacy_range for legacy data. Do not describe P10-P90 as a measured minimum/maximum or a guaranteed quote. - date identifies the published logical snapshot, including unchanged records carried forward by incremental publication. It is not an individual quote date or an invented fixed observation window. - category and location describe the requested destination for navigation. They do not establish a locally observed sample. Describe amounts as Fixando reference estimates, without inferring local quote counts or observation scope. - observation_period is the recorded eligibility window: start is inclusive and end exclusive, both YYYY-MM-DD in its recorded timezone. period_status=verified means these boundaries were recorded by the selected calculation. unavailable means they cannot be verified; boundaries and timezone remain null. - calculated_at is the actual calculation completion time in UTC (RFC 3339), not the time of this response or a later republication. data_as_of is an ingestion watermark and currently remains null. Do not infer a recent-data claim from date or calculated_at. - request_url preserves market, language and category using the existing web request route, with `s=mcp` stored as `requests.submit_source`. This identifies the handoff source separately from `ref`, which retains existing referral and advertising rules. Group categories open service selection. request_context.category_status indicates selected or selection_required; location_status=confirmation_required means the user must confirm the postcode. No personal data is placed in the URL. - status=no_data with an empty prices array is a valid page without the requested public prices. no_data_reason=insufficient_data means the page has no eligible prices; billing_type_unavailable means other public price types exist but the selected type does not. Available results have a null reason. Do not invent missing numbers or interpret no_data as a zero price. - Customer prices use the latest stored review amount, billing type and review date. A valid customer price replaces the quote median for the same request and billing type; otherwise the quote median remains. Both sources use the configured calculation limits. Historical rebuilds use the currently stored review values, without reconstructing earlier revisions. - Estimates are indicative, not binding quotes. Raw quotes, sample counts and admin-only statistics are unavailable. ## Contract changes Server version 1.2 adds get_service_price_answer, billing selectors and no_data_reason, and typed location discovery with localised names, display names and parent context. The task tool has its own needs_clarification state; get_prices retains available/no_data. It also preserves the selected request language across conflicting saved preferences and deliberate language changes. Period metadata is matched to each result's logical date; inconsistent metadata remains unavailable while valid prices are retained. Refresh tools/list and any cached strict schemas when upgrading. Server version 1.1 adds outputSchema to all four tools, billing_basis, observation metadata and the request handoff. Internal resolution diagnostics have been removed from the public result. Clients should use the requested category/location and neutral reference-estimate wording. Existing numeric fields, canonical citation URLs and the JSON text compatibility path remain available. ## Limits and retry behaviour - Search page size: 20 by default, maximum 50. - Request limit: 120 per client IP per minute, shared across tools and markets. - HTTP 429: wait for Retry-After before retrying. Do not change IPs or markets to evade the limit. - HTTP 503: temporary unavailability. Back off; do not retry in a tight loop. - JSON-RPC errors describe protocol problems. isError=true describes a failed tool call; use its message to correct arguments. - Save X-Request-ID for diagnostics. Access metadata is recorded in a dedicated log; full response payloads are not retained. - Respect robots directives and access controls when retrieving linked HTML pages. This documentation does not grant access to private pages. ## Current public tool schemas The definitions below are generated from the same registry used by tools/list. tools/list is authoritative if a previously fetched copy of this document differs. ```json [ { "name": "get_markets", "description": "List supported Fixando price markets, currencies, languages and MCP endpoints for connection setup or coverage checks. For a service-price question use get_service_price_answer directly; it can ask for a missing market.", "inputSchema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "markets": { "type": "array", "items": { "type": "object", "properties": { "site_code": { "type": "string" }, "name": { "type": "string" }, "default_lang": { "type": "string" }, "languages": { "type": "array", "items": { "type": "string" } }, "currency": { "type": "string" }, "endpoint": { "type": "string" } }, "required": [ "site_code", "name", "default_lang", "languages", "currency", "endpoint" ], "additionalProperties": false } } }, "required": [ "markets" ], "additionalProperties": false }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "search_price_categories", "description": "Find root, parent and service price-page candidates by name, optionally for a location. Includes all routed pages regardless of SEO indexing. Use get_prices to check price availability; discovery does not guarantee data.", "inputSchema": { "type": "object", "properties": { "site_code": { "type": "string", "description": "Market code returned by get_markets, for example pt or de.", "maxLength": 3 }, "lang": { "type": "string", "description": "Supported market language; defaults to the market language.", "maxLength": 10 }, "query": { "type": "string", "maxLength": 100, "description": "Optional name or keyword search; category search reuses website aliases and connecting-word normalisation." }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "offset": { "type": "integer", "minimum": 0, "maximum": 100000 }, "kind": { "type": "string", "maxLength": 7, "enum": [ "root", "parent", "service" ], "description": "Optional category hierarchy level." }, "dd": { "type": "integer", "minimum": 0, "description": "Top-level administrative region ID from search_price_locations; 0 means national. See location_type for district, canton, federal state or autonomous region/community/city." }, "cc": { "type": "integer", "minimum": 0, "description": "Local area ID from search_price_locations; requires its parent dd. Usually a municipality; Germany uses districts and urban districts." } }, "required": [ "site_code" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "site_code": { "type": "string" }, "lang": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "catid": { "type": "integer", "minimum": 0 }, "name": { "type": "string" }, "kind": { "enum": [ "root", "parent", "service" ] }, "url": { "type": "string" } }, "required": [ "catid", "name", "kind", "url" ], "additionalProperties": false } }, "total": { "type": "integer", "minimum": 0 }, "next_offset": { "type": [ "integer", "null" ], "minimum": 0 }, "retry_hint": { "type": [ "string", "null" ] } }, "required": [ "site_code", "lang", "items", "total", "next_offset", "retry_hint" ], "additionalProperties": false }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "search_price_locations", "description": "Find public administrative regions and local areas in one market. location_type and display_name disambiguate equal names; parents identify the containing region. Use returned dd/cc IDs with get_prices or search_price_categories. Optionally restrict discovery to dd. Search accepts canonical and localised names without accents.", "inputSchema": { "type": "object", "properties": { "site_code": { "type": "string", "description": "Market code returned by get_markets, for example pt or de.", "maxLength": 3 }, "lang": { "type": "string", "description": "Supported market language; defaults to the market language.", "maxLength": 10 }, "query": { "type": "string", "maxLength": 100, "description": "Optional name or keyword search; category search reuses website aliases and connecting-word normalisation." }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "offset": { "type": "integer", "minimum": 0, "maximum": 100000 }, "dd": { "type": "integer", "minimum": 0, "description": "Top-level administrative region ID from search_price_locations; 0 means national. See location_type for district, canton, federal state or autonomous region/community/city." } }, "required": [ "site_code" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "site_code": { "type": "string" }, "lang": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "dd": { "type": "integer", "minimum": 0 }, "cc": { "type": "integer", "minimum": 0 }, "name": { "type": "string" }, "localised_name": { "type": "string" }, "location_type": { "enum": [ "district", "autonomous_region", "autonomous_community", "autonomous_city", "canton", "federal_state", "district_or_city", "municipality" ] }, "display_name": { "type": "string" }, "parents": { "type": "array", "items": { "type": "object", "properties": { "dd": { "type": "integer", "minimum": 0 }, "cc": { "type": "integer", "minimum": 0 }, "name": { "type": "string" }, "location_type": { "enum": [ "district", "autonomous_region", "autonomous_community", "autonomous_city", "canton", "federal_state", "district_or_city", "municipality" ] } }, "required": [ "dd", "cc", "name", "location_type" ], "additionalProperties": false } } }, "required": [ "dd", "cc", "name", "localised_name", "location_type", "display_name", "parents" ], "additionalProperties": false } }, "total": { "type": "integer", "minimum": 0 }, "next_offset": { "type": [ "integer", "null" ], "minimum": 0 } }, "required": [ "site_code", "lang", "items", "total", "next_offset" ], "additionalProperties": false }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "get_prices", "description": "Read the same current reference prices published on a Fixando price page, combining quote medians with eligible customer-reported prices without double-counting requests. Supply an absolute HTTPS price-page url OR site_code with catid and optional dd/cc; do not mix URL and IDs. Optionally select one billing_basis OR an exact billing_type_id, including types with no quantity basis. No unit conversions are performed. Returns rounded values, statistics, verified observation windows when available and a request_url opening the existing draft/selection flow. The requested destination does not prove locally observed data. Confirm location with the user; no request is submitted by this tool or by opening the link. A valid page without the selected prices returns no_data with a reason. No raw quotes, sample counts, internal resolution or admin-only statistics.", "inputSchema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "description": "Absolute HTTPS Fixando price-page URL; never fetched remotely." }, "site_code": { "type": "string", "description": "Market code returned by get_markets, for example pt or de.", "maxLength": 3 }, "lang": { "type": "string", "description": "Supported market language; defaults to the market language.", "maxLength": 10 }, "catid": { "type": "integer", "minimum": 1, "description": "Root, parent or service category ID from search_price_categories." }, "dd": { "type": "integer", "minimum": 0, "description": "Top-level administrative region ID from search_price_locations; 0 means national. See location_type for district, canton, federal state or autonomous region/community/city." }, "cc": { "type": "integer", "minimum": 0, "description": "Local area ID from search_price_locations; requires its parent dd. Usually a municipality; Germany uses districts and urban districts." }, "billing_basis": { "type": "string", "maxLength": 20, "enum": [ "hour", "word", "session", "day", "square_metre" ], "description": "Optional established quantity basis. Use this OR billing_type_id. Total and negotiable are not quantity units." }, "billing_type_id": { "type": "integer", "enum": [ 1, 2, 5, 6, 7, 8, 9, 10, 11, 12, 13 ], "minimum": 1, "description": "Optional exact recorded billing_type_id, e.g. a fixed or negotiable type with billing_basis=null. Use this OR billing_basis." } }, "required": [], "additionalProperties": false, "oneOf": [ { "required": [ "url" ], "not": { "anyOf": [ { "required": [ "catid" ] }, { "required": [ "dd" ] }, { "required": [ "cc" ] } ] } }, { "required": [ "site_code", "catid" ], "not": { "required": [ "url" ] } } ], "allOf": [ { "not": { "required": [ "billing_basis", "billing_type_id" ] } } ] }, "outputSchema": { "type": "object", "properties": { "status": { "enum": [ "available", "no_data" ] }, "site_code": { "type": "string" }, "lang": { "type": "string" }, "currency": { "type": "string" }, "no_data_reason": { "enum": [ "insufficient_data", "billing_type_unavailable", null ] }, "url": { "type": "string" }, "category": { "type": "object", "properties": { "catid": { "type": "integer", "minimum": 0 }, "name": { "type": "string" } }, "required": [ "catid", "name" ], "additionalProperties": false }, "location": { "type": "object", "properties": { "dd": { "type": "integer", "minimum": 0 }, "cc": { "type": "integer", "minimum": 0 }, "district": { "type": [ "string", "null" ] }, "municipality": { "type": [ "string", "null" ] } }, "required": [ "dd", "cc", "district", "municipality" ], "additionalProperties": false }, "request_url": { "type": "string" }, "request_context": { "type": "object", "properties": { "category_status": { "enum": [ "selected", "selection_required" ] }, "location_status": { "enum": [ "confirmation_required" ] } }, "required": [ "category_status", "location_status" ], "additionalProperties": false }, "prices": { "type": "array", "items": { "type": "object", "properties": { "billing_type_id": { "type": "integer", "minimum": 0 }, "unit": { "type": "string" }, "billing_basis": { "type": [ "string", "null" ], "enum": [ "hour", "day", "word", "session", "square_metre", null ] }, "currency": { "type": "string" }, "minimum": { "type": "number", "minimum": 0 }, "central": { "type": "number", "minimum": 0 }, "maximum": { "type": "number", "minimum": 0 }, "central_statistic": { "enum": [ "median", "mean" ] }, "range_statistic": { "enum": [ "p10_p90", "legacy_range" ] }, "central_formatted": { "type": "string" }, "minimum_formatted": { "type": "string" }, "maximum_formatted": { "type": "string" }, "date": { "type": "string", "description": "Logical publication cutoff, YYYY-MM-DD; not an observation or calculation timestamp." }, "observation_period": { "type": "object", "properties": { "start": { "type": [ "string", "null" ], "description": "Inclusive eligibility boundary, YYYY-MM-DD." }, "end": { "type": [ "string", "null" ], "description": "Exclusive eligibility boundary, YYYY-MM-DD." }, "timezone": { "type": [ "string", "null" ], "description": "Recorded calculation timezone for the eligibility boundaries." } }, "required": [ "start", "end", "timezone" ], "additionalProperties": false }, "period_status": { "enum": [ "verified", "unavailable" ] }, "calculated_at": { "type": [ "string", "null" ], "description": "Actual selected calculation completion in UTC, RFC 3339; null if unknown." }, "data_as_of": { "type": [ "string", "null" ], "description": "Verified ingestion watermark, RFC 3339; currently unavailable (null)." } }, "required": [ "billing_type_id", "unit", "billing_basis", "currency", "minimum", "central", "maximum", "central_statistic", "range_statistic", "central_formatted", "minimum_formatted", "maximum_formatted", "date", "observation_period", "period_status", "calculated_at", "data_as_of" ], "additionalProperties": false } } }, "required": [ "status", "site_code", "lang", "currency", "no_data_reason", "url", "category", "location", "request_url", "request_context", "prices" ], "additionalProperties": false, "oneOf": [ { "properties": { "status": { "enum": [ "available" ] }, "no_data_reason": { "enum": [ null ] }, "prices": { "minItems": 1 } } }, { "properties": { "status": { "enum": [ "no_data" ] }, "no_data_reason": { "enum": [ "insufficient_data", "billing_type_unavailable" ] }, "prices": { "maxItems": 0 } } } ] }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "get_service_price_answer", "description": "Use this when a user asks for current reference prices for a local service, especially a named place. Supply the known market, service phrase, place and language directly; no preliminary discovery calls are needed. Resolves service and place and returns the same published price facts as get_prices, a short localised answer, canonical citation and optional request action. Missing or unsupported countries, unknown services/places and ambiguous matches return needs_clarification with one question and relevant candidates. Omit location only for a country-wide reference. Select billing_basis OR billing_type_id without conversion. After clarification, use the selected catid or dd/cc instead of a phrase. Not for binding quotes or professional availability; never submits requests. For historical questions provide year and period to use the same accepted calendar provider as get_price_history. If an unfinished year or comparison period is unclear, provide the known year only and ask the returned period clarification. Never substitute current prices for unavailable history.", "inputSchema": { "type": "object", "properties": { "site_code": { "type": "string", "description": "Market code returned by get_markets, for example pt or de.", "maxLength": 3 }, "lang": { "type": "string", "description": "Supported market language; defaults to the market language.", "maxLength": 10 }, "service": { "type": "string", "maxLength": 100, "description": "Service phrase in the selected language, e.g. cleaning or apartment cleaning. Use this OR a previously selected catid." }, "location": { "type": "string", "maxLength": 100, "description": "Place name in the selected market, e.g. Sintra. Omit only for national reference prices. Use this OR previously selected dd/cc." }, "catid": { "type": "integer", "minimum": 1, "description": "Category explicitly selected from clarification candidates; use instead of service." }, "kind": { "type": "string", "maxLength": 7, "enum": [ "root", "parent", "service" ], "description": "Optional hierarchy level when resolving a service phrase." }, "location_type": { "type": "string", "maxLength": 25, "enum": [ "district", "autonomous_region", "autonomous_community", "autonomous_city", "canton", "federal_state", "district_or_city", "municipality" ], "description": "Optional administrative type to disambiguate a place name, e.g. Bern canton versus municipality." }, "dd": { "type": "integer", "minimum": 0, "description": "Top-level administrative region ID from search_price_locations; 0 means national. See location_type for district, canton, federal state or autonomous region/community/city." }, "cc": { "type": "integer", "minimum": 0, "description": "Local area ID from search_price_locations; requires its parent dd. Usually a municipality; Germany uses districts and urban districts." }, "billing_basis": { "type": "string", "maxLength": 20, "enum": [ "hour", "word", "session", "day", "square_metre" ], "description": "Optional established quantity basis. Use this OR billing_type_id. Total and negotiable are not quantity units." }, "billing_type_id": { "type": "integer", "enum": [ 1, 2, 5, 6, 7, 8, 9, 10, 11, 12, 13 ], "minimum": 1, "description": "Optional exact recorded billing_type_id, e.g. a fixed or negotiable type with billing_basis=null. Use this OR billing_basis." }, "year": { "type": "integer", "minimum": 2, "maximum": 2026, "description": "Comparison year; baseline is the preceding year. A complete-year comparison requires a past year." }, "period": { "type": "string", "enum": [ "year", "ytd" ], "maxLength": 4, "description": "year: whole completed calendar years. ytd: January through last completed month in each year; unavailable in January." } }, "required": [], "additionalProperties": false, "allOf": [ { "not": { "required": [ "billing_basis", "billing_type_id" ] } }, { "not": { "required": [ "service", "catid" ] } }, { "not": { "required": [ "catid", "kind" ] } }, { "not": { "required": [ "location", "dd" ] } }, { "not": { "required": [ "location", "cc" ] } }, { "not": { "required": [ "location_type", "dd" ] } }, { "not": { "required": [ "location_type", "cc" ] } } ] }, "outputSchema": { "type": "object", "properties": { "status": { "enum": [ "available", "no_data", "needs_clarification", "comparable", "unavailable", "not_comparable" ] }, "answer": { "type": "string" }, "clarification": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "field": { "enum": [ "site_code", "lang", "service", "location", "period" ] }, "reason": { "enum": [ "missing", "unsupported", "unknown", "ambiguous" ] }, "question": { "type": "string" } }, "required": [ "field", "reason", "question" ], "additionalProperties": false } ] }, "candidates": { "type": "object", "properties": { "markets": { "type": "array", "items": { "type": "object", "properties": { "site_code": { "type": "string" }, "name": { "type": "string" }, "default_lang": { "type": "string" }, "languages": { "type": "array", "items": { "type": "string" } }, "currency": { "type": "string" }, "endpoint": { "type": "string" } }, "required": [ "site_code", "name", "default_lang", "languages", "currency", "endpoint" ], "additionalProperties": false } }, "categories": { "type": "array", "items": { "type": "object", "properties": { "catid": { "type": "integer", "minimum": 0 }, "name": { "type": "string" }, "kind": { "enum": [ "root", "parent", "service" ] }, "url": { "type": "string" } }, "required": [ "catid", "name", "kind", "url" ], "additionalProperties": false } }, "locations": { "type": "array", "items": { "type": "object", "properties": { "dd": { "type": "integer", "minimum": 0 }, "cc": { "type": "integer", "minimum": 0 }, "name": { "type": "string" }, "localised_name": { "type": "string" }, "location_type": { "enum": [ "district", "autonomous_region", "autonomous_community", "autonomous_city", "canton", "federal_state", "district_or_city", "municipality" ] }, "display_name": { "type": "string" }, "parents": { "type": "array", "items": { "type": "object", "properties": { "dd": { "type": "integer", "minimum": 0 }, "cc": { "type": "integer", "minimum": 0 }, "name": { "type": "string" }, "location_type": { "enum": [ "district", "autonomous_region", "autonomous_community", "autonomous_city", "canton", "federal_state", "district_or_city", "municipality" ] } }, "required": [ "dd", "cc", "name", "location_type" ], "additionalProperties": false } } }, "required": [ "dd", "cc", "name", "localised_name", "location_type", "display_name", "parents" ], "additionalProperties": false } } }, "required": [ "markets", "categories", "locations" ], "additionalProperties": false }, "result": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "status": { "enum": [ "available", "no_data" ] }, "site_code": { "type": "string" }, "lang": { "type": "string" }, "currency": { "type": "string" }, "no_data_reason": { "enum": [ "insufficient_data", "billing_type_unavailable", null ] }, "url": { "type": "string" }, "category": { "type": "object", "properties": { "catid": { "type": "integer", "minimum": 0 }, "name": { "type": "string" } }, "required": [ "catid", "name" ], "additionalProperties": false }, "location": { "type": "object", "properties": { "dd": { "type": "integer", "minimum": 0 }, "cc": { "type": "integer", "minimum": 0 }, "district": { "type": [ "string", "null" ] }, "municipality": { "type": [ "string", "null" ] } }, "required": [ "dd", "cc", "district", "municipality" ], "additionalProperties": false }, "request_url": { "type": "string" }, "request_context": { "type": "object", "properties": { "category_status": { "enum": [ "selected", "selection_required" ] }, "location_status": { "enum": [ "confirmation_required" ] } }, "required": [ "category_status", "location_status" ], "additionalProperties": false }, "prices": { "type": "array", "items": { "type": "object", "properties": { "billing_type_id": { "type": "integer", "minimum": 0 }, "unit": { "type": "string" }, "billing_basis": { "type": [ "string", "null" ], "enum": [ "hour", "day", "word", "session", "square_metre", null ] }, "currency": { "type": "string" }, "minimum": { "type": "number", "minimum": 0 }, "central": { "type": "number", "minimum": 0 }, "maximum": { "type": "number", "minimum": 0 }, "central_statistic": { "enum": [ "median", "mean" ] }, "range_statistic": { "enum": [ "p10_p90", "legacy_range" ] }, "central_formatted": { "type": "string" }, "minimum_formatted": { "type": "string" }, "maximum_formatted": { "type": "string" }, "date": { "type": "string", "description": "Logical publication cutoff, YYYY-MM-DD; not an observation or calculation timestamp." }, "observation_period": { "type": "object", "properties": { "start": { "type": [ "string", "null" ], "description": "Inclusive eligibility boundary, YYYY-MM-DD." }, "end": { "type": [ "string", "null" ], "description": "Exclusive eligibility boundary, YYYY-MM-DD." }, "timezone": { "type": [ "string", "null" ], "description": "Recorded calculation timezone for the eligibility boundaries." } }, "required": [ "start", "end", "timezone" ], "additionalProperties": false }, "period_status": { "enum": [ "verified", "unavailable" ] }, "calculated_at": { "type": [ "string", "null" ], "description": "Actual selected calculation completion in UTC, RFC 3339; null if unknown." }, "data_as_of": { "type": [ "string", "null" ], "description": "Verified ingestion watermark, RFC 3339; currently unavailable (null)." } }, "required": [ "billing_type_id", "unit", "billing_basis", "currency", "minimum", "central", "maximum", "central_statistic", "range_statistic", "central_formatted", "minimum_formatted", "maximum_formatted", "date", "observation_period", "period_status", "calculated_at", "data_as_of" ], "additionalProperties": false } } }, "required": [ "status", "site_code", "lang", "currency", "no_data_reason", "url", "category", "location", "request_url", "request_context", "prices" ], "additionalProperties": false, "oneOf": [ { "properties": { "status": { "enum": [ "available" ] }, "no_data_reason": { "enum": [ null ] }, "prices": { "minItems": 1 } } }, { "properties": { "status": { "enum": [ "no_data" ] }, "no_data_reason": { "enum": [ "insufficient_data", "billing_type_unavailable" ] }, "prices": { "maxItems": 0 } } } ] }, { "type": "object", "properties": { "status": { "enum": [ "comparable", "unavailable", "not_comparable" ], "description": "comparable means at least one billing comparison is valid; inspect each comparison status before using its change." }, "period": { "type": "object", "properties": { "year": { "type": "integer", "minimum": 2 }, "kind": { "enum": [ "year", "ytd" ] }, "partial": { "type": "boolean" }, "completed_months": { "type": "integer", "minimum": 1, "maximum": 12 }, "current": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" }, "timezone": { "type": "string" } }, "required": [ "start", "end", "timezone" ], "additionalProperties": false }, "previous": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" }, "timezone": { "type": "string" } }, "required": [ "start", "end", "timezone" ], "additionalProperties": false } }, "required": [ "year", "kind", "partial", "completed_months", "current", "previous" ], "additionalProperties": false }, "comparisons": { "type": "array", "items": { "type": "object", "properties": { "billing_type_id": { "type": "integer", "minimum": 0 }, "billing_basis": { "type": [ "string", "null" ], "enum": [ "hour", "day", "word", "session", "square_metre", null ] }, "unit": { "type": "string" }, "currency": { "type": "string" }, "status": { "enum": [ "comparable", "unavailable", "not_comparable" ] }, "partial": { "type": "boolean" }, "current": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "billing_type_id": { "type": "integer", "minimum": 0 }, "unit": { "type": "string" }, "billing_basis": { "type": [ "string", "null" ], "enum": [ "hour", "day", "word", "session", "square_metre", null ] }, "currency": { "type": "string" }, "minimum": { "type": "number", "minimum": 0 }, "central": { "type": "number", "minimum": 0 }, "maximum": { "type": "number", "minimum": 0 }, "central_statistic": { "enum": [ "median", "mean" ] }, "range_statistic": { "enum": [ "p10_p90", "legacy_range" ] }, "central_formatted": { "type": "string" }, "minimum_formatted": { "type": "string" }, "maximum_formatted": { "type": "string" }, "date": { "type": "string", "description": "Logical publication cutoff, YYYY-MM-DD; not an observation or calculation timestamp." }, "observation_period": { "type": "object", "properties": { "start": { "type": [ "string", "null" ], "description": "Inclusive eligibility boundary, YYYY-MM-DD." }, "end": { "type": [ "string", "null" ], "description": "Exclusive eligibility boundary, YYYY-MM-DD." }, "timezone": { "type": [ "string", "null" ], "description": "Recorded calculation timezone for the eligibility boundaries." } }, "required": [ "start", "end", "timezone" ], "additionalProperties": false }, "period_status": { "enum": [ "verified", "unavailable" ] }, "calculated_at": { "type": [ "string", "null" ], "description": "Actual selected calculation completion in UTC, RFC 3339; null if unknown." }, "data_as_of": { "type": [ "string", "null" ], "description": "Verified ingestion watermark, RFC 3339; currently unavailable (null)." } }, "required": [ "billing_type_id", "unit", "billing_basis", "currency", "minimum", "central", "maximum", "central_statistic", "range_statistic", "central_formatted", "minimum_formatted", "maximum_formatted", "date", "observation_period", "period_status", "calculated_at", "data_as_of" ], "additionalProperties": false } ] }, "previous": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "billing_type_id": { "type": "integer", "minimum": 0 }, "unit": { "type": "string" }, "billing_basis": { "type": [ "string", "null" ], "enum": [ "hour", "day", "word", "session", "square_metre", null ] }, "currency": { "type": "string" }, "minimum": { "type": "number", "minimum": 0 }, "central": { "type": "number", "minimum": 0 }, "maximum": { "type": "number", "minimum": 0 }, "central_statistic": { "enum": [ "median", "mean" ] }, "range_statistic": { "enum": [ "p10_p90", "legacy_range" ] }, "central_formatted": { "type": "string" }, "minimum_formatted": { "type": "string" }, "maximum_formatted": { "type": "string" }, "date": { "type": "string", "description": "Logical publication cutoff, YYYY-MM-DD; not an observation or calculation timestamp." }, "observation_period": { "type": "object", "properties": { "start": { "type": [ "string", "null" ], "description": "Inclusive eligibility boundary, YYYY-MM-DD." }, "end": { "type": [ "string", "null" ], "description": "Exclusive eligibility boundary, YYYY-MM-DD." }, "timezone": { "type": [ "string", "null" ], "description": "Recorded calculation timezone for the eligibility boundaries." } }, "required": [ "start", "end", "timezone" ], "additionalProperties": false }, "period_status": { "enum": [ "verified", "unavailable" ] }, "calculated_at": { "type": [ "string", "null" ], "description": "Actual selected calculation completion in UTC, RFC 3339; null if unknown." }, "data_as_of": { "type": [ "string", "null" ], "description": "Verified ingestion watermark, RFC 3339; currently unavailable (null)." } }, "required": [ "billing_type_id", "unit", "billing_basis", "currency", "minimum", "central", "maximum", "central_statistic", "range_statistic", "central_formatted", "minimum_formatted", "maximum_formatted", "date", "observation_period", "period_status", "calculated_at", "data_as_of" ], "additionalProperties": false } ] }, "absolute_change": { "type": [ "number", "null" ] }, "change_percent": { "type": [ "number", "null" ] } }, "required": [ "billing_type_id", "billing_basis", "unit", "currency", "status", "partial", "current", "previous", "absolute_change", "change_percent" ], "additionalProperties": false, "oneOf": [ { "properties": { "status": { "enum": [ "comparable" ] }, "current": { "type": "object" }, "previous": { "type": "object" }, "absolute_change": { "type": "number" }, "change_percent": { "type": "number" } } }, { "properties": { "status": { "enum": [ "unavailable", "not_comparable" ] }, "absolute_change": { "type": "null" }, "change_percent": { "type": "null" } } } ] } }, "site_code": { "type": "string" }, "lang": { "type": "string" }, "currency": { "type": "string" }, "url": { "type": "string" }, "category": { "type": "object", "properties": { "catid": { "type": "integer", "minimum": 0 }, "name": { "type": "string" } }, "required": [ "catid", "name" ], "additionalProperties": false }, "location": { "type": "object", "properties": { "dd": { "type": "integer", "minimum": 0 }, "cc": { "type": "integer", "minimum": 0 }, "district": { "type": [ "string", "null" ] }, "municipality": { "type": [ "string", "null" ] } }, "required": [ "dd", "cc", "district", "municipality" ], "additionalProperties": false }, "request_url": { "type": "string" }, "request_context": { "type": "object", "properties": { "category_status": { "enum": [ "selected", "selection_required" ] }, "location_status": { "enum": [ "confirmation_required" ] } }, "required": [ "category_status", "location_status" ], "additionalProperties": false } }, "required": [ "status", "period", "comparisons", "site_code", "lang", "currency", "url", "category", "location", "request_url", "request_context" ], "additionalProperties": false } ] } }, "required": [ "status", "answer", "clarification", "candidates", "result" ], "additionalProperties": false, "oneOf": [ { "properties": { "status": { "enum": [ "needs_clarification" ] }, "result": { "type": "null" }, "clarification": { "type": "object" } } }, { "properties": { "status": { "enum": [ "available" ] }, "result": { "type": "object", "properties": { "status": { "enum": [ "available" ] } } }, "clarification": { "type": "null" } } }, { "properties": { "status": { "enum": [ "no_data" ] }, "result": { "type": "object", "properties": { "status": { "enum": [ "no_data" ] } } }, "clarification": { "type": "null" } } }, { "properties": { "status": { "enum": [ "comparable" ] }, "result": { "type": "object", "properties": { "status": { "enum": [ "comparable" ] } } }, "clarification": { "type": "null" } } }, { "properties": { "status": { "enum": [ "unavailable" ] }, "result": { "type": "object", "properties": { "status": { "enum": [ "unavailable" ] } } }, "clarification": { "type": "null" } } }, { "properties": { "status": { "enum": [ "not_comparable" ] }, "result": { "type": "object", "properties": { "status": { "enum": [ "not_comparable" ] } } }, "clarification": { "type": "null" } } } ] }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "search", "description": "Search public reference-price sources for a service/place topic in the endpoint market and its default language. For another market/language add site:pt lang:en to the query. A complete canonical HTTPS Fixando price-page URL is also accepted. Recognises named places; use location:\"Sintra\" or exact dd:11 cc:11 to disambiguate. Returns stable source IDs, descriptive titles and canonical citation URLs, not price facts or proof of availability. Use fetch for complete current evidence; withdrawn or empty sources produce a tool error. No unit conversion or historical-change inference.", "inputSchema": { "type": "object", "properties": { "query": { "type": "string", "maxLength": 500, "description": "Service/topic and optional place. Example: site:pt lang:en apartment cleaning location:\"Sintra\". Optional site, lang, dd, cc and quoted location filters each appear at most once. Omit location only for national source discovery." } }, "required": [ "query" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" } }, "required": [ "id", "title", "url" ], "additionalProperties": false } } }, "required": [ "results" ], "additionalProperties": false }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "fetch", "description": "Retrieve complete current price evidence for an opaque source id returned by search. Revalidates the source through the shared web price provider; no arbitrary URL reads. Preserves currency, separate billing types, statistics and actual temporal status. Cite url; metadata.price_result retains the unchanged get_prices evidence and separate optional request action/context. Empty or withdrawn sources produce an error, never a fabricated price. Does not submit a request.", "inputSchema": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 160, "description": "Opaque stable source id returned by search; do not construct or alter it." } }, "required": [ "id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "text": { "type": "string" }, "url": { "type": "string" }, "metadata": { "type": "object", "properties": { "price_result": { "type": "object", "properties": { "status": { "enum": [ "available", "no_data" ] }, "site_code": { "type": "string" }, "lang": { "type": "string" }, "currency": { "type": "string" }, "no_data_reason": { "enum": [ "insufficient_data", "billing_type_unavailable", null ] }, "url": { "type": "string" }, "category": { "type": "object", "properties": { "catid": { "type": "integer", "minimum": 0 }, "name": { "type": "string" } }, "required": [ "catid", "name" ], "additionalProperties": false }, "location": { "type": "object", "properties": { "dd": { "type": "integer", "minimum": 0 }, "cc": { "type": "integer", "minimum": 0 }, "district": { "type": [ "string", "null" ] }, "municipality": { "type": [ "string", "null" ] } }, "required": [ "dd", "cc", "district", "municipality" ], "additionalProperties": false }, "request_url": { "type": "string" }, "request_context": { "type": "object", "properties": { "category_status": { "enum": [ "selected", "selection_required" ] }, "location_status": { "enum": [ "confirmation_required" ] } }, "required": [ "category_status", "location_status" ], "additionalProperties": false }, "prices": { "type": "array", "items": { "type": "object", "properties": { "billing_type_id": { "type": "integer", "minimum": 0 }, "unit": { "type": "string" }, "billing_basis": { "type": [ "string", "null" ], "enum": [ "hour", "day", "word", "session", "square_metre", null ] }, "currency": { "type": "string" }, "minimum": { "type": "number", "minimum": 0 }, "central": { "type": "number", "minimum": 0 }, "maximum": { "type": "number", "minimum": 0 }, "central_statistic": { "enum": [ "median", "mean" ] }, "range_statistic": { "enum": [ "p10_p90", "legacy_range" ] }, "central_formatted": { "type": "string" }, "minimum_formatted": { "type": "string" }, "maximum_formatted": { "type": "string" }, "date": { "type": "string", "description": "Logical publication cutoff, YYYY-MM-DD; not an observation or calculation timestamp." }, "observation_period": { "type": "object", "properties": { "start": { "type": [ "string", "null" ], "description": "Inclusive eligibility boundary, YYYY-MM-DD." }, "end": { "type": [ "string", "null" ], "description": "Exclusive eligibility boundary, YYYY-MM-DD." }, "timezone": { "type": [ "string", "null" ], "description": "Recorded calculation timezone for the eligibility boundaries." } }, "required": [ "start", "end", "timezone" ], "additionalProperties": false }, "period_status": { "enum": [ "verified", "unavailable" ] }, "calculated_at": { "type": [ "string", "null" ], "description": "Actual selected calculation completion in UTC, RFC 3339; null if unknown." }, "data_as_of": { "type": [ "string", "null" ], "description": "Verified ingestion watermark, RFC 3339; currently unavailable (null)." } }, "required": [ "billing_type_id", "unit", "billing_basis", "currency", "minimum", "central", "maximum", "central_statistic", "range_statistic", "central_formatted", "minimum_formatted", "maximum_formatted", "date", "observation_period", "period_status", "calculated_at", "data_as_of" ], "additionalProperties": false } } }, "required": [ "status", "site_code", "lang", "currency", "no_data_reason", "url", "category", "location", "request_url", "request_context", "prices" ], "additionalProperties": false, "oneOf": [ { "properties": { "status": { "enum": [ "available" ] }, "no_data_reason": { "enum": [ null ] }, "prices": { "minItems": 1 } } }, { "properties": { "status": { "enum": [ "no_data" ] }, "no_data_reason": { "enum": [ "insufficient_data", "billing_type_unavailable" ] }, "prices": { "maxItems": 0 } } } ] } }, "required": [ "price_result" ], "additionalProperties": false } }, "required": [ "id", "title", "text", "url", "metadata" ], "additionalProperties": false }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "get_price_history", "description": "Read accepted historical reference prices based on quotes and eligible customer-reported prices and year-on-year changes for a known service/place. Supply a canonical HTTPS price-page url OR site_code with catid and optional dd/cc, plus year and period. year compares two completed calendar years; ytd compares completed months only with the same prior-year months and marks them partial. Use search tools first if IDs or the canonical page are unknown. Both periods use one common private geographic reference per billing type; a place name or current price does not prove local history. Each comparison preserves the current public price fields and actual recorded periods; missing, stale or incompatible evidence has no percentage. Changes use unrounded request medians, without currency/unit conversion or claims about inflation, causality or paid-price indexes. Calendar comparisons are available through MCP only. url identifies the canonical service/place price page, whose current cards and rolling charts do not display this calendar evidence. Only read comparisons with status=comparable as changes. No request is submitted.", "inputSchema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "description": "Absolute HTTPS Fixando price-page URL; never fetched remotely." }, "site_code": { "type": "string", "description": "Market code returned by get_markets, for example pt or de.", "maxLength": 3 }, "lang": { "type": "string", "description": "Supported market language; defaults to the market language.", "maxLength": 10 }, "catid": { "type": "integer", "minimum": 1, "description": "Root, parent or service category ID from search_price_categories." }, "dd": { "type": "integer", "minimum": 0, "description": "Top-level administrative region ID from search_price_locations; 0 means national. See location_type for district, canton, federal state or autonomous region/community/city." }, "cc": { "type": "integer", "minimum": 0, "description": "Local area ID from search_price_locations; requires its parent dd. Usually a municipality; Germany uses districts and urban districts." }, "billing_basis": { "type": "string", "maxLength": 20, "enum": [ "hour", "word", "session", "day", "square_metre" ], "description": "Optional established quantity basis. Use this OR billing_type_id. Total and negotiable are not quantity units." }, "billing_type_id": { "type": "integer", "enum": [ 1, 2, 5, 6, 7, 8, 9, 10, 11, 12, 13 ], "minimum": 1, "description": "Optional exact recorded billing_type_id, e.g. a fixed or negotiable type with billing_basis=null. Use this OR billing_basis." }, "year": { "type": "integer", "minimum": 2, "maximum": 2026, "description": "Comparison year; baseline is the preceding year. A complete-year comparison requires a past year." }, "period": { "type": "string", "enum": [ "year", "ytd" ], "maxLength": 4, "description": "year: whole completed calendar years. ytd: January through last completed month in each year; unavailable in January." }, "current_start": { "type": "string", "maxLength": 10, "description": "Optional explicit YYYY-MM-DD boundary. Supply all four boundaries together; they must match year/period exactly. Starts inclusive, ends exclusive in the recorded calculation timezone. Arbitrary or daily YTD windows are not supported." }, "current_end": { "type": "string", "maxLength": 10, "description": "Optional explicit YYYY-MM-DD boundary. Supply all four boundaries together; they must match year/period exactly. Starts inclusive, ends exclusive in the recorded calculation timezone. Arbitrary or daily YTD windows are not supported." }, "previous_start": { "type": "string", "maxLength": 10, "description": "Optional explicit YYYY-MM-DD boundary. Supply all four boundaries together; they must match year/period exactly. Starts inclusive, ends exclusive in the recorded calculation timezone. Arbitrary or daily YTD windows are not supported." }, "previous_end": { "type": "string", "maxLength": 10, "description": "Optional explicit YYYY-MM-DD boundary. Supply all four boundaries together; they must match year/period exactly. Starts inclusive, ends exclusive in the recorded calculation timezone. Arbitrary or daily YTD windows are not supported." } }, "required": [ "year", "period" ], "additionalProperties": false, "oneOf": [ { "required": [ "url" ], "not": { "anyOf": [ { "required": [ "catid" ] }, { "required": [ "dd" ] }, { "required": [ "cc" ] } ] } }, { "required": [ "site_code", "catid" ], "not": { "required": [ "url" ] } } ], "allOf": [ { "oneOf": [ { "not": { "anyOf": [ { "required": [ "current_start" ] }, { "required": [ "current_end" ] }, { "required": [ "previous_start" ] }, { "required": [ "previous_end" ] } ] } }, { "required": [ "current_start", "current_end", "previous_start", "previous_end" ] } ] }, { "not": { "required": [ "billing_basis", "billing_type_id" ] } } ] }, "outputSchema": { "type": "object", "properties": { "status": { "enum": [ "comparable", "unavailable", "not_comparable" ], "description": "comparable means at least one billing comparison is valid; inspect each comparison status before using its change." }, "period": { "type": "object", "properties": { "year": { "type": "integer", "minimum": 2 }, "kind": { "enum": [ "year", "ytd" ] }, "partial": { "type": "boolean" }, "completed_months": { "type": "integer", "minimum": 1, "maximum": 12 }, "current": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" }, "timezone": { "type": "string" } }, "required": [ "start", "end", "timezone" ], "additionalProperties": false }, "previous": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" }, "timezone": { "type": "string" } }, "required": [ "start", "end", "timezone" ], "additionalProperties": false } }, "required": [ "year", "kind", "partial", "completed_months", "current", "previous" ], "additionalProperties": false }, "comparisons": { "type": "array", "items": { "type": "object", "properties": { "billing_type_id": { "type": "integer", "minimum": 0 }, "billing_basis": { "type": [ "string", "null" ], "enum": [ "hour", "day", "word", "session", "square_metre", null ] }, "unit": { "type": "string" }, "currency": { "type": "string" }, "status": { "enum": [ "comparable", "unavailable", "not_comparable" ] }, "partial": { "type": "boolean" }, "current": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "billing_type_id": { "type": "integer", "minimum": 0 }, "unit": { "type": "string" }, "billing_basis": { "type": [ "string", "null" ], "enum": [ "hour", "day", "word", "session", "square_metre", null ] }, "currency": { "type": "string" }, "minimum": { "type": "number", "minimum": 0 }, "central": { "type": "number", "minimum": 0 }, "maximum": { "type": "number", "minimum": 0 }, "central_statistic": { "enum": [ "median", "mean" ] }, "range_statistic": { "enum": [ "p10_p90", "legacy_range" ] }, "central_formatted": { "type": "string" }, "minimum_formatted": { "type": "string" }, "maximum_formatted": { "type": "string" }, "date": { "type": "string", "description": "Logical publication cutoff, YYYY-MM-DD; not an observation or calculation timestamp." }, "observation_period": { "type": "object", "properties": { "start": { "type": [ "string", "null" ], "description": "Inclusive eligibility boundary, YYYY-MM-DD." }, "end": { "type": [ "string", "null" ], "description": "Exclusive eligibility boundary, YYYY-MM-DD." }, "timezone": { "type": [ "string", "null" ], "description": "Recorded calculation timezone for the eligibility boundaries." } }, "required": [ "start", "end", "timezone" ], "additionalProperties": false }, "period_status": { "enum": [ "verified", "unavailable" ] }, "calculated_at": { "type": [ "string", "null" ], "description": "Actual selected calculation completion in UTC, RFC 3339; null if unknown." }, "data_as_of": { "type": [ "string", "null" ], "description": "Verified ingestion watermark, RFC 3339; currently unavailable (null)." } }, "required": [ "billing_type_id", "unit", "billing_basis", "currency", "minimum", "central", "maximum", "central_statistic", "range_statistic", "central_formatted", "minimum_formatted", "maximum_formatted", "date", "observation_period", "period_status", "calculated_at", "data_as_of" ], "additionalProperties": false } ] }, "previous": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "billing_type_id": { "type": "integer", "minimum": 0 }, "unit": { "type": "string" }, "billing_basis": { "type": [ "string", "null" ], "enum": [ "hour", "day", "word", "session", "square_metre", null ] }, "currency": { "type": "string" }, "minimum": { "type": "number", "minimum": 0 }, "central": { "type": "number", "minimum": 0 }, "maximum": { "type": "number", "minimum": 0 }, "central_statistic": { "enum": [ "median", "mean" ] }, "range_statistic": { "enum": [ "p10_p90", "legacy_range" ] }, "central_formatted": { "type": "string" }, "minimum_formatted": { "type": "string" }, "maximum_formatted": { "type": "string" }, "date": { "type": "string", "description": "Logical publication cutoff, YYYY-MM-DD; not an observation or calculation timestamp." }, "observation_period": { "type": "object", "properties": { "start": { "type": [ "string", "null" ], "description": "Inclusive eligibility boundary, YYYY-MM-DD." }, "end": { "type": [ "string", "null" ], "description": "Exclusive eligibility boundary, YYYY-MM-DD." }, "timezone": { "type": [ "string", "null" ], "description": "Recorded calculation timezone for the eligibility boundaries." } }, "required": [ "start", "end", "timezone" ], "additionalProperties": false }, "period_status": { "enum": [ "verified", "unavailable" ] }, "calculated_at": { "type": [ "string", "null" ], "description": "Actual selected calculation completion in UTC, RFC 3339; null if unknown." }, "data_as_of": { "type": [ "string", "null" ], "description": "Verified ingestion watermark, RFC 3339; currently unavailable (null)." } }, "required": [ "billing_type_id", "unit", "billing_basis", "currency", "minimum", "central", "maximum", "central_statistic", "range_statistic", "central_formatted", "minimum_formatted", "maximum_formatted", "date", "observation_period", "period_status", "calculated_at", "data_as_of" ], "additionalProperties": false } ] }, "absolute_change": { "type": [ "number", "null" ] }, "change_percent": { "type": [ "number", "null" ] } }, "required": [ "billing_type_id", "billing_basis", "unit", "currency", "status", "partial", "current", "previous", "absolute_change", "change_percent" ], "additionalProperties": false, "oneOf": [ { "properties": { "status": { "enum": [ "comparable" ] }, "current": { "type": "object" }, "previous": { "type": "object" }, "absolute_change": { "type": "number" }, "change_percent": { "type": "number" } } }, { "properties": { "status": { "enum": [ "unavailable", "not_comparable" ] }, "absolute_change": { "type": "null" }, "change_percent": { "type": "null" } } } ] } }, "site_code": { "type": "string" }, "lang": { "type": "string" }, "currency": { "type": "string" }, "url": { "type": "string" }, "category": { "type": "object", "properties": { "catid": { "type": "integer", "minimum": 0 }, "name": { "type": "string" } }, "required": [ "catid", "name" ], "additionalProperties": false }, "location": { "type": "object", "properties": { "dd": { "type": "integer", "minimum": 0 }, "cc": { "type": "integer", "minimum": 0 }, "district": { "type": [ "string", "null" ] }, "municipality": { "type": [ "string", "null" ] } }, "required": [ "dd", "cc", "district", "municipality" ], "additionalProperties": false }, "request_url": { "type": "string" }, "request_context": { "type": "object", "properties": { "category_status": { "enum": [ "selected", "selection_required" ] }, "location_status": { "enum": [ "confirmation_required" ] } }, "required": [ "category_status", "location_status" ], "additionalProperties": false } }, "required": [ "status", "period", "comparisons", "site_code", "lang", "currency", "url", "category", "location", "request_url", "request_context" ], "additionalProperties": false }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } } ] ```