AGENT DOCUMENTATIONPreview

For AI agents: Preview: contract may change. The MCP endpoint is coming soon.

search_listings

.md

Start with the renter's housing request in query. Fairway interprets supported criteria as filters and reports what it applied. The worked examples below are illustrative; the input and output schemas follow them and come from the checked-in preview contract.

Purpose#

Find rental listings in SF Bay Area from the renter's housing request.

When to use / when not to use#

Use for a new rental search. Send the housing request, not personal details.

Access#

Preview: contract may change. Planned open access without an API key. The endpoint is coming soon.

Annotations#

readOnlyHint: true, openWorldHint: false (preview).

Example request#

Illustrative preview only. This is not a callable endpoint.

json

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "search_listings",
    "arguments": {
      "query": "2BR near BART under $3,000, dog friendly, on a quiet street"
    }
  }
}

Pin a value with filters when it must override what Fairway reads from the query:

json

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "search_listings",
    "arguments": {
      "query": "2BR near BART under $3,000, dog friendly",
      "filters": {
        "rent_max": 280000
      }
    }
  }
}

Example response#

Illustrative shape only. Listing IDs, values, and URLs below are examples.

json

{
  "applied_filters": {
    "beds_min": 2,
    "rent_max": 300000,
    "pets": "dog"
  },
  "not_applied": [
    "quiet street"
  ],
  "listings": [
    {
      "id": "example-listing-1",
      "status": "available",
      "property": {
        "name": "Example home",
        "address": "Example address"
      },
      "rent_min": 295000,
      "beds_min": 2,
      "checked_at": "2026-10-30T00:00:00Z",
      "listing_url": "https://fairwayrent.ai/property/ca/menlo-park/example",
      "share_url": "https://fairwayrent.ai/property/ca/menlo-park/example"
    }
  ],
  "pagination": {
    "has_next_page": false,
    "limit": 25
  },
  "checked_at_range": {
    "oldest": "2026-10-30T00:00:00Z",
    "newest": "2026-10-30T00:00:00Z"
  },
  "map_url": "https://www.fairwayrent.ai/map?l=example-listing-1"
}

Input schema#

FieldTypeNotes
querystringThe renter's housing request in their own words, such as a two-bedroom near transit under their stated budget that allows dogs. Fairway turns it into filters. Send the housing request, not personal details.
filtersobjectOptional structured fields. Any field here overrides what Fairway took from the query.
bboxobjectA map box in degrees. If neither filters.area nor query names a metro, Fairway searches the metro that contains the center of the box.
nearobjectA point and radius in meters. For now Fairway searches the box that contains this circle. If neither filters.area nor query names a metro, Fairway searches the metro that contains the point.
paginationobjectSee JSON Schema
json

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "description": "The renter's housing request in their own words, such as a two-bedroom near transit under their stated budget that allows dogs. Fairway turns it into filters. Send the housing request, not personal details.",
      "maxLength": 1000
    },
    "filters": {
      "type": "object",
      "description": "Optional structured fields. Any field here overrides what Fairway took from the query.",
      "properties": {
        "beds_min": {
          "type": "number",
          "minimum": 0,
          "maximum": 20
        },
        "beds_max": {
          "type": "number",
          "minimum": 0,
          "maximum": 20
        },
        "baths_min": {
          "type": "number",
          "minimum": 0,
          "maximum": 20
        },
        "rent_min": {
          "type": "integer",
          "minimum": 0,
          "description": "USD cents",
          "maximum": 10000000
        },
        "rent_max": {
          "type": "integer",
          "minimum": 0,
          "description": "USD cents",
          "maximum": 10000000
        },
        "pets": {
          "type": "string",
          "enum": [
            "dog",
            "cat",
            "none"
          ]
        },
        "move_in_by": {
          "type": "string",
          "format": "date"
        },
        "amenities": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80
          },
          "maxItems": 32
        },
        "area": {
          "type": "string",
          "description": "City, neighborhood, or area to search.",
          "minLength": 1,
          "maxLength": 200
        }
      },
      "additionalProperties": false
    },
    "bbox": {
      "type": "object",
      "description": "A map box in degrees. If neither filters.area nor query names a metro, Fairway searches the metro that contains the center of the box.",
      "properties": {
        "north": {
          "type": "number",
          "minimum": -90,
          "maximum": 90
        },
        "south": {
          "type": "number",
          "minimum": -90,
          "maximum": 90
        },
        "east": {
          "type": "number",
          "minimum": -180,
          "maximum": 180
        },
        "west": {
          "type": "number",
          "minimum": -180,
          "maximum": 180
        }
      },
      "required": [
        "north",
        "south",
        "east",
        "west"
      ],
      "additionalProperties": false
    },
    "near": {
      "type": "object",
      "description": "A point and radius in meters. For now Fairway searches the box that contains this circle. If neither filters.area nor query names a metro, Fairway searches the metro that contains the point.",
      "properties": {
        "lat": {
          "type": "number",
          "minimum": -90,
          "maximum": 90
        },
        "lng": {
          "type": "number",
          "minimum": -180,
          "maximum": 180
        },
        "radius_m": {
          "type": "number",
          "exclusiveMinimum": 0,
          "maximum": 50000
        }
      },
      "required": [
        "lat",
        "lng",
        "radius_m"
      ],
      "additionalProperties": false
    },
    "pagination": {
      "type": "object",
      "properties": {
        "cursor": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "limit": {
          "type": "integer",
          "minimum": 1,
          "maximum": 25,
          "default": 25,
          "description": "Listings per page. Calls without an API key get at most 5."
        }
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false,
  "required": [
    "query"
  ]
}

Output schema#

FieldTypeNotes
applied_filtersobjectFilters Fairway applied from the query and any explicit filters overrides.
not_appliedarrayParts of the query that did not become a filter, such as quiet street. The agent may use these for its own ranking.
listingsarraySee JSON Schema
paginationobjectSee JSON Schema
checked_at_rangeobjectSee JSON Schema
map_urlstringSee JSON Schema
json

{
  "type": "object",
  "properties": {
    "applied_filters": {
      "type": "object",
      "description": "Filters Fairway applied from the query and any explicit filters overrides.",
      "properties": {
        "beds_min": {
          "type": "number",
          "minimum": 0
        },
        "beds_max": {
          "type": "number",
          "minimum": 0
        },
        "baths_min": {
          "type": "number",
          "minimum": 0
        },
        "rent_min": {
          "type": "integer",
          "minimum": 0,
          "description": "USD cents"
        },
        "rent_max": {
          "type": "integer",
          "minimum": 0,
          "description": "USD cents"
        },
        "pets": {
          "type": "string",
          "enum": [
            "dog",
            "cat",
            "none"
          ]
        },
        "move_in_by": {
          "type": "string",
          "format": "date"
        },
        "amenities": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "area": {
          "type": "string",
          "description": "City, neighborhood, or area to search."
        }
      },
      "additionalProperties": false
    },
    "not_applied": {
      "type": "array",
      "description": "Parts of the query that did not become a filter, such as quiet street. The agent may use these for its own ranking.",
      "items": {
        "type": "string"
      }
    },
    "listings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "const": "available"
          },
          "property": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "address": {
                "type": "string"
              },
              "coordinates": {
                "type": "object",
                "properties": {
                  "lat": {
                    "type": "number"
                  },
                  "lng": {
                    "type": "number"
                  }
                }
              }
            }
          },
          "rent_min": {
            "type": "integer",
            "minimum": 0,
            "description": "USD cents"
          },
          "rent_max": {
            "type": "integer",
            "minimum": 0,
            "description": "USD cents"
          },
          "beds_min": {
            "type": "number"
          },
          "checked_at": {
            "type": "string",
            "format": "date-time"
          },
          "listing_url": {
            "type": "string",
            "format": "uri"
          },
          "share_url": {
            "type": "string",
            "format": "uri"
          }
        },
        "required": [
          "id",
          "status",
          "property",
          "checked_at",
          "listing_url",
          "share_url"
        ]
      }
    },
    "pagination": {
      "type": "object",
      "properties": {
        "cursor": {
          "type": "string"
        },
        "has_next_page": {
          "type": "boolean"
        },
        "total_count": {
          "type": "integer",
          "minimum": 0,
          "description": "Estimate, not exact"
        },
        "limit": {
          "type": "integer",
          "minimum": 1,
          "maximum": 25,
          "description": "Listings per page for this call."
        }
      },
      "required": [
        "has_next_page",
        "limit"
      ]
    },
    "checked_at_range": {
      "type": "object",
      "properties": {
        "oldest": {
          "type": "string",
          "format": "date-time"
        },
        "newest": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "map_url": {
      "type": "string",
      "format": "uri"
    }
  },
  "required": [
    "applied_filters",
    "not_applied",
    "listings",
    "pagination",
    "checked_at_range",
    "map_url"
  ]
}

