> 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) 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, and pricing. |

## Graph & signals

The relationship graph and at-risk queue. See [**Graph & relationship tools**](/for-developers/graph.md) for the full model (edges, resilience, vulnerability 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 and defection risk.                                                                           |
| `get_open_signals`        | Read | operations | The open at-risk queue (drift, freq\_softening, pause\_drift, at\_risk\_threshold, missed\_second\_visit, milestone). |
| `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 resilience analytics). Denials return an empty result, not an error:

| Tool                    | Kind | Min level  | What it does                                                                  |
| ----------------------- | ---- | ---------- | ----------------------------------------------------------------------------- |
| `get_member_context`    | Read | operations | One member's resilience, vulnerability 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 quadrant spread.            |
| `list_quadrant_members` | Read | operations | The members in a vulnerability quadrant at a location, most-vulnerable first. |
| `simulate_departure`    | Read | operations | Who's at risk 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.                               |
| `create_skill`     | Write       | operations | Save a custom skill (lands as a draft for review).          |
| `deprecate_skill`  | Destructive | admin      | Mark a skill deprecated.                                    |

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

## Semantic search

| Tool                     | Kind  | Min level | What it does                                       |
| ------------------------ | ----- | --------- | -------------------------------------------------- |
| `get_embeddings_status`  | Read  | analytics | Whether semantic search is enabled for the studio. |
| `set_embeddings_enabled` | Write | admin     | Turn semantic search on/off (opt-in).              |

## Artifacts

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

## Ignition (the diagnostic engine)

> Studio Ignition is a separate **paid marketplace add-on** — these tools are available only on studios that have added it. See [Studio Ignition](/skills/studio-ignition.md).

| Tool                   | Kind        | Min level  | What it does                      |
| ---------------------- | ----------- | ---------- | --------------------------------- |
| `get_ignition_status`  | Read        | operations | Current diagnostic state.         |
| `get_ignition_intake`  | Read        | operations | The intake form schema.           |
| `save_ignition_intake` | Write       | operations | Submit intake answers.            |
| `run_ignition`         | Destructive | admin      | Run a diagnostic stage.           |
| `close_ignition_gate`  | Write       | admin      | Finalise a diagnostic stage gate. |

## Evals

| Tool                 | Kind  | Min level  | What it does               |
| -------------------- | ----- | ---------- | -------------------------- |
| `list_eval_cases`    | Read  | operations | List a skill's test cases. |
| `get_eval_summary`   | Read  | operations | Aggregate eval metrics.    |
| `add_eval_case`      | Write | operations | Add a test case.           |
| `record_eval_result` | Write | operations | Record one eval result.    |

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

## Logs & feedback

| Tool                  | Kind  | Min level  | What it does                                                    |
| --------------------- | ----- | ---------- | --------------------------------------------------------------- |
| `get_error_summary`   | Read  | operations | Aggregated errors from ingest jobs — the connector health view. |
| `get_mcp_usage_stats` | Read  | operations | Per-tool usage metrics for the studio.                          |
| `submit_feedback`     | Write | analytics  | Submit feedback on a tool result (append-only).                 |

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.kula.digital/for-developers/tools.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.