Tools reference

Once connected, your assistant has the tools below. They map directly to the REST API, so the responses and the permission rules are identical. Everything is read-only except the tools under “Changing announcements”, which need a connection granted the announcement:write scope, the tools that add documents and YouTube videos, which need content:write, and the tools under “Assigning training”, which need training:assign.

search_mereon

Search the organization’s business knowledge base (processes, policies, facts, and source documents and transcripts). This is usually the first tool to call: it returns type-tagged results with snippets, relevance scores, and web links.

Input	Type	Notes
query	string	Natural-language search query. Required.
types	string[]	Restrict to topic and/or chapter. Defaults to all.
limit	number	Max results, 1–50. Default 10.

list_topics

List the knowledge graph’s topics, in alphabetical order by name, optionally restricted to one category. Use it to browse or enumerate topics. search_mereon finds a topic by what it is about, and list_spaces shows how topics are grouped. Each topic gives its name, category and link. Read one in full with get_topic, find who owns it with get_duties, and list its items with get_topic_items.

Input	Type	Notes
categorySlug	string	Restrict to one category, e.g. operations, hr, finance. An unrecognized slug is an error rather than a silent match-everything.
filter	string	A stewardship worklist instead of every topic: no-owner (no one is Responsible for the topic itself), no-verification-interval (no review cadence set), or verification-overdue (the next review date has passed). An unknown value is an error.
cursor	string	Pagination cursor from a previous response. It is the id of the last topic returned.
limit	number	Max topics, 1–100. Default 50.

get_topic

Fetch a knowledge topic by id: its description, category, the items under it (processes, policies, facts), and related topics. Use after search_mereon to read a topic in full.

Input	Type	Notes
topicId	string	Topic id from search results or related topics. Required.

get_topic_items

List the items (processes, policies, facts) under a topic, as a nested tree. Use it after get_topic or list_topics surfaces a topic id when you need every item rather than the summaries get_topic carries. Read one in full, with its evidence, using get_item.

Input	Type	Notes
topicId	string	Topic id from list_topics or search results. Required.

get_item

Fetch a single item (process, policy, or fact) by id, including its child items and the source evidence backing it: quotes, video timestamps, document ranges, and confidence, with links to the original content.

Input	Type	Notes
itemId	string	Item id from a topic’s items list. Required.

get_content

Fetch a single content resource by id: its title, type (document, video, audio, or guide), summary, duration (for video), and link. Use to look up a resource’s metadata once you have its id. For the full wording use get_content_text; to find a resource by title use list_content.

Input	Type	Notes
contentId	string	Content id from search results, list_content, or item evidence. Required.

get_content_text

Fetch the full text of a source document, or the transcript of a video, split into chapters. Use when search snippets are not enough and you need the original wording.

Input	Type	Notes
contentId	string	Content id from search results or item evidence. Required.

get_content_transcript

Get the timed transcript of a video or an audio recording: each spoken segment with its start and end in milliseconds, in order. Use it to cite where in a recording something is said, or to read an earlier version of it. A document or a guide has no timing, so read it with get_content_text.

It is the current version unless versionId names another, which has to belong to this resource. A version learners have not had (a completed one above the current version, a draft, or a processing or failed one) is an editor’s working copy and is shown only to someone who may edit the resource.

Input	Type	Notes
contentId	string	Content id of a video or an audio recording. Required.
versionId	string	A version id from list_content_versions. Defaults to the current version.

list_content_versions

List a resource’s versions, newest first: which one learners see now, which it replaced, who published each, and what the publisher said should happen to learners already enrolled (retrainingIntent: none, full_retake or changed_material). Use it to answer “when did this change” and “did that update retrain people”.

Anyone who can read the resource sees its released versions: the current one and the completed ones it replaced. A completed version above the current one (a publish not yet live, or one a rollback moved away from), a draft, or a processing or failed version is an editor’s working copy and is shown only to someone who may edit the resource. Not paginated.

Input	Type	Notes
contentId	string	Content id, from list_content or search results. Required.

get_duties

Find who is Responsible, Accountable, Consulted, or Informed for a topic, item, space, or category, including duties inherited from parent entities. Answers “who owns this process” and “who should I ask about this”. Each duty says whether a person set it or the system suggested it (source, confidence).

Input	Type	Notes
entityType	string	One of TOPIC, ITEM, SPACE, CATEGORY. Required.
entityId	string	The entity id. Required.

list_issues

List the organization’s data-quality issues (conflicts, duplicates, content and structure gaps, stale or misclassified knowledge), most recent first.

Input	Type	Notes
status	string	OPEN, IN_PROGRESS, RESOLVED, or DISMISSED.
type	string	CONFLICT, DUPLICATE, MISCLASSIFICATION, STALE, CONTENT_GAP, STRUCTURE_GAP, or OTHER.
severity	string	CRITICAL, HIGH, MEDIUM, or LOW.
assignedToMe	boolean	Only issues assigned to the connected user, either directly or through a role they currently hold.
targetType	string	TOPIC, ITEM, SPACE, or CATEGORY. Use it with targetId.
targetId	string	Only issues that concern the topic, item, space, or category with this id.
search	string	Text to find in the title, the description, or a target’s title. The whole text has to appear, in that order, and case does not matter.
cursor	string	Pagination cursor from a previous response.
limit	number	Max issues, 1–100. Default 50.

