---
title: "Lookup Listings"
description: "lookup_listings tool status"
status: "preview"
canonical_url: "https://fairwayrent.ai/docs/agents/tools/lookup_listings"
last_updated: "2026-11-04"
related:
  - "/agents"
  - "/docs/agents/tools"
audience: "agents, developers"
---

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

```json example

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

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

```

## Input schema

| Field | Type | Notes |
| --- | --- | --- |
| `ids` | array | See JSON Schema |

```json example

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

```json example

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

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

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