JobMojito

[Coaching catalogue] Create a directory (page) in the coaching portal catalogue. A directory nests other directories (`tags_sub`), lists coaching sessions whose own `tags` match its `tags_interview_set_filter`, and can carry a fully custom Markdown page (`content_md`) with `[sessions]`, `[directory:…]`, `[session:…]` and `[plan-progress]` directives. One directory can hold several languages: the top-level fields are the default language, `translations` adds the others. Coaching-platform feature. Creates a directory (page) in the coaching portal catalogue. A directory nests other directories through `tags_sub`, lists coaching sessions through `tags_interview_set_filter`, and can replace the default grid with a custom Markdown page through `content_md`. The id you choose is the catalogue URL segment and cannot be changed afterwards.

[Interviews] Create a new interview and auto-generate its question sequence from position data. The `interview_template_id` you pass also sets the modality (voice-only vs realtime/pre-recorded avatar) — see `list_avatars`. Creates a new interview / coaching / assessment definition, generates its description, questions and candidate expectations via AI, and provisions default steps. Optionally provisions an embed key.

[Interviews] Create a new interview from an explicit array of questions. The AI rephrases your wording by default; pass `interview_tone="exact"` to have each question asked verbatim, which is what you want when the wording is a script (compliance, translated, or legally reviewed text). Creates a new interview definition set from a caller-provided array of questions, builds its default and generated steps, optionally activates it, and optionally creates an embed key.

[Interviews] Create a role-play persona: an avatar that plays a defined role in a free-form conversation instead of a scored Q&A interview. FIRST CHOOSE `portal`, because it selects between two different products: `portal="interview"` builds a SIMULATED PERSONA a recruiter invites candidates to — scored, billed to merchant credits, and listed with the recruiter's other results; `portal="coaching"` (THE DEFAULT) builds a coaching persona learners start themselves from the catalogue, paid per second from their own coaching minutes and never visible to recruiters. Pass `portal="interview"` explicitly for any hiring, screening or assessment use. Then set `persona_role_avatar`/`persona_role_user` for the roles and `opening_line` for the avatar's first spoken line (defaults to a generic 'Hello'). FIRST DECIDE `portal`. This endpoint creates two different products and the default is NOT the recruiter one: - `portal: "interview"` — an INTERVIEW ROLE-PLAY. Use this whenever the goal is to ASSESS or SCREEN candidates: hiring, assessments, sales role-plays for job applicants, anything a recruiter runs. Candidates are invited through the normal invitation flow, results appear in the recruiter's result list, it is billed against merchant credits, and attempts are capped via `interview_attempts` — exactly like an interview. - `portal: "coaching"` (THE DEFAULT) — a coaching persona for practice/training on the coaching portal. Consumed against the mentee's own coaching credits, self-started from the catalogue, and its results are NOT visible to recruiters. Omitting `portal` gives you this one, so pass `portal: "interview"` explicitly for any recruiting/assessment use case. The conversation itself behaves identically in both. The avatar plays a defined role in a free-form conversation instead of running a scored Q&A interview. No AI question/description generation runs; the persona role fields ARE the configuration. The session runs as: a welcome message → the avatar's OPENING LINE (the first thing it says, set via `opening_line`) → the candidate replies and the free-form role-play begins → a closing message. Because there is no question list, `opening_line` is how the avatar starts the scene — set it to a concrete in-character line; if omitted it defaults to a generic "Hello". Set `welcome_message` and `thank_you_message` too — omitting them leaves the generic platform defaults. Also set `candidate_expectations`: it is the yardstick the session is scored against. The four avatar prompts divide up as: `persona_avatar_who_is` (identity and what drives it), `persona_avatar_knowledge` (the private facts it may use), `persona_avatar_progress` (how the conversation is allowed to move forward, and what gates the later personal details), and `persona_avatar_end_conditions` (when to stop). Without `persona_avatar_progress` the avatar has no defined arc and tends to either concede immediately or never concede at all. Provisions the default conversational steps and optionally an embed key.

[Reports] Save a new custom report from a definition (schema jobmojito.report/v1). It is created as Only me: tell the user they can share it from the returned admin_url. Check the definition with preview_report first. Stores a new custom report. It is created as "Only me" (private to you); share it from the JobMojito admin. Returns its id, version and the admin link to open it. Check the definition with preview_report first.

[Results] Generate an interview result report (HTML/PDF/JSON) for a completed interview. The report is decision-support material for a human reviewer, not an automated hiring decision. Generates an interview result report as a PDF (returns a signed URL), raw HTML, or structured JSON. Provide either `interview_result_id` for a single result or `interview_result_ids` for a combined multi-result report.

[Interviews] Generate a signed public interview URL/token. Generates a public, token-signed URL for an existing interview, profile, or result. The required id fields depend on `type`.

