Talpy Aya — AI recruiter (WhatsApp interviews)

Lists the company's job openings with their status and how many candidates each one has. Read-only. Use it to find a job id before looking at candidates or inviting someone.

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "ATIVA",
        "RASCUNHO",
        "EM_APROVACAO",
        "PAUSADA",
        "CONCLUIDA",
        "ENCERRADA",
        "REJEITADA",
        "all"
      ],
      "description": "Filter by job status. ATIVA = open/published, RASCUNHO = draft. Defaults to ATIVA."
    },
    "language": {
      "type": "string",
      "enum": [
        "pt-BR",
        "pt-PT",
        "en",
        "es",
        "de",
        "fr"
      ],
      "description": "Optional. Language for the text in this tool's response (labels, notes, messages). Defaults to the account's language."
    }
  }
}

Shows one job in detail, including the competencies Aya (the AI interviewer) evaluates and the weight of each — the criteria behind every candidate score. Read-only.

{
  "type": "object",
  "properties": {
    "jobId": {
      "type": "string",
      "description": "Job id, from listar_vagas."
    },
    "language": {
      "type": "string",
      "enum": [
        "pt-BR",
        "pt-PT",
        "en",
        "es",
        "de",
        "fr"
      ],
      "description": "Optional. Language for the text in this tool's response (labels, notes, messages). Defaults to the account's language."
    }
  },
  "required": [
    "jobId"
  ]
}

Lists the candidates of a job with their interview score, profile fit and pipeline stage, highest score first. Read-only. Does NOT return phone, e-mail or résumé.

{
  "type": "object",
  "properties": {
    "jobId": {
      "type": "string",
      "description": "Job id, from listar_vagas."
    },
    "minScore": {
      "type": "number",
      "description": "Only candidates whose interview score is at least this value (0 to 10)."
    },
    "stage": {
      "type": "string",
      "enum": [
        "NOVO",
        "CONVIDADO",
        "EM_ENTREVISTA",
        "AVALIADO",
        "APROVADO",
        "REJEITADO",
        "all"
      ],
      "description": "Filter by pipeline stage (NOVO = new, CONVIDADO = invited, EM_ENTREVISTA = interviewing, AVALIADO = evaluated, APROVADO = approved, REJEITADO = rejected). Defaults to all."
    },
    "language": {
      "type": "string",
      "enum": [
        "pt-BR",
        "pt-PT",
        "en",
        "es",
        "de",
        "fr"
      ],
      "description": "Optional. Language for the text in this tool's response (labels, notes, messages). Defaults to the account's language."
    }
  },
  "required": [
    "jobId"
  ]
}

Full evaluation of one candidate: score per competency, the evidence behind each score, red flags, highlights and the human decision if there is one. Read-only. Does NOT return phone, e-mail or résumé.

{
  "type": "object",
  "properties": {
    "candidateId": {
      "type": "string",
      "description": "Candidate id, from listar_candidatos."
    },
    "language": {
      "type": "string",
      "enum": [
        "pt-BR",
        "pt-PT",
        "en",
        "es",
        "de",
        "fr"
      ],
      "description": "Optional. Language for the text in this tool's response (labels, notes, messages). Defaults to the account's language."
    }
  },
  "required": [
    "candidateId"
  ]
}

Company-wide recruiting numbers: open jobs, candidates, completed interviews, average score and plan usage. Read-only. Contains no personal data.

{
  "type": "object",
  "properties": {
    "language": {
      "type": "string",
      "enum": [
        "pt-BR",
        "pt-PT",
        "en",
        "es",
        "de",
        "fr"
      ],
      "description": "Optional. Language for the text in this tool's response (labels, notes, messages). Defaults to the account's language."
    }
  }
}

Shows the company's current plan, this cycle's usage (interviews and open jobs against the limits), the plans available with prices, and the link to subscribe or change plan in the Talpy dashboard. Read-only: it never charges or changes the subscription — payment happens only in the dashboard.

{
  "type": "object",
  "properties": {
    "language": {
      "type": "string",
      "enum": [
        "pt-BR",
        "pt-PT",
        "en",
        "es",
        "de",
        "fr"
      ],
      "description": "Optional. Language for the text in this tool's response (labels, notes, messages). Defaults to the account's language."
    }
  }
}

Creates a new job opening in the company's Talpy account and generates the interview profile Aya will use (competencies and weights). By default the job is created as a DRAFT (not public); set publish=true to open it right away. Counts against the plan's open-job limit. Requires an API key with the mcp:write scope. Returns in a few seconds with the job id, its status, the dashboard link and profileStatus: "generating" means the full competency profile is still being built in the background (usually under a minute) — call detalhar_vaga later to see it.

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "Job title, e.g. \"Sales Representative\"."
    },
    "description": {
      "type": "string",
      "minLength": 20,
      "description": "Job description (at least 20 characters): responsibilities and requirements. Aya's evaluation criteria are derived from it."
    },
    "seniority": {
      "type": "string",
      "description": "Optional seniority level, e.g. \"Junior\", \"Mid-level\", \"Senior\"."
    },
    "language": {
      "type": "string",
      "enum": [
        "pt-BR",
        "pt-PT",
        "en",
        "es",
        "de",
        "fr"
      ],
      "description": "Optional. Language of the job: Aya opens the candidate interview in it. Also used for the text of this response. Defaults to the account's language."
    },
    "publish": {
      "type": "boolean",
      "description": "Optional. true = publish the job now (status ATIVA, open to applications). Default false = draft (RASCUNHO) for a human to review."
    }
  },
  "required": [
    "title",
    "description"
  ]
}

Adds a candidate to a job and immediately invites them to an interview with Aya, the AI recruiter. SIDE EFFECTS: with a phone number it sends a real WhatsApp invite to the candidate; without a phone but with an e-mail it sends a real e-mail with the link to the web interview. Uses one interview from the company's balance when the interview happens. Requires an API key with the mcp:write scope. Only invite people who applied or agreed to be contacted. Returns candidateId, interviewId and the invite channel.

{
  "type": "object",
  "properties": {
    "jobId": {
      "type": "string",
      "description": "Job id, from listar_vagas or criar_vaga."
    },
    "name": {
      "type": "string",
      "description": "Candidate's full name."
    },
    "phone": {
      "type": "string",
      "description": "Candidate's WhatsApp number in international format with country code, e.g. +5511912345678. If given, the invite goes by WhatsApp."
    },
    "email": {
      "type": "string",
      "description": "Candidate's e-mail. Used for the invite (web interview link) when there is no phone."
    },
    "resumeText": {
      "type": "string",
      "description": "Optional résumé as plain text. Used to pre-score the candidate against the job profile."
    },
    "language": {
      "type": "string",
      "enum": [
        "pt-BR",
        "pt-PT",
        "en",
        "es",
        "de",
        "fr"
      ],
      "description": "Optional. Language for the text in this tool's response (labels, notes, messages). Defaults to the account's language."
    }
  },
  "required": [
    "jobId",
    "name"
  ]
}