Skip to main content
Glama

flatin.pt — Portuguese homes: taxes, construction, new-builds

Search new-build projects in Portugal

search_newbuilds
Read-onlyIdempotent

Use this when the person wants to find published new-build projects (empreendimentos) in Portugal on flatin.pt. Do not use it for one project's details (get_newbuild with its slug) or for how much is being built (construction_barometer). With typology, the budget applies to those typologies' prices; projects without a published price drop out when a budget is given. Pass next_offset as offset for the next page. A misspelt filter is refused, not ignored. Prices are as checked on developers' pages or agency listings, dated.

Example tool call

This call uses example arguments supplied in the tool’s input schema.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "typology": [
        "T2"
      ],
      "price_max": 400000,
      "municipality": "Porto"
    },
    "name": "search_newbuilds"
  }
}

Input Schema

NameRequiredDescriptionDefault
sortNoprice: cheapest first; delivery: soonest first; new: recently added first. Projects with a price always come before those withoutprice
limitNoResults per call
stageNoConstruction stage: planned, licensed, building (under construction), selling (on sale), delivered (completed)
offsetNoSkip this many results: pass next_offset from the previous answer
parishNoParish (freguesia) name. Exact name, accents optional
on_saleNoOnly projects with a published price
languageNoLanguage of the page URLs and of the labels (stage, typology, nearby places); the text summary shows the typology labels in it. Field names stay English. uk is accepted as ua.en
typologyNoBedrooms: T0 studio … T5 (five or more). Any of the listed matches
price_maxNoBudget upper bound in euros, e.g. 350000. With typology, the budget applies to those typologies' prices. Projects with no published price are left out when a budget is given
price_minNoBudget lower bound in euros
delivery_byNoCompleted, or promised for this year or earlier (overdue promises included), e.g. 2027; at most five years back. Projects with no announced date are left out
energy_classNoEnergy certificate class of at least one unit, as stated by the source. Often not published: filter only when asked
municipalityNoCity / municipality (concelho): name, slug or four-digit code, e.g. Porto, Lisboa, Vila Nova de Gaia, Matosinhos, 1312. English names (Lisbon) and accents-free spelling are understood; an ambiguous name (Lagoa) is refused with candidates

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed19 schema fields changed
    • changedInput schema / properties / delivery_by / description
      Previous value: -"Completed, or promised for this year or earlier (overdue promises included), e.g. 2027. Projects with no announced date are left out"New value: +"Completed, or promised for this year or earlier (overdue promises included), e.g. 2027; at most five years back. Projects with no announced date are left out"
    • addedInput schema / properties / delivery_by / maximum
      Added value: +2100
    • addedInput schema / properties / language / default
      Added value: +"en"
    • changedInput schema / properties / language / description
      Previous value: -"Language of the page URLs and labels: pt, en, ru, ua, de, fr, nl. Default en"New value: +"Language of the page URLs and of the labels (stage, typology, nearby places); the text summary shows the typology labels in it. Field names stay English. uk is accepted as ua."
    • changedInput schema / properties / language / enum
      Previous value: -[
      -  "pt",
      -  "en",
      -  "ru",
      -  "ua",
      -  "de",
      -  "fr",
      -  "nl"
      -]New value: +[
      +  "pt",
      +  "en",
      +  "ru",
      +  "ua",
      +  "de",
      +  "fr",
      +  "nl",
      +  "uk"
      +]
    • addedInput schema / properties / limit / default
      Added value: +10
    • changedInput schema / properties / limit / description
      Previous value: -"Results per call, default 10"New value: +"Results per call"
    • addedInput schema / properties / municipality / examples
      Added value: +[
      +  "Porto",
      +  "Vila Nova de Gaia",
      +  "1312"
      +]
    • addedInput schema / properties / offset / default
      Added value: +0
    • changedInput schema / properties / offset / description
      Previous value: -"Skip this many results (use next_offset)"New value: +"Skip this many results: pass next_offset from the previous answer"
    • addedInput schema / properties / on_sale / default
      Added value: +false
    • changedInput schema / properties / on_sale / description
      Previous value: -"Only projects with a published price. Default false"New value: +"Only projects with a published price"
    • changedInput schema / properties / parish / description
      Previous value: -"Parish (freguesia) name, e.g. Paranhos. Exact name, accents optional"New value: +"Parish (freguesia) name. Exact name, accents optional"
    • addedInput schema / properties / parish / examples
      Added value: +[
      +  "Paranhos"
      +]
    • addedInput schema / properties / price_max / maximum
      Added value: +999999999
    • addedInput schema / properties / price_min / maximum
      Added value: +999999999
    • addedInput schema / properties / sort / default
      Added value: +"price"
    • changedInput schema / properties / sort / description
      Previous value: -"price (cheapest first, default), name, delivery (soonest first), new (recently added first). Projects with a price always come before those without"New value: +"price: cheapest first; delivery: soonest first; new: recently added first. Projects with a price always come before those without"
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "anyOf": [
      +    {
      +      "properties": {
      +        "attribution": {
      +          "type": "object"
      +        },
      +        "catalog_url": {
      +          "description": "Absolute URL",
      +          "type": "string"
      +        },
      +        "language": {
      +          "type": "string"
      +        },
      +        "limit": {
      +          "type": "integer"
      +        },
      +        "next_offset": {
      +          "description": "Pass as offset for the next page; null = last",
      +          "type": [
      +            "integer",
      +            "null"
      +          ]
      +        },
      +        "offset": {
      +          "type": "integer"
      +        },
      +        "results": {
      +          "items": {
      +            "type": "object"
      +          },
      +          "type": "array"
      +        },
      +        "total": {
      +          "type": "integer"
      +        }
      +      },
      +      "required": [
      +        "total",
      +        "offset",
      +        "limit",
      +        "next_offset",
      +        "language",
      +        "catalog_url",
      +        "results",
      +        "attribution"
      +      ],
      +      "type": "object"
      +    },
      +    {
      +      "properties": {
      +        "candidates": {
      +          "items": {
      +            "type": "object"
      +          },
      +          "type": "array"
      +        },
      +        "error": {
      +          "type": "string"
      +        },
      +        "field": {
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "message": {
      +          "type": "string"
      +        },
      +        "suggestions": {
      +          "items": {
      +            "type": "object"
      +          },
      +          "type": "array"
      +        }
      +      },
      +      "required": [
      +        "error",
      +        "message"
      +      ],
      +      "type": "object"
      +    }
      +  ],
      +  "description": "Success, or a refusal with an error code. Units: *_cents euro cents, *_eur euros, *_eur_m2 euros per m², *_pct and percent in percent.",
      +  "type": "object"
      +}
  2. Added

