Run AI interviews, manage candidates and read hiring analytics on JobMojito.
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Average 4.2/5 across 24 of 24 tools scored. Lowest: 3.3/5.
Tools are mostly distinct with clear purposes. Minor overlap between create_interview variants is clarified by descriptions. Multiple list and get tools target different entities without confusion.
All tool names follow a consistent verb_noun pattern (e.g., create_interview, list_avatars, get_merchant_status). No mixing of conventions.
24 tools is within the borderline range (16-25) for the rubric. While the server covers multiple domains (interviews, candidates, analytics, admin), the count feels slightly heavy for a single MCP server.
Core workflows are covered (create, read, list, register, report generation), but explicit update and delete tools are missing for some entities (e.g., no update_interview, delete_candidate). State changes via set_interview_state partially compensate.
create_interviewCreate interviewA[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.
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | Optional external code/reference for the interview. | |
| name | Yes | Interview / position name. | |
| tags | No | Free-form tags stored on the interview. | |
| type | Yes | Product type of the interview. Options — `interview`: Standard candidate interview for a role — answers are AI-scored and produce a hiring recommendation. | `coaching`: Practice/coaching session — candidate-facing feedback to help them improve; not a hiring evaluation. Only available on the coaching portal, NOT the interview portal. | `assessment`: Skills/knowledge assessment — evaluates competencies and is scored like an interview.. | |
| status | Yes | Lifecycle 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.. | |
| location | Yes | Job location. | |
| recording | No | Cheating/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.. | |
| visibility | Yes | Who 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.. | |
| description | No | Short, two-sentence job description shown to the candidate. Provide it to use it as-is; leave it null/blank and it is AI-generated from the position name and any other context. | |
| is_embedded | No | Set true when the interview will be embedded as an iframe on an external page. Provisions an embed key and returns embed_id / embed_signing_key, which are used to authenticate/sign the iframe embed. | |
| merchant_id | No | Merchant id. Admin / sub-merchant callers only; otherwise taken from your token. | |
| result_view | No | Result 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_duration | No | Maximum interview duration in minutes used to scope question generation. | |
| max_followups | No | Maximum number of AI follow-up questions. 0 disables follow-ups; presets are 0-3 (none/low/normal/high) and custom values start at 4; null uses the template default (Normal). | |
| custom_scoring | No | Custom result-scoring overrides merged with defaults and template overrides. | |
| interview_tone | No | Interview tone — configures the AI avatar's speaking style and the tone of the AI-generated questions and follow-ups; omit to default to relaxed. Suggested values — `relaxed`: Friendly and conversational tone that helps candidates feel at ease. | `simple`: Plain language at CEFR A2 level — short sentences and simple words. | `professional`: Formal and business-like approach suitable for senior roles. | `persuasive`: Engaging style that encourages candidates to elaborate.. Case-insensitive; other strings are accepted but unknown tones fall back to the default. | |
| interview_type | No | Interview style — configures the AI avatar and shapes both the AI-generated questions and the follow-up questions asked during the interview. Defaults to pre-screening when omitted. Options — `pre-screening`: Pre-screening — quick qualification check focusing on basic requirements and availability. | `pre-screening-with-test-questions`: Pre-screening with test questions — pre-screening plus practical questions to test relevant skills. | `second-interview`: Second round interview — deeper dive for candidates who passed initial screening. | `remote-freelancer-verification`: Remote worker verification — verify remote work capabilities and communication skills. | `strength-based-interview`: Strength-based interview — focus on what candidates enjoy and excel at to predict job satisfaction. | `potential-based-interview`: Potential-based interview — assess learning ability and growth potential rather than past experience. | `process-verification-from-knowledge-base`: Knowledge Base interview — generate questions from your knowledge base documents.. | |
| cover_image_url | No | Cover image URL. | |
| seniority_level | No | Target seniority level for the role; auto-detected from the job description when omitted. Options — `entry-level`: Early-career or graduate roles. | `intermediate`: Some experience required. | `senior`: Experienced professional. | `managerial`: Team or department lead. | `director`: Director-level responsibility. | `executive`: C-suite or executive role.. | |
| welcome_message | No | Custom welcome message shown to the candidate. | |
| description_long | No | Full job description in Markdown (Job Purpose, Responsibilities, Required & Preferred Qualifications). Provide it to use it as-is; leave it null/blank and it is AI-generated (interview and assessment types only). | |
| interview_length | No | Number of questions to generate (max 40). | |
| interview_salary | No | Salary range shown for the position. | |
| thank_you_message | No | Custom thank-you message shown after the interview. | |
| additional_context | No | Arbitrary additional context object merged into AI generation. | |
| hiring_for_company | No | Who the position is really for. Omit/null (or an object with name null/blank) when hiring for yourself; { name: 'undisclosed' } for an unnamed external client; or { name: '<company>' } plus optional description/location/sector/company_size for a named client. Stored in creation_parameters.hiring_for_company. | |
| interview_attempts | No | Allowed candidate attempts (1-20). | |
| instructional_video | No | Show an instructional video before approval. Defaults to false. | |
| interview_department | No | Department the position belongs to. | |
| mojito_language_code | Yes | Platform language code used for the interview. Must be one of the platform-languages.json codes. | |
| recruiter_profile_id | No | Profile id of the recruiter owning this interview. Must be a merchant/merchant_owner/admin profile of the same merchant. | |
| interview_template_id | Yes | Id of the interview template to base this interview on. | |
| candidate_expectations | No | Free-text candidate expectations folded into AI generation. | |
| include_closing_prompt | No | Include a closing prompt. Defaults to true. | |
| pdf_export_auto_config | No | Auto-generate a candidate PDF report with these options once the interview completes. null disables auto-export. | |
| recording_full_session | No | Full 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.. | |
| required_pronunciation | No | Require pronunciation assessment (restricts to pronunciation-capable languages). Defaults to false. | |
| knowledge_base_store_id | No | Knowledge base store id to source additional context from. | |
| questions_random_subset | No | Ask only a random subset of the questions, expressed as a fraction between 0.01 and 0.9 (e.g. 0.5 = 50%). null asks all questions. | |
| include_rapport_question | No | Include an opening rapport question. Defaults to false. | |
| interview_available_till | No | ISO date/time after which the interview is no longer available to candidates. null keeps it always available. | |
| use_enhanced_expectations | No | Reserved flag passed through to generation. | |
| candidate_video_introduction | No | Whether a candidate video introduction is optional or required. | |
| interview_conversation_speed | No | Conversation 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.. | |
| result_enable_edit_transcript | No | Allow editing the transcript on the result view. Defaults to true. | |
| instructional_video_custom_text | No | Custom narration text for the instructional video. |
| Name | Required | Description |
|---|---|---|
| embed_id | No | Embed id, present only when is_embedded=true. |
| embed_signing_key | No | Embed signing key, present only when is_embedded=true. |
| interview_def_set_id | Yes | Id of the newly created interview definition set. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and idempotentHint=false. The description adds transparency by explaining the auto-generation of description, questions, and candidate expectations via AI, and optionally provisioning an embed key. It does not contradict annotations and provides useful behavioral context beyond structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences. The first sentence front-loads the core purpose and the second adds optional key details. Every sentence serves a purpose with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (46 parameters, 7 required, 11 enums) and the availability of a rich output schema, the description provides adequate high-level context: AI generation, embed key provisioning, and the role of interview_template_id. While it doesn't cover all edge cases, the schema fills those gaps, making the description sufficiently complete for an agent to understand the tool's scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 46 parameters with examples and descriptions. The description only mentions 'interview_template_id' specifically, referencing that it sets modality. With high schema coverage, the description adds minimal parameter value, achieving baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates an interview and auto-generates question sequence from position data, distinguishing it from siblings like 'create_interview_from_questions' which likely uses predefined questions. It specifies the tool creates interview/coaching/assessment definitions and provisions default steps and optionally an embed key.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you want AI-generated questions from position data, but does not explicitly state when to avoid this tool or name alternative tools like 'create_interview_from_questions' for manual question setup. The context of sibling tools helps, but the description itself lacks explicit when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_interview_from_questionsCreate interview from questionsB[Interviews] Create a new interview from an explicit array of questions.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | Optional external code/reference. | |
| name | Yes | Interview/position name. | |
| tags | No | Free-form tags stored on the interview. | |
| type | Yes | Product type of the interview. Options — `interview`: Standard candidate interview for a role — answers are AI-scored and produce a hiring recommendation. | `coaching`: Practice/coaching session — candidate-facing feedback to help them improve; not a hiring evaluation. Only available on the coaching portal, NOT the interview portal. | `assessment`: Skills/knowledge assessment — evaluates competencies and is scored like an interview.. | |
| status | Yes | Lifecycle 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.. | |
| location | Yes | Interview location. | |
| questions | Yes | Ordered list of interview questions to create as steps. | |
| recording | No | Cheating/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.. | |
| visibility | Yes | Who 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.. | |
| description | Yes | Short interview description. | |
| is_embedded | No | Set true when the interview will be embedded as an iframe on an external page. Creates an embed key and returns embed_id/embed_signing_key, used to authenticate/sign the iframe embed. | |
| merchant_id | No | Target merchant id (admins / sub-merchant only). | |
| result_view | No | Result 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_followups | No | Maximum number of AI follow-up questions. 0 disables follow-ups; presets are 0-3 (none/low/normal/high) and custom values start at 4; null uses the template default (Normal). | |
| custom_scoring | No | Custom scoring overrides merged with defaults. | |
| interview_tone | No | Tone — configures the AI avatar's speaking style and the follow-up questions it generates; the base `questions` you supply are not affected. Omit to default to relaxed. Suggested values — `relaxed`: Friendly and conversational tone that helps candidates feel at ease. | `simple`: Plain language at CEFR A2 level — short sentences and simple words. | `professional`: Formal and business-like approach suitable for senior roles. | `persuasive`: Engaging style that encourages candidates to elaborate.. Case-insensitive; other strings are accepted but unknown tones fall back to the default. | |
| interview_type | No | Interview style — configures the AI avatar and the follow-up questions it generates during the interview. The base `questions` you supply are used as-is and are NOT affected by this setting. Options — `pre-screening`: Pre-screening — quick qualification check focusing on basic requirements and availability. | `pre-screening-with-test-questions`: Pre-screening with test questions — pre-screening plus practical questions to test relevant skills. | `second-interview`: Second round interview — deeper dive for candidates who passed initial screening. | `remote-freelancer-verification`: Remote worker verification — verify remote work capabilities and communication skills. | `strength-based-interview`: Strength-based interview — focus on what candidates enjoy and excel at to predict job satisfaction. | `potential-based-interview`: Potential-based interview — assess learning ability and growth potential rather than past experience. | `process-verification-from-knowledge-base`: Knowledge Base interview — generate questions from your knowledge base documents.. | |
| cover_image_url | No | Cover image URL. | |
| seniority_level | No | Target seniority level for the role; auto-detected from the job description when omitted. Options — `entry-level`: Early-career or graduate roles. | `intermediate`: Some experience required. | `senior`: Experienced professional. | `managerial`: Team or department lead. | `director`: Director-level responsibility. | `executive`: C-suite or executive role.. | |
| welcome_message | No | Custom welcome message. | |
| description_long | No | Long-form interview description. | |
| interview_salary | No | Salary range shown for the position. | |
| thank_you_message | No | Custom thank-you message. | |
| additional_context | No | Extra context forwarded to expectation generation. | |
| hiring_for_company | No | Who the position is really for. Omit/null (or an object with name null/blank) when hiring for yourself; { name: 'undisclosed' } for an unnamed external client; or { name: '<company>' } plus optional description/location/sector/company_size for a named client. Stored in creation_parameters.hiring_for_company. | |
| interview_attempts | No | Allowed attempts, 1-20. | |
| instructional_video | No | Enable an instructional video before approval. | |
| interview_department | No | Department the position belongs to. | |
| mojito_language_code | Yes | Platform language code (one of the platform-languages.json codes); must also resolve to a supported language with an Azure speech mapping. | |
| recruiter_profile_id | No | Profile id of the recruiter owning this interview. Must be a merchant/merchant_owner/admin profile of the same merchant. | |
| disable_deduplication | No | When true, skip step deduplication on insert. | |
| interview_template_id | Yes | Id of the interview template to use. Must reference an existing interview_templates row. | |
| candidate_expectations | No | Free-text candidate expectations. | |
| pdf_export_auto_config | No | Auto-generate a candidate PDF report with these options once the interview completes. null disables auto-export. | |
| recording_full_session | No | Full 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.. | |
| required_pronunciation | No | Require pronunciation assessment (restricts to pronunciation-capable languages). Defaults to false. | |
| knowledge_base_store_id | No | Optional knowledge base store id; validated for existence. | |
| questions_random_subset | No | Fraction of questions to randomly ask, between 0.01 and 0.9. | |
| interview_available_till | No | ISO date/time after which the interview is no longer available to candidates. null keeps it always available. | |
| candidate_expectations_json | No | Pre-generated candidate expectations, bucketed by requirement level (weak/moderate/strong); auto-generated when omitted for type=interview. Extra keys are preserved. | |
| candidate_video_introduction | No | Whether a candidate video introduction is optional or required. | |
| interview_conversation_speed | No | Conversation 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.. | |
| result_enable_edit_transcript | No | Allow editing the transcript on the result view. Defaults to true. | |
| instructional_video_custom_text | No | Custom text for the instructional video. |
| Name | Required | Description |
|---|---|---|
| embed_id | No | Embed id, present only when is_embedded=true. |
| embed_signing_key | No | Embed signing key, present only when is_embedded=true. |
| interview_def_set_id | Yes | Id of the newly created interview definition set. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive and non-read-only behavior. The description adds that it builds steps, optionally activates, and optionally creates an embed key, providing additional behavioral context. However, it does not detail side effects like overwriting existing interviews or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (about 25 words) but front-loaded with the essential purpose. It avoids unnecessary words, though it could be slightly more structured with bullet points for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool complexity (44 parameters, 9 required), the description provides minimal context. It does not mention return values, required parameters, or the embedding feature beyond a brief mention. The presence of an output schema reduces some burden, but the description lacks completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds no new parameter information beyond mentioning 'explicit array of questions', which corresponds to the 'questions' parameter. No other parameter details are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates an interview from an explicit array of questions, distinguishing it from sibling 'create_interview' by specifying the input method. The verb 'Create' and resource 'interview' are unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'create_interview'. No when-not-to-use or prerequisite information provided. The description implies usage but lacks explicit context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_personaCreate role-play personaA[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. 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'). Coaching-platform feature.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | Optional external code/reference for the persona. | |
| name | Yes | Persona / session name. | |
| tags | No | Free-form tags stored on the persona. | |
| portal | No | REQUIRED 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. | |
| status | Yes | Lifecycle 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.. | |
| recording | No | Cheating/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.. | |
| visibility | Yes | Who 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.. | |
| description | No | Short 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. | |
| is_embedded | No | Set 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_id | No | Merchant id. Admin / sub-merchant callers only; otherwise taken from your token. | |
| result_view | No | Result 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_duration | No | Maximum conversation duration in seconds. Defaults to 1200 (20 min) when omitted. | |
| opening_line | No | The 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. | |
| cover_image_url | No | Cover image URL. | |
| welcome_message | No | Custom 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_user | Yes | The 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_message | No | Custom thank-you message shown after the session — set it; omitting it leaves a generic platform default. | |
| interview_attempts | No | Allowed 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_location | No | Optional location label shown for the session. | |
| persona_role_avatar | Yes | The 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_code | Yes | Platform language code used for the conversation. Must be one of the platform-languages.json codes. | |
| recruiter_profile_id | No | Profile id of the recruiter owning this persona. Must be a merchant/merchant_owner/admin profile of the same merchant. | |
| interview_template_id | Yes | Id of the interview template (avatar) the persona uses. | |
| persona_avatar_who_is | No | Who 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_expectations | No | Mentee assessment goals — free-text describing what the candidate is expected to achieve (max 2100 chars). | |
| recording_full_session | No | Full 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_progress | No | How 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_knowledge | No | Private 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_introduction | No | Whether a candidate video introduction is optional or required. | |
| interview_conversation_speed | No | Conversation 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_conditions | No | When 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. |
| Name | Required | Description |
|---|---|---|
| embed_id | No | Embed id, present only when is_embedded=true. |
| embed_signing_key | No | Embed signing key, present only when is_embedded=true. |
| interview_def_set_id | Yes | Id of the newly created persona definition set. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description extensively discloses behavioral traits beyond annotations: it creates two different products, the default is coaching, no AI question generation runs, session flow (welcome -> opening line -> free-form -> closing), necessity of persona_avatar_progress, and billing/visibility differences. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with a front-loaded portal decision block and clear sections. It could be slightly more concise, but the complexity justifies the length. No wasted sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 31 parameters, 100% schema coverage, and an output schema, the description covers all critical behavioral aspects, including the two-product nature, session flow, parameter dependencies, and example values. It is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 100% schema coverage, the description adds significant meaning, such as explaining the portal parameter's business logic, the opening_line being a literal spoken line, the persona_avatar_progress format, and the candidate_expectations as scoring yardstick. This goes well beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Create a role-play persona: an avatar that plays a defined role in a free-form conversation instead of a scored Q&A interview.' It distinguishes from the sibling interview tools by emphasizing free-form versus scored Q&A.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use each portal, with detailed use cases: 'portal: "interview"' for assessing/screening candidates (hiring, assessments) vs 'portal: "coaching"' for practice/training. It also explains the default and the consequences of omitting portal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
generate_interview_reportGenerate interview reportA[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.
| Name | Required | Description | Default |
|---|---|---|---|
| store_file | No | When true (pdf only), persist the file to storage and return a signed URL. | |
| export_type | Yes | ||
| interview_result_id | No | ||
| interview_result_ids | No | Generate a single combined report for multiple results. | |
| export_features_result | No |
| Name | Required | Description |
|---|---|---|
| result | Yes | The generated report. Exactly one of the three shapes below is returned, selected by the request `export_type`: `pdf` → `{ pdf_export_url, pdf_export_valid_until }`; `html` → `{ html_export }`; `json` → `{ json_export }`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that PDF can be persisted and returns a signed URL, and that translation costs 0.1 credit per result. Annotations indicate destructiveHint=true and idempotentHint=true, which align with the described behavior. Adds context beyond annotations without contradiction, though it could clarify the idempotent nature more explicitly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct with two paragraphs: the first establishes purpose and context, the second details the two usage paths and export formats. Every sentence carries value, with no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the essential aspects: purpose, input parameters, and key options. Given the complexity (nested object with many flags), the description relies on the schema for sub-property details, which is acceptable. The existence of an output schema reduces the need to describe return values, though the description could briefly mention that reports are generated synchronously or any limitations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful context for the ID parameters and export types by explaining their relationship (single vs. combined report) and the three output formats. While the nested export_features_result object is not elaborated in the description, its sub-properties are well-documented in the schema. The description compensates for the 40% schema coverage by clarifying the core parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates interview result reports in HTML/PDF/JSON formats for completed interviews, serving as decision-support material. It specifies the target audience (human reviewer) and distinguishes from siblings by focusing on report generation rather than creation, listing, or result details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit instruction to provide either interview_result_id for a single result or interview_result_ids for a combined multi-result report. However, it does not explicitly state when not to use this tool or mention alternatives like get_interview_result_details for raw data, though the context of 'completed interview' implies applicable scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
generate_interview_urlGenerate shareable interview linkA[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.
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | Which kind of signed URL to generate. | |
| hide_menu | No | Pass the string 'false' to show the navigation menu; any other value hides it (default). | |
| merchant_id | No | Override merchant id (admin / sub-merchant only). | |
| interview_id | No | Interview or position id. Required for interview-for-profile and interview-results-for-position. | |
| interview_result_id | No | Interview result id. Required for interview-result-candidate and interview-result-talent-seeker. | |
| interview_profile_id | No | Candidate profile id. Required for interview-for-profile and results-for-profile. |
| Name | Required | Description |
|---|---|---|
| result | Yes | The signed interview URL. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide destructiveHint=true and readOnlyHint=false, and the description adds that the URL is signed and public. However, it does not elaborate on side effects (e.g., token expiration, invalidation of previous URLs) or required permissions beyond what the schema indicates.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded with a category tag and two sentences. It is efficient, though the '[Interviews]' bracket prefix is somewhat redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with six parameters, one required enum, and an output schema, the description covers the core idea but lacks guidance on selecting the appropriate 'type' value. An agent would need to infer from the schema descriptions, which are present but not synthesized in the tool description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter described. The description reinforces that required IDs depend on 'type', but adds little beyond the schema's parameter descriptions. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it generates a signed public URL/token for an existing interview, profile, or result. The verb 'generate' and resource 'interview URL/token' are specific, and the tool's function is distinct from sibling tools like create_interview or list_interviews.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for generating shareable links for existing objects, but it does not explicitly state when to use this tool versus alternatives, nor does it provide exclusionary guidance or conditions like when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_documentationRead a JobMojito documentation pageAFetch 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.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The documentation page URL. | |
| max_chars | No | Truncate content to this many characters (default 20000). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds context: auto-fetches Markdown for developer docs, truncates based on max_chars, and domain restrictions. This provides value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four concise sentences, each adding distinct information: purpose, URL source, special behavior for developer docs, and domain restrictions. No fluff, front-loaded with primary purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description covers essential context: what it does, how to get the URL, automatic Markdown handling, and domain restrictions. It does not detail error behavior or output format, but output schema exists and annotations cover safety.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover both parameters (100% coverage), so baseline is 3. The description adds meaning by specifying that the URL must come from search_documentation and that only certain domains are allowed, which aids correct usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches the full content of a single documentation page (specific verb+resource). It distinguishes from sibling tools like search_documentation by specifying that it accepts URLs from that tool and only allows certain domains.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use a URL from search_documentation and restricts usage to specific domains. It implies when to use (after searching) but does not explicitly state when not to use or mention alternatives beyond search_documentation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_interview_definitionGet interview definitionA[Interviews] Get the definition/configuration of an interview (position).
Retrieves the interview definition for a given interview-definition id or position id. Returns the compiled calc_definition_json plus basic metadata. Access is subject to the caller's row-level security.
| Name | Required | Description | Default |
|---|---|---|---|
| position_id | Yes | Identifier of either an interview definition (single-stage) or a position definition (multi-stage). The function resolves whichever matches. |
| Name | Required | Description |
|---|---|---|
| code | Yes | Caller-supplied external code/reference. |
| name | Yes | Interview or position name. |
| type | Yes | Interview type. Null for multi-stage positions. |
| stage | Yes | Hiring-pipeline stage. Null for multi-stage positions. |
| status | Yes | Lifecycle status of the interview/position. |
| recording | Yes | Per-answer recording mode. Null for multi-stage positions. |
| created_at | Yes | |
| updated_at | Yes | |
| visibility | Yes | Who can see and access the interview/position. |
| description | Yes | Short description. |
| merchant_id | Yes | Owning merchant id. |
| result_view | Yes | Result view level. Null for multi-stage positions. |
| type_credit | Yes | Credit bucket the interview draws from. Null for multi-stage positions. |
| is_multistage | Yes | True when the id resolved to a multi-stage position rather than a single interview. |
| is_voice_only | Yes | Convenience flag derived from interview_template_type: true when voice-only (`interactive_elevenlabs`), false when avatar-based, null when the template type could not be resolved. |
| result_scoring | No | Resolved result-scoring config. Null for multi-stage positions. |
| cover_image_url | Yes | Cover image URL. |
| interview_location | Yes | Location (create field `location`). |
| creation_parameters | No | The creation parameters recorded at build time (interview_type, interview_tone, interview_length, additional_context, include_rapport_question, include_closing_prompt, knowledge_base_store_id, seniority_level). |
| calc_definition_json | No | The compiled interview definition JSON (structure varies by interview type). |
| mojito_language_code | Yes | Platform (mojito) language code. |
| speech_language_code | Yes | Azure speech language code. Null for multi-stage positions. |
| speech_language_name | Yes | Azure speech language display name. Null for multi-stage positions. |
| interview_template_id | Yes | Interview template id. For multi-stage positions this is the first interview step's template. |
| candidate_expectations | Yes | Free-text candidate expectations. Null for multi-stage positions. |
| recording_full_session | Yes | Full-session recording mode. Null for multi-stage positions. |
| interview_template_type | Yes | Type of the linked interview template. `interactive_elevenlabs` is voice-only; the others (`interactive_heygen`, `offline_heygen`, `offline_elai`, `offline_synthesia`) are avatar-based. Null when the template could not be resolved. |
| knowledge_base_store_id | Yes | Linked knowledge base store id. Null for multi-stage positions. |
| interview_description_long | Yes | Long description (create field `description_long`). |
| candidate_expectations_json | No | Structured candidate expectations JSON. Null for multi-stage positions. |
| candidate_video_introduction | Yes | Whether a candidate video introduction is hidden/optional/required. Null for multi-stage positions. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds value by specifying that it returns compiled calc_definition_json and basic metadata, and mentions row-level security, which goes beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with purpose, no redundant information. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a single parameter, existing annotations, output schema, and a description covering return type and security, the tool is fully specified for its simple read-only operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and explains that position_id can be an interview or position id. The description reiterates this, adding no new meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves the definition/configuration of an interview (position) given an id, distinguishing it from siblings like list_interviews or get_interview_result_details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use (retrieve definition for a given id) but does not explicitly exclude alternatives or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_interview_result_detailsGet interview result detailsA[Results] Get full interview result details including transcript and scores. Scores are assistive output for a human reviewer.
Returns an interview result with its full transcript and AI assessment. Optionally attaches signed recording URLs.
| Name | Required | Description | Default |
|---|---|---|---|
| interview_result_id | Yes | The interview result to fetch the transcript and details for. | |
| get_signed_recordings | No | When true, includes short-lived signed recording URLs for the session, the video introduction, and each transcript answer. | false |
| Name | Required | Description |
|---|---|---|
| end | No | Interview end timestamp (training_end, ISO 8601). |
| score | No | Overall interview score. |
| start | No | Interview start timestamp (training_start, ISO 8601). |
| status | No | Coach/interview status (coach_status), e.g. started, completed. |
| duration | No | Total duration in deciseconds (duration_ds). |
| score_text | No | Human-readable score summary. |
| transcript | No | Ordered interactions (questions + answers) of the interview. |
| ai_analysis | No | Candidate-facing AI analysis of the whole interview. |
| score_answer | No | Aggregate answer sub-score. |
| recording_url | No | Signed session-recording URL; present only when get_signed_recordings=true. |
| recruiter_risks | No | Detected recruiter risk flags (jsonb). |
| score_sentiment | No | Sentiment sub-score. |
| score_simulation | No | Overall simulated score. |
| recording_is_video | No | Whether the session recording is video. |
| score_pronunciation | No | Pronunciation sub-score. |
| ai_completion_reason | No | Why the interview completed (ai_completed_reason). |
| recording_local_path | No | Storage path of the full session recording. |
| ai_analysis_recruiter | No | Recruiter-facing AI analysis of the whole interview. |
| score_words_per_minute | No | Speaking-pace (words per minute) sub-score. |
| video_introduction_url | No | Signed video-introduction URL; present only when get_signed_recordings=true. |
| user_feedback_recruiter | No | Recruiter-entered feedback note. |
| video_introduction_local_path | No | Storage path of the candidate video introduction. |
| ai_analysis_recruiter_why_hire | No | Reasons to hire (list/text). |
| ai_interview_coverage_percentage | No | Percentage of the intended interview the AI judged to be covered. |
| ai_analysis_recruiter_why_not_hire | No | Reasons not to hire (list/text). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint, describing the safety profile. The description adds context: scores are 'assistive output for a human reviewer' and recording URLs are optional. This goes beyond annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with four sentences, front-loading the main purpose. The use of '[Results]' as a tag adds categorization. However, the structure is slightly fragmented; grouping optional details more tightly could improve readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, presence of an output schema, and comprehensive annotations, the description covers key aspects: transcript, scores, AI assessment, and optional recordings. No further details (e.g., prerequisites, permissions) are necessary for this read-only tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters (interview_result_id, get_signed_recordings) have clear descriptions in the input schema (100% coverage). The tool description mentions 'Optionally attaches signed recording URLs' but does not add new meaning beyond the schema. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get full interview result details including transcript and scores' and mentions optionally attaching recording URLs. This distinguishes it from sibling tools like list_interview_results which returns a list without details. The verb 'get' and resource 'interview result details' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when full details are needed (e.g., 'Get full interview result details') but does not explicitly state when to use this over alternatives like list_interview_results. No exclusions or 'when not to use' guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_merchant_analyticsGet merchant analyticsA[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.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of records to return (1–1000). | |
| offset | No | Number of records to skip from the start of the result set. | |
| date_to | Yes | End of the date range (inclusive), YYYY-MM-DD. | |
| date_from | Yes | Start of the date range (inclusive), YYYY-MM-DD. | |
| merchant_id | No | Optional merchant to scope to. Admins and sub-merchant operators only; other callers always use their token's merchant. | |
| interview_id | No | Optional interview (interview_def_set) or position (position_def_set) id to drill the event counts down. The type is detected automatically: a position aggregates the daily counts across every interview that makes up the position; an interview filters to that single definition. |
| Name | Required | Description |
|---|---|---|
| data | Yes | Daily event counts for the requested range, ordered by day ascending. Only day/event combinations with a non-zero count are returned; missing combinations should be treated as 0 by the caller. |
| pagination | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint: false), the description adds critical behavioral details: pagination cap at 1000 records per page, only non-zero counts returned (implicit zero padding), and optional drilling to interview. This provides valuable context for an AI agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is clear and front-loaded with purpose, but it is a single paragraph that could be slightly more structured. It is concise, but the note about zero padding could be separated for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, optional drilling, pagination) and the presence of an output schema, the description adequately covers usage scope, pagination behavior, and zero-padding note. It omits explicit read-only mention, but annotations cover that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all six parameters with descriptions, and the description adds minimal extra meaning beyond schema. It mentions scoping and drilling, but these are already in the schema descriptions. Baseline 3 is appropriate given 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves daily event analytics for a merchant using specific verbs and resources ('Get the merchant's daily event analytics'). It distinguishes itself from sibling tools like get_merchant_credit_usage and get_merchant_status by focusing on event-count time-series, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool, including scoping to token merchant or merchant_id override and optional drilling to an interview. However, it does not explicitly state when not to use it or compare with alternatives, which would raise the score to 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_merchant_credit_usageGet merchant credit usageA[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.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of records to return (1–1000). | |
| offset | No | Number of records to skip from the start of the result set. | |
| merchant_id | No | Optional merchant to scope to. Admins and sub-merchant operators only; other callers always use their token's merchant. | |
| interview_id | No | Optional interview (interview_def_set) or position (position_def_set) id to drill the credit-usage ledger down to a single interview or position. The type is detected automatically: for a position the response combines pre-screening and interview-result credits across the whole position; for an interview it returns that interview's credit events (including simulations and report translations). |
| Name | Required | Description |
|---|---|---|
| data | Yes | Credit-consuming analytics events for the merchant, most recent first. Each row is one billable event; the credits it consumed are in stats.credit_amount. |
| pagination | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds that results are ordered most recent first and capped at 1000 records per page, which are useful behavioral details. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (about 5 lines), front-loaded with the main purpose, and every sentence adds value. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the annotations (readOnlyHint, idempotentHint, etc.) and the presence of an output schema, the description provides sufficient context: it explains the return format (ledger with credit_amount), ordering, pagination limit, and parameter behavior. It is complete for a read-only tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant meaning beyond the input schema: it explains the merchant_id scope permission, and the interview_id parameter's dual behavior (detecting interview vs. position and combining credits accordingly). Schema coverage is 100%, but the description enriches understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a per-event credit-usage ledger for a merchant, listing billable analytics events that consumed credits. It distinguishes from siblings like get_merchant_analytics and get_merchant_status by focusing on detailed credit consumption events rather than aggregated analytics or status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains scoping (token's merchant or merchant_id override for admins) and drilling down via interview_id or position_id. However, it does not explicitly compare to sibling tools or state when to prefer this tool over alternatives, leaving some inference required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_merchant_statusGet merchant statusA[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.
| Name | Required | Description | Default |
|---|---|---|---|
| merchant_id | No | Optional merchant to scope to. Admins and sub-merchant operators only; other callers always use their token's merchant. |
| Name | Required | Description |
|---|---|---|
| candidates | Yes | Total candidates (non-archived profile_interview rows) for the merchant. |
| profile_id | Yes | The calling user's profile id (auth user id), taken from the JWT. |
| merchant_id | Yes | The merchant this status is scoped to — the default_merchant_id unless an admin / sub-merchant operator overrode it via the merchant_id query param. |
| invitations_sent | Yes | Interview invitations sent during the current subscription period. |
| interview_results | Yes | Total non-archived interview results for the merchant. |
| invitations_limit | Yes | Maximum invitations allowed this period (4x available credits). Null for unlimited (Special) plans. |
| subscription_type | Yes | Subscription plan name (e.g. Free, Starter, Growth, Special). |
| candidates_history | Yes | Daily new-candidate counts for the last 14 days, most recent first. |
| definitions_active | Yes | Count of active interview + position definitions. |
| interviews_ongoing | Yes | Interviews currently in progress (coach_status = started). |
| default_merchant_id | Yes | The caller's home merchant id pinned in the JWT (app_metadata.merchant_id). Null if the token carries no merchant. |
| subscription_status | Yes | Subscription status (e.g. active, past_due, canceled). Null when no subscription. |
| interviews_undecided | Yes | Completed interviews awaiting a recruiter decision. |
| invitations_available | Yes | Remaining invitations this period. Null for unlimited (Special) plans. |
| credits_interview_extra | Yes | Extra (top-up) interview credits available on top of the monthly allowance. |
| credits_interview_single | Yes | Single-position interview credits available. |
| interview_result_history | Yes | Daily new-interview-result counts for the last 14 days, most recent first. |
| credits_interview_monthly | Yes | Remaining monthly interview credits. |
| interviews_without_credits | Yes | Completed interviews that have not yet consumed a credit. |
| credits_interview_monthly_limit | Yes | Monthly interview-credit allowance for the current plan. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds that the tool echoes caller's profile_id and default_merchant_id, and clarifies authorization boundaries for the merchant_id parameter. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: a high-level summary followed by a detailed list of components. It is front-loaded with the purpose and succinctly expands without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description need not cover return values. It fully describes all components of the snapshot and the caller info echo, making it complete for a read-only, idempotent tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with description for the only parameter (merchant_id). The tool description adds valuable context about who can use the override (admins/sub-merchant operators), improving clarity beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves a 'merchant status snapshot' and lists specific components like credit balances, subscription, pending-work counts, etc. It distinguishes from sibling tools such as 'get_merchant_analytics' and 'get_merchant_credit_usage' by detailing the unique fields included.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains scope: default to token's merchant, with optional merchant_id for admins/sub-merchant operators. While it doesn't explicitly name alternatives, it provides clear context on when to use the optional parameter and who can use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
jobmojito_configurationChoose a JobMojito merchantAShow 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).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, idempotentHint, destructiveHint. The description adds useful behavioral context: it renders a UI, is interactive, and instructs the agent to pass merchant_id on subsequent calls. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the main purpose. Every sentence adds value, and it efficiently conveys usage instructions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no parameters and no output schema, the description is complete. It explains the action, when to use it, and the expected behavior, including integration with other tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters (empty input schema), so baseline is 4. The description correctly handles this by not needing to add parameter info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Show the interactive JobMojito merchant picker (UI).' It uses a specific verb and resource, and the context differentiates it from sibling tools like list_my_merchants.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: 'ALWAYS call this when the user wants to choose, switch, or set a merchant...' and includes what not to do ('Do NOT list merchants as text...'). It also instructs the agent to stop and wait for the user's selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_avatarsList avatars and voice templatesA[Admin] List available avatar/voice templates. Each item's type decides the interview modality: interactive_elevenlabs = voice-only (no video avatar); interactive_heygen = realtime interactive avatar (video); 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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Filter by avatar template type. Omit for all. | |
| limit | No | Maximum number of records to return (1–1000). | |
| offset | No | Number of records to skip from the start of the result set. | |
| status | No | Filter by status. Omit for all except archived (see include_archived). | |
| filter_text | No | Case-insensitive search on template name or voice language name. | |
| merchant_id | No | Optional merchant to scope to. Admins and sub-merchant operators only; other callers always use their token's merchant. | |
| include_public | No | Also include public templates shared across merchants, in addition to this merchant's own. | false |
| include_archived | No | Include archived templates (excluded by default). | false |
| mojito_language_code | No | Filter by platform language code. |
| Name | Required | Description |
|---|---|---|
| data | Yes | The merchant's avatar templates for this page, newest-updated first. |
| pagination | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, and the description adds behavior details: pagination with 1000 cap, merchant scoping, and the inclusion of legacy types. This is valuable context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise paragraphs, front-loading the key purpose and usage guidance. It avoids unnecessary repetition but could be slightly more structured (e.g., separating param details).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description adequately covers purpose, usage, behavioral nuances, and parameter intent. It mentions pagination limits and legacy types, making it complete for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 9 parameters. The description does not add per-parameter details but provides overall context (e.g., meaning of 'type' values). Since schema covers parameters, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists avatar/voice templates, explains how the 'type' field maps to interview modalities, and notes that the 'id' is used as interview_template_id in creation tools. This distinguishes it from sibling list tools and adds context beyond a simple 'list avatars'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides guidance on selecting templates by type for the desired experience, warns about legacy types that cannot be used, and mentions merchant scope and pagination. However, it does not explicitly compare to other list tools or state when to avoid this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_candidatesList candidatesA[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.
| Name | Required | Description | Default |
|---|---|---|---|
| tab | No | Filter candidates by recent activity. Omit (or empty) to include all. | |
| limit | No | Maximum number of records to return (1–1000). | |
| offset | No | Number of records to skip from the start of the result set. | |
| source | No | Filter by how the candidate entered: invited or self-registered. Omit for both. | |
| order_by | No | Sort order of the result set. | created_at_newest |
| filter_text | No | Case-insensitive search on candidate name or email. | |
| merchant_id | No | Optional merchant to scope to. Admins and sub-merchant operators only; other callers always use their token's merchant. | |
| filter_emoji | No | Filter by the candidate emoji marker. |
| Name | Required | Description |
|---|---|---|
| data | Yes | The merchant's candidates for this page. |
| pagination | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds useful behavioral details: pagination with a 1000-record cap, scoping to merchant, and optional merchant_id override. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three short sentences, no redundant information. It is front-loaded with the core purpose. Could be slightly more structured, but no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description adequately covers the tool's behavior (pagination, scoping, cap). It could mention filtering options, but the schema handles that. Completeness is sufficient for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover all 8 parameters (100% coverage), so the description's contribution is minimal. It mentions pagination cap but does not explain individual parameters beyond what the schema provides. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists the merchant's candidates, with pagination and scoping to the token's merchant or an override. The verb 'list' and resource 'candidates' are explicit, and there is no sibling tool with a similar purpose to cause confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool (listing candidates) and constraints like scoping and pagination limits. However, it does not explicitly state alternatives or when not to use it, though no direct alternatives exist among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_interview_resultsList interview resultsA[Results] List the merchant's interview results.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| tab | No | Filter by decision/completion state. Omit (or empty) to include all. | |
| step | No | Filter by pipeline step (pre-screening vs interview). Omit for both. | |
| type | No | Product type of results to list. | interview |
| limit | No | Maximum number of records to return (1–1000). | |
| risks | No | Comma-separated list of recruiter-risk keys to filter by (matches any). | |
| offset | No | Number of records to skip from the start of the result set. | |
| order_by | No | Sort order of the result set. | created_at_newest |
| filter_text | No | Case-insensitive search on candidate name or email. | |
| merchant_id | No | Optional merchant to scope to. Admins and sub-merchant operators only; other callers always use their token's merchant. | |
| filter_emoji | No | Filter by the candidate emoji marker. | |
| interview_id | No | Filter to a single interview definition id. | |
| profile_interview_id | No | Filter to a single candidate (profile_interview) id. |
| Name | Required | Description |
|---|---|---|
| data | Yes | The merchant's interview results for this page. |
| pagination | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds valuable behavioral context: pagination cap of 1000 records, scoping rules, and that it's the admin-portal results list.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with purpose, and uses two short paragraphs. Every sentence adds value without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (12 parameters, output schema exists), the description covers the purpose, pagination, scoping, and cap. It could mention the default type or sort order, but the output schema compensates. Overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The tool-level description does not add significant per-parameter meaning beyond what the schema provides. It mentions the 1000 cap, which is reflected in the limit parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (list), resource (interview results), and scope (merchant's, admin-portal). It differentiates from siblings like get_interview_result_details and list_candidates by focusing on a paginated list of results.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly indicates when to use this tool (to list results, paginated, scoped) but does not explicitly state when not to use it or suggest alternatives. The context of scoping is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_interviewsList interviewsA[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.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Product type of interviews to list. | interview |
| limit | No | Maximum number of records to return (1–1000). | |
| offset | No | Number of records to skip from the start of the result set. | |
| status | No | Filter by lifecycle status. Omit to include all statuses. | |
| show_demo | No | Include demo/sample interviews. | false |
| filter_text | No | Case-insensitive search on the interview name. | |
| merchant_id | No | Optional merchant to scope to. Admins and sub-merchant operators only; other callers always use their token's merchant. | |
| show_public | No | Include interviews shared publicly across merchants (coaching/avatars). | false |
| filter_emoji | No | Filter by the interview emoji marker. |
| Name | Required | Description |
|---|---|---|
| data | Yes | The merchant's interview definitions for this page, newest-updated first. |
| pagination | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds behavioral details: paginated list, capped at 1000 records, scoped to merchant, and optional merchant_id override for admins. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences plus a header. It front-loads the action and every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 params, many siblings, output schema exists), the description covers the main purpose, scoping, pagination cap, and merchant override. Output details are handled by the existing output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, baseline is 3. The description adds value by explaining merchant_id scoping and the 1000 cap, which relate to parameters not fully covered in schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List the merchant's interview definitions' and 'Paginated list of a merchant's interview definitions'. It identifies the verb (list) and resource (interview definitions), distinguishing it from sibling tools like get_interview_definition (singular) and create_interview.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions scoping to token's merchant or merchant_id override and a cap of 1000 records per page, providing usage context. However, it does not explicitly state when to use this tool versus alternatives like get_interview_definition or create_interview.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_languagesList supported languagesA[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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| languages | Yes | Supported platform languages, sorted by English name. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds admin restriction and specifies exact return fields (code, names, flag URL, etc.), adding value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two paragraphs restate similar information, with redundancy. Could be condensed into one sentence with bullet points for fields. Not excessively long but not optimally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and presence of output schema, the description still adds valuable context (admin requirement, usage of code) and lists return fields. Complete for its purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, so baseline is 4. Description explains returned fields, though it is somewhat repetitive. Still provides clarity on what is returned.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it lists supported platform languages, including specific fields like code, names, and flag URL. Distinct from siblings which are about interviews and personas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Includes [Admin] prefix indicating intended audience, and mentions using the code in interviews/personas. Lacks explicit when-to-use vs alternatives, but context is sufficient for a simple list tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_my_merchantsList merchants you can act asAFALLBACK 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).
| Name | Required | Description | Default |
|---|---|---|---|
| search | No | Optional case-insensitive filter on sub-merchant name. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint true and destructiveHint false. The description adds behavioral context: it is a fallback, returns own account plus sub-merchants, and advises how to use the result. No contradictions, and the extra context is helpful, though it doesn't detail rate limits or authentication.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using three sentences that front-load the key purpose ('FALLBACK merchant list') and then efficiently cover usage, return content, and follow-up actions. No unnecessary verbiage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional parameter, output schema present), the description is complete: it explains purpose, when to use, what it returns, and how to use the output. The presence of an output schema relieves the need for return value details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter described. The description does not add new semantic information beyond the schema's parameter description; it merely restates 'sub-merchant name' implicitly. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: a fallback merchant list for clients without UI support. It explicitly distinguishes from the interactive picker (jobmojito_configuration) and implies differentiation from list_sub_merchants by indicating it returns both own account and sub-merchants.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance on when to use (only when client cannot render UI), when not to use (when UI is available, use jobmojito_configuration instead), and what not to do (do not hand-format as text). Also provides usage instructions for the returned merchant IDs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_sub_merchantsList sub-merchantsA[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.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of records to return (1–1000). | |
| offset | No | Number of records to skip from the start of the result set. | |
| order_by | No | Sort order of the result set. | created_at_newest |
| filter_text | No | Case-insensitive search on the sub-merchant name. | |
| merchant_id | No | Optional merchant to scope to. Admins and sub-merchant operators only; other callers always use their token's merchant. |
| Name | Required | Description |
|---|---|---|
| data | Yes | The sub-merchants the caller administers for this page. |
| pagination | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral details: pagination capped at 1000 records, row-level security, and admin scope, which go beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-load the admin context and purpose, followed by pagination and security details. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With full schema coverage and annotations, the description covers core purpose, pagination cap, and security. Output schema exists, so return values are not needed. Lacks mention of sorting/filtering but schema handles that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for all 5 parameters. The description adds minimal new meaning, only reiterating the pagination cap already present in the schema. Baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'List sub-merchants under the merchant account' with a clear verb (list) and resource (sub-merchants). No sibling tool has a similar name, so differentiation is inherent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies admin context and row-level security, giving clear usage context. However, it does not explicitly exclude alternative tools or provide when-not guidance, though naming makes it unique.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
register_users_for_interviewRegister candidates for interviewA[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).
| Name | Required | Description | Default |
|---|---|---|---|
| users | Yes | Candidates to register for the interview. Each gets a one-time interview URL. | |
| is_test | No | When true (or the string "true"), mints a test token that can take a draft/unpublished interview and flags the result as a test. For a DRAFT interview it also recompiles the definition (interview_recalc_definition) first, so the test session includes the current questions/welcome. This makes it a single-call "trigger interview test". | |
| hide_menu | No | When true (or the string "true"), the interview UI hides its menu (view_hm). | |
| send_email | No | Whether to send an invitation email to each registered candidate. | |
| hide_iframe | No | When true (or the string "true"), the interview UI hides its iframe chrome (view_hi). | |
| merchant_id | No | Merchant id. Required when authenticating with the service key; for user tokens it is optional and only honored for admin / sub-merchant accounts. | |
| interview_id | Yes | Interview definition (interview_def_set) or position (position_def_set) id to register users for. |
| Name | Required | Description |
|---|---|---|
| result | Yes | The input users, each annotated with its registration result and (on success) interview URL. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond annotations by specifying authentication requirements and the return of one-time URLs, but does not detail side effects like email sending or error conditions. Annotations already indicate destructiveHint=true, so no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the core purpose, and every sentence adds value without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers core functionality, authentication, and return value, and the schema covers all parameters. It is complete enough for an AI agent to understand usage, though it could mention edge cases like duplicate registration.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description summarizes the purpose but does not add significant meaning beyond the schema's per-parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'register' and the resource 'users/candidates for a specific interview', and specifies the outcome 'return their personal interview links'. It distinguishes from sibling tools like 'create_interview' or 'generate_interview_url'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on authentication (JWT vs service key) and mentions it can update existing profiles, but does not explicitly state when to use this tool vs alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
request_another_interview_attemptRe-open interview for another attemptA[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.
| Name | Required | Description | Default |
|---|---|---|---|
| interview_result_id | Yes | The interview result to reopen for another attempt. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true, and the description elaborates on the destructive actions: marking unsuccessful, resetting to draft, and clearing the recruiter decision. This adds context beyond annotations about the specific state changes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, followed by detailed effects. No redundant information. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the preconditions (submitted+completed) and the effects. With an output schema present, return values are not needed. It is sufficiently complete for a mutation tool with clear annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the single parameter 'interview_result_id' is described in the schema. The description does not add extra meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reopens a submitted interview result for another attempt. It specifies the action, resource, and effects (marks unsuccessful, resets to draft, clears decision), distinguishing it from siblings like set_interview_state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on when to use the tool: for submitted (active+completed) interview results. It implies preconditions but does not explicitly mention when not to use or alternatives. This is clear enough for most agents.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_documentationSearch JobMojito documentationASearch 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.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results per source (1-25). | |
| query | Yes | Natural-language search query or keywords. | |
| source | No | "all" (default), "developer", or "help" to restrict the search. | all |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and idempotentHint=true. The description goes beyond by detailing the parallel search across two sources, merging with source labels, and serving as the single entry point. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with clear structure: purpose, behavior, usage guidance, and a note about subsequent use of `get_documentation`. Bullet points effectively list the two documentation sources. Every sentence contributes meaning without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (search with merging) and the presence of an output schema (confirmed by context), the description fully explains the return format (merged, source-labeled list) and the role of the tool alongside `get_documentation`. It is complete for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents the parameters. The description adds value by explaining the content of the 'developer' source (API reference, schemas, etc.) and 'help' source (product guides), enriching understanding of the `source` parameter beyond its enum values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches all JobMojito documentation, merging results from two sources (developer and help) with labels. It distinguishes itself from the sibling tool `get_documentation` by positioning itself as the entry point and advising subsequent use of `get_documentation` for full pages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use the tool: '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.' It also clarifies that the user does not need to choose a source or call a separate tool because it handles both sources in parallel.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
set_interview_stateChange interview stateA[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.
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | New lifecycle status to apply. | |
| is_embedded | No | Controls iframe embedding of the interview on an external page. When true, ensures an embed key exists (returns embed_id/embed_signing_key, used to authenticate/sign the iframe embed). When false, removes the embed keys (disables embedding). | |
| position_id | Yes | Interview definition id or position id whose state should change. |
| Name | Required | Description |
|---|---|---|
| result | Yes | Returns `{ embed_id, embed_signing_key }` when an embed key was created/returned (is_embedded=true), otherwise `{ success: true }`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond annotations: it explains that the embed key is managed via is_embedded, and lists all possible statuses including 'deleted' (destructive). However, it does not mention irreversible effects of deletion or behavior when both parameters are provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first front-loads the core purpose, the second adds detail. No unnecessary words, efficient structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of annotations, full schema coverage, and an output schema, the description covers the main behaviors and parameter constraints. It lacks information about side effects (e.g., reversible? error conditions?) but is largely complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the baseline is 3. The description adds value by clarifying the constraint 'Provide at least one of status or is_embedded' and explaining the purpose of is_embedded (managing embed key), which supplements the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool changes the lifecycle status of an interview/position and manages its embed key. The examples 'draft, active, archived' give specificity. However, the parenthetical '(e.g. open, closed)' is slightly inconsistent with the listed enum values, causing minor confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a parameter usage guideline ('Provide at least one of status or is_embedded') but does not explicitly tell when to use this tool versus siblings like create_interview or list_interviews. The context is implied but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
upload_knowledge_base_documentUpload knowledge base documentA[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).
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | The document file (binary). | |
| name | No | Document name (with extension). Falls back to the uploaded file name for multipart. | |
| merchant_id | No | Override merchant id (admin / sub-merchant only). | |
| knowledge_base_store_id | Yes | The knowledge base store to add the document to. |
| Name | Required | Description |
|---|---|---|
| knowledge_base_id | Yes | Id of the created knowledge_base record. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true (modifies data). The description adds that uploading queues the document for processing, implying asynchronous behavior. However, it does not detail what happens after processing, whether overwriting occurs, or error scenarios. The description adds some context beyond annotations but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two paragraphs, front-loaded with the purpose, and provides necessary details succinctly. It is slightly verbose in repeating file formats but overall efficient. No unnecessary sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists (return values are handled separately), the tool description covers the main behavior: uploading, queuing, and accepted formats. It lacks details about processing time, error handling, or file size limits, but annotations and schema mitigate some gaps. For a 4-parameter tool, it is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds value by explaining that the file parameter can be binary or base64 depending on Content-Type, and that the name falls back to the uploaded file name for multipart. This clarifies parameter usage beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The title and description clearly state that the tool uploads and processes a knowledge base document. It uses specific verbs (upload, process) and identifies the resource (knowledge base document), distinguishing it from sibling tools focused on interviews, personas, and merchants.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that the tool accepts file as multipart/form-data or JSON, and mentions queuing for processing. However, it does not explicitly state when to use this tool versus alternatives, nor does it provide prerequisites (e.g., store must exist) or exclusion cases. Nonetheless, no direct sibling tool performs similar uploading, so the guidance is adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
