> For the complete documentation index, see [llms.txt](https://docs.kula.digital/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kula.digital/for-developers/tools.md).

# Tool reference

This is the catalogue of tools the MCP server exposes. Each is annotated **Read** (read-only) or **Write** / **Destructive**, and the minimum [permission level](/connect-claude-and-access/scopes.md) it needs.

The server is the source of truth — ask a connected client to list its tools to see exactly what's advertised to you. Tools you call without a high enough permission level return a clear `403` and reveal nothing.

> **Conventions.** Read-only tools carry `readOnlyHint`. Tools that modify or delete data carry `destructiveHint`. Creating or saving workspace data (saved views, notes, skills, artifacts, business context) requires at least the `operations` level; deleting them and other destructive/admin actions require `admin`. **No tool changes member, booking or payment records at any level** — those are read-only to the assistant. The exception is the studio's shared **memory** — the assistant's own scratchpad, not business data — where creating and editing notes is available at **any** level (see [Memory](#memory-shared-per-studio)).

## Querying your data

| Tool                     | Kind | Min level  | What it does                                                                                                 |
| ------------------------ | ---- | ---------- | ------------------------------------------------------------------------------------------------------------ |
| `list_tables`            | Read | analytics  | List the tables available in your studio's database.                                                         |
| `get_table_schema`       | Read | analytics  | Column definitions for a table.                                                                              |
| `execute_query`          | Read | analytics  | Run a read-only `SELECT`/`WITH` query. No writes. **Schema:** [schema reference](/for-developers/schema.md). |
| `build_query`            | Read | analytics  | Help compose a parameterised `SELECT`. **Schema:** [schema reference](/for-developers/schema.md).            |
| `entity_lookup`          | Read | analytics  | Resolve a name or email to a canonical entity id (member, location, org).                                    |
| `get_member_payments`    | Read | operations | A member's sales/payment history (honours scoping).                                                          |
| `get_member_plan_status` | Read | operations | A member's plan/membership status.                                                                           |

## Business context & catalogue

| Tool                      | Kind  | Min level  | What it does                                                                                                                                                          |
| ------------------------- | ----- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_semantic_catalogue`  | Read  | analytics  | The data dictionary plus operator-authored business context for this studio.                                                                                          |
| `get_business_context`    | Read  | analytics  | The studio's profile, classes, demographics, goals, brand voice, people, and pricing.                                                                                 |
| `update_business_context` | Write | operations | Saves a confirmed answer into one business-context section. Merges into the section's existing content — only the keys you send are changed, nothing else is touched. |

## Graph & signals

The relationship graph (who is connected to whom and how healthy those connections are) plus the separate attention-signal queue. See [**Graph & relationship tools**](/for-developers/graph.md) for the full model (edges, connection tiers, connection strength, quadrants, signals) and per-tool detail.

Summary rollups:

| Tool                         | Kind | Min level  | What it does                                                                                                                                                                                                                       |
| ---------------------------- | ---- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_member_affinity`        | Read | operations | A member's primary coach, top-3 staff, and affinity concentration.                                                                                                                                                                 |
| `get_staff_concentration`    | Read | operations | Per-staff routing value: how many members' connections are anchored on this coach.                                                                                                                                                 |
| `get_open_signals`           | Read | operations | The open attention-signal queue (drift, freq\_softening, pause\_drift, at\_risk\_threshold, missed\_second\_visit, milestone).                                                                                                     |
| `list_member_status_changes` | Read | operations | Who changed status, membership type, plan or suspension state in the last N days, with the reason where one is knowable. Live-forward only — the log begins when capture started, because no source system records status history. |
| `get_cac_by_cohort`          | Read | analytics  | Customer-acquisition cost broken down by cohort.                                                                                                                                                                                   |

Relationship context — each takes a required `purpose` that scopes the response (analysis purposes anonymise; service-delivery purposes withhold the connection-strength analytics). Denials return an empty result, not an error:

| Tool                    | Kind | Min level  | What it does                                                                           |
| ----------------------- | ---- | ---------- | -------------------------------------------------------------------------------------- |
| `get_member_context`    | Read | operations | One member's connection strength (resilience + quadrant) and affinity routing.         |
| `get_staff_context`     | Read | operations | A staff member's profile, concentration and locations.                                 |
| `get_location_context`  | Read | operations | A location's operational resilience and aggregate connection-strength quadrant spread. |
| `list_quadrant_members` | Read | operations | The members in a connection-strength quadrant at a location, weakest-connection first. |
| `simulate_departure`    | Read | operations | Which members would lose their strongest connection if a staff member left a location. |
| `get_entity_edges`      | Read | operations | The graph edges around a member/staff/location.                                        |

## Views

| Tool            | Kind        | Min level  | What it does                |
| --------------- | ----------- | ---------- | --------------------------- |
| `list_views`    | Read        | analytics  | List saved views.           |
| `describe_view` | Read        | analytics  | A view's SQL and metadata.  |
| `create_view`   | Write       | operations | Create a named, saved view. |
| `drop_view`     | Destructive | admin      | Delete a view.              |

## Skills

| Tool               | Kind | Min level | What it does                                                |
| ------------------ | ---- | --------- | ----------------------------------------------------------- |
| `list_skills`      | Read | analytics | List available skills (built-in + your own).                |
| `get_skill`        | Read | analytics | Fetch a skill's full definition (may be operator-authored). |
| `list_skill_files` | Read | analytics | List a skill's bundled files.                               |
| `get_skill_file`   | Read | analytics | Fetch one bundled skill file.                               |

> Skill *authoring* via the connector (creating or deprecating skills from a chat session) is not currently exposed — skills are authored and managed in the Kula console. Connector-side authoring returns in v2.

## Memory (shared, per-studio)

| Tool            | Kind        | Min level  | What it does                                 |
| --------------- | ----------- | ---------- | -------------------------------------------- |
| `memory_view`   | Read        | any        | Read a note from the studio's shared memory. |
| `memory_create` | Write       | any        | Create a memory note.                        |
| `memory_edit`   | Write       | any        | Edit a memory note.                          |
| `memory_rename` | Write       | operations | Rename a memory note.                        |
| `memory_delete` | Destructive | admin      | Delete a memory note.                        |

> This is the **studio's** shared memory, stored in this connector's database — separate from the AI client's own conversation memory. It's the assistant's scratchpad, not studio business data, so **storing** a note — `memory_create` / `memory_edit` — works at any level, including a read-only login that can't change anything else. Renaming needs `operations`; deleting (irreversible) needs `admin`.

## Knowledge wiki

| Tool               | Kind  | Min level  | What it does                         |
| ------------------ | ----- | ---------- | ------------------------------------ |
| `search_knowledge` | Read  | operations | Search the studio's knowledge notes. |
| `get_knowledge`    | Read  | operations | Fetch a knowledge note.              |
| `add_note`         | Write | operations | Add a knowledge note.                |
| `link_knowledge`   | Write | operations | Link knowledge notes/entities.       |

## Artifacts

| Tool              | Kind  | Min level  | What it does                                                |
| ----------------- | ----- | ---------- | ----------------------------------------------------------- |
| `create_artifact` | Write | operations | Save a report/export/summary that persists beyond the chat. |

## Ingest audit (raw records)

| Tool               | Kind  | Min level | What it does                                 |
| ------------------ | ----- | --------- | -------------------------------------------- |
| `list_raw_records` | Read  | admin     | Query the raw ingest log.                    |
| `get_raw_record`   | Read  | admin     | Fetch one raw ingest payload.                |
| `record_raw`       | Write | admin     | Write a raw ingest payload (ingest tooling). |

## What you won't find

No tools move money, issue refunds, generate media, or read across studios. Those capabilities are deliberately absent — see [Security & data handling](/trust-and-legal/security.md).