The response is { issues, nextCursor }, the same shape as the other paged lists. Each issue says what raised it (trigger), and you pass nextCursor back as cursor to read the next page. Earlier versions returned the issues as a bare list with no way to reach a second page, so a client that read that list directly needs to read issues instead.

get_content_knowledge

List the topics a resource contributed knowledge to, with how many items came from it. Use to answer “what did we learn from this document” without reading the whole text.

Latest-only: archived and superseded records are excluded, so this is what the resource currently supports.

Input	Type	Notes
contentId	string	Content id, from search results or list_content.

get_content_usage

List what depends on a resource: the lessons that teach it, and the topics it is the only evidence for. Use before suggesting a change to a document — the sole-evidence topics are the ones that would lose their basis without it.

Lessons are limited to the ones you can see, and only lessons still teaching are counted: a withdrawn one is not. An external account is refused. Each list carries a true count plus a preview of at most 20 entries.

Input	Type	Notes
contentId	string	Content id, from search results or list_content.

list_third_parties

List the external organizations that hold duties in this knowledge base — vendors, contractors, regulators. They own areas of the work alongside internal roles.

Takes no inputs.

get_third_party

Read one third party. For what it answers for, use list_third_party_duties.

Input	Type	Notes
thirdPartyId	string	Third party id, from list_third_parties.

list_third_party_duties

List everything a third party answers for: each topic, item, space, or category it holds a duty on, the level, and whether the duty is inherited from an ancestor rather than assigned directly. Each duty also says whether a person set it or the system suggested it (source, with a confidence for a suggestion).

This is the holder’s side of get_duties, which instead names who owns a given topic. Limited to entities you can read, and needs raci-assignment.read as get_duties does.

Input	Type	Notes
thirdPartyId	string	Third party id, from list_third_parties.
entityType	string	Restrict to TOPIC, ITEM, SPACE or CATEGORY.
cursor	string	Pagination cursor from a previous response.
limit	number	Rows per page, 1–100. Default 50.

list_role_duties

List everything a role answers for, in the same shape as list_third_party_duties, and with the same raci-assignment.read requirement. Each row also carries how far the duty reaches across the role’s advancement path, so a duty covering only senior levels is distinguishable from one covering the whole role.

A duty on a topic inherits down to every item on that topic, so an unfiltered list is mostly item rows. Pass entityType: "TOPIC" for the summary a person would recognize.

Input	Type	Notes
companyRoleId	string	Company role id, from list_company_roles.
entityType	string	Restrict to TOPIC, ITEM, SPACE or CATEGORY.
cursor	string	Pagination cursor from a previous response.
limit	number	Rows per page, 1–100. Default 50.

list_categories

List the organization’s categories, with the titles and descriptions it uses itself. Categories are the top of the structure — a category holds spaces, a space holds topics, a topic holds items — so start here when you do not know where a subject lives.

Takes no inputs.

get_issue

Read one data-quality issue in full. Each target carries the affected content itself (an item target’s block type and text), so you can explain what conflicts, duplicates, or is stale rather than only naming it. Closed issues carry the resolution strategy.

Input	Type	Notes
issueId	string	Issue id, from list_issues.

Each target carries its own id.

get_issue_research_log

Read what the AI knowledge review has already looked at for an issue: each pass with its status, the searches it ran, whether it decided the knowledge base already covers the topic, and its summary. Use it before looking into an issue yourself, so you do not repeat what has been checked. Newest first.

Visible to whoever can read the issue.

Input	Type	Notes
issueId	string	Issue id, from list_issues. Required.

list_spaces

List the spaces the organization’s knowledge is grouped into. A category holds spaces, a space holds topics, so this is how to see the shape of the graph before drilling into it.

Input	Type	Notes
categorySlug	string	Restrict to one category, e.g. operations, hr, finance. An unrecognized slug is an error rather than a silent match-everything.

get_space

Read one space and the topics it groups. Topics are limited to those you can see, and to the current graph (nothing archived or superseded).

Input	Type	Notes
spaceId	string	Space id, from list_spaces.

list_content

List viewable content resources (documents, videos, audio, and guides), most recent first. Use to find a specific resource by name or browse a type. For questions about what the content says, use search_mereon instead.

Input	Type	Notes
query	string	Title keywords. Every word must appear in the title, any order, case-insensitive.
type	string	Restrict to one of document, video, audio, guide.
tags	string[]	Tag names from list_tags. A resource must carry every one. An invalid name is an error, and an external account may not filter by tag.
teamId	string	Content everyone can read, or that is shared to this team, an id from list_teams.
readyOnly	boolean	Only resources that are processed and indexed.
cursor	string	Pagination cursor from a previous response.
limit	number	Max resources, 1–100. Default 50.

Each resource says who can read it (visibility, teams), its tags, who uploaded it, and whether it is ready to teach from. A contribution still waiting in the review queue is not listed, whoever is asking.

list_tags

List the organization’s tags by name. They are the vocabulary list_content filters by and each resource’s tags are drawn from, so call this to learn which tags exist before filtering. An external account is refused. No inputs.

list_lessons

