Skip to content

MCP Tools Reference

The Mention MCP server exposes seven 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 tools are designed to be used in a flow. Most Agents will:

  1. Discover Audiences with list_audiences.
  2. Call read_audience with the chosen audience_id to load that domain's index — every Concept with its definition, every Process with its objective and SOP task titles. Article and SOP bodies are not included.
  3. Drill in with read_concept (for a Concept's full Article) or read_sop (for a Process's full SOP) when the index alone isn't enough.
  4. Pull a pre-written answer with list_questions + read_question when the user's question matches one an admin has already captured.
  5. Fall back to ask only for cross-cutting questions that no single Article, SOP, or Question covers.

Articles and SOPs are pre-generated when you are added to an Audience, so they are normally ready immediately. If read_audience marks anything as still generating, retry the relevant tool after ~30–90 seconds.

list_audiences

Lists all Audiences (knowledge domains) the Agent has access to. This is usually the first call.

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.

read_audience

Loads the index for one Audience — enough structure and detail 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 with these sections:

  • Pending content — only shown when something hasn't finished generating. Lists each Article / SOP that is still being produced.
  • Concepts — every Concept in learning order, each with its stored definition, label, optional acronym, and a one-line note about Article availability (ready, still generating, or failed). Followed by a Prerequisites list of dependencies between Concepts, and — when any exist — a Mutually-referential concepts list of Concept clusters that are defined in terms of each other and have no order among themselves.
  • Processes — every Process, each with its objective and a one-line note about SOP availability that includes the titles of every task in the SOP when it's ready.

This is the orientation tool. It is small enough to load fully every time and tells the Agent which Concept Articles or SOP bodies are worth pulling. It does not include Article bodies or SOP step content — use read_concept and read_sop for those.

read_concept

Loads the full Article for one Concept.

Input:

  • audience_id (string) — the Audience the Concept belongs to.
  • concept_id (string) — the Concept's ID, taken from the Concepts section of read_audience.

Returns: the Concept's Article body — every section's markdown plus knowledge-check questions — or a _Still generating._ / _Generation failed: …_ placeholder.

Call this when the one-line definition in read_audience isn't enough for the user's question (e.g. you need an example, the full explanation, or the knowledge-check answers).

read_sop

Loads the full SOP for one Process.

Input:

  • audience_id (string) — the Audience the Process belongs to.
  • process_id (string) — the Process's ID, taken from the Processes section of read_audience.

Returns: the SOP body — every task, every step within each task, callouts, and knowledge-check questions — or a _Still generating._ / _Generation failed: …_ placeholder.

Call this when the task titles shown under a Process in read_audience aren't enough to act on the user's question.

list_questions

Lists the answerable Questions an admin has added to one Audience, with a short summary line per Question. Questions whose answer couldn't be produced from the Audience's sources (no answer found, or generation failed) are omitted. The answers are not included — use read_question to load a specific answer.

Input:

  • audience_id (string) — the Audience to list Questions for.

Returns: an array of Question overviews, each containing the Question text, its question_token, and a note when the answer is still being generated.

Call this when the user's question sounds like a recurring FAQ that an admin may already have captured. Cheaper than ask when there's a match.

read_question

Loads the full Markdown answer to one Question in an Audience.

Input:

  • audience_id (string) — the Audience the Question belongs to.
  • question_token (string) — the Question's token, taken from list_questions.

Returns: the Question's Markdown answer (wiki-linked to relevant Concepts in the Audience's Glossary), or a placeholder when the answer is still generating, when generation failed, or when no answer was found in the Audience's sources.

Call this after list_questions when one of the captured Questions matches the user's request closely enough.

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 pre-generated Articles, SOPs, and Questions already contain more material than ask can synthesize. Use ask only when:

  • You have already consulted the relevant Article(s), SOP(s), or Question(s) and found them insufficient, or
  • The question genuinely spans multiple Concepts or Processes (e.g. "how do X and Y interact?") and no single Article, SOP, or Question covers it.

Expect noticeably higher latency than reading an already-generated Article or SOP.

list_audiences
  └─ pick an audience_id
       │
       └─ read_audience → returns the index: Concepts (with definitions),
            │              Processes (with objectives + task titles)
            │
            ├─ for a specific Concept you need the full Article on:
            │     read_concept(audience_id, concept_id)
            │
            ├─ for a specific Process you need the full SOP on:
            │     read_sop(audience_id, process_id)
            │
            ├─ for FAQ-style questions captured by an admin:
            │     list_questions(audience_id) → read_question(audience_id, question_token)
            │
            └─ for a cross-cutting question after the above:
                  ask(audience_id, question)