[Interviews] Register users/candidates for a specific interview and return their personal interview links. Registers (or updates) one or more candidate profiles for an interview and returns a one-time interview URL for each. Accepts a Supabase user JWT (merchant/admin) or the service key (merchant_id then required).

[Feedback] Report a technical problem to JobMojito support. It opens a support conversation from the signed-in user's account (their e-mail), with their company and the interview or result ids given; support answers there. Describe what was done, what was expected and what happened (error text as shown). Confirm the wording with the user first; at most 5 a day. Reports a technical problem to JobMojito support. It opens a support conversation from your account (your e-mail), with your company and the ids you give; support answers there. At most 5 reports per user in 24 hours. Requires a user token (admin console session or MCP sign-in) of a merchant, merchant owner or admin.

[Results] Re-open a submitted interview result so the candidate can retry. Marks a submitted (active + completed) interview result as unsuccessful so the candidate can retake it. Resets the result to draft and clears the recruiter decision.

[Interviews] Change the state of an interview/position (e.g. open, closed). Changes the lifecycle status of an interview or position (draft, active, archived, preparing, completed, deleted) and/or manages its embed key. Provide at least one of `status` or `is_embedded`.

[Feedback] Send a feature request to the JobMojito product team. It is posted on the public feature request board under the signed-in user's name, where they get status updates; the company is not named. Write a short title and a description of the need and why (no candidate data or company names). Confirm the wording with the user before submitting; at most 5 a day. Sends a feature request to the JobMojito product team. It is posted on the public feature request board under your name (from your account e-mail), where you get status updates and others can vote on it; your company is not named. At most 5 requests per user in 24 hours. Requires a user token (admin console session or MCP sign-in) of a merchant, merchant owner or admin.

[Coaching catalogue] Update a coaching catalogue directory: rename it, change which sessions it lists (`tags_interview_set_filter`), re-order its sub-directories (`tags_sub`), author its custom Markdown page (`content_md`), or add, replace or remove a language version (`translations`, per language; null removes one). Only the fields you send are changed. Coaching-platform feature. Updates a directory (page) of the coaching portal catalogue. Only the fields present in the request body are written — everything else keeps its current value, and sending null clears a nullable field. Use it to rename a directory, re-point which sessions it lists (`tags_interview_set_filter`), re-order or replace its sub-directories (`tags_sub`), author its custom Markdown page (`content_md`), or add, replace and remove its other language versions (`translations`).

[Interviews] Update the configuration of an existing interview/position: name, description, avatar template, recording, scoring, tags and the rest of the create-time settings. Only the fields you send are changed. To change the questions, send `questions` — the WHOLE list you want the interview to end up with, in order, in the format get_interview_definition returns. OMIT `questions` and the existing questions are left completely alone; there is no way to change one question on its own, so read the interview first, edit that array, and send it back. Resending an unchanged array does nothing. Not updated by this tool at all: the welcome and thank-you messages and the instructional-video screen (stored as steps, not questions), and the language, which the existing questions are already written in. Use `tags` to place a coaching session into a catalogue directory. MULTI-STAGE POSITIONS: some per-interview settings do not exist at position level and are rejected with a 422 naming the field — `candidate_expectations_json` is the one seen in practice. Read the position with get_interview_definition, then update the individual stage you mean instead of sending that field to the position. Updates the configuration of an existing interview (single-stage) or position (multi-stage). Only the fields present in the request body are written — everything else keeps its current value, and sending null clears a nullable field. The question list is only touched when you send `questions`; omit that field and the questions are left exactly as they are. When sent, it must be the complete list and is applied as a diff against what is stored (matched on external_id, then id, then identical content), so unchanged questions keep their existing records, edited ones are unlinked and re-created, and dropped ones are unlinked — and re-sending the array job-interview-get returned changes nothing. See the field description, and `questions_diff` in the response for what was decided. Questions of an interview that is already `active` can only be changed on interactive avatar templates, where re-publishing is instant; on the offline (pre-rendered video) templates set the interview back to `draft` first. The welcome / thank-you messages and the instructional-video screen are stored as steps rather than questions and are never changed here. `mojito_language_code` cannot be changed — the existing questions and rendered videos are in the original language — so create a new interview to change language. A multi-stage position only carries the shared identity fields (name, code, location, description, description_long, cover_image_url, department, salary, available_till, recruiter, status, visibility, hiring_for_company); sending an interview-only field for a position is a 422.

[Reports] Replace a custom report's definition (send the whole definition and the version from get_report). On a report shared with other people the change is saved as a draft that the owner publishes in the admin; a private report updates at once. Replaces the definition of a report you own or may edit. Send the version you read; if someone changed the report since, you get 409 and should get it again. A report shared with others keeps your change as a draft until it is published in the admin, so viewers never see a half-finished report.