List lessons in the catalog (authored training units), most recent first. For the raw source videos and documents use list_content; for what the material says use search_mereon.

Input	Type	Notes
query	string	Text to find in the lesson title, case-insensitively.
tags	string[]	Tag names from list_tags. A lesson must carry every one. An invalid name is an error.
teamId	string	Lessons shared to this team, an id from list_teams. It has to be your team unless you can read the whole organization.
cursor	string	Pagination cursor from a previous response.
limit	number	Max lessons, 1–100. Default 50.

Each lesson says how thorough the teaching is, who it is shared with and its tags. Someone who manages lessons across the organization also sees how many people are enrolled (stats). It needs access to lessons, which an external account does not have.

get_lesson

Fetch one lesson in detail: its metadata, who it is shared with, its tags and the source content pieces it teaches, in order, limited to the ones you can read. stats (how many people are enrolled, in progress and finished) is shown only to someone who may manage the lesson. A withdrawn lesson reports status CLOSED, and closedByRetirement when it closed because its topic was retired. A lesson made for one learner or from a review is not in the catalog and is not found.

Input	Type	Notes
lessonId	string	The lesson id. Required.

get_lesson_topics

List the topics a lesson covers, in the order it teaches them, each with whether the author picked it (EXPLICIT) or it follows from the resources they picked (DERIVED). Only live topics you can read are listed, so a lesson closed because its topic was retired covers nothing. Each is a name and a link; read its items with get_topic_items. Not paginated.

Input	Type	Notes
lessonId	string	The lesson id, from list_lessons. Required.

get_lesson_retraining_policy

Get how often people who finished a lesson are asked to take it again: none or recurring with an interval in days, and whether that means the whole lesson (full_retake) or what changed (changed_material). policy is null when none was set, which is not the same as no retraining: the organization’s default applies, and a company role’s curriculum can override either, which get_company_role reports as the item’s retrainingOverride. Needs access to enrollments, and the lesson has to be one you can see.

Input	Type	Notes
lessonId	string	The lesson id, from list_lessons. Required.

list_company_roles

List the organization’s company roles (named org-chart positions), sorted alphabetically by name. Each result carries how many people hold the role and the role it reports to. Available only when the connected user can read the org chart.

Input	Type	Notes
query	string	Case-insensitive match on the role name.
cursor	string	Pagination cursor from a previous response.
limit	number	Max roles, 1–100. Default 50.

get_company_role

Fetch one company role in detail: its reporting parent and member count, its training curriculum (the lessons and topics everyone in the role must complete), and its current members.

Input	Type	Notes
companyRoleId	string	The company role id. Required.

list_content_review_requests

List content-review requests — proposed content and issue-resolutions awaiting (or past) review. A reviewer sees the whole organization’s queue; everyone else sees only their own submissions (pass mine=true to force that). Requires content-review read access.

Input	Type	Notes
status	string	PENDING, APPROVED, REJECTED, CHANGES_REQUESTED, CANCELED, or SUPERSEDED.
resourceType	string	document, video, audio, or guide.
kind	string	content, content-resolves-issue, or issue-only.
submitterId	string	Reviewers only: restrict to one submitter.
mine	boolean	Only the connected user’s own submissions.
cursor	string	Pagination cursor from a previous response.
limit	number	Max requests, default 50 (max 100).

get_content_review_ontology_plan

Get what approving a content-review request would do to the knowledge base before anyone decides: the topics and claims it would add, change or retire. state says whether there is a plan to read: not-requested, working (waiting will help), failed (waiting will not), or ready, and only ready carries a plan, which may still propose no changes. Use it to judge a proposal by its effect and not only its wording.

A reviewer can read any request in the org; everyone else only their own. Requires content-review read access.

Input	Type	Notes
requestId	string	The content-review request id, from list_content_review_requests. Required.

get_content_review_request

Fetch one content-review request by id: its workflow state, the content or issue it concerns, the submitter and reviewer, and any notes. A reviewer can read any request in the org; everyone else only their own.

Input	Type	Notes
requestId	string	The content-review request id. Required.

get_maturity

Get the organization’s knowledge-base maturity: its level (UNDOCUMENTED → OPTIMIZED), the signals behind it (topic ownership, structured content, verification cadence, category coverage, open issues), and ranked recommendations for what to improve next. Readable by any member who can read the organization.

Input	Type	Notes
categorySlug	string	Scope to one category (e.g. operations, hr). Omit for org-wide maturity.

list_category_health

List every category (always 14) with its maturity level, or null when the category has too few topics to score. The “which areas are weakest” overview. Readable by any member who can read the organization. No inputs.

find_people

Find members of the organization by name or email, and get the id a write needs. The person to tell in add_announcement_audience (actorType INDIVIDUAL) is named by the id this returns. Each match is an id, a name and an email. It includes members who hold no role and are on no team, which the org chart and team rosters leave out. An admin sees everyone, and a team-scoped user sees their teams.

Input	Type	Notes
query	string	Matches anywhere in the name or email, case-insensitively.
limit	integer	At most this many people, 1 to 50. Defaults to 25. There is no cursor, so narrow with query.

list_teams

List the organization’s teams and their current members, and get the id a write needs. The team to tell in add_announcement_audience (actorType TEAM) is named by the id this returns. Each member is an id, a name and an email. An organization admin sees every team, a team admin sees their own, and anyone else sees none. Not paginated. No inputs.

list_members

List the organization’s people, as the members page does: each person’s role, whether they are active or have left, their teams and company roles and, for an organization admin, who they report to. Active people unless status says otherwise, ordered by name, with a total. Use it to answer “who is on the team”, “who holds this company role”, or “who has left”, or to find the id get_member and get_user_progress take. To find one person by name, find_people is cheaper.

An owner, admin or billing admin reads everyone. Anyone else is shown only themself, and an external account is refused. noManager and the organization-only fields are for an organization admin. Limited to 30 calls a minute.

Input	Type	Notes
query	string	Text to find in the name or email. The whole text has to appear in one of them, and case does not matter.
status	string	active (the default), deactivated, or all.
teamId	string	Only members of this team, an id from list_teams.
noManager	boolean	Only people with no manager. Organization admins only.
cursor	string	Pagination cursor from a previous response.
limit	number	Max members, 1–100. Default 50.

get_member

Get one person in the organization, at any status: their role, teams, company roles and, for an organization admin, their manager, phone and when they left. An owner, admin or billing admin may open anyone with a record here. Anyone else may open only themself and is told anyone else was not found, which is also the answer for an id from another organization. An external account is refused.

Input	Type	Notes
memberId	string	The person’s user id, from list_members or find_people. Required.

list_pending_invitations

List the invitations that have been sent and not yet accepted, newest first, with the role each person will have when they accept. Expired invitations are included and marked. Use it to answer “who have we invited but not heard from”. An invitation has no id here, because the id is what its public accept page is addressed by. Organization admins only. No inputs.

list_member_progress

List each person with how much training they have: their lesson enrollments, pop quizzes and last review, as the progress page does. People who have left are included, because this is a record of who was trained, and someone loaded in bulk who has never signed in is not listed until they do. For how one person is doing, with completion and overdue counts, use get_user_progress.

An organization admin sees every row. Anyone else sees their own, and an external account is refused. Limited to 30 calls a minute.

Input	Type	Notes
query	string	Text to find in the name or email. The whole text has to appear in one of them, and case does not matter.
teamId	string	Only members of this team, an id from list_teams.
cursor	string	Pagination cursor from a previous response.
limit	number	Max people, 1–100. Default 50.

list_reporting_lines

List each person and the manager they have been given. This is the reporting line, not the role tree: two people who share a title are not each other’s managers. reportsTo is null for someone with no manager, a manager who has left is still named with their status, and a manager the organization records without an account has a null id and name. Use noManager for “who has no manager”, and get_org_chart for the chart of roles.

Organization admins only. Limited to 30 calls a minute.

Input	Type	Notes
status	string	active (the default), deactivated, or all.
noManager	boolean	Only people with no manager.
cursor	string	Pagination cursor from a previous response.
limit	number	Max people, 1–100. Default 50.

get_me

Describe this connection: the person it acts as, their organization with its time zone, the token behind it and when it expires, the product features the organization has, and what the person may do. Use it to learn what you can and cannot do before trying, and the organization’s time zone to read a date it means as local. The time zone is null when the organization has not set one. No inputs.

list_findings

List what the organization has told Mereon to treat as true about itself, newest first: facts an admin wrote and ones the system recorded from the organization’s website or a research conversation. The AI features read them as established fact, so this is where to look when an answer assumes something about the organization. Each says whether a person or the system wrote it; who wrote it is not returned.

Needs the access an organization admin has (owners, admins and billing admins); anyone else is refused.

Input	Type	Notes
cursor	string	Pagination cursor from a previous response.
limit	number	Max findings, 1–100. Default 50.

get_org_chart_verification

Get whether an admin has confirmed the org chart recently: never_verified, current, or reverification_due, when it was last confirmed and when the next confirmation is due. Confirmations are every 90 days. Use it for “is our org chart up to date”. Who confirmed it is not returned. Needs access to the org chart. No inputs.

get_directory_sync

Get the organization’s connection to its identity directory (SCIM): its status, when the directory last authenticated and last changed something, whether it paused itself and why, and how many people it has provisioned, updated, deactivated and skipped. eligible says whether the plan includes it; a lapsed organization can still read what the directory did. The token is not returned, not even its display prefix. Needs the access an organization admin has; anyone else is refused. No inputs.

list_directory_sync_events

List what the identity directory has done to the organization’s people, newest first: each operation, whether it was applied, skipped, rejected or failed, and why, with the address the directory’s request named. Use it to answer “why was she not provisioned” or “what failed overnight”. The sentence the app prints, the directory’s own id for the person and the employee record are left out. Pass the cursor from the last response to read the next page. Needs the access an organization admin has; anyone else is refused.

Input	Type	Notes
outcome	string	Only events with this outcome: APPLIED, SKIPPED, REJECTED, or FAILED.
cursor	string	The cursor from the previous response.
limit	number	Max events, 1–100. Default 50.

get_org_chart

Get the organization chart: every position with the role it reports to, the people who currently hold it, and whether it is vacant. Someone who has left does not count as holding a role, so a seat only they held reads as vacant. Rebuild the tree from each role’s reportsToRoleId. Use it for “who holds this role?” and “which roles are unfilled?”. This is the chart of roles, and who answers to whom is a different question, which get_my_reporting_line answers for the connected user. Needs access to the org chart (company-role.read). Not paginated. No inputs.

get_my_reporting_line

Get the connected user’s place in the organization: the roles they hold, who they report to (at most one person), and who reports directly to them. People come from the manager each person has been given and not from the role tree, so two people who share a title are not each other’s managers. Only people who are currently employed are listed. Needs access to the org chart (company-role.read). No inputs.

get_user_progress

Get another person’s training progress: the lessons they are enrolled in, each with completion and score, the obligations they have been assigned, each with a due date and whether it is overdue, and a roll-up count. Use it for “how is Maria doing on her training?”.

The rule is whatever the app applies to those two lists. You can read your own, and an organization admin can read anyone’s. A manager cannot, because the app’s own lists refuse them for a report; use get_user_learning_queue for a report instead. Anyone you may not read is reported as not found, as is a person from another organization. A person who has left is found, because the app keeps their record and an audit asks for it. For your own training, use list_my_enrollments and list_my_obligations.

Input	Type	Notes
userId	string	The person’s id, from find_people, list_teams or get_org_chart. Required.

get_user_learning_queue

Get the ranked list of topics a person should study next: why each is queued (NEW, PARTIAL, RETRAINING or DEEPEN), its priority, any due date and whether it is overdue, whether an unfinished prerequisite blocks it, and a lesson to start from. Use it for “what is Maria behind on?” or “who has overdue training?”. The result also names the person.

The rule is the one the app applies to a person’s learning queue. You can read your own, an organization admin can read anyone’s, and anyone else can read the people who report to them, directly or further down the org chart. The reporting line is the manager each person has been given, not the role tree. Anyone you may not read is reported as not found, as is a person from another organization. A person who has left has an empty queue. Topics are limited to what you can read, but lessons assigned to the person are listed by title either way. For your own queue, use get_my_learning_queue. It is worked out from scratch on every call, so it is limited to 20 calls a minute, and so is get_my_learning_queue.

Input	Type	Notes
userId	string	The person’s id, from find_people, list_teams or get_org_chart. Required.
cursor	string	Pagination cursor from a previous response.
limit	number	Max entries, 1–100. Default 50.

Your own training

The tools below read the connected user’s own training. None of them takes a person as an input, so there is no way to use them to read a colleague’s record. They need only the read scope.

list_my_obligations

List the training the connected user has been assigned: lessons, topics and items, each with its due date, whether it is required, whether it is overdue, and whether it is still active or completed. Cancelled and waived obligations are administrative states and are not returned. Not paginated. No inputs.

list_my_enrollments

List the lessons the connected user is enrolled in, newest first, each with whether it is completed or in progress, the score where one is recorded, and any due date. The id of an enrollment is what get_quiz_results takes. Not paginated. No inputs.

list_my_pop_quizzes

List the pop quizzes assigned to the connected user, each with its prompt, due date, and the connected user’s own status and score. It never shows how anyone else did. A pop quiz’s id is what get_pop_quiz takes. Not paginated. No inputs.

list_pop_quizzes

List the organization’s pop quizzes, newest first, each with who sent it, how many people it went to and how many have finished. Use it to find the id get_pop_quiz takes, which is how you read how each recipient did. It needs organization-wide access to pop quizzes, which owners, admins and billing admins have. Anyone else is refused, and list_my_pop_quizzes lists the ones sent to them. A pop quiz that certifies an announcement carries its announcementId.

Input	Type	Notes
sentByMe	boolean	Only the pop quizzes the connected user sent.
cursor	string	Pagination cursor from a previous response.
limit	number	Max pop quizzes, 1–100. Default 50.

get_my_learning_queue

Get the ranked list of topics the connected user should study next, the same queue as their dashboard. Each entry says why it is queued (NEW, PARTIAL, RETRAINING or DEEPEN), its priority, any due date and whether it is overdue, whether an unfinished prerequisite blocks it, and a lesson to start from when one exists. total counts the whole queue. The queue is recomputed on every call, so entries can shift between pages.

Input	Type	Notes
cursor	string	Pagination cursor from a previous response.
limit	number	Max entries, 1–100. Default 50.

get_quiz_results

Get the per-question results of the quizzes on one lesson enrollment: for each question, whether the learner got it right, the answer they gave, the correct answer and the explanation, plus the overall score and summary. A learner reads their own. Anyone else needs the review access the app asks for before it shows an enrollment’s answers, which only owners, admins and billing admins have, and a manager does not. Anyone else is told it was not found. The correct answer and explanation are withheld for a question that has not been answered yet, for a reviewer as well as the learner.

Input	Type	Notes
lessonEnrollmentId	string	The id of an entry from list_my_enrollments. Required.

get_pop_quiz

Get one pop quiz with its recipients and how each did: who it went to, whether they finished, and their score, plus how many finished. An owner, admin or billing admin sees every recipient. A recipient sees the pop quiz they were sent with only their own row. Anyone else is told it was not found. Ids come from list_pop_quizzes, which is for admins, and from list_my_pop_quizzes, which lists the ones sent to the connected user.

