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

# get_financial_guide

> Answer affordability, budgeting, and cost-of-living questions.

`get_financial_guide` answers affordability, budgeting, and cost-of-living
questions using a curated financial reference library — cost of living, rent
benchmarks by metro, taxes, median income, utilities, and renters insurance. It
may take several seconds to return.

## When to use it

Use it for questions like "what can I expect to pay?", "what's a reasonable
budget for this city?", "is this rent affordable?", "what income do I need?",
"how much should I budget for utilities?", or "how does cost of living compare
to another city?". Prefer it over a general web search for these questions.

Pass a `query` with the renter's question and/or a `listing_id` to frame the
answer around that listing's city and rent. **At least one of `query` or
`listing_id` is required.** When only `listing_id` is given, a general
affordability overview for its city is returned.

Requests that tie affordability to a protected class are blocked by Fair
Housing guardrails and return `FAIR_HOUSING_VIOLATION`.

## Input

```json theme={null}
{
  "listing_id": "listing-record-id",
  "query": "what income do I need to afford this?"
}
```

| Field        | Type   | Required    | Notes                                                                                                                  |
| ------------ | ------ | ----------- | ---------------------------------------------------------------------------------------------------------------------- |
| `listing_id` | string | Conditional | A listing snapshot id from `search_listings`. When provided, the answer is framed around that listing's city and rent. |
| `query`      | string | Conditional | The financial question to answer. Required when no `listing_id` is given.                                              |

## Output

```json theme={null}
{
  "status": "available",
  "listing_id": "listing-record-id",
  "query": "what income do I need to afford this? (listing in Austin, TX for a renter paying $2200/mo)",
  "city": "Austin",
  "state": "TX",
  "message": null,
  "content": "A common guideline is spending no more than 30% of gross income on rent...",
  "source": "Curated financial reference library"
}
```

| Field        | Type           | Notes                                                                       |
| ------------ | -------------- | --------------------------------------------------------------------------- |
| `status`     | string         | `available` when reference data matched; `no_data` when nothing matched.    |
| `listing_id` | string \| null | Echoes the requested id, or `null` when only a `query` was given.           |
| `query`      | string         | The resolved query, including any city/rent context added from the listing. |
| `city`       | string \| null | The listing's city when a `listing_id` framed the answer; otherwise `null`. |
| `state`      | string \| null | The listing's state, if known.                                              |
| `message`    | string \| null | Set when `status` is `no_data`, explaining why; otherwise `null`.           |
| `content`    | string \| null | The financial digest when `available`; otherwise `null`.                    |
| `source`     | string \| null | Provenance line for the content; `null` when no data matched.               |

When no reference data matches, the tool returns a successful response with
`status: "no_data"` and a human-readable `message` rather than an error.
Unknown listing ids return `LISTING_NOT_FOUND`.