For AI agents: Preview: contract may change. The MCP endpoint is coming soon.
lookup_listings
The input and output schemas below are generated from the checked-in preview contract.
Purpose#
Refresh known listing IDs before you show them again.
When to use / when not to use#
Use to refresh IDs already known to your agent. Do not use it to discover new listings.
Access#
Preview: contract may change. Planned open access without an API key. The endpoint is coming soon.
Annotations#
readOnlyHint: true, idempotentHint: true, openWorldHint: false (preview).
Example request#
Illustrative preview only. This is not a callable endpoint.
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "lookup_listings",
"arguments": {
"ids": [
"listing-id"
]
}
}
}
Example response#
Illustrative shape only. Listing IDs, values, and URLs below are examples.
{
"listings": [
{
"id": "listing-id",
"status": "not_found"
}
]
}
Input schema#
| Field | Type | Notes |
|---|---|---|
ids | array | See JSON Schema |
{
"type": "object",
"properties": {
"ids": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"minItems": 1,
"maxItems": 50
}
},
"required": [
"ids"
],
"additionalProperties": false
}
Output schema#
| Field | Type | Notes |
|---|---|---|
listings | array | See JSON Schema |
{
"type": "object",
"properties": {
"listings": {
"type": "array",
"items": {
"oneOf": [
{
"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"
]
},
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"not_found",
"leased"
]
},
"checked_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"status"
],
"additionalProperties": false
}
]
}
}
},
"required": [
"listings"
]
}
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.
{
"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. |
If the service times out or cannot read its data, the result has isError: true and { "error": ... } with lookup_timeout or lookup_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.
{
"rate_limited": -31001,
"invalid_api_key": -31002,
"insufficient_scope": -31003
}
Notes for agents#
Check checked_at before describing availability. Link to the Fairway listing. Keep renter preferences and ranking in your own context.