> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brightplace.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage

> How to drive brightplace Connect and read its tool results.

## Get started

1. Add the remote MCP server URL in your AI client. See [Install](/install/claude)
   for client-specific steps.
2. If your client asks for authorization, complete the brightplace consent flow.
3. Ask the client to use brightplace Connect for an apartment search.
4. Review listing details, tour slots, and any tour request before acting on
   them.

## Typical flow

A renter conversation usually walks through the tools in this order:

1. `search_listings` — find listings matching objective criteria.
2. `get_listing` — read full detail, including brightplace grades, for a result.
3. `get_neighborhood_guide` / `get_financial_guide` — add neighborhood context
   and affordability detail for a listing.
4. `get_tour_availability` — check open tour slots.
5. `book_tour` — submit a tour request for a chosen slot.

Only `book_tour` performs a write. Review the renter name, email, phone,
listing, and slot before allowing it.

## Example workflow

A full renter conversation, with the tool each turn triggers:

1. **Search.** The renter asks:

   ```text theme={null}
   Use brightplace Connect to search for one-bedroom apartments in Brooklyn under $4,500 that are pet friendly and near the subway.
   ```

   The client calls `search_listings` and returns a list of matches.

2. **Inspect a result.** The renter asks to see one of them:

   ```text theme={null}
   Show me the full details for the second result.
   ```

   The client calls `get_listing` with that `listing_id`, including its
   brightplace grades.

3. **Add context.** The renter wants more than the snapshot:

   ```text theme={null}
   What's the neighborhood like, and is the rent affordable on a $120k salary?
   ```

   The client calls `get_neighborhood_guide` and `get_financial_guide` for the
   listing.

4. **Find a tour.** The renter asks:

   ```text theme={null}
   Are any tours available this weekend?
   ```

   The client calls `get_tour_availability` and lists open slots.

5. **Book it.** The renter picks a slot:

   ```text theme={null}
   Book the Saturday 11am tour. My name is Jordan Lee, jordan@example.com.
   ```

   The client calls `book_tour`. Confirm the renter name, email, phone,
   listing, and slot before allowing this write.

## Tool results

Tool responses use a consistent envelope:

```json theme={null}
{
  "ok": true,
  "data": {},
  "latency_ms": 42
}
```

Errors use the same envelope with an `error` object:

```json theme={null}
{
  "ok": false,
  "error": {
    "error_code": "VALIDATION_ERROR",
    "message": "Tool input failed validation.",
    "details": {}
  },
  "latency_ms": 2
}
```

See [Errors & Troubleshooting](/errors-troubleshooting) for the public error
set and how to handle each code.