MCP Tools Reference¶

The Mention MCP server exposes up to sixteen tools, scoped by role: nine learner tools every member gets, five more owner tools for Audience owners, and two org admin tools. This page documents each one — its inputs, what it returns, and when an Agent should prefer it. For setup, see MCP Server Overview.

The learner tools are designed to be used in a flow, and which flow depends on the connected user's mode for the entry in question:

Learn mode — the user hasn't finished that entry's Lesson. The Agent answers from the Article, then teaches the Lesson one exercise at a time.
Read mode — the user has finished it (or owns the Audience). There is nothing left to teach.

Most Agents will:

Discover Audiences with list_audiences.
Call read_audience with the chosen audience_id to load that domain's table of contents — every entry the Audience's owner commissioned, and whether each Article has been written yet. Documents and exercises are not included.
Call read_article for the entry that covers the question. It always hands over the whole document. In Learn mode it also carries the lesson_id — which is where the mode announces itself.
In Learn mode, call read_lesson with that lesson_id for the current exercise, pose it verbatim, take the person's answer, and submit it with record_progress — then teach from the verdict and correction that come back, and move to the next exercise.
Call review_session when the person wants to keep material they have already passed — it draws whatever has fallen due in that Audience and runs it item by item.
Call read_concept whenever a term might mean something specific to this organization.
Fall back to ask only for cross-cutting questions that no single Article covers.

Articles are written when an owner adds an entry to the table of contents, and each Lesson is composed from its Article once that Article is finished, so both are normally ready immediately — your access simply follows your Audience memberships. If read_audience marks anything as still in flight, retry after ~30–90 seconds.

The Agent never holds the answers. Answer keys, rubric criteria, and corrections are stripped from every learner-scoped response and arrive only in the result of a submitted attempt. An Agent cannot reveal what it was never given, and it should not guess: submitting the attempt is how the answer becomes available.

Learner tools¶

`list_audiences`¶

Lists all Audiences (knowledge domains) the Agent has access to. This is usually the first call — and the tool's description instructs Agents to make it before performing, drafting, or explaining any operational task, so the organization's own answer takes precedence over the model's general knowledge. At connection time the Agent also receives a compact inventory of the user's Audiences and their Article names, so a request like "I need to issue an ops bulletin" matches the Article by name immediately.

Input: none.

Returns: an array of Audience records, each containing:

id — the Audience ID, used as audience_id in read_audience.
name — human-readable name.
description — what the Audience covers.

Use this to pick the right Audience for the user's question.

The same inventory is also exposed as MCP resources: one mention://audiences/{audienceId} per Audience, listable and readable as a JSON record with the same id, name, and description, for clients that surface resources.

`read_audience`¶

Loads the table of contents for one Audience — enough structure and learner state for the Agent to know what's there and where to drill in.

Input:

audience_id (string) — the Audience to load.

Returns: a formatted document listing every entry in the table of contents, alphabetically by name. Each entry carries:

its name and article_id, for read_article;
a status line when the entry is not ready: an Article still being written, not ready with the reason Mention could not write it from the connected sources, or a failed write with its error.

Finished entries carry no status line. The owner's prompt behind each entry is not shown here — it is an authoring detail, available to owners through read_audience_admin.

This is the orientation tool. It is small enough to load fully every time, and it tells the Agent which entry to open. Which of the two things happens next — teach the Lesson, or hand over the document — is decided by read_article, from the connected user's own progress rather than from anything the Agent asserts.

`read_lesson`¶

Loads the exercise the connected user is currently on, in the Lesson composed from one Article.

Input:

audience_id (string) — the Audience the Lesson belongs to.
lesson_id (string) — from the read_article heading in Learn mode.

Returns: the Lesson's title, how many exercises it has, how far the user has got, a progress block — the material the Lesson covers and which of it the user has passed — and one exercise: its scenario (if any), its prompt, the options to choose from when it is a selection exercise, and whether it expects written prose instead. Some exercises carry an illustration alongside the prompt — the same interactive widget the web app renders, delivered here as structured text. A Lesson still being composed says so and is usually ready after ~30–90 seconds.

Specifically not returned: the answer key, the rubric criteria, the reference answer, and the correction. These do not exist in this response at all, for any caller. They arrive only in the result of record_progress.

The exercise is a script, not a layout — the Agent poses it as written, without adding hints, restating it as a leading question, or offering the answer for confirmation. A Lesson has between 5 and 9 exercises, and the six kinds range from an ungraded warm-up guess to reconstructing a procedure from memory.

Once the Lesson is finished, this tool has nothing left to serve for it and the user is in Read mode — use read_article.

`record_progress`¶

Submits an attempt at the current exercise and returns the verdict. This is the only tool that writes learner progress.

Input:

audience_id (string) — the Audience the Lesson belongs to.
lesson_id (string) — the Lesson being attempted.
step_id (string) — the exercise, from read_lesson.
selection (array of strings) — the option IDs the person chose, for a selection exercise. Ordered when the exercise asks for an ordering.
response (string) — the person's answer in their own words, for a written exercise. Pass what they actually said; do not improve it, complete it, or answer on their behalf.

Exactly one of selection or response must be provided — the server rejects an attempt carrying both or neither.

Returns:

the result — passed, failed, or ungraded;
for a written answer, a per-criterion verdict: each criterion, whether it was met, and short feedback saying why;
the correction — the verdict note and the explanation, drawn from the Article;
the reference answer or the correct option IDs;
the user's updated mastery of the material this exercise covers, including when it next falls due for review;
the next exercise, or a retry if they failed, and whether the Lesson is now complete.

This is where teaching happens. The Agent takes the verdict and works through what the person missed, using the per-criterion feedback rather than restating the model answer at them. Passing a written answer requires meeting every required criterion; there is no partial pass.

A failed attempt is retryable, and the retry is a variant — the same material set in a different situation, not the same prompt again. An ungraded result means Mention could not grade it at that moment (the grader was unavailable, or the organization is out of credits); the attempt was accepted rather than lost, and the person can try again. An ungraded result carries no correction, reference answer, or answer key — nothing was adjudicated, so the Agent has nothing to teach from and should say so plainly rather than filling the gap itself. Learner prose is not stored, so a retry means retyping.

Recording progress requires the connected user to be personally enrolled in the Audience — org admins who are not enrolled get a permission error. In the web app they can join as a learner; over MCP, read without recording until they are enrolled.

`roleplay`¶

Runs the Audience's final exam — one multi-turn roleplay drawn across everything its Lessons taught, open only once the person has finished every Lesson. The person plays their own role, Mention plays the counterpart, and the Agent relays between them.

Input:

audience_id (string) — the Audience whose exam it is.
action (status, start, say, or conclude) — report where the person stands, draw the exam and return the scene, take one turn, or end it and have the transcript graded as it stands.
message (string) — required for say: what the person said, in their own words and unedited.

Returns: for status, whether the exam can be sat, is under way, or is waiting to be graded. For start, the scene the person is dropped into — they speak first. For say, the counterpart's reply and how many turns are left. When the exam ends — the turn budget of eight runs out, the token budget runs out, or the person concludes — it is graded topic by topic, and the result comes back as counts: how many drawn topics held up, fell down, or were never genuinely reached. A fallen topic drops to the first review rung and falls due immediately; the transcript is not kept.

Neither the Agent nor the person is told which topics were drawn or given any rubric — the situation is real and the person supplies the knowledge. The Agent is the channel, not either party. It reads the counterpart's line back as written, sends the person's words through unedited, and never improvises the counterpart or answers on the person's behalf. If the counterpart comes back unavailable — the model was unreachable, or the organization is out of credits — nothing was lost and the session is left exactly as it was.

`review_session`¶

Runs the spaced-repetition review a person owes one Audience: the material they already passed, drawn again once it falls due. This is the only way to work through review outside the web app.

Input:

audience_id (string) — the Audience to review.
action (start, read, or answer) — draw the session (or hand back the one already open), look at where an open session stands, or submit one item.
item_id (string) — required for answer: the item being answered.
selection (array of strings) — the option IDs the person chose, for a selection item.
response (string) — the person's answer in their own words, for a written item.

For answer, exactly one of selection or response must be provided — the server rejects an attempt carrying both or neither.

Returns: how many items are left in the session and one item — its scenario, its prompt, and either the options or a request for prose. Answer keys, rubric criteria, reference answers and corrections are stripped exactly as they are from read_lesson. An answer returns the same result shape record_progress does — verdict, per-criterion feedback, correction, reference answer or correct option IDs, updated mastery — plus the next item inline, so the Agent works through a session from what comes back rather than re-reading it between items.

start is idempotent: called with a session already open, it hands that session back rather than drawing a new one. read never fails for lack of a session, and it distinguishes the two cases an empty session cannot: it reports how many items starting would actually draw, so an Agent can tell someone to start when material is waiting, and when nothing is due it says when the next item comes back. Nothing due is reported plainly rather than papered over with practice questions of the Agent's own.

That count is what a session would ask, not merely what has fallen due. Material whose Lesson no longer exercises it in a drawable form — the coverage survived a recompose but no graded question now teaches it — is excluded, so the count never promises items start would then drop.

Three things differ from a Lesson, and they matter:

There is no retry. A failed review item is still answered and the session still moves on; the material simply drops to the shortest interval and comes back sooner. The Agent teaches the correction instead of asking again.
Results are passed, failed, or ungraded. Only an ungraded result comes back as the same item — Mention could not grade the attempt at that moment, so it was accepted rather than lost and is served again.
Review items are never warm-ups. A review item is one question with one answer, so it can be a different kind of exercise than the one that first taught the material, but never a multi-turn one.

