---
title: mentor operations
---

The exact fields each `mentor.*` operation takes and returns.

<!-- Generated by `python scripts/codegen/docs_reference.py` from the op registry; edit the models, not this page. -->

Every op is `POST /v1/<op>` over HTTP and the MCP tool `loom_<op>`. The identity fields (`org`, `namespace`, `agent`, `user_id`, `session_id`) are filled from the token and the MCP session when a transport can; for an HTTP call with no token on a single-user server, the install's org on every op but `code.*` and `tracker.*` (which keep their plane's), and on [some ops](/docs/reference/http-api#request) its namespace and agent; see [identities and namespaces](/docs/concepts/identities-and-namespaces). The [operations index](/docs/reference/operations) explains role, kind and the MCP `all` listing. Unknown input fields are served and named in `ignored_args`.

<!-- prettier-ignore-start -->

## `mentor.brief`

One agent's usage profile and the store's hints.

`POST /v1/mentor.brief` · MCP `loom_mentor_brief` · role `viewer` · read

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `agent` | `str` | `''` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `window_seconds` | `int` | `604800` | How far back the ledger read reaches, in seconds; 1 hour to 90 days. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `org` | `str` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | The namespace the op reads or writes. |
| `agent` | `str` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `window_seconds` | `int` | The window the profile was computed over, in seconds; a profile served from the cache keeps the window it was computed with. |
| `computed_at` | `datetime` | When the profile was computed (UTC); older than the call when served from the cache. |
| `sessions` | `int` | Distinct client-named sessions of this agent in the window (`-` and `*` not counted). |
| `usage` | `dict[str, int]` | Calls per operation by this agent in the window. |
| `planes` | `list[MentorPlane]` | Every plane the mentor knows, with this agent's calls to it and whether it is available. |
| `hints` | `list[MentorHint]` | The rules that fired for this agent, each with the counts that fired it; empty when none. |
| `adoption` | `list[MentorAdoption]` | Per hint code, sessions it was shown in and followed in, most shown first; empty when no hint reached the agent or the read failed. |
| `usage_evidence` | `list[UsageRung]` | The agent's use of Loom in the window, one rung each, weakest claim first: from a call made to a graded run. |
| `ledger_from` | `datetime \| None` | Oldest ledger row of this agent in the window, of any kind; None when it holds none or the read failed. |
| `ledger_retention_days` | `int \| None` | Days the configured retention keeps this namespace's call ledger rows; 0 keeps them until deleted, None when the read failed. |
| `agents` | `list[str]` | The namespace's writers in the window, most active first; the brief defaults to the first when the caller has no agent name of its own (the dashboard) — `agent_defaulted` says so. |
| `agent_defaulted` | `bool` | True when the caller named no real agent and the brief picked the top writer in `agents`. |
| `skipped` | `list[str]` | Facts the brief could not read, as "step: reason". |
| `healthy` | `bool` | No warning or critical hint. |

## `mentor.guide`

The agent guide this server ships; the same for every caller.

`POST /v1/mentor.guide` · MCP `loom_mentor_guide` · role `viewer` · read · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `part` | `Literal['skill', 'reference', 'all']` | `'skill'` | Which part: `skill` (the loop and rules, the default), `reference` (each plane) or `all`. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `version` | `str` | The guide's version (`metadata.version` of skills/loom/SKILL.md). |
| `part` | `Literal['skill', 'reference', 'all']` | The part returned, as requested. |
| `text` | `str` | The guide as Markdown, without the skill's frontmatter. |

<!-- prettier-ignore-end -->