TDQS

A4.7/5.0
Behavior4/5

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

Annotations already declare this a safe, idempotent, closed-world read, so the bar is lower. The description still adds real behavioral context the annotations don't: misspelt filters are refused rather than ignored, projects without a published price silently drop out when a budget is given, and prices are dated from developers/agency sources. It doesn't discuss result cardinality beyond pagination, but the output schema covers return shape.

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

Conciseness5/5

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

Five short sentences, front-loaded with the routing decision and exclusions before any filtering nuance. Every sentence carries distinct information — no restatement of the name or title.

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

Completeness5/5

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

For a 13-parameter search with zero required params, an output schema and full annotations, the description supplies exactly the missing layer: sibling routing, the price/typology interaction, typo-refusal behavior, and pagination handoff. An agent has enough to call it correctly on the first attempt.

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

Parameters4/5

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

Schema coverage is 100%, so baseline would be 3; the description earns above that by explaining a genuine cross-parameter interaction ('with typology, the budget applies to those typologies' prices') and the silent exclusion it triggers, which the schema only states per-property. It also bridges the pagination contract by telling the agent to pass next_offset as offset, linking the request to the response.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('find published new-build projects (empreendimentos) in Portugal on flatin.pt') and immediately pins down scope against the two nearest siblings. An agent can distinguish this from get_newbuild and construction_barometer 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.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use clause plus explicit when-not-to-use with the named alternatives and the condition that selects each ('one project's details' → get_newbuild with its slug; 'how much is being built' → construction_barometer). Nothing is left to inference.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources