AGENT DOCUMENTATIONPreview

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

lookup_listings

.md

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.

json

{
  "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.

json

{
  "listings": [
    {
      "id": "listing-id",
      "status": "not_found"
    }
  ]
}

Input schema#

FieldTypeNotes
idsarraySee JSON Schema
json

{
  "type": "object",
  "properties": {
    "ids": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "minItems": 1,
      "maxItems": 50
    }
  },
  "required": [
    "ids"
  ],
  "additionalProperties": false
}

Output schema#

FieldTypeNotes
listingsarraySee JSON Schema
json

{
  "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.

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. |

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.

json

{
  "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.