The AI Interview Agents MCP Server enables you to manage an end-to-end AI-driven hiring pipeline via natural language from any MCP client, covering everything from role creation to scored interview reports.
Role Management
List existing job roles and create new ones from job descriptions
Set up dedicated screening roles with skills, experience, location, and work mode requirements
Candidate & CV Processing
Parse CV/resume files (PDF, DOCX, up to 20 per call) with OCR fallback to extract candidate info
Add parsed candidates to screening roles and reassign candidates between roles
CV Screening & Ranking
Trigger async AI scoring of CVs against a job description
Retrieve ranked results with scores (0–100), verdicts (strong/possible/weak/reject), matched/missing skills, and location fit
Interview Scheduling & Management
Schedule AI-driven voice interviews (screening, technical, or HR types; multilingual support)
Use dry-run mode to preview configuration before sending invites or consuming quota
Reschedule, cancel, and send reminder emails for interviews
Schedule top-ranked screened candidates directly for interviews
Question Preview
Generate and preview AI-tailored interview questions before committing to a schedule
Reporting & Pipeline
List interviews with filters (role, candidate, status, date)
Retrieve full interview details including transcripts and feedback
Access scored reports with analysis summaries, strengths, weaknesses, and recommendations
View the candidate pipeline funnel (invited/scheduled/completed/no-show) per role
Provides authentication integration with Firebase, enabling secure user sign-in and bearer token validation for API requests.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@AI Interview Agents MCP Server List all candidates for the senior developer role."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
The official Model Context Protocol server for AI Interview Agents, a voice-AI hiring platform. It lets any MCP client (Claude, Cursor, custom agents) drive the recruiting workflow in natural language: create roles, screen CVs, schedule and manage candidate interviews, and read back scored reports with transcripts.
The live voice interview itself is out of scope here (that runs on a separate real-time service). This server triggers interviews and reads back the results.
Roles — list your roles, or create one from a job description.
Candidates & CVs — parse dropped CV/PDF files, normalize messy pasted candidate lists (names, emails, phone numbers, experience, skills), and reassign candidates between roles.
Interviews — schedule interviews (with a dry_run mode that normalizes and previews without sending anything or consuming quota), reschedule, cancel, and send reminders.
Reports — read the candidate pipeline and pull back scored interview reports with transcripts.
Related MCP server: HRizzle-HR-Assist
The server runs remotely with OAuth sign-in. Point any Streamable-HTTP MCP client at:
{
"mcpServers": {
"ai-interview-agents": {
"type": "streamable-http",
"url": "https://mcp.aiinterviewagents.com/mcp"
}
}
}Your client discovers the auth flow automatically via /.well-known/oauth-protected-resource and signs you in with your AI Interview Agents account. It is also listed in the official MCP Registry as com.aiinterviewagents/interviews.
pip install -e .
export AIIA_FIREBASE_TOKEN="<your token>" # or: aiia-mcp login
aiia-mcpAIIA_BACKEND_URL overrides the API base if you are pointing at your own deployment.
The server holds no account secrets. Each request carries the user's own Firebase ID token, forwarded to the backend as a bearer token — the same trust path as the web app. For the hosted transport, an OAuth layer (dynamic client registration + PKCE) bridges MCP clients to Firebase sign-in.
pip install -e ".[dev]"
pytest
ruff check .MIT — see LICENSE.
Attach parsed CVs to a screening as candidates, ready to be scored.
Pass the rows returned by parse_cvs straight through — each
{"identity": {...}, "details": {...}} row is reshaped automatically into
what the backend needs. Already-flat dicts ({firstName, lastName, email,
summary, parsedResumeData, number, location}) also work.
Email is NOT required here — screening scores a CV, it doesn't message
anyone. CVs with no email are kept and given an unroutable placeholder so
they still rank; the response's 'withoutEmail' count tells you how many.
Those rows CANNOT be scheduled later until a real email is added — surface
that number to the user.
Returns {savedCount, skippedEmpty (CVs with no readable content),
withoutEmail, candidates}. After this, call run_screening(role_id).
| Name | Required | Description | Default |
|---|---|---|---|
| role_id | Yes | ||
| candidates | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate write operation (readOnlyHint=false) and not destructive. The description adds significant behavioral details: email is not required, CVs without email get a placeholder and are counted in withoutEmail, and they cannot be scheduled later until email is added. This 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?
The description is multi-sentence but front-loaded with the main purpose. Every sentence adds value, though slightly verbose. Could be trimmed slightly but still 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?
Despite no output schema, the description explains the return fields (savedCount, skippedEmpty, withoutEmail, candidates) and provides next-step guidance (call run_screening). This 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?
Schema coverage is 0%, but the description compensates by explaining the candidates parameter accepts two formats (rows from parse_cvs or flat dicts) and details the structure. role_id is not explained, but the main complex parameter is well described.
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 attaches parsed CVs to a screening as candidates. It specifies the input format (rows from parse_cvs or flat dicts) and distinguishes itself from sibling tools like schedule_screened_candidates by implying it's the step before run_screening.
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 tells when to use (after parse_cvs) and provides clear context about email handling and the next step (call run_screening). It does not explicitly state when not to use or mention alternatives, but the usage is well-scoped.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cancel a scheduled interview. Destructive — meeting and candidate rows are deleted.
ASK BEFORE CALLING if the user said "that interview" / "Priya's"
/ anything ambiguous and you don't have a specific meeting_id from
a prior list_meetings result. Call list_meetings first to surface
candidates, then confirm with the user which meeting they mean.
Cancelling the wrong meeting cannot be undone in-band — the
candidate has to be rescheduled from scratch.
| Name | Required | Description | Default |
|---|---|---|---|
| meeting_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (destructiveHint=true), the description discloses that meeting and candidate rows are deleted and that cancellation cannot be undone in-band. This adds critical context about side effects and recovery limitations.
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?
Efficiently structured with a clear purpose first, then destructive warning, and finally usage guidelines in a logical order. 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?
For a destructive tool with a single parameter and no output schema, the description covers purpose, behavior prerequisites, parameter source, and risks. No gaps remain for effective agent usage.
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 has 0% description coverage, but the description explains meeting_id as a value from list_meetings and implies its role in identifying the specific interview. While it doesn't specify format, the context is sufficient for a simple string 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 ('Cancel a scheduled interview') and identifies the resource (interview) with specific destructive consequences. It implicitly distinguishes from siblings like reschedule_interview by calling out its destructive nature.
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 guidance on when to ask before calling (ambiguous references) and directs to call list_meetings first. Also warns about irreversibility, offering a clear decision framework for the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a Screening — a role to rank CVs against a JD before spending any interview credit. Returns {"roleId": , ...}; keep that roleId for the rest of the flow.
THE SCREENING FLOW (call these tools in order):
1. create_screening_role ← you are here
2. parse_cvs(files=...) — extract candidates from resume files
3. add_screening_candidates(role_id, candidates=<parse_cvs rows>)
4. run_screening(role_id) — starts async CV-vs-JD scoring
5. get_screening_results(role_id) — poll until scored, read the ranking
6. schedule_screened_candidates(role_id, candidate_ids) — invite the good ones
FIELDS:
- name: the screening / role title (required, e.g. "Senior Backend Engineer").
- job_description: paste the full JD text if you have it — it drives the
score most. Optional but strongly recommended.
- must_have_skills vs nice_to_have_skills: skills the role weighs heavily
vs would-be-nice. Neither AUTO-REJECTS anyone — they shape the LLM
score and the matched/related/missing breakdown.
- experience: free text, e.g. "5+ years".
- location + work_mode: work_mode is 'remote', 'onsite', or 'hybrid'.
Location is a soft signal only (a remote role ignores it); nobody is
dropped for being in the wrong city.
- additional_requirements: free text the model folds into scoring, e.g.
"valid work visa", "bachelor's degree", "AWS certified".
- language: 'en', 'hi', or 'ar'. company_name: optional.
This creates a role record (screening_enabled). If the user already has a
screening for this opening, call list_screening_roles first and reuse its
roleId instead of making a duplicate.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| language | No | en | |
| location | No | ||
| work_mode | No | ||
| experience | No | ||
| company_name | No | ||
| job_description | No | ||
| must_have_skills | No | ||
| nice_to_have_skills | No | ||
| additional_requirements | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare non-read-only, non-destructive, non-open-world. Description adds that it creates a role record, returns roleId, does not auto-reject, and that location is a soft signal for remote roles. 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?
Well-structured with numbered flow, fields list, and usage notes. Front-loaded with return value. Slightly long but justified by complexity of 10 parameters and flow context.
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?
Provides return format (roleId), full flow, parameter details, and duplicate avoidance guidance. Lacks output schema but description compensates adequately 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?
Schema coverage is 0% but description explains each of the 10 parameters with examples, constraints (e.g., required name, soft signals, language enum), and behavioral impact (e.g., job_description drives scoring).
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 a screening role, part of a CV ranking flow, and distinguishes it from sibling tools by explaining the overall flow and when to use list_screening_roles instead.
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 provides when to use (creating a new screening), when not to (reuse existing roleId from list_screening_roles if duplicate), and outlines the complete six-step flow with tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate interview questions using AI. Read-only — does not create a role or schedule anything. Use to preview what the bot will ask before committing to schedule_interview.
interview_type: 'screening' or 'technical'.
language: 'en', 'hi', 'ar'.
| Name | Required | Description | Default |
|---|---|---|---|
| duration | No | ||
| language | No | en | |
| position | Yes | ||
| company_name | No | ||
| interview_type | Yes | ||
| job_description | No | ||
| required_skills | Yes | ||
| required_experience | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already set readOnlyHint=true. Description reinforces 'Read-only' and adds 'does not create a role or schedule anything,' which aligns with annotations and clarifies non-destructive nature. No additional behavioral traits disclosed 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 concise sentences. First sentence states purpose, second clarifies scope, third hints at parameter values. No fluff, but could be better structured with bullet points for parameters.
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 8 parameters, no output schema, and many siblings, the description covers main use case and parameter hints. However, it lacks description of return format or behavior on invalid input, which is needed since no output schema exists.
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 0%, so description must compensate. It provides enum values for interview_type and language, but leaves 6 other parameters (duration, position, company_name, job_description, required_skills, required_experience) unexplained. Insufficient for an 8-parameter tool.
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 action ('Generate interview questions using AI') and resource. Distinguishes from siblings by noting it does not create a role or schedule anything, and specifically references schedule_interview as the alternative.
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 states when to use: 'Use to preview what the bot will ask before committing to schedule_interview.' Implies not to use for actual scheduling, providing clear context and alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full details of a single meeting including transcript and feedback.
meeting_id accepts the UUID or the integer primary key.
| Name | Required | Description | Default |
|---|---|---|---|
| meeting_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description adds value by specifying the output includes 'transcript and feedback', which is beyond what annotations provide. However, it does not disclose potential errors or latency.
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 with no fluff. The first sentence covers purpose and output content, the second clarifies the parameter. Every word is essential.
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 no output schema, the description adequately explains the return value (transcript and feedback) for a read-only tool with one parameter. It could be more detailed on the return structure, but overall it's sufficient for agent usage.
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 0% schema coverage, the description compensates by clarifying that 'meeting_id' accepts 'UUID or integer primary key', adding format details beyond the schema's string type. This helps agents correctly format the 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 verb 'get' and the resource 'single meeting', specifying it returns 'full details including transcript and feedback'. This differentiates it from sibling tools like 'list_meetings' which only list meetings without detailed content.
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 explicit guidance on when to use this tool versus alternatives. The description does not mention prerequisites, such as needing a meeting ID from 'list_meetings', or exclude scenarios where other tools might be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pipeline view (invited / scheduled / completed / no-show) for a role.
Use to answer 'how is the hiring going for this role'.
| Name | Required | Description | Default |
|---|---|---|---|
| role_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds the pipeline stages but does not disclose behavior like response format, pagination, or error handling. For a read-only tool, this is acceptable but not excellent.
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 short, focused sentences that front-load the core information. No unnecessary words or repetition. Efficiently conveys the essence.
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?
No output schema exists, so the description should hint at what is returned. It mentions stages but not whether it returns counts, candidate details, or both. For a simple tool, it is adequate but leaves some ambiguity.
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?
Single parameter role_id is self-explanatory from its name and type (integer). Schema coverage is 0%, but the description does not need to elaborate further. 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?
Description clearly states it's a pipeline view for a role with specific stages (invited, scheduled, completed, no-show). It directly answers the question 'how is the hiring going for this role', making the tool's 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?
Explicitly says to use it to answer a specific question, providing clear context. However, it does not mention when not to use it or compare with sibling tools like get_screening_results, which could be similar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scored interview report: analysisSummary, strengths, weaknesses, recommendations, averagePercentage, nextSteps.
Returns status=processing if the report hasn't generated yet.
| Name | Required | Description | Default |
|---|---|---|---|
| meeting_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the tool is safe. The description adds that it returns status=processing if the report hasn't generated yet, which is important behavioral context beyond the 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 sentences, no wasted words. First sentence conveys the purpose and contents, second sentence adds a special case. Well front-loaded.
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 retrieval tool with one parameter and no output schema, the description covers the core output fields and an edge case (processing). It lacks details on error states or prerequisites, but given the readOnly annotation, it is reasonably 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 0%, so the description should compensate. It does not explain the meeting_id parameter (e.g., what it refers to, format, or where to get it). The context implies it's an interview meeting ID, but explicitly documenting it would be helpful.
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 a scored interview report and lists specific fields (analysisSummary, strengths, etc.). It distinguishes from sibling tools like get_meeting, which likely returns raw meeting data, not a scored report.
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 get_meeting or get_screening_results. There is no mention of prerequisites or context for when this report is available.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a screening's ranked candidates (the poll for run_screening).
Returns {roleId, count, role:{name, mustHaveSkills, niceToHaveSkills,
location, workMode, additionalRequirements}, candidates:[...]}, candidates
sorted best-first by screeningScore. Each candidate:
{id, name, email, hasEmail, phone, position, experienceYears, location,
locationFit ('remote'|'in_region'|'other'|null), screeningScore (0-100),
screeningVerdict ('strong'|'possible'|'weak'|'reject'), screeningStatus,
reason, matchedSkills, relatedSkills, missingSkills, status, screenedAt}.
DONE-SIGNALS (scoring is async): a candidate is finished when
screeningStatus is 'scored', 'hard_filtered', 'overridden', or 'error',
and still pending at 'not_screened'. The whole screening is done when
every row has left 'not_screened' (or screenedCount == candidateCount in
list_screening_roles). If rows are still 'not_screened', wait and call again.
To schedule, take the 'id' of each candidate you want and pass them to
schedule_screened_candidates. Skip rows where hasEmail is false — they
need a real email first.
Results are capped at `limit` (default 100, top by score) and each
'reason' is truncated to keep the response small; raise limit if you
need more rows.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| role_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=true, destructiveHint=false), the description explains async scoring behavior, done-signals, result capping at limit, and truncation of 'reason' fields. 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 well-structured with bullet points and clear sections, but slightly verbose. Every sentence adds value, though some details (e.g., full candidate fields) could be condensed.
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 no output schema, the description provides a detailed output structure. It covers async behavior, status checks, and usage context. Missing explicit mention of requiring a prior screening run, but generally complete for a read 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?
With 0% schema description coverage, the description adds meaning for 'limit' (capping and default) and implicitly clarifies 'role_id' through context. It could explicitly state that 'role_id' identifies the screening's role.
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 'Read a screening's ranked candidates' with a specific verb ('read') and resource ('screening's ranked candidates'). It distinguishes from siblings like 'run_screening' and 'schedule_screened_candidates' by focusing on reading 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 provides explicit guidance on when to use the tool: after running a screening, how to check completion via screeningStatus, and when to poll again. It also names an alternative ('list_screening_roles') for checking candidate counts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List interviews for the authenticated HR user.
Optional filters:
- role_id, candidate_id — narrow to a specific role / candidate
- status — one of: Scheduled, Completed, Cancelled, Expired
- scheduled_after — ISO datetime or YYYY-MM-DD; only meetings
scheduled on/after this point. Use for "last week" / "this
month" queries (compute the cutoff client-side).
Returns paginated meeting records with totals for completed and
cancelled. The 'role_name' field on each row is the easiest way to
surface 'recent roles' when the user hasn't named one yet.
Rows are summaries: transcripts and full report payloads are
stripped to keep responses small — use get_meeting / get_report
for one meeting's full detail.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| size | No | ||
| status | No | ||
| role_id | No | ||
| candidate_id | No | ||
| scheduled_after | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=true, destructiveHint=false), the description discloses that returns are paginated with totals for completed and cancelled, and that rows are summaries with transcripts/reports stripped to keep responses small. This adds meaningful behavioral context.
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 well-structured with bullet points for filters, but slightly verbose in parts (e.g., parenthetical 'compute the cutoff client-side'). However, every sentence adds value, and it avoids 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 no output schema, the description covers return type (paginated records, totals, role_name field), partial nature of data, and references sibling tools for full detail. This is complete for a list tool with good 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?
Despite 0% schema description coverage, the description fully explains each parameter: role_id, candidate_id, status (with enumerated values), and scheduled_after (with ISO datetime format and usage examples). This compensates entirely for the lack of 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 interviews for the authenticated HR user.' It uses a specific verb and resource, and distinguishes itself from sibling tools like get_meeting and get_report by noting that rows are summaries and full detail is elsewhere.
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 filters (e.g., 'Use for last week / this month queries') and advises using get_meeting/get_report for full details. It also explains the role_name field as an easy way to surface recent roles.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the authenticated HR user's roles (job postings / openings).
Use this whenever the user hasn't named a role and you need to ask
"which role should I schedule against?" — surface 2-3 recent ones
from the response by 'name' / 'position'. Also use for queries like
"what roles do I have" or "what openings am I hiring for".
Returns: {"data": [{roleId, name, position, experience, skills,
evaluationFocus, interviewType, jobDescription, language, ...}]}.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds value by detailing the return format with sample fields (roleId, name, position, etc.) and noting that recent ones should be surfaced, providing behavioral 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 concise yet informative: first sentence defines purpose, then usage guidelines, then return format. It is front-loaded and every sentence earns its place.
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 annotations covering safety, the description covers purpose, usage, and return format. It provides enough context for the agent to use the tool correctly without gaps.
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 has zero parameters, so the description does not need to add parameter information. Baseline for 0 params is 4; the description correctly omits param details.
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 starts with 'List the authenticated HR user's roles' which is a specific verb and resource. It clearly distinguishes from sibling tools like list_meetings or list_screening_roles by specifying roles as job postings/openings.
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 when-to-use guidance: 'Use this whenever the user hasn't named a role and you need to ask which role should I schedule against?' and gives example queries like 'what roles do I have'. This helps the agent select the tool correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the authenticated user's screenings (CV-screening roles).
Use this to find an existing screening's roleId (so you don't create a
duplicate), or to report progress. Each row carries:
{roleId, name, position, location, workMode, candidateCount,
screenedCount, topMatches (score >= 60), scheduledCount, createdAt}.
screenedCount == candidateCount means scoring has finished for that
screening (the role-level done-signal for run_screening). topMatches is
the count worth scheduling.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, but description adds context about completion condition and meaning of fields beyond safety. 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?
Concise, front-loaded with purpose, followed by actionable details in a compact 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?
Fully covers all aspects: what it does, what fields are returned, how to interpret them, and how it ties to run_screening. No gaps.
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 exist; baseline 4 as description adds no confusion. Schema coverage 100% trivial.
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?
Clear verb 'list' with specific resource 'screenings (CV-screening roles)', distinguishes from siblings by mentioning roleId and avoiding duplicates.
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 states when to use (find roleId to avoid duplicate, report progress) and provides signal for completion: 'screenedCount == candidateCount means scoring has finished'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract candidate identity (name, email, phone) from CV/resume files (PDF or DOCX, up to 20 per call). Runs OCR fallback for image-based PDFs. Returns deduplicated candidate rows ready to pass to schedule_interview.
Each entry in 'files' must have:
- 'name': filename including extension
- 'bytes_base64': base64-encoded file contents
If role_id is provided, dedups against candidates already attached to
that role. Files exceeding 20 are rejected — batch across multiple calls.
After parsing, ALWAYS show the user the extracted name/email/phone for
each file before scheduling, then call schedule_interview with the
returned 'candidates' list.
| Name | Required | Description | Default |
|---|---|---|---|
| files | Yes | ||
| role_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate non-destructive read but description adds context: OCR fallback, dedup logic, rejection of over 20 files. 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?
Well-structured with purpose first then details. Slightly wordy but each sentence adds value. Could be tightened slightly.
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?
No output schema, but description mentions returning candidate rows ready for schedule_interview. Could specify structure more precisely. Covers error handling and batch guidance.
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 0% schema description coverage, the description fully explains the 'files' array requires name and bytes_base64 fields, and role_id for dedup. Schema is minimal but description compensates.
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?
Description clearly states the tool extracts candidate identity from CV/resume files, handles PDF/DOCX, and includes OCR fallback. It distinguishes from siblings like schedule_interview, add_screening_candidates, etc.
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: after parsing, show results before scheduling, then call schedule_interview. Also advises batching if more than 20 files.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move a candidate from their current role to a different one. Existing meetings cascade to the new role. Records the reassignment in reassignmentAuditLogs with the optional reason.
ASK BEFORE CALLING if either candidate_id or to_role_id is not
unambiguous from the user's message. Reassignment affects all the
candidate's open meetings — confirm before moving.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | ||
| to_role_id | Yes | ||
| candidate_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations set readOnlyHint=false and destructiveHint=false, but the description adds important behavioral details: 'Existing meetings cascade to the new role' and 'Records the reassignment in reassignmentAuditLogs with the optional reason.' It also warns about affecting open meetings. There is 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 five sentences, front-loaded with the core purpose. Every sentence adds value (side effects, audit logging, usage warnings). It is slightly verbose but not wasteful; could be more streamlined but remains effective.
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 mutation tool with no output schema, the description covers key aspects: what it does, side effects (meetings cascade), recording in audit logs, and when to ask for confirmation. It lacks details on return value or potential errors, but overall it provides sufficient context for safe usage.
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 0%, so the description must compensate. It names all three parameters (candidate_id, to_role_id, reason) and explains that reason is optional. However, it does not provide further detail like data types or expected values beyond what the schema shows. This adds moderate value but leaves gaps.
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: 'Move a candidate from their current role to a different one.' It specifies the verb (move/reassign) and resource (candidate), and the mention of existing meetings and audit logs adds specificity. Among siblings, no other tool performs reassignment, so it is well-distinguished.
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: 'ASK BEFORE CALLING if either candidate_id or to_role_id is not unambiguous from the user's message.' It also instructs to confirm before moving because 'Reassignment affects all the candidate's open meetings.' This tells the agent when to call and when to avoid automated invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reschedule a meeting. Emails the candidate a new invite link.
ASK BEFORE CALLING if the meeting isn't unambiguously identified
by the user's message. Same rule as cancel_interview: a
rescheduled-wrong-meeting message is awkward to clean up.
| Name | Required | Description | Default |
|---|---|---|---|
| meeting_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate non-read-only and non-destructive. Description adds that it emails the candidate and warns about awkward cleanup of wrong meetings. No contradictions; adds 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 concise sentences plus a brief warning block. No redundant information, front-loaded with purpose and outcome.
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 purpose, guidelines, side effects (email), and caution about ambiguity. Does not mention constraints like meeting must be in future, but sufficient for most use cases given simplicity.
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?
One required parameter 'meeting_id' with 0% schema coverage. The description implies its use but does not explicitly explain its format or source. Adequate for a single-param tool, but could be more explicit.
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?
Description clearly states the verb 'Reschedule' and resource 'meeting', and specifies the outcome 'Emails the candidate a new invite link'. It differentiates from sibling 'cancel_interview' by referencing the same rule.
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 instructs to ask before calling if the meeting is not unambiguously identified, and references sibling 'cancel_interview' for the same reasoning. Provides clear when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start CV-vs-JD scoring for a screening's candidates. ASYNC: this returns immediately with {"status": "queued"} and NO scores — the LLM scoring runs in the background.
To read results, poll get_screening_results(role_id) a few seconds later
(and again until candidates leave the 'not_screened' status). Do not
expect scores in this tool's response.
- Scoring is idempotent: candidates whose CV+JD are unchanged since the
last run are skipped. Pass force=True to re-score everything (e.g.
after you have not changed the JD but want a fresh pass).
- limit: optionally cap how many candidates get scored this run.
- Uses a cheap model; safe to run on a large roster.
| Name | Required | Description | Default |
|---|---|---|---|
| force | No | ||
| limit | No | ||
| role_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds significant context beyond annotations: async return, background scoring, idempotency with skip, force re-scoring, limit parameter, cheap model, safe for large roster. 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?
Well-formatted with async warning upfront, bullet points for details, no redundant sentences. Each 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?
Covers async return, polling pattern, idempotency, force, limit, model safety. With no output schema, explains what to expect and how to get results.
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 0% schema description coverage, explains all three parameters: force (re-score all), limit (cap candidates), role_id implied as required. Adds practical usage details.
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?
Clear action verb 'Start' with specific resource 'CV-vs-JD scoring for a screening's candidates'. Distinguishes from sibling tools like get_screening_results which reads 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?
Explicitly states async behavior, polling pattern with get_screening_results, idempotency with force option, and when to expect scores. No ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Schedule AI-driven interviews. Creates meetings and sends invite emails.
ASK BEFORE CALLING — DO NOT PICK A ROLE ON YOUR OWN:
- A role is MANDATORY and now ENFORCED: if you pass neither role_id
nor a position, this tool schedules NOTHING and returns
{"status": "role_required", "existingRoles": [...]}. When you get
that, ask the user which role to use, suggesting the returned
existingRoles, and only call again once they pick one.
- If the user did not name a role AND did not give enough info to
create a new one (position + JD/skills), STOP and ask first.
- Wrong role = wrong invite goes out. Treat role selection as
mandatory clarifying input; never default.
DRY RUN FIRST IF YOU'RE AUTO-FILLING ANYTHING:
- If you are supplying any field the user did not explicitly state —
interview_type, position, job_description, evaluation_focus,
duration, language, required_skills, OR candidates extracted from
a paste/CV — CALL WITH dry_run=True FIRST.
- The response returns the normalized candidates + the role payload
that WOULD be created or used, including the evaluation focus
split. Persists nothing, sends no email, consumes no quota.
- Read it back to the user in chat as a brief "here's what I'd send"
summary (4–6 bullet lines covering candidates, role, interview
type, focus split, JD if auto-generated). Get explicit go-ahead.
- THEN call again with dry_run=False to actually send invites.
- Only skip dry_run when EVERY field came from the user verbatim
(e.g. they named the role, the interview type, and pasted clean
structured candidates with no extraction).
EVALUATION FOCUS HANDLING:
- If user didn't specify, leave evaluation_focus out — backend
reuses the existing role's stored split, or applies an
interview-type default for new roles (screening:
role-fit/comms/experience/motivation; technical:
depth/problem-solving/comms/system-design; hr:
comms/culture/motivation/leadership).
- The dry-run response surfaces what the resolved split will be so
the user can override before invites go out.
CANDIDATE FIELDS:
- Each candidate dict requires 'firstName' and 'email'. Optional:
'lastName', 'phoneNumber', 'experience', 'summary'.
- Email must be well-formed; phone numbers auto-normalise to 10
digits (Indian format).
TIMING — IMPORTANT:
- This tool sends an invite EMAIL. The candidate opens the link
when they're ready; THEY pick the moment to start the interview.
You cannot pin an interview to a clock time via this tool.
- If a user says "schedule Priya for 3pm Tuesday" — explain that
AIIA invites are candidate-self-served, then offer to send the
invite now (so Priya has it in her inbox) or note the desired
window in the candidate summary so HR can chase if she hasn't
joined by then.
OTHER:
- interview_type: 'screening', 'technical', or 'hr'.
- duration: seconds per interview (default 900 = 15 min).
- language: 'en', 'hi', or 'ar'.
- If role_id is provided, position/jobDescription are ignored.
Returns per-candidate status. Some rows may succeed while others
fail (invalid email, quota exhausted, duplicate within role). Never
assume the whole batch succeeded.
| Name | Required | Description | Default |
|---|---|---|---|
| dry_run | No | ||
| role_id | No | ||
| duration | No | ||
| language | No | en | |
| position | No | ||
| candidates | Yes | ||
| experience | No | ||
| company_name | No | ||
| interview_type | Yes | ||
| job_description | No | ||
| required_skills | No | ||
| evaluation_focus | No | ||
| interview_questions | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description fully discloses write behavior (creates meetings, sends emails), dry run semantics (no persistence, no email, no quota), partial failure possibilities, and quota consumption. No contradiction with annotations (readOnlyHint=false, destructiveHint=false); adds context beyond annotation hints.
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?
Well-structured with clear section headers (ALL CAPS) and front-loaded critical rules. However, the description is lengthy and includes minor details (e.g., phone normalization to 10 digits Indian format) that could be delegated to the schema or a separate format specification.
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 13 parameters (2 required), no output schema, and nested objects, the description is exceptionally complete. Covers all parameters, error cases (partial failure, role_required response), dry run procedure, evaluation focus defaults, candidate field constraints, and timing nuances. Leaves no major gaps 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?
With 0% schema description coverage, the description thoroughly explains all 13 parameters: dry_run, role_id, interview_type, duration, language, candidates (required fields, optional), evaluation_focus (default behavior), and others. Includes defaults, constraints (e.g., email well-formed), and interaction logic.
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 opens with 'Schedule AI-driven interviews. Creates meetings and sends invite emails,' clearly stating the verb and resource. It distinguishes from siblings like schedule_screened_candidates (which targets already-screened candidates) and reschedule_interview, eliminating ambiguity.
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?
Extensive guidance: explicit 'ASK BEFORE CALLING' for role selection, mandatory dry run when auto-filling, and explanation of when to skip dry run. It also clarifies when to use this tool versus asking the user for more info, and details the role_required error response pattern.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Schedule AI interviews for chosen candidates of a screening. Sends a real invite EMAIL to each and consumes interview quota.
CONFIRM BEFORE CALLING:
- Read back to the user which candidates (by name) you're about to invite
and get explicit go-ahead. This spends money and emails real people —
inviting the wrong candidates is not undoable in-band.
- Pull candidate_ids from get_screening_results 'id' fields. Only include
rows with hasEmail=true; rows with a placeholder email are REJECTED
(the whole call 400s) until a real email is added.
The interview reuses the screening role's stored config (JD, questions,
evaluation focus) — same as the web 'Schedule these N' action. The
candidate self-serves the interview when they open the link; you cannot
pin a clock time. duration is seconds per interview (default 900 = 15 min).
Returns {scheduledCount, scheduled_candidates:[{candidateId,
candidate_email, status ('scheduled'|'needs_email'|'skipped_existing'|
'failed'), meetingId, meetingUrl, reason}]}. Some rows may succeed while
others fail or are skipped (already scheduled) — never assume the whole
batch went out.
| Name | Required | Description | Default |
|---|---|---|---|
| role_id | Yes | ||
| duration | No | ||
| candidate_ids | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations destructiveHint=true warn of side effects, but description adds crucial context: sends real emails, consumes quota, cannot undo, returns partial successes. Explains duration default (900 sec), self-served interview (no clock time), and response format. 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?
Well-structured with a clear warning section and logical flow. Somewhat long but each sentence adds value. No redundancy. Minor deduction for length could be tightened.
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 no output schema, description explains return shape, partial success/failure, error conditions (400 for missing email), and preconditions. Covers side effects, quota consumption, and usage pattern. Highly complete for a destructive batch 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 has no descriptions (0% coverage). Description adds context: candidate_ids must come from get_screening_results with hasEmail=true, duration default 900. However, role_id is not explained, and other parameter nuances are missing. Partially compensates but not exhaustive.
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 schedules AI interviews for screened candidates, sending real emails and consuming quota. It distinguishes from siblings like schedule_interview (individual) and add_screening_candidates by specifying the screening context and batch scheduling.
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 provides 'CONFIRM BEFORE CALLING' with steps: read back candidates, get go-ahead, pull IDs from get_screening_results with hasEmail=true. Warns about placeholder emails causing 400 and mentions the tool uses stored config like the web action. This gives clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send reminder emails for one or more pending interviews. Skips already-completed meetings. Pass the same idempotency_key on retry to avoid duplicate sends.
ASK BEFORE CALLING if the user said "remind everyone" / "the
no-shows" / anything that resolves to >1 meeting and you don't
have an explicit list. Call list_meetings (filter by status) first,
show the user the meetings you'd remind, and confirm before sending.
Reminder emails to the wrong candidates are an embarrassing leak.
Cap: 100 meeting_ids per call. For more, batch across multiple calls.
| Name | Required | Description | Default |
|---|---|---|---|
| meeting_ids | Yes | ||
| idempotency_key | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotation idempotentHint=true is reinforced with idempotency_key explanation; describes skipping completed meetings and batch limit. 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?
Well-structured with clear warnings, no redundant sentences, and efficient use of whitespace.
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 all key behaviors, retry pattern, and batching; no output schema needed for this 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 0%, but description adds context for idempotency_key and meeting_ids cap. Lacks explicit mention of array type but adds useful semantics beyond 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 sends reminder emails for pending interviews, distinguishing it from sibling tools like list_meetings or schedule_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?
Provides explicit guidance: ask before calling for ambiguous requests, list meetings first, confirm with user, and mentions batch cap of 100.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tools have distinct purposes with detailed descriptions, but there is slight overlap between schedule_interview and schedule_screened_candidates (both schedule interviews, one for unscreened and one for screened candidates). Overall, the differences are clear from the descriptions.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., list_meetings, create_screening_role, run_screening). No mixing of conventions like camelCase or irregular verbs.
With 18 tools, the set covers the full interview management lifecycle without being overwhelming. Each tool serves a specific function, and the count is appropriate for the domain.
The tool surface covers the screening pipeline (from role creation to scheduling screened candidates) and interview management (schedule, cancel, reschedule, list, get details, report, reminders). Minor gaps include no tool for updating candidate email or deleting roles, but core workflows are well-supported.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
AI voice interviewer: create roles, screen CVs, schedule interviews, read scored reports.
AI screening interviews, resume matching, and evidence-linked scorecards for recruiting teams.
AI-powered hiring for recruiters & candidates - video interviews, transcripts, scores, profiles.
7 recruiting tools over one MCP endpoint: ATS boards, LinkedIn jobs, profiles, companies, Naukri.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/dpkdhingra91/aiia-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