Input	Type	Notes
popQuizId	string	The id of an entry from list_pop_quizzes or list_my_pop_quizzes. Required.

Announcements

An announcement tells people something has changed and makes the knowledge base agree with what was said. See Announcements for the model: who may read one is separate from who is told, and sending is not a single call.

The author’s tools below need announcement access, which admins, owners and billing admins have.

list_announcements

List the organization’s announcements, in every state from draft to retracted. Each one gives its title, status, who it is for, what it says, and whether it asks recipients to take a pop quiz. This is the author’s view. To read one you were sent, use read_announcement.

Input	Type	Notes
status	string	Only announcements in this state: DRAFT, PLANNING, PLANNED, IN_REVIEW, READY, SENDING, SENT, FAILED or RETRACTED.

get_announcement

Fetch one announcement as its author sees it: what it says (resolved from the topics, items and resources it draws on), the selections and audience it was built from, whether it asks for a pop quiz, and where it is in its life. Selection and audience entry ids come from here.

Input	Type	Notes
announcementId	string	The announcement id. Required.

get_announcement_plan

The changes to the knowledge base that sending an announcement would make (items added, superseded or retired, topics added or superseded), and which of them the author has excluded. plan is null until planning has been started.

Input	Type	Notes
announcementId	string	The announcement id. Required.

get_announcement_delivery

How far a send got: how many people were addressed, how many could not be told, how many are still outstanding, and how many failed. delivery is null until it has been sent.

Input	Type	Notes
announcementId	string	The announcement id. Required.

get_announcement_pop_quiz

For an announcement that asked recipients to take a pop quiz on what it says: who has taken it, whether they finished, and their score. popQuiz is null when it did not ask.

Input	Type	Notes
announcementId	string	The announcement id. Required.

get_announcement_retraction_preview

What retracting a sent announcement would undo, which of those changes cannot be undone (an issue is filed for each instead), and how many people would be told it was withdrawn. canRetract is false once the 48-hour window has closed.

Input	Type	Notes
announcementId	string	The announcement id. Required.

read_announcement

Read a sent announcement as its audience does: the title, who wrote it, when it was sent and what it says. Works for anyone the announcement was visible to, with no announcement access needed, unlike get_announcement, which is the author’s view of one in any state. A draft, or one you cannot see, is not found.

Input	Type	Notes
announcementId	string	The announcement id. Required.

Changing announcements

These need a connection granted the announcement:write scope, and the person behind it must hold the matching permission, checked on every call. Each one is recorded in the audit log against the announcement. A tool that loses something or sends it is marked so an assistant can ask before running it.

create_announcement

Start a draft announcement. Nothing is required up front. Then say what it says, choose who may read it and who is told, plan it, and send it. Nothing reaches anyone until send_announcement. Needs announcement.create.

Input	Type	Notes
title	string	The title recipients see. Can be empty while drafting; sending needs one.
everyone	boolean	True if everyone in the organization may read it, false for admins only. This is who can see it, not who is told.

update_announcement

Change a draft: its title, who may read it, and whether recipients are asked to take a pop quiz confirming they understood it. Sending needs everyone and requiresPopQuiz each chosen, true or false. The title and everyone can only change while it is a draft, so call reopen_announcement first if it has been planned.

Input	Type	Notes
announcementId	string	The announcement id. Required.
title	string	The new title.
everyone	boolean	True if everyone may read it, false for admins only.
requiresPopQuiz	boolean	True to ask recipients to take a short pop quiz confirming they understood it.
popQuizDueDate	string | null	ISO 8601 date-time the pop quiz is due, with any UTC offset, in the future. null returns to the default window.

delete_announcement

Permanently delete a draft. Anything past draft is refused: reopen a planned one first, and withdraw a sent one with retract_announcement. Needs announcement.delete.

Input	Type	Notes
announcementId	string	The announcement id. Required.

set_announcement_text

Set the text the author wrote for a draft, as opposed to what is drawn from the library. Calling it again replaces the earlier text, and an empty body clears it.

Input	Type	Notes
announcementId	string	The announcement id. Required.
body	string	The announcement text. Required.
title	string	A name for the text. Defaults to the announcement’s title.

add_announcement_content

Draw on something already in the knowledge base so the announcement says what the knowledge base says: a whole resource, a topic, or a single item.

Input	Type	Notes
announcementId	string	The announcement id. Required.
kind	string	RESOURCE, TOPIC or ITEM. Required.
targetId	string	The content id, topic id or item id, matching kind. Required.

remove_announcement_content

Take something out of a draft. With only selectionId it removes that whole selection. With itemId as well it keeps the selection and leaves just that item out.

Input	Type	Notes
announcementId	string	The announcement id. Required.
selectionId	string	The selection id, from get_announcement. Required.
itemId	string	Leave just this item out instead of removing the whole selection.

add_announcement_audience

Choose who a draft is told to. An audience wider than who may read the announcement is refused, and third parties cannot be added.

Input	Type	Notes
announcementId	string	The announcement id. Required.
actorType	string	INDIVIDUAL, TEAM, ROLE, ROLE_KIND or ORGANIZATION. Required.
actorId	string	For INDIVIDUAL a user id (an active member), for TEAM or ROLE the team or company role id, for ORGANIZATION the organization id, for ROLE_KIND INTERNAL or EXTERNAL. Required.

