Skip to main content
Glama

JobMojito

by com.jobmojito
OverviewDiscussionsAdmin

Create role-play persona

create_persona
Destructive

[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, billed to their own coaching credits 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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
codeNoOptional external code/reference for the persona.
nameYesPersona / session name.
tagsNoFree-form tags stored on the persona. Tags are also the coaching-catalogue mapping key: a catalogue directory (see the catalogue-tag-create / catalogue-tag-update endpoints) lists a coaching or persona session when the session's tags contain EVERY tag in that directory's `tags_interview_set_filter`. Only `active` sessions with visibility `public` or `merchant_public` are listed.
portalNoREQUIRED IN PRACTICE — pick deliberately; the default is the coaching product, not the recruiting one. `interview`: an interview role-play. Choose this for ANY recruiting or assessment use case (screening candidates, hiring, sales role-plays for applicants). Candidates are invited through the normal invitation flow, results are visible to the recruiter alongside ordinary interview results, it is billed against your merchant credits on the same basis as an interview, and attempts are capped (see `interview_attempts`). | `coaching` (DEFAULT when omitted): the classic coaching persona for practice/training. Runs on the coaching portal, is consumed against the mentee's own coaching credits, is started by the mentee from the catalogue or a shared link, and its results are NOT visible to recruiters. The conversation itself behaves identically in both cases — only the portal, billing, visibility and attempt limits differ.
statusYesLifecycle status of the interview. Options — `draft`: Created but not published — not visible to candidates and cannot be run yet. Use to stage an interview before going live. | `active`: Published and live — candidates can run it..
recordingNoCheating/proctoring detection mode for candidate answers — this is NOT a full session recording. Video options also record the candidate. Omit/null to disable. Options — `audio_first_5_answers`: Audio-only cheating detection, first 5 answers only. | `audio_all`: Audio-only cheating detection on every answer. | `video_all`: Audio + video cheating detection on every answer (candidate is recorded for all answers). | `video_first_5_answers`: Audio + video cheating detection, first 5 answers only..
visibilityYesWho can discover and access the interview. Options — `merchant_public`: Listed on the merchant's public interview list — anyone with the merchant link can find and start it. | `merchant_invite`: Invite-only — only candidates explicitly invited (by email/link) can access it; not listed anywhere. | `merchant_unlisted`: Reachable only via a direct link — not listed anywhere; share the link manually..
descriptionNoShort persona description shown to the candidate on the pre-session poster. Candidate-visible — keep it to max 2 sentences. Unlike job-interview-create, personas run no AI generation, so this is never auto-generated: leave it null/blank and the poster simply shows no description; set it to frame the scene.
environmentNoWhich of your webhook environments results from this interview are delivered to. Defaults to production. Options — `production`: Live hiring. Results reach the webhooks configured as production. This is the default when the field is omitted. | `uat`: User-acceptance testing - an isolated environment for pre-release verification. | `development`: Development/testing. Use for interviews created by a test or preview app so their results never reach the production webhook. | `demo`: Demonstrations and sales trials..
is_embeddedNoSet true when the persona will be embedded as an iframe on an external page. Provisions an embed key and returns embed_id / embed_signing_key.
merchant_idNoMerchant id. Admin / sub-merchant callers only; otherwise taken from your token.
result_viewNoResult screen shown to the candidate after finishing. With any value other than `none`, the candidate sees a results screen where they can provide feedback, record an intro video and edit the transcript, and must then submit the result; the value sets how much score/result detail is shown. Options — `none`: No results screen at all — the interview is submitted immediately when the candidate finishes (no feedback, intro video, transcript edit or manual submit step). | `minimal`: Minimal results layout, no score shown. | `minimal_with_score`: Minimal results layout including the overall score. | `advanced`: Advanced results layout with more detail. | `full`: Full results layout with all sections. | `full_expand_scores`: Full results with every score breakdown expanded..
max_durationNoMaximum conversation duration in seconds. Defaults to 1200 (20 min) when omitted.
opening_lineNoThe avatar's opening line — the FIRST thing it says out loud when the session starts, before the candidate has said anything. This is a literal spoken line, NOT a description: write the exact words the avatar should say, in character and consistent with persona_role_avatar. For an escalated scenario it should already convey that state (e.g. an angry customer opens angrily). If omitted, the platform inserts a generic default ("Hello"), which is usually a weak opener — set this for anything other than a neutral greeting.
conversation_idNoPass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request.
cover_image_urlNoCover image URL.
welcome_messageNoCustom welcome message spoken to the candidate before the role-play starts — set it; omitting it leaves a generic platform default. This is the scene-setting message; the avatar's first in-character line is `opening_line`, which comes after it.
persona_role_userYesThe role the candidate (mentee) plays. Candidate-visible — shown on the pre-session poster as 'Your role', so write it as candidate-facing setup and keep it to max 2 sentences. Example: 'is to be a sales person trying to sell an additional product to the customer'.
thank_you_messageNoCustom thank-you message shown after the session — set it; omitting it leaves a generic platform default.
interview_attemptsNoAllowed candidate attempts (1-20), defaulting to 3. Only meaningful when `portal` is `interview`; coaching personas are unlimited. A recruiter can still grant an extra attempt afterwards.
interview_locationNoOptional location label shown for the session.
persona_role_avatarYesThe role the AI avatar plays. Candidate-visible — shown on the pre-session poster as 'Role of the agent', so write it as candidate-facing setup and keep it to max 2 sentences. Example: 'is to act as a happy customer responding to questions'.
mojito_language_codeYesPlatform language code used for the conversation. Must be one of the platform-languages.json codes.
recruiter_profile_idNoProfile id of the recruiter owning this persona. Must be a merchant/merchant_owner/admin profile of the same merchant.
interview_template_idYesId of the interview template (avatar) the persona uses.
persona_avatar_who_isNoWho the avatar represents: name, role, context, personality, woven with what drives them underneath (motive, fear, what they refuse until heard, what they do not know until told). One continuous description; no labelled subsections.
candidate_expectationsNoMentee assessment goals — free-text describing what the candidate is expected to achieve (max 2100 chars).
recording_full_sessionNoFull interview-session recording (includes the avatar and voice) produced as a single file. Independent of `recording`. Omit/null to disable. Options — `audio_all`: Record the whole session audio (avatar + candidate voice) into a single file. Adds +0.2 credits. | `video_all`: Record the whole session video + audio (avatar + candidate) into a single file. Adds +0.4 credits..
persona_avatar_progressNoHow the conversation moves forward — one plain-text value starting with `Mode: turning point` (resistance) or `Mode: steps` (difficult conversation protocol), then the labelled lines for that mode (Initial hold / Unlocks when / … or Framework / Steps / …), including a Gates line: do not share later personal details from persona_avatar_knowledge until progress is earned.
persona_avatar_knowledgeNoPrivate facts the avatar can use (numbers, dates, names, objections), plus any personal details shareable only after progress and only if natural — timing written inline, not as labelled subsections. Those personal details are never required for the goal.
candidate_video_introductionNoWhether a candidate video introduction is optional or required.
interview_conversation_speedNoConversation pace of the AI avatar. Omit/null keeps the template default pace. Options — `slower`: The avatar speaks more slowly — easier to follow for non-native speakers. | `normal`: Default speaking pace. | `faster`: The avatar speaks more quickly for a snappier conversation..
persona_avatar_end_conditionsNoWhen the avatar should end the session. Prefer referring to persona_avatar_progress: wrap up when progress is complete (turning point unlocked and a plan accepted, or steps "Done when" reached), or when the conversation has clearly broken down.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
embed_idNoEmbed id, present only when is_embedded=true.
_mcp_instructionsNoServer-issued metadata for this conversation.
embed_signing_keyNoEmbed signing key, present only when is_embedded=true.
interview_def_set_idYesId of the newly created persona definition set.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / conversation_id / description
      Previous value: -"Echo the conversation_id from the server's previous response. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it."New value: +"Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request."
  2. Changed2 schema fields changed
    • addedInput schema / properties / conversation_id
      Added value: +{
+  "description": "Echo the conversation_id from the server's previous response. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it.",
+  "type": "string"
+}
    • addedOutput schema / properties / _mcp_instructions
      Added value: +{
+  "description": "Server-issued metadata for this conversation.",
+  "properties": {
+    "conversation_id": {
+      "description": "The server-issued conversation identifier.",
+      "type": "string"
+    }
+  },
+  "type": "object"
+}
  3. Changed1 schema field changed
    • addedInput schema / properties / environment
      Added value: +{
+  "description": "Which of your webhook environments results from this interview are delivered to. Defaults to production. Options — `production`: Live hiring. Results reach the webhooks configured as production. This is the default when the field is omitted. | `uat`: User-acceptance testing - an isolated environment for pre-release verification. | `development`: Development/testing. Use for interviews created by a test or preview app so their results never reach the production webhook. | `demo`: Demonstrations and sales trials..",
+  "enum": [
+    "production",
+    "uat",
+    "development",
+    "demo",
+    null
+  ],
+  "example": "production",
+  "type": [
+    "string",
+    "null"
+  ]
+}
  4. Changed2 schema fields changed
    • changedInput schema / properties / tags / description
      Previous value: -"Free-form tags stored on the persona."New value: +"Free-form tags stored on the persona. Tags are also the coaching-catalogue mapping key: a catalogue directory (see the catalogue-tag-create / catalogue-tag-update endpoints) lists a coaching or persona session when the session's tags contain EVERY tag in that directory's `tags_interview_set_filter`. Only `active` sessions with visibility `public` or `merchant_public` are listed."
    • changedInput schema / properties / tags / example
      Previous value: -[
-  "sales",
-  "role-play"
-]New value: +[
+  "interview-practice",
+  "sales"
+]
  5. First observed

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare mutation/open-world/destructive; the description goes far beyond them, disclosing billing destination (merchant vs coaching credits), recruiter visibility, attempt caps, the session flow (welcome → opening line → role-play → closing), that no AI question generation runs, and which omitted fields fall back to generic platform defaults.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is front-loaded and organized, but the portal guidance is stated twice in near-duplicate form — once in the bracketed intro paragraph and again under 'FIRST DECIDE portal' — and several defaults are repeated. The duplication is real waste, though the bulk of the length is load-bearing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 33-parameter creation tool with an output schema, the description supplies everything the agent needs: required-vs-optional intent, defaulting behavior, billing and visibility consequences, the session lifecycle, and how the template/avatar fields interact. Nothing material is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is already 100%, so the baseline is 3, but the description adds genuine cross-parameter meaning: it splits the four persona_avatar_* prompts by purpose (who_is / knowledge / progress / end_conditions) and warns that omitting persona_avatar_progress causes the avatar to have no arc, plus clarifies opening_line is a literal spoken line rather than a description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb+resource ('Create a role-play persona: an avatar that plays a defined role in a free-form conversation instead of a scored Q&A interview') and explicitly contrasts the result with its closest siblings create_interview / create_interview_from_questions. An agent can tell what this creates and how it differs from the scored-interview tools without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It opens with an explicit decision instruction ('FIRST CHOOSE portal') and gives when-to-use conditions for each branch: 'interview' for hiring/screening/assessment, 'coaching' for practice/training, plus the critical warning that the default is NOT the recruiter product. Alternatives and exclusions are stated outright.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All JobMojito toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources