> ## Documentation Index > Fetch the complete documentation index at: https://developer.jobmojito.com/llms.txt > Use this file to discover all available pages before exploring further. # MCP tools reference > The JobMojito MCP tool inventory by category, how to build admin UI deep-links, and the docs-first calling pattern agents should follow. The MCP server exposes three kinds of tools: **documentation search**, the **JobMojito API** (auto-generated from the [OpenAPI spec](/how-the-api-works), 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](https://help.jobmojito.com) 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 | 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](/mcp/overview#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, **including its ordered `questions` array** — in the same format `create_interview_from_questions` accepts, so it can be edited and sent straight back to `update_interview`. | | `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. To change the questions, send `questions`: the **whole** list you want, applied as a diff (see below). **Omit `questions` and the existing questions are untouched.** Still out of scope: the welcome / thank-you messages and the instructional-video screen (stored as steps, not 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). | 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](/cookbooks/edit-interview-questions). ## Coaching catalogue Coaching-platform only. The catalogue is a tree of **directories**; each directory is one page at `/catalogue/` 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:]` | A card for one sub-directory. | | `[session:]` | A card for one session. | | `[sessions]` | Every session in this directory. | | `[sessions:]` | Sessions matching a term. | | `[sessions:filter=,limit=]` | 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](/how-the-api-works) 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](/how-the-api-works): 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**](/mcp/identifiers) 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.