Skip to main content
Glama

Search homes

search_homes
Read-onlyIdempotent

Use this when the user wants to find homes for sale or to rent in the UK. Give a place (town, area, street or postcode) and any budget, bedrooms or type they mention. Put what they want from the home or area in their own words in wishes (for example "a garden", "walk to a station", "good primary schools nearby", "within 45 minutes of King's Cross"); homes are then ranked by fit, each with a 0-100 match score and the evidence behind it (station and school distances, advertised features). Put a physical feature they insist on and an advert would state ("garage", "annexe") in must_haves; anything about lifestyle or the area ("near the sea", "wild swimming", "good schools") always goes in wishes. Returns up to 10 homes with price, bedrooms, agent and a link, and for each home what is nearby: the nearest primary and secondary schools with their Ofsted grade, station, park, GP surgery, supermarket and broadband.

Input Schema

NameRequiredDescriptionDefault
sortNo
limitNoDefault 6.
placeYesOne UK place: a town, city, district, county, region, national park, National Landscape, named coast, island or postcode, e.g. "Harrogate", "Dorset", "the Lake District", "the South West", "the south coast", "Jersey", "LS6", or a street with its town, e.g. "Mill Road, Cambridge". Each is searched as one whole area; a street shows the homes on it first, then those near it. "near Totnes" takes in about 3 miles around it.
wishesNoWhat the user wants, in their words. Homes are ranked by how well they match.
max_bedsNo
min_bedsNo
max_priceNoPounds. For rent, per calendar month.
min_priceNoPounds. For rent, per calendar month.
must_havesNoA physical feature the advert must state word for word, e.g. "garage". Never lifestyle or area wishes: those go in wishes.
buy_or_rentNoDefault buy.
property_typeNo

Output Schema

NameRequiredDescriptionDefault
noteNo
homesYes
placeNo
townsNoFor a coast or national park: the towns searched, each with its search on MyPorta.
more_urlNoThe same search on MyPorta, with every result.
place_foundNoFalse when MyPorta did not recognise the place; no homes are returned then.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed10 schema fields changed
    • changedInput schema / properties / place / description
      Previous value: -"One UK place: a town, city, district, county, region, national park, National Landscape, named coast, island or postcode, e.g. \"Harrogate\", \"Dorset\", \"the Lake District\", \"the South West\", \"the south coast\", \"Jersey\", \"LS6\". Each is searched as one whole area. \"near Totnes\" takes in about 3 miles around it."New value: +"One UK place: a town, city, district, county, region, national park, National Landscape, named coast, island or postcode, e.g. \"Harrogate\", \"Dorset\", \"the Lake District\", \"the South West\", \"the south coast\", \"Jersey\", \"LS6\", or a street with its town, e.g. \"Mill Road, Cambridge\". Each is searched as one whole area; a street shows the homes on it first, then those near it. \"near Totnes\" takes in about 3 miles around it."
    • addedOutput schema / properties / homes / items / properties / also_listed_by
      Added value: +{
      +  "description": "Other agents advertising the same home (same address, price and bedrooms), shown once.",
      +  "items": {
      +    "properties": {
      +      "agent": {
      +        "type": "string"
      +      },
      +      "url": {
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "agent",
      +      "url"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
    • changedOutput schema / properties / homes / items / properties / local / description
      Previous value: -"What is near the home, measured by MyPorta: the nearest primary and secondary schools with their Ofsted grade, the nearest station, bus stop, park, GP surgery, pharmacy, supermarket and place of worship, and broadband. Distances are straight-line."New value: +"What is near the home, measured by MyPorta: the nearest primary and secondary schools with their Ofsted grade when known, the nearest station, bus stop, park, GP surgery, pharmacy, supermarket and place of worship, and broadband. Distances are straight-line, in miles."
    • addedOutput schema / properties / homes / items / properties / local_note
      Added value: +{
      +  "description": "Present when the distances in `local` were measured from the home's area, not its exact address.",
      +  "type": "string"
      +}
    • addedOutput schema / properties / homes / items / properties / lookalike_note
      Added value: +{
      +  "description": "When another home in these results has the same address line: what tells this one apart.",
      +  "type": "string"
      +}
    • addedOutput schema / properties / homes / items / properties / on_street
      Added value: +{
      +  "description": "Street searches only: true for a home on the street asked for, false for one near it (listed after them).",
      +  "type": "boolean"
      +}
    • changedOutput schema / properties / homes / items / properties / reasons / description
      Previous value: -"Evidence for the match, e.g. \"Station 0.1 miles\", \"Garden · advertised\"."New value: +"Evidence for the match, worded and measured as in `local`, e.g. \"Nearest primary school: Western Primary School, 0.1 miles (Ofsted: Outstanding)\", \"Garden · advertised\". A line ending \"area-level estimate\" was measured from the home's area."
    • addedOutput schema / properties / homes / items / properties / status
      Added value: +{
      +  "description": "\"Available\", or what the agent says has happened: \"Sold STC\", \"Under offer\", \"Let agreed\". Homes no longer available are still shown, after the available ones.",
      +  "type": "string"
      +}
    • addedOutput schema / properties / homes / items / properties / summary
      Added value: +{
      +  "description": "The opening of the agent's advert, in the agent's words (compare_homes).",
      +  "type": "string"
      +}
    • addedOutput schema / properties / homes / items / properties / type / description
      Added value: +"In plain words: house, detached house, flat, studio flat, maisonette, bungalow, land, park home or room. On a search for one type, the home is that type."
  2. Changed1 schema field changed
    • changedOutput schema / properties / homes / items / properties / local / description
      Previous value: -"What is near the home, measured by MyPorta: the nearest primary and secondary schools with their Ofsted grade, the nearest station, park, GP surgery, supermarket and place of worship, and broadband. Distances are straight-line."New value: +"What is near the home, measured by MyPorta: the nearest primary and secondary schools with their Ofsted grade, the nearest station, bus stop, park, GP surgery, pharmacy, supermarket and place of worship, and broadband. Distances are straight-line."
  3. First observed

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already declare this is a safe, idempotent, non-destructive read; the description goes further by disclosing the ranking mechanism, the 0-100 match score with supporting evidence, the 10-result ceiling, and the amenity payload per home. It says nothing about rate limits or failure behaviour for an unrecognised place, which is the only meaningful omission.

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?

Three dense sentences front-load the trigger, then the input rules, then the return shape — a logical order with no filler. The long amenity enumeration is justified because it tells the agent what evidence it can cite back to the user.

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

Completeness4/5

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

For an 11-parameter, read-only search tool with an output schema, the description is largely self-sufficient: it explains input partitioning, ranking, result count and evidence fields. The return-value recap is partly redundant given the output schema exists, but nothing needed to call it correctly is missing.

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 64%, and the description compensates for the gaps: it defines the semantic boundary between `wishes` (lifestyle/area, ranked softly) and `must_haves` (verbatim advert features), and explains that ranking derives from wishes. Parameters like `sort`, `limit` and `property_type` get no mention, leaving the remaining coverage gap unfilled.

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

Purpose4/5

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

States a specific verb and resource with geography ('find homes for sale or to rent in the UK') and adds the outcome ('homes are then ranked by fit, each with a 0-100 match score'). It never names compare_homes, get_area_guide or get_home, so the distinction from siblings is inferable (single search vs. single home vs. comparison) rather than explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

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

Opens with an explicit trigger ('Use this when the user wants to find homes for sale or to rent') and then gives routing rules for inputs, including the tricky split between `wishes` and `must_haves` with worked examples. It stops short of stating when to use a sibling instead, so it is clear context without exclusions.

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