remove_announcement_audience

Take an entry out of a draft’s audience.

Input	Type	Notes
announcementId	string	The announcement id. Required.
audienceId	string	The audience entry id, from get_announcement. Required.

plan_announcement

Start working out which knowledge-base items and topics sending would add, supersede or retire. The announcement needs its own words first, because every change the plan proposes cites them. It runs in the background and returns at once with the announcement in PLANNING; poll get_announcement_plan until the plan appears. send_announcement is refused until this has been done.

Input	Type	Notes
announcementId	string	The announcement id. Required.

set_announcement_change_excluded

Decide whether one planned change is left out of what sending does. State the outcome rather than toggling, so repeating the call is safe.

Input	Type	Notes
announcementId	string	The announcement id. Required.
sequence	number	The change’s sequence, from get_announcement_plan. Required.
excluded	boolean	True to leave the change out, false to put it back. Required.

preview_announcement_notification

Show what the email and text will say and how many people they would go to, without sending anything. willBeTold is the number of people a send would tell right now: pass it as expectedRecipientCount to send_announcement. It writes the opening line if there is not one yet, so the sentence previewed is the sentence delivered.

Input	Type	Notes
announcementId	string	The announcement id. Required.

send_announcement

Tell the audience by email and text, publish what the plan changes, and make the announcement readable. This reaches real people, and can be withdrawn for 48 hours, which tells everyone. Send only when the person has explicitly asked, after they have seen the plan and the notification. Refused until the announcement has been planned, has a title, has had everyone and requiresPopQuiz chosen, and has an audience. Having a plan does not mean anyone has read it, so pass expectedRecipientCount: a send that would now tell a different number of people is refused and nothing goes out. Returns at once with the announcement in SENDING; follow it with get_announcement_delivery. Calling it again on a FAILED send finishes it. Limited to five calls a minute and thirty an hour.

Input	Type	Notes
announcementId	string	The announcement id. Required.
expectedRecipientCount	integer	The number of people you expect it to tell: willBeTold from preview_announcement_notification. If it would now tell a different number, nothing is sent. It is checked when the call is accepted, so it guards against a stale preview and not against a change in the seconds before delivery starts.

retract_announcement

Within 48 hours of sending, undo what the announcement changed in the knowledge base and tell everyone the send attempted that it was withdrawn. Changes that cannot be undone are left, with an issue filed for each. Call get_announcement_retraction_preview first and show the person what it would do.

Input	Type	Notes
announcementId	string	The announcement id. Required.

reopen_announcement

Take a planned announcement that has not been sent back to editing, so its words, title or content can change. The plan is kept until you change what the announcement says or draws on, and a plan that survived can be sent as it is. After such a change, plan it again.

Input	Type	Notes
announcementId	string	The announcement id. Required.

Adding documents and videos

These add content to the organization’s library. They need a connection granted the content:write scope, and the person behind it must be allowed to add that kind of content, checked on every call. They create and never edit: none of them changes something that already exists. See Creating documents and YouTube videos for the full rules.

Every one takes a visibility, which is the person’s choice: an assistant should ask rather than assume everyone. For a document it also decides whether it publishes or goes to an administrator for review, and the result says which in mode. Each one is recorded in the audit log, and each is limited to 10 calls a minute and 100 an hour. Sending for review is held lower, because every proposal emails the administrators: 3 a minute and 20 an hour for one person, across every connection and the REST API together.

create_document_from_scratch

Write a new document into the library from a title and a markdown body. If the person may publish to the visibility named, it is published (or kept as a draft with asDraft); otherwise it goes to review. Returns mode, draft, contentId, reviewRequestId, title and url. draft: true means the document exists and is not live: do not create it again. Needs document.create, or content-review.create to submit for review.

Input	Type	Notes
title	string	Required. Up to 255 characters, on one line.
content	string	The whole document, in markdown, up to 500,000 characters. Required.
visibility	string	everyone, teams or admins. Required.
teamIds	string[]	Team ids from list_teams, with teams only.
asDraft	boolean	Leave it unpublished, for someone to look over and publish in Mereon. Ignored when it goes to review.

create_document_from_url

Fetch a public page or file, such as a PDF, and add it to the library as a document. Publishes or goes to review on the same rule, and returns the same fields. Addresses on a private network and video sites are refused. Needs document.create, or content-review.create to submit for review.

Input	Type	Notes
url	string	An http or https address. Required.
visibility	string	everyone, teams or admins. Required.
teamIds	string[]	Team ids from list_teams, with teams only.

add_youtube_video

Add a YouTube video to the library by its link. There is no review lane, as in the app: it needs video.create, and the visibility has to be one the person may publish to. Returns contentId, alreadyInLibrary, title and url. For a video already in the library, alreadyInLibrary is true, nothing is created, and its visibility is left as it was; if the person cannot see that video, its contentId, title and url are null. title is also null for a new import until processing reads it from YouTube.

Input	Type	Notes
url	string	A YouTube watch, share or shorts link. Required.
visibility	string	everyone, teams or admins. Required.
teamIds	string[]	Team ids from list_teams, with teams only.

Assigning training

