Agent Skills / maison-hierarchy

Install this skill alone, or read it below. Raw file: SKILL.md · references/tools.md

bash

npx skills add https://docs.maison-labs.com --skill maison-hierarchy

Maison — Multi-property groups (Maison staff)

Manage hotel groups: read a hotel's parent and children, find attachable candidates, attach or detach child properties, and run property discovery on a group website (start, read, edit candidates, approve/reject in bulk, approve to provision). Use when onboarding a brand or group site with several hotels, or when a property must move between groups.

Part of the Maison public API. Read the maison-public-api skill first for authentication, discovery and transport details (https://docs.maison-labs.com/skills/maison-public-api/SKILL.md).

When to use

A group website was onboarded with multiProperty: true — start_property_discovery then review candidates.
Link an existing hotel under a group — attach_child_property.

Before you start

Send x-api-key: <key> on every call; the key only reaches /api/v1.
GET /api/v1/tools (or MCP tools/list) returns the tools THIS key may run — if a tool below is missing there, you lack a grant; do not retry it.
Client-scoped tools take clientId (a hotel id). whoami lists the ids you can act on.

Tools

Tool	What it does	REST	Needs
`approve_property_discovery`	Provision the APPROVED candidates of an AWAITING_REVIEW run as child clients.	`POST /api/v1/client/{clientId}/propertydiscovery/{sessionId}/approve`	clients WRITE (global); plan: `property-discovery`
`attach_child_property`	Attach an existing client as a child property of a parent group.	`POST /api/v1/client/{clientId}/child`	clients WRITE (global)
`decide_property_candidates`	Apply a bulk decision (APPROVED or REJECTED) to candidates.	`POST /api/v1/client/{clientId}/propertydiscovery/{sessionId}/decisions`	clients WRITE (global); plan: `property-discovery`
`detach_child_property`	Detach a child property from its parent group.	`DELETE /api/v1/client/{clientId}/child/{childClientId}`	clients WRITE (global); destructive
`get_client_hierarchy`	Return the client's parent group and its list of child properties.	`GET /api/v1/client/{clientId}/hierarchy`	clients READ (global); read-only
`get_property_discovery`	Return a discovery session.	`GET /api/v1/client/{clientId}/propertydiscovery`	clients READ (global); plan: `property-discovery`; read-only
`list_child_candidates`	Search active clients that could be attached as children of a parent group.	`GET /api/v1/client/{clientId}/children/candidates`	clients WRITE (global); read-only
`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`).	`GET /api/v1/client/{clientId}/children/features`	client-feature-management READ (global); read-only
`start_property_discovery`	Kick off automated nearby-property discovery for a multi-property group client.	`POST /api/v1/client/{clientId}/propertydiscovery`	clients EXECUTE (global); plan: `property-discovery`
`update_property_candidate`	Edit one proposed property candidate: correct its name, location, URL prefixes or decision.	`PATCH /api/v1/client/{clientId}/propertydiscovery/{sessionId}/candidate/{candidateId}`	clients WRITE (global); plan: `property-discovery`

Full input fields for every tool: references/tools.md.

Recommended workflows

Discover and provision a group's properties

start_property_discovery on the parent (202; 409 if a run is active).
Poll get_property_discovery until candidates appear; fix names/URLs with update_property_candidate.
decide_property_candidates with decision: "APPROVED" (all, or candidateIds), then approve_property_discovery — 202 { status: "PROVISIONING", sessionId, approved } at once; the run continues in the background.
Poll get_property_discovery until PROVISIONING turns COMPLETED (or FAILED); get_client_hierarchy shows the resulting children.

Tips

grant_feature_to_children (features skill) propagates a plan feature to every child; list_children_feature_counts first shows which features are only partly rolled out.

Pitfalls

Hierarchy tools need GLOBAL clients grants; discovery additionally requires the parent's plan to include property-discovery (waived for Maison staff holding it globally).
Attaching a child that is already a parent elsewhere, or would create a cycle, answers 409.
approve_property_discovery answers 409 when the run is not awaiting review or no candidate is approved.

Calling conventions

Same tool, three transports — pick whichever your runtime already speaks. Always send x-api-key.

bash

# REST
curl -X POST "https://maison-labs.com/api/v1/client/<clientId>/propertydiscovery/<sessionId>/approve" -H "x-api-key: $MAISON_API_KEY" -H "content-type: application/json" -d '{}'

json

// MCP (https://maison-labs.com/mcp, Streamable HTTP): tools/call
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "approve_property_discovery", "arguments": {} } }

json

// A2A (https://maison-labs.com/a2a): tasks/send with a data part
{ "jsonrpc": "2.0", "id": 1, "method": "tasks/send", "params": { "message": { "role": "user", "parts": [{ "type": "data", "data": { "tool": "approve_property_discovery", "input": {} } }] } } }

Errors are the same everywhere: 401 no/invalid key; 403 forbidden with details.missing (the grants you lack — fall back to the composite's parts or stop); 403 not_entitled (the hotel's plan lacks the feature); 404, 409, 413 too_large, 503. Inputs that fail validation return 400 invalid_input with the Zod issues — fix and retry once.