MCP tools reference

The MCP server exposes three kinds of tools: documentation search, the JobMojito API (auto-generated from the OpenAPI spec, one tool per endpoint with a curated name), and merchant selection. Tool descriptions are prefixed with a [Category] label so agents can group them.

​

Docs-first calling pattern

The server’s instructions ask agents to understand before acting:

1. To learn how an endpoint, field or workflow behaves, search_documentation is faster and more reliable than experimenting; get_documentation(url) then reads the page in full. Calling action tools speculatively just to discover their inputs is the slow path.
2. search_documentation is a single entry point: one call searches both this developer/API reference and the help center in parallel.
3. For multi-step work, search for a step-by-step cookbook and follow it rather than chaining tools by trial and error.
4. Prefer the read-only list tools to look things up before creating or changing anything.

​

Read-only vs. state-changing

Every tool carries standard MCP annotations, so a client knows whether it can run without asking you first:

• readOnlyHint: true — only reads. All list_* and get_* tools, plus the documentation tools and the merchant picker. Most clients run these without a confirmation prompt.
• destructiveHint: true — creates, changes or sends something. Everything else, including report generation and link creation, which consume credits or produce shareable artifacts. Clients should ask before running these, and you should let them.

Any newly added endpoint is treated as state-changing until it is explicitly curated, so the safe default is never the silent one.

​

Documentation

​

Configuration / merchants

Pass the chosen merchant_id on subsequent calls; omit it to act on your own account. See Merchant scoping.

​

Interview — create & manage

Read before you write: questions is replaced wholesale, so call get_interview_definition first, edit the array it returns, and send the whole list back — there is no per-question call. Keep each question’s id on the ones you did not mean to change; that is what marks a question as unchanged. It is applied as a diff, matched on external_id, then id, then identical content. Unchanged questions keep their existing record (and with it their answer rules and any rendered avatar video); an edited one is unlinked and re-created; one you dropped is unlinked. Nothing is ever deleted — questions are shared records, so removal only unlinks them from this interview. questions_diff in the response reports exactly what was decided. Re-sending an unchanged array is a no-op — no write happens at all — so the read → edit → write loop is safe to repeat, and safe to run when you are not sure anything changed. Questions of an active interview can only be changed on the interactive avatar templates (where re-publishing is instant); on offline_* set status to draft first. Full walkthrough: Edit interview questions.

​

Coaching catalogue

Coaching-platform only. The catalogue is a tree of directories; each directory is one page at /catalogue/<id> on the merchant’s coaching portal. Read before you write: content_md, tags_sub and tags_interview_set_filter are replaced wholesale, so fetch the current value with get_catalogue_directory and send the extended list — not just your additions. Two fields do the real work:

• tags_interview_set_filter selects the sessions. A coaching or persona session appears in the directory when the session’s own tags contain every tag in this list (an AND, not an OR), it is active, and its visibility is public or merchant_public. Set the matching tags on the session with create_interview, create_interview_from_questions, create_persona or update_interview.
• content_md turns the directory into a custom page. With it set, your Markdown replaces the default grid and decides the layout; leave it null for the plain grid. These directives each go alone on their own line:

  Directive	Renders
  [plan-progress]	The learner’s coaching-plan progress.
  [directory:<tag-id>]	A card for one sub-directory.
  [session:<interview-id>]	A card for one session.
  [sessions]	Every session in this directory.
  [sessions:<term>]	Sessions matching a term.
  [sessions:filter=<term>,limit=<n>]	A filtered, capped list.

​

Results & reports

​

Knowledge base

​

Merchant lists (read-only)

​

Not exposed as MCP tools

A few endpoints are intentionally excluded from the MCP surface (they’re administrative or one-shot flows not suited to general agent use) but remain fully available over the HTTP API: bulk invite-users, create-for-candidate-with-token, and the pre-screening endpoints (pre-screening-create, resume text/binary pre-screen). Call these directly with a bearer token when you need them.

​

Result size

Tool results are capped so a client never receives a silently truncated response. If a call exceeds the limit it returns an error asking you to narrow the request rather than a half-complete answer — page with limit and offset, or filter by merchant_id, a date range or a status.

​

Identifiers & admin links

Which id goes in which field is the most common source of errors — and the same interview id is named interview_def_set_id, position_id, or interview_id depending on the endpoint. See Identifiers & admin links for the full id glossary, the “same id, different field name” tables, the admin app link patterns, and how to resolve an id from a name. The MCP server’s own instructions point agents at that guide before they pass an unfamiliar id.