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 what that readership is told — every article its owner commissioned, grouped by the topic it explains, with the questions that topic has already settled 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 an Audience's 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 what one readership is told about the product — 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, grouped under the topic it explains — a heading per topic, General last holding anything filed under no topic. Each entry carries:

its name and its 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.

Each topic also lists the questions your organization has already answered about it, so the Agent can see what is settled without opening anything; open questions are left out, because they belong to the owner's queue rather than to the reader. read_concept on that topic returns those answers in full.

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 full document — how one topic is explained for one readership — in the shape the connected user's mode allows.

Input:

audience_id (string) — the Audience the Article belongs to.
article_id (string) — from the entries 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. For a term labelled Topic, the definition is followed by the questions filed under that topic — whatever your members actually asked, plus the ones Mention seeded and answered when an Audience was created. Each one says how often it was asked and is shown as answered, stale (answered, but a refresh is pending after something changed), or open with nobody having answered it yet. An open question carries its question_id, which an Audience owner can pass to manage_unanswered_questions action answer without listing the queue first; the Agent is told to report the gap rather than fill it in itself. A question that has been turned into an Article names that article_id.

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: an answer with cited source facts, ending with how many sources it cites.

A question your organization has already answered is served the recorded answer with its citations instantly, rather than generated afresh — and when an owner has promoted that question into an article, the response adds a pointer to read it with read_article (its article_id). New or unmatched questions go through the full retrieval and generation pipeline.

Asking is recorded. The ask is filed against your organization's record of that question — bumping its counts when it matches one already on record, opening a new one when it does not — and a question Mention could not answer becomes a gap on the owners' Gaps tab. A question opened this way is filed when it is answered, under the topic the answer's cited facts point to, or General when they point at no topic.

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 — the contents section comes back under the heading "What this readership is told (admin view)". 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 — what this readership is told, 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`¶

Commissions what a readership is told — available to Audience owners. The tool kept its name; what it authors is the Audience's 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 readership: how many articles it is told, plus stalled learners — members who have gone idle with Lessons still unfinished.

Input: audience_id.

Returns: how many Articles the readership is told, 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 everything the organization has not settled: questions nobody has answered and the contradictions still pending. It mirrors the web app — the same questions, in the same order, as each Audience's Gaps tab, and the same contradictions as the Conflicts page. 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 question belongs to can answer, file, or dismiss it.

Input: action (list, answer, assign_topic, route, dismiss, approve_proposal, or reject_proposal) plus question_id for every action but list, answer for answer, topic for assign_topic (a topic name or a 32-character concept_id; omit it to file the question under General), and audience_id — required on list for Audience owners (an audience they own); optional for org admins to narrow the org-wide queue; required for route (the audience that should own the question) and for dismiss (dismissal sets a question aside for one audience only; it comes back if someone asks again).

Returns: the open questions most-asked-first (each with how often and by how many members it was asked, which topic it is filed under, whether a refresh is pending, and any proposal held on it), how many open questions each topic still accounts for, and the pending contradictions — or a confirmation. Questions Mention could not route to an audience sit with the organization's Default audience and are marked "needs routing" in the list; route moves one to the audience that should own it. Answering records the answer as what your organization says for every audience that asked, which is what lets Articles whose prompts depend on it be written. assign_topic moves where a question is filed; filing is a pointer move and is never a precondition for answering. approve_proposal records a held proposal — always from a person who does not own the audience — as the answer; reject_proposal discards it and leaves the question open. Resolving a contradiction is resolve_contradictions, which the server registers for org admins.

Org admin tools¶

`manage_audience`¶

Creates, re-scopes, or deletes an Audience.

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

questions is the list of questions this Audience must be able to answer, in the owner's own words — Mention searches the organization's sources with them to build the Audience's Contents, and writes the Audience's description from them. update_metadata replaces the whole list, so send it in full; read the current one from read_audience_admin section contents. Changing the questions proposes further Articles and never removes or rewrites existing ones.

Returns: a confirmation (and the new audience_id for create). Deleting an Audience removes its 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 → what this readership is told
            │
            ├─ 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
            │       (a Topic also returns the questions filed under it;
            │        an open one is a gap, closed with
            │        manage_unanswered_questions and its question_id)
            │
            └─ for a cross-cutting question no single Article covers:
                  ask(audience_id, question)
                    (the ask is recorded; an unanswerable one
                     becomes a gap in the owners' queue)

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
    (the open-question queue: list → answer / assign_topic / dismiss;
     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`¶