MCP tools reference - JobMojito Developer / Agent

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:

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.
search_documentation is a single entry point: one call searches both this developer/API reference and the help center in parallel.
For multi-step work, search for a step-by-step cookbook and follow it rather than chaining tools by trial and error.
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

Tool	Purpose
`search_documentation`	Search developer docs + help center in parallel. Read-only.
`get_documentation`	Fetch a documentation page by URL. Read-only.

Configuration / merchants

Tool	Purpose
`jobmojito_configuration`	Interactive, searchable merchant picker (UI clients). Run it whenever a `merchant_id` is needed but none is selected.
`list_my_merchants`	Text list of your merchants (supports a `search` filter) — the fallback for non-UI clients.

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

Interview — create & manage

Tool	Endpoint	Purpose
`create_interview`	`POST /job-interview-create`	Create an interview with AI-generated questions from a job description.
`create_interview_from_questions`	`POST /job-interview-create-from-array`	Create an interview from your own array of questions.
`create_persona`	`POST /persona-create`	Create a role-play (avatar plays a defined role; no AI question generation). Set `portal` deliberately — `interview` for assessing/screening candidates (recruiter-visible, invited, merchant-billed); `coaching` is the default and creates a coaching-portal practice persona instead. Also set `welcome_message`, `thank_you_message` and `candidate_expectations`, which otherwise fall back to generic defaults, and `persona_avatar_progress` — without it the avatar has no arc and tends to either concede immediately or never concede at all.
`get_interview_definition`	`POST /job-interview-get`	Fetch an interview’s definition/configuration.
`update_interview`	`POST /job-interview-update`	Change the settings of an existing interview or position — name, description, avatar template, recording, scoring, tags and the rest. Only the fields you send are written. Questions are out of scope, and so are the welcome / thank-you messages (stored as questions) and the language (the questions are already written in it).
`set_interview_state`	`POST /job-interview-set-state`	Change lifecycle state / manage the iframe embed key.
`generate_interview_url`	`POST /job-interview-token`	Generate a signed public interview URL.
`request_another_interview_attempt`	`POST /job-interview-result-request-another-attempt`	Re-open a submitted result so the candidate can retry. Grants an attempt even past the `interview_attempts` cap.
`register_users_for_interview`	`POST /job-interview-register-users`	Register candidates for an interview and get their links (batch, per-row results).

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.

Tool	Endpoint	Purpose
`list_catalogue_directories`	`GET /catalogue-tag-list`	Find directories: search by text, filter by language/status/visibility, or pass `parent_tag` to list one directory’s children in display order. `is_start_directory` marks the catalogue’s root.
`get_catalogue_directory`	`GET /catalogue-tag-get`	One directory in full — its `content_md`, its resolved sub-directories, and the sessions its tag filter currently matches, which is how you check a session really landed in it.
`create_catalogue_directory`	`POST /catalogue-tag-create`	Create a directory. Pass `parent_tag` to nest it under an existing one.
`update_catalogue_directory`	`POST /catalogue-tag-update`	Rename a directory, re-point which sessions it lists, re-order its sub-directories, or author its custom page.

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

Tool	Endpoint	Purpose
`get_interview_result_details`	`POST /job-interview-details`	Full result with transcript and AI analysis.
`generate_interview_report`	`POST /job-interview-pdf`	Generate an HTML / PDF / JSON report for a completed interview.

Knowledge base

Tool	Endpoint	Purpose
`upload_knowledge_base_document`	`POST /knowledge-base-document-upload`	Upload a document the AI can draw questions/context from.

Merchant lists (read-only)

Tool	Purpose
`list_interviews`	List the merchant’s interview definitions.
`list_candidates`	List candidates.
`list_interview_results`	List interview results.
`list_avatars`	List available interviewer avatars.
`list_sub_merchants`	List sub-merchants you manage.
`get_merchant_analytics`	Fetch merchant daily event analytics.
`get_merchant_status`	Status snapshot: credit balances, subscription, pending-work counts, candidate/result totals, and invitation headroom.
`get_merchant_credit_usage`	Fetch the merchant’s credit usage.
`list_languages`	List supported platform (mojito) languages: code, English/local names, SVG flag URL, per-interface enablement (coaching/interview/admin), and Azure speech accents.

New JobMojito endpoints appear as tools automatically (with an auto-generated name) even before they’re curated here, so this table can lag slightly behind the live tool list. The API Reference is the source of truth for request/response schemas.

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.

​Docs-first calling pattern

​Read-only vs. state-changing

​Documentation

​Configuration / merchants

​Interview — create & manage

​Coaching catalogue

​Results & reports

​Knowledge base

​Merchant lists (read-only)

​Not exposed as MCP tools

​Result size

​Identifiers & admin links

Docs-first calling pattern

Read-only vs. state-changing

Documentation

Configuration / merchants

Interview — create & manage

Coaching catalogue

Results & reports

Knowledge base

Merchant lists (read-only)

Not exposed as MCP tools

Result size

Identifiers & admin links