[Knowledge base] Upload and process a knowledge base document (multipart form-data). Uploads a document to a knowledge base store and queues it for processing. Accepts the file either as multipart/form-data (binary `file`) or as application/json (base64 `file`).

[Reports] Run a saved custom report and return each block's rows (aggregated numbers, at most 500 rows per block). Optional `filters` JSON overrides the period / positions / interviews for this run only. Report numbers are decision-support material for a human reviewer. Runs every block of a saved report and returns its rows. Filters start from the report's defaults, then your own saved filters, then `filters` if you pass it. Each block runs on its own: a block that fails returns ok=false with an error while the others still return data. Numbers are aggregated; no block returns more than 500 rows.

[Coaching catalogue] Read one catalogue directory in full: its settings, its custom Markdown page (`content_md`), its resolved sub-directories, and the coaching sessions its tag filter currently matches — which is how you verify that a session's `tags` actually place it in this directory. Read before updating: `content_md`, `tags_sub` and `tags_interview_set_filter` are replaced wholesale, so you need the current value to extend it. Other language versions of the page are in `translations` (`languages` lists them, default first). Reads one catalogue directory in full: its settings, its custom Markdown page (`content_md`), the sub-directories it nests, and the coaching sessions its `tags_interview_set_filter` currently matches. Read a directory before updating it — `content_md`, `tags_sub` and `tags_interview_set_filter` are replaced wholesale by catalogue-tag-update, so you need the current value to extend rather than overwrite it.

Fetch the full content of a single JobMojito documentation page. Accepts a URL returned by `search_documentation`. For developer docs the clean Markdown (.md) variant is fetched automatically. Only developer.jobmojito.com and help.jobmojito.com URLs are allowed.

[Interviews] Get the definition/configuration of an interview (position), including its ordered `questions` array. The questions come back in the same format create_interview_from_questions accepts, so you can read an interview here, change the array, and send it to update_interview. Each question's `id` identifies it — keep the ids you did not mean to change. Retrieves the interview definition for a given interview-definition id or position id. Returns the compiled `calc_definition_json`, the ordered `questions` array (in the same format job-interview-create-from-array accepts, so it round-trips into job-interview-update) plus basic metadata. Access is subject to the caller's row-level security.

[Results] Get full interview result details including transcript and scores. Scores are assistive output for a human reviewer. One result is a large record, so `view` controls how much of it comes back — the default (`standard`) omits only the raw machine assessment data. Returns an interview result with its full transcript and AI assessment. Optionally attaches signed recording URLs.

[Results] Get the merchant's daily event analytics. Daily event-count time-series for a merchant over a date range (the admin-portal analytics events graph), scoped to your token's merchant (or a merchant_id override). Optionally drilled to a single interview. Capped at 1000 records per page. Note: only day/event combinations with a non-zero count are returned — any day/event pair absent from the response should be treated as a count of 0 by the caller.

[Results] Get the merchant's credit usage. Per-event credit-usage ledger for a merchant: every billable analytics event (interview, pre-screening, public avatar, simulation, …) that consumed credits, ordered most recent first. Scoped to your token's merchant, or a merchant_id override for admins / sub-merchant operators. The credits consumed by each event are in stats.credit_amount. Capped at 1000 records per page.

[Admin] Get a merchant status snapshot: credit balances, subscription, pending-work counts, candidate/result totals, and invitation headroom. Status snapshot for a merchant: interview-credit balances, subscription type/status, pending-work counts (undecided / ongoing / uncredited interviews), candidate & result totals with 14-day history, and invitation headroom. Scoped to your token's merchant (or a merchant_id override for admins / sub-merchant operators). Also echoes the caller's profile_id and default_merchant_id from the token, plus the effective merchant_id.

[Reports] Get a custom report's JSON definition, visibility, your access and its version. Read it before update_report: the definition is replaced whole and the version must match. The report's JSON definition, visibility, your access (owner, edit, view) and its version (needed to update it). People who can edit also get the unpublished draft, if any.

Show the interactive JobMojito merchant picker (UI). ALWAYS call this when the user wants to choose, switch, or set a merchant, or when a tool needs a `merchant_id` and none is selected. It renders a searchable picker with clickable options. Do NOT list merchants as text or ask the user to type a name — render this picker instead. After calling it, STOP and wait for the user's selection; then pass `merchant_id=<chosen id>` on every JobMojito call (omit it for the user's own account).

[Admin] List available avatar/voice templates. Each item's `type` decides the interview modality: `interactive_elevenlabs` = voice-only (no video avatar); `interactive_spatius` = realtime interactive 3D avatar (rendered in the candidate's browser, 1.25 credits, no early stop); `interactive_heygen` = premium realtime interactive video avatar; `offline_heygen` = pre-recorded, non-interactive avatar. An item's `id` is the `interview_template_id` you pass to the create-interview tools, so pick the template whose type matches the experience you want. Note: `offline_elai` and `offline_synthesia` are legacy integrations that may still appear here but cannot be used to create new interviews. Rows are large, so this returns 15 at a time; page with `offset` while `pagination.has_more` is true, or narrow with `type`/`filter_text`. Paginated list of a merchant's avatar templates (the admin-portal avatars list), scoped to your token's merchant (or a merchant_id override). Capped at 1000 records per page.

[Candidates] List the merchant's candidates. Paginated list of a merchant's candidates (the admin-portal candidates list), scoped to your token's merchant (or a merchant_id override). Capped at 1000 records per page.

[Coaching catalogue] List the coaching-catalogue directories you can see (your merchant's own plus the platform-wide public ones). Start here to find a directory id, to pick a parent for a new one, or to walk the tree with `parent_tag`; `is_start_directory` marks the page the catalogue opens on. The custom Markdown page is not included — read it with get_catalogue_directory. Returns 25 at a time; page with `offset` while `pagination.has_more` is true. Paginated list of the coaching-catalogue directories visible to you: your merchant's own, plus the platform-wide `public` ones unless you set include_public=false. Use it to find a directory id before updating one, to pick a `parent_tag`, or to walk the tree with `parent_tag`. The custom Markdown page is not included — fetch it per directory with catalogue-tag-get.

[Results] List the merchant's interview results. Rows carry the candidate's scores and recruiter risk flags, so this returns 20 at a time; page with `offset` while `pagination.has_more` is true, or narrow with `tab`/`interview_id`/`filter_text`. Paginated list of a merchant's interview results (the admin-portal results list), scoped to your token's merchant (or a merchant_id override). Capped at 1000 records per page.

[Interviews] List the merchant's interview definitions. Paginated list of a merchant's interview definitions (the admin-portal interview list), scoped to your token's merchant (or a merchant_id override). Capped at 1000 records per page.

[Admin] List supported platform (mojito) languages: the `code` to pass as `mojito_language_code`, English/local names, SVG flag URL, per-interface enablement flags, and Azure speech accents. Returns all supported platform (mojito) languages: the mojito language code, English and local names, and an SVG flag image URL. Use the `code` as `mojito_language_code` when creating interviews or personas.

FALLBACK merchant list for clients WITHOUT UI support. Do NOT use this to choose or switch merchants when a UI is available — call `jobmojito_configuration` instead (it renders an interactive picker), and do not hand-format a merchant list as text. Use this tool only when the client cannot render MCP App UI. Returns the user's own account plus any sub-merchants; after a pick, pass `merchant_id=<chosen id>` on subsequent calls (OMIT for the own account).

[Reports] List what a custom report can use on this account: datasets (interview results, invitations, position pipeline, ATS pipeline, credits, coaching sessions - only those the account and your role include), their dimensions (group by / conditions, with allowed values) and measures. Call this first: a report definition may only use ids listed here. Custom reports are switched on per account by JobMojito; while they are off, every report tool is refused with 403 'Custom reports are not enabled for this account.' Tell the user to contact JobMojito rather than retrying. Everything a custom report may use on this account: the datasets (interview results, invitations, position pipeline, ATS pipeline, credits, coaching sessions - only those your account and role include), their dimensions (group by / filter) and measures (numbers), block types, condition operators and period presets. Read this before writing a report definition: ids not listed here are refused.

[Reports] List custom reports you can open (yours, shared with you) and the JobMojito templates, with id, title, visibility, your access and version. Custom reports you can open on this account (yours, the ones shared with you) and the JobMojito templates. Pinned first, then most recently updated.

[Admin] List sub-merchants under the merchant account. Paginated list of the sub-merchants the caller administers (the admin-portal sub-merchants list). Visibility is enforced by row-level security. Capped at 1000 records per page.

[Reports] Validate a report definition against the catalogue and run it without saving anything. Use it before create_report / update_report: a block that is wrong comes back with ok=false and an error naming the field and the valid ids. Validates a report definition against the catalogue and runs it, without storing anything. Use it to check a definition before create_report or update_report. A 422 names the block and field that is wrong and lists the valid ids.

Search ALL JobMojito documentation. This is the single entry point. One call searches both documentation sources in parallel and returns a merged, source-labeled list — you do not need to choose a source or call a separate tool: • "developer" — developer.jobmojito.com: API reference, request/response schemas, tables, webhooks, code examples, integration guides. • "help" — help.jobmojito.com: recruiter, candidate, and administrator product guides (how the platform behaves for end users). Use this whenever you need to understand how a feature, endpoint, field, or workflow works — including before calling an action tool you're unsure about. Then call `get_documentation(url)` with a returned URL to read the full page.