> ## Documentation Index
> Fetch the complete documentation index at: https://developers.cutshort.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Cutshort MCP Tools Reference: Parameters and Examples

> Complete reference for all 5 Cutshort MCP tools: search_candidates, get_candidate_profile, create_job, get_shortlist, and send_invite.

The Cutshort MCP server exposes five tools that an AI agent can call. Each tool maps to a Cutshort API operation. This reference covers each tool's input schema, output shape, and example usage from an AI agent conversation.

<AccordionGroup>
  <Accordion title="search_candidates" icon="magnifying-glass">
    Searches the Cutshort candidate pool by skills, experience, location, and quality score. Use this tool to find candidates that match a job's requirements before creating a shortlist or sending invites.

    **Input parameters**

    <ParamField body="skills" type="string" required>
      Comma-separated skill names to filter by. Example: `"python,django,aws"`
    </ParamField>

    <ParamField body="experience_min" type="integer">
      Minimum years of experience the candidate must have.
    </ParamField>

    <ParamField body="experience_max" type="integer">
      Maximum years of experience the candidate may have.
    </ParamField>

    <ParamField body="location" type="string">
      City name to filter by, or `"Remote"` for remote-only candidates. Example: `"Bengaluru"`
    </ParamField>

    <ParamField body="quality_score_min" type="integer">
      Minimum Cutshort quality score (0–100). Candidates below this threshold are excluded.
    </ParamField>

    <ParamField body="availability" type="string">
      Filter by job-seeking status. Accepted values: `"active"`, `"open"`, or `"active,open"`.
    </ParamField>

    <ParamField body="page" type="integer">
      Page number for paginated results. Defaults to `1`.
    </ParamField>

    <ParamField body="per_page" type="integer">
      Number of results to return per page. Maximum: `50`.
    </ParamField>

    **Example**

    > *"Find senior Python engineers in Bengaluru with at least 5 years of experience"*

    ```json theme={null}
    {
      "tool": "search_candidates",
      "input": {
        "skills": "python",
        "experience_min": 5,
        "location": "Bengaluru"
      }
    }
    ```
  </Accordion>

  <Accordion title="get_candidate_profile" icon="user">
    Retrieves the full profile of a candidate by their Cutshort candidate ID. Use this tool after a `search_candidates` call when you need complete details — work history, education, skills, and contact preferences — for a specific candidate.

    **Input parameters**

    <ParamField body="candidate_id" type="string" required>
      The unique identifier of the candidate. Obtained from the `id` field in a `search_candidates` response. Example: `"cand_8f3kL9mN"`
    </ParamField>

    **Example**

    ```json theme={null}
    {
      "tool": "get_candidate_profile",
      "input": {
        "candidate_id": "cand_8f3kL9mN"
      }
    }
    ```
  </Accordion>

  <Accordion title="create_job" icon="briefcase">
    Creates a new job posting on Cutshort and activates AI candidate matching for that role. Once created, the job is immediately eligible for shortlist generation via `get_shortlist`.

    **Input parameters**

    <ParamField body="title" type="string" required>
      Job title displayed to candidates. Example: `"Senior Backend Engineer"`
    </ParamField>

    <ParamField body="description" type="string" required>
      A description of the role, responsibilities, and team context.
    </ParamField>

    <ParamField body="skills_required" type="array" required>
      Array of skill names required for the role. Example: `["Python", "FastAPI", "PostgreSQL"]`
    </ParamField>

    <ParamField body="experience_min" type="integer" required>
      Minimum years of experience required for this role.
    </ParamField>

    <ParamField body="experience_max" type="integer">
      Maximum years of experience considered for this role.
    </ParamField>

    <ParamField body="location" type="string">
      Primary city for the role. Example: `"Mumbai"`
    </ParamField>

    <ParamField body="remote_type" type="string">
      Work arrangement. Accepted values: `"onsite"`, `"remote"`, or `"hybrid"`.
    </ParamField>

    <ParamField body="salary_min" type="integer">
      Minimum annual salary in INR (e.g., `2000000` for ₹20,00,000).
    </ParamField>

    <ParamField body="salary_max" type="integer">
      Maximum annual salary in INR (e.g., `3000000` for ₹30,00,000).
    </ParamField>

    **Example**

    ```json theme={null}
    {
      "tool": "create_job",
      "input": {
        "title": "Senior Backend Engineer",
        "description": "Building scalable APIs for a fintech platform",
        "skills_required": ["Python", "FastAPI", "PostgreSQL"],
        "experience_min": 4,
        "location": "Mumbai",
        "remote_type": "hybrid",
        "salary_min": 2000000,
        "salary_max": 3000000
      }
    }
    ```
  </Accordion>

  <Accordion title="get_shortlist" icon="list-check">
    Retrieves the AI-generated candidate shortlist for a specific job. Cutshort's matching engine ranks candidates by fit score based on the job's required skills, experience range, location, and salary band.

    **Input parameters**

    <ParamField body="job_id" type="string" required>
      The unique identifier of the job. Obtained from the `id` field in a `create_job` response. Example: `"job_4xRt2wPv"`
    </ParamField>

    <ParamField body="limit" type="integer">
      Maximum number of shortlisted candidates to return. Maximum: `50`.
    </ParamField>

    **Example**

    ```json theme={null}
    {
      "tool": "get_shortlist",
      "input": {
        "job_id": "job_4xRt2wPv",
        "limit": 10
      }
    }
    ```
  </Accordion>

  <Accordion title="send_invite" icon="paper-plane">
    Sends outreach invites to one or more candidates for a specific job. You can reach candidates over WhatsApp, email, or both channels simultaneously. Invite delivery and open status are tracked in the Cutshort dashboard.

    **Input parameters**

    <ParamField body="job_id" type="string" required>
      The unique identifier of the job for which the invite is being sent. Example: `"job_4xRt2wPv"`
    </ParamField>

    <ParamField body="candidate_ids" type="array" required>
      Array of candidate IDs to invite. You can invite multiple candidates in a single call. Example: `["cand_8f3kL9mN", "cand_2pQr7sYk"]`
    </ParamField>

    <ParamField body="channel" type="string">
      Outreach channel to use. Accepted values: `"whatsapp"`, `"email"`, or `"both"`. Defaults to `"both"`.
    </ParamField>

    **Example**

    ```json theme={null}
    {
      "tool": "send_invite",
      "input": {
        "job_id": "job_4xRt2wPv",
        "candidate_ids": ["cand_8f3kL9mN", "cand_2pQr7sYk"],
        "channel": "whatsapp"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

<Note>
  The MCP server returns structured JSON for all tool calls. Tool outputs match the corresponding REST API response schemas — see the [API Reference](/api-reference) for full field descriptions.
</Note>