Errors#

These codes come from the MCP service in development. They can change before launch.

A request error is a tool result with isError: true. Its structuredContent has the HTTP status, a code, and the path of the field at fault. The same JSON is also the text content of the result.

json

{
  "status": 400,
  "code": "UNKNOWN_FIELD",
  "path": "filters.radius"
}

| Code | Path | Meaning |

| --- | --- | --- |

| UNKNOWN_FIELD | The unknown field | The request has a field that the schema does not list. Remove it. |

| MALFORMED_REQUEST | The invalid field | A field has the wrong type or is out of range. Fix the value. |

| UNKNOWN_AMENITY | filters.amenities.<index> | The amenity is not in the filter vocabulary. Remove it or put it in query. |

| CONFLICTING_CRITERIA | near or a filter | The request sends both bbox and near, or a minimum is above its maximum. |

| AREA_REQUIRED | filters.area | Neither the request nor query names an area. Send filters.area, bbox, or near. |

| AREA_UNRESOLVED | filters.area | Fairway cannot find the named area. Ask the renter for a city or neighborhood. |

| UNSUPPORTED_METRO | filters.area, bbox, or near | The area is outside the metros that Fairway serves. |

| METRO_NOT_ADMITTED | filters.area, bbox, or near | Fairway serves the metro, but agent search does not cover it yet. |

| NO_SEARCH_SCOPE | scope | Fairway could not build a search area from the request. |

| UNSUPPORTED_CRITERION | The criterion | Search cannot apply this criterion. Remove it or put it in query. |

| SEARCH_TOO_BROAD | filters | The search matches too much inventory. Add an area or narrower filters. |

| CURSOR_EXPIRED | pagination.cursor | The cursor is no longer valid. Run the search again without cursor. |

If the service times out or cannot read its data, the result has isError: true and { "error": ... } with search_timeout or search_unavailable. Retry later with the same request.

Rate limits and API key problems are not tool results. They are JSON-RPC errors. error.data.error names the problem, and error.code is the number below for that name. A rate-limit error also has error.data.retry_after in seconds and a Retry-After header. Wait that long before you retry.

json

{
  "rate_limited": -31001,
  "invalid_api_key": -31002,
  "insufficient_scope": -31003
}

Notes for agents#

Send the renter’s housing request as they said it, without personal details. Use filters only to pin a value. Rank on not_applied and your own context. Check checked_at before describing availability and link to the Fairway listing.