These decide what people owe. They need a connection granted the training:assign scope, and the person behind it must be allowed to do the act, checked on every call. An organization admin reaches anyone, a team admin the people on teams they administer, and only an organization admin may excuse someone or move a due date. See Assigning training for the full rules.

Several reach real people by email and text. An assistant should only call them when the person asked, and confirm who they go to first. Each is recorded in the audit log. assign_training and unassign_training are limited to 10 calls a minute and 60 an hour, create_pop_quiz to 5 and 30, and the rest to 30 and 300.

Obligation ids come from get_user_progress (another person’s) or list_my_obligations (your own). The obligation tools return the obligation as it stands after the change: id, userId, itemType, itemId, status, required, dueDate, dueDateOverridden and needsReview.

assign_training

Require a lesson of everyone, of the people on some teams, or of named people, optionally with a deadline. Each person it newly reaches gets the lesson, a quiz prepared for them, and an email and text. Returns lessonId, title and assigned, one { userId, enrollmentId } per person newly reached; people who already had it are not listed. Needs lesson-enrollment.create.

Input	Type	Notes
lessonId	string	From list_lessons. Required.
audience	string	everyone, teams or users. Required.
teamIds	string[]	Team ids from list_teams, with teams only.
userIds	string[]	Person ids from find_people, with users only. Up to 500.
dueDate	string	Due at this moment, ISO 8601 with a UTC offset.
dueInDays	integer	Due this many days after it is assigned, 1 to 3,650. Give at most one of dueDate and dueInDays.

unassign_training

Take a lesson back from named people. Their enrollment in progress is removed with their progress in it, and the requirement is cancelled; a completed enrollment is kept. Only an organization admin may take back a lesson that is required of someone. Returns lessonId, title and removedCount. Needs lesson-enrollment.delete.

Input	Type	Notes
lessonId	string	Required.
userIds	string[]	Person ids from find_people. Required.

set_retraining_policy

Set how often people who completed a lesson must take it again, or turn that off. Needs permission to edit that lesson. Returns the policy as get_lesson_retraining_policy does.

Input	Type	Notes
lessonId	string	Required.
retrainingType	string	recurring, or none. Required.
intervalDays	integer	Days between retakes, 1 to 3,650. With recurring only.
completionMode	string	full_retake or changed_material. With recurring only.

assign_knowledge_obligation

Require one person to learn a topic or a knowledge item. They must hold a duty on it, directly or through a role or team; the level they must reach follows from that duty. Returns the obligation. Needs lesson-enrollment.create.

Input	Type	Notes
userId	string	From find_people. Required.
itemType	string	topic or item. Required.
itemId	string	Required.
dueDays	integer	Days from now until it is due, 1 to 3,650.
reason	string	Up to 2,000 characters.

assign_manual_retraining

Require one person to take a lesson again within a number of days, and tell them. Returns the obligation. Needs lesson-enrollment.create.

Input	Type	Notes
userId	string	Required.
lessonId	string	Required.
dueDays	integer	1 to 3,650. Required.
retrainingResetsClock	boolean	Whether completing it counts as their next scheduled retake. Required.
reason	string	Up to 2,000 characters.

waive_obligation

Excuse a person from something they owe, as a deliberate exception. For a lesson they are told. It cannot be undone. Returns the obligation, now waived. Needs lesson-enrollment.update, at organization scope in practice.

Input	Type	Notes
obligationId	string	Required.
reason	string	Why, kept on the record. Required.

cancel_obligation

End a requirement that was assigned by mistake or no longer applies. For a lesson the person is told, and their enrollment is left as it is. Returns the obligation, now cancelled. Needs lesson-enrollment.update, at organization scope in practice.

Input	Type	Notes
obligationId	string	Required.
reason	string	Why, kept on the record. Required.

override_obligation

Set the due date a person sees on something they owe, by hand, or pass null to take that override off. For a lesson, setting a date tells the person. Returns the obligation. Needs lesson-enrollment.update, at organization scope in practice.

Input	Type	Notes
obligationId	string	Required.
dueDate	string | null	ISO 8601 with a UTC offset, or null. Required.

confirm_obligation_review

Settle an obligation flagged needsReview at the date given, or with none, and clear the flag. Returns the obligation. Needs lesson-enrollment.update, at organization scope in practice.

Input	Type	Notes
obligationId	string	Required.
resolvedDueDate	string | null	ISO 8601 with a UTC offset. Leave out or null for none.

create_pop_quiz

Send a short quiz on a video, document or guide to everyone, to some teams, or to named people. Questions are written for each person after this returns, and each is told by email and text once theirs are ready; follow it with get_pop_quiz. Every recipient must be able to see the content. If its questions cannot be started, nothing is created and it is safe to try again. Returns id, title, dueDate and url. Needs pop-quiz.create at organization scope.

Input	Type	Notes
contentId	string	A video, document or guide. Required.
audience	string	everyone, teams or users. Required.
teamIds	string[]	With teams only.
userIds	string[]	With users only.
dueDate	string	ISO 8601 with a UTC offset, in the future. Required.
difficulty	string	SIMPLE, MODERATE, CHALLENGING or ADVANCED.

Note

Tools return the same data as their REST equivalents, scoped to what the connected user can see and always reflecting the latest state of the knowledge base. See Lifecycle & history for how superseded and archived records are handled.