# Multi-property groups (Maison staff) — tool reference

Generated from the OpenAPI document (`https://maison-labs.com/api/v1/openapi.json`). Field types are JSON Schema types; GET/DELETE inputs travel as path or query, other methods as a JSON body.

## `approve_property_discovery` — Approve property discovery

Provision the APPROVED candidates of an AWAITING_REVIEW run as child clients. Returns 202 `{ status: "PROVISIONING", sessionId, approved }` at once; the run continues in the background — poll `get_property_discovery` (PROVISIONING → COMPLETED / FAILED). Optionally re-scrapes the parent after narrowing its knowledge-base scope. 409 when the run is not awaiting review or nothing is approved. Maison-only or requires the `property-discovery` entitlement.

- REST: `POST https://maison-labs.com/api/v1/client/{clientId}/propertydiscovery/{sessionId}/approve`
- MCP tool / A2A skill: `approve_property_discovery`
- Needs: clients WRITE (global); client plan must include `property-discovery`

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes | Client (hotel) id; format uuid |
| `sessionId` | path | string | yes | Discovery session id; format uuid |
| `rescrapeParent` | body | boolean | no | Re-scrape the parent client after narrowing its KB scope to group-level pages (default false); default false |

## `attach_child_property` — Attach child property

Attach an existing client as a child property of a parent group. Maison-only. 409 when the relationship already exists or would create a cycle.

- REST: `POST https://maison-labs.com/api/v1/client/{clientId}/child`
- MCP tool / A2A skill: `attach_child_property`
- Needs: clients WRITE (global)

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes | Client (hotel) id; format uuid |
| `childClientId` | body | string | yes | Id of the client to attach as a child; format uuid |

## `decide_property_candidates` — Decide property candidates

Apply a bulk decision (APPROVED or REJECTED) to candidates. When `candidateIds` is omitted, sets all candidates in the session to the decision; otherwise updates only the specified candidates. Maison-only or requires the `property-discovery` entitlement.

- REST: `POST https://maison-labs.com/api/v1/client/{clientId}/propertydiscovery/{sessionId}/decisions`
- MCP tool / A2A skill: `decide_property_candidates`
- Needs: clients WRITE (global); client plan must include `property-discovery`

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes | Client (hotel) id; format uuid |
| `sessionId` | path | string | yes | Discovery session id; format uuid |
| `decision` | body | enum: APPROVED \| REJECTED | yes | Decision to apply |
| `candidateIds` | body | array of string | no | Specific candidates to update; omit to update all |

## `detach_child_property` — Detach child property

Detach a child property from its parent group. Maison-only. Destructive. The child client is not deleted — only the relationship is removed.

- REST: `DELETE https://maison-labs.com/api/v1/client/{clientId}/child/{childClientId}`
- MCP tool / A2A skill: `detach_child_property`
- Needs: clients WRITE (global)
- Destructive — confirm with the user first.

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes | Client (hotel) id; format uuid |
| `childClientId` | path | string | yes | Id of the child client to detach; format uuid |

## `get_client_hierarchy` — Get client hierarchy

Return the client's parent group and its list of child properties. Maison-only. Use `attach_child_property` / `detach_child_property` to change the hierarchy.

- REST: `GET https://maison-labs.com/api/v1/client/{clientId}/hierarchy`
- MCP tool / A2A skill: `get_client_hierarchy`
- Needs: clients READ (global)
- Read-only.

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes | Client (hotel) id; format uuid |

## `get_property_discovery` — Get property discovery

Return a discovery session. When `sessionId` is omitted returns the latest session; 404 when none. Provide `sessionId` to fetch a specific past run. Maison-only or requires the `property-discovery` entitlement.

- REST: `GET https://maison-labs.com/api/v1/client/{clientId}/propertydiscovery`
- MCP tool / A2A skill: `get_property_discovery`
- Needs: clients READ (global); client plan must include `property-discovery`
- Read-only.

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes | Client (hotel) id; format uuid |
| `sessionId` | query | string | no | Specific session id; omit for the latest run; format uuid |

## `list_child_candidates` — List child candidates

Search active clients that could be attached as children of a parent group. Requires global clients WRITE (same as attach). Maison-only.

- REST: `GET https://maison-labs.com/api/v1/client/{clientId}/children/candidates`
- MCP tool / A2A skill: `list_child_candidates`
- Needs: clients WRITE (global)
- Read-only.

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes | Client (hotel) id; format uuid |
| `search` | query | string | no | Case-insensitive name search (empty returns top results); default "" |
| `limit` | query | integer | no | Maximum candidates to return; default 20 |

## `list_children_feature_counts` — List children feature counts

For a group client: how many active child properties it has (`children`) and, per catalogue feature, how many of them are entitled to it (`items[].entitled`). Maison-only. Use to see which features are only partly rolled out before `grant_feature_to_children`.

- REST: `GET https://maison-labs.com/api/v1/client/{clientId}/children/features`
- MCP tool / A2A skill: `list_children_feature_counts`
- Needs: client-feature-management READ (global)
- Read-only.

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes | Client (hotel) id; format uuid |

## `start_property_discovery` — Start property discovery

Kick off automated nearby-property discovery for a multi-property group client. Returns the new discovery session (status DISCOVERING). 409 when a run is already active. Maison-only or requires the `property-discovery` entitlement.

- REST: `POST https://maison-labs.com/api/v1/client/{clientId}/propertydiscovery`
- MCP tool / A2A skill: `start_property_discovery`
- Needs: clients EXECUTE (global); client plan must include `property-discovery`

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes | Client (hotel) id; format uuid |

## `update_property_candidate` — Update property candidate

Edit one proposed property candidate: correct its name, location, URL prefixes or decision. Only the fields sent are changed. Maison-only or requires the `property-discovery` entitlement.

- REST: `PATCH https://maison-labs.com/api/v1/client/{clientId}/propertydiscovery/{sessionId}/candidate/{candidateId}`
- MCP tool / A2A skill: `update_property_candidate`
- Needs: clients WRITE (global); client plan must include `property-discovery`

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes | Client (hotel) id; format uuid |
| `sessionId` | path | string | yes | Discovery session id; format uuid |
| `candidateId` | path | string | yes | Candidate property id; format uuid |
| `name` | body | string | no | Corrected property name |
| `city` | body | string \| null | no |  |
| `country` | body | string \| null | no |  |
| `address` | body | string \| null | no |  |
| `urlPrefixes` | body | array of string | no | URL prefixes that belong to this property |
| `decision` | body | enum: PENDING \| APPROVED \| REJECTED | no | Review decision for this candidate |