Like record_progress, this writes real progress and requires the connected user to be personally enrolled in the Audience.

`read_article`¶

Loads one Article's document, in the shape the connected user's mode allows.

Input:

audience_id (string) — the Audience the Article belongs to.
article_id (string) — from the table of contents returned by read_audience.

Returns: the Article's full Markdown document, in either mode. In Learn mode it is preceded by a note naming the mode and carrying the lesson_id to pass to read_lesson. An Article that is still being written returns _Still being written._; one that failed returns its error; one that is not ready returns the reason Mention could not write it from the sources connected so far.

The gate is in the tool rather than in the instructions, deliberately: an Agent that would rather answer in one turn than eight has no easier path to the document. Owners and users who have finished the Lesson get the whole thing immediately.

This is the primary call in either mode. The document is the organization's own written answer, so the Agent hands it over — quoting, summarizing, or walking through it at whatever depth the person asks for — rather than answering from general knowledge. When an Article is not ready, the Agent is instructed to say so plainly instead of filling the gap itself.

`read_concept`¶

Looks up one term in the organization's glossary.

Input:

concept (string) — the term itself (e.g. Client Upgrade Pack), or the 32-character id taken from a wikilink in an Article or a lesson.

Returns: the term's definition, what kind of thing it is, and how widely your sources mention it.

Glossary terms are organization-wide, so this tool takes no audience_id. Article documents, and the prose of a lesson exercise, mark the first mention of a glossary term as a link written [Term](@id) — the Agent can pass either that id or the term the person typed. Definitions carry the same links where they use another glossary term, so the Agent can follow a chain of related terms by feeding those ids straight back in. A term that is not in the glossary comes back with up to five suggestions — glossary names that contain what was typed — rather than an error, so the Agent says the organization has no definition for it instead of inventing one.

Reach for this whenever a word might mean something specific here, so the answer uses your organization's meaning rather than the industry's.

`ask`¶

Asks a synthesized question that is answered against the Audience's underlying fact graph and grounded in cited source facts.

Input: both fields are required — the server rejects calls missing audience_id.

audience_id (string) — the Audience to query. Obtain this from list_audiences before calling ask; never call ask as a first step.
question (string) — a natural-language question. More specific questions retrieve more focused answers.

Returns: a synthesized answer with cited source facts.

This is not the primary Q&A tool. The Articles an owner has commissioned already contain more material than ask can synthesize. Use ask only when:

You have already read the relevant Article(s) and found them insufficient, or
The question genuinely spans several Articles and no single one covers it.

Expect noticeably higher latency than reading an already-written Article.

Owner tools¶

Available to Audience owners and org admins. All of them operate on content the connected user can curate; the server enforces permissions on every call.

`read_audience_admin`¶

Loads the owner view of one Audience, one section at a time. Call it before editing — it returns the IDs the editing tools take.

Input:

audience_id (string) — the Audience.
section (string) — members or contents.

Returns: by section:

members — owner and learner rosters (Clerk user IDs), for manage_members.
contents — the table of contents, each entry with its article_id, the name learners see, and the prompt the owner wrote for it, for manage_toc.

`manage_members`¶

Manages one Audience member.

Input: audience_id, user_id (Clerk user ID), action (add_owner, add_learner, change_role, or remove), and role (owner or learner, required for change_role).

Returns: a confirmation.

`manage_toc`¶

Authors an Audience's table of contents. Read the current state first with read_audience_admin (section: contents).

Each entry is a name learners see plus a prompt saying what the Article should cover. Mention writes the document from that prompt against the organization's connected sources, then composes that Article's Lesson from the finished document; there is no way to write either by hand.

Input: audience_id and action, plus the fields that action needs:

add — name, prompt. Adds an entry and returns its new article_id; entries are ordered alphabetically by name, not by when they were added.
update — article_id, name, prompt. Changing the prompt makes Mention write the document again and compose its Lesson again.
remove — article_id. Deletes the entry, its Article, its Lesson, and the progress that goes with them.

Returns: a confirmation, and the new article_id for add.

Writing and composition are asynchronous — check progress with read_audience, which shows each entry's status. An Article that comes back not ready means the connected sources cannot support that prompt yet: narrow the prompt or connect more sources rather than retrying blindly. A Lesson that fails to compose leaves its Article readable, and sometimes means the entry is pure reference with nothing in it to exercise.

Learners are not reset by a rewrite: mastery is recorded against the material an exercise covers, not against the exercise, so a recomposed Lesson keeps everything that did not change.

`read_adoption`¶

Reads the adoption report for one Audience: the size of its table of contents, plus stalled learners — members who have gone idle with Lessons still unfinished.

Input: audience_id.

Returns: how many Articles the table of contents holds, and the stalled-learners list: each stalled member with how many of the Audience's Lessons they have finished, how long they have been idle, and when they last finished something. A finished Lesson means the member passed every piece of material it grades, so this is a measurement rather than a self-report. This is the tool for "who needs a nudge?" — it does not return a progress report for every member, only the ones who have stalled.

`manage_unanswered_questions`¶

Works the inbox of knowledge gaps — questions members asked that Mention could not answer from its sources. Each question is recorded once org-wide, with the audiences it was asked in. Available to Audience owners and org admins; the API still enforces that only an owner of an audience the gap was asked in can answer or dismiss it.

Input: action (list, answer, or dismiss) plus answer_id for answer and dismiss, answer for answer, and audience_id — required on list for Audience owners (an audience they own); optional for org admins to narrow the org-wide inbox; required for dismiss (dismissal sets a gap aside for one audience only; it comes back if someone asks again).

Returns: the knowledge-gap list (each with how often and by how many members it was asked), or a confirmation. Answering adds the missing knowledge to the knowledge base for every audience that asked, which is what lets Articles whose prompts depend on it be written.

Org admin tools¶

`manage_audience`¶

Creates, renames/redescribes, or deletes an Audience.

Input: action (create, update_metadata, or delete) plus: for create — name, description, context_url, optional owner_ids / learner_ids; for update_metadata — audience_id, name, description; for delete — audience_id.

Returns: a confirmation (and the new audience_id for create). Deleting an Audience removes its table of contents, its Articles, their Lessons, and its members' progress.

`resolve_contradictions`¶

Manages contradictions between facts in the knowledge graph.

Input: action (list, resolve, or discard) plus: resolutions for resolve (per contradiction, the contradiction_id and the winning_fact_id that is correct); contradiction_ids for discard.

Returns: the pending-contradictions list (each with two conflicting facts), or a confirmation. Resolving retires the losing fact.

Recommended flow¶

list_audiences
  └─ pick an audience_id
       │
       └─ read_audience → the table of contents
            │
            ├─ read_article(audience_id, article_id) → the mode decides
            │    │
            │    ├─ Read mode (Lesson finished, or you own the Audience):
            │    │     the whole document
            │    │       └─ hand it over, answer questions from it
            │    │
            │    └─ Learn mode (the Lesson isn't finished):
            │          the whole document, plus the lesson_id
            │            └─ read_lesson(audience_id, lesson_id)
            │                 → one exercise, no answers
            │                 └─ pose it as written, take their answer
            │                      └─ record_progress(audience_id, lesson_id,
            │                           step_id, selection | response)
            │                           → verdict, per-criterion feedback,
            │                             correction, updated mastery,
            │                             next exercise (or a variant)
            │                           └─ teach from it, then loop
            │                 (every lesson finished? the final exam runs
            │                  through roleplay: start → say → conclude)
            │
            ├─ material already passed, once it falls due:
            │     review_session(audience_id, action: start)
            │       → one due item, no answers
            │       └─ review_session(audience_id, action: answer,
            │            item_id, selection | response)
            │            → verdict, correction, updated mastery,
            │              and the next item inline
            │            └─ teach from it, then loop until the
            │               session is complete
            │       (an empty session means nothing is due — say so)
            │
            ├─ a [Term](@id) link, or a word that might be jargon:
            │     read_concept(concept)   ← organization-wide, no audience_id
            │
            └─ for a cross-cutting question no single Article covers:
                  ask(audience_id, question)

owners additionally:
  read_audience_admin → manage_toc / manage_members
    (a changed prompt makes Mention write the Article again,
     and compose its Lesson again from the new document)
  read_adoption
  manage_unanswered_questions
    (owners pass audience_id on list; org admins may omit it)

org admins additionally:
  manage_audience, resolve_contradictions

MCP Tools Reference¶

Learner tools¶

list_audiences¶

read_audience¶

read_lesson¶

record_progress¶

roleplay¶

review_session¶

read_article¶

read_concept¶

ask¶

Owner tools¶

read_audience_admin¶

manage_members¶

manage_toc¶

read_adoption¶

manage_unanswered_questions¶

Org admin tools¶

manage_audience¶

resolve_contradictions¶

Recommended flow¶

Related pages¶

`list_audiences`¶

`read_audience`¶

`read_lesson`¶

`record_progress`¶

`roleplay`¶

`review_session`¶

`read_article`¶

`read_concept`¶

`ask`¶

`read_audience_admin`¶

`manage_members`¶

`manage_toc`¶

`read_adoption`¶

`manage_unanswered_questions`¶

`manage_audience`¶

`resolve_contradictions`¶