## Why It Matters

When an AI assistant connects to your Kit account, it gets access to a set of tools. Each tool does one thing — list your job postings, fetch template details, invite a team member. This page documents every tool so you know what your AI assistant can and cannot do.

## Getting Started

Every connected AI assistant sees this instruction first:

> Start with `hiring_get_setup_guide` to understand this account's hiring capabilities, available templates, and current state.

The guide tool returns your account stats and available stage types, giving the assistant context before it takes any action.

## Hiring Tools

### Setup & Templates

#### hiring_get_setup_guide

Returns an overview of your hiring setup: template count, active job postings, total candidates, and all available stage types.

**Parameters:** None

**Returns:** Account name, quick stats, stage type descriptions, suggested next steps.

---

#### hiring_list_templates

Lists all hiring process templates available to your account — both system templates and custom ones you've created.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `tag` | string | No | Filter templates by tag |
| `published_only` | boolean | No | Only published templates (default: true) |

**Returns:** Array of templates with ID, name, tags, stage count, stage types, and usage count.

---

#### hiring_get_template

Returns full details of a specific template including every stage and its configuration.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `template_id` | integer | Yes | Template ID from `hiring_list_templates` |

**Returns:** Template metadata, ordered stages with type/config, and associated email templates.

---

#### hiring_create_process_template

Creates a hiring process template with the given stages. Returns the template name, stage count, and edit URL.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | string | Yes | Template name (e.g. "Software Engineer Hiring") |
| `stages` | array | Yes | Array of stage objects, each with `name` (string), `type` (string), optional `config` (object), and optional `reviewers` (array of `{email, role}`) |
| `description` | string | No | Short description of this template |
| `tags` | array | No | Tags for categorization |

**Returns:** Template ID, name, stage count, and edit URL.

**Requires:** Active subscription.

---

### Job Postings

#### hiring_list_job_postings

Lists all job postings with status and application counts. Filter by status to narrow results.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `status` | string | No | `draft`, `published`, `paused`, `closed`, or `active` |

**Returns:** Array of postings with ID, title, department, location, status, stage count, application breakdown (total/active/rejected/withdrawn), and public URL if published.

---

#### hiring_get_job_posting

Returns everything about a specific job posting: stages with reviewer assignments, team members, and pipeline stats.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `job_posting_id` | integer | Yes | Job posting ID from `hiring_list_job_postings` |

**Returns:** Full posting details, stages with reviewer names, team members with roles, pipeline counts (total/active/rejected/withdrawn/offered).

---

#### hiring_create_job_posting

Creates a new job posting in draft status. Returns the edit URL so you can review and publish it in the browser.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `title` | string | Yes | Job title |
| `description` | string | Yes | Job description in markdown (do not include title) |
| `department` | string | No | Department name |
| `location` | string | No | Job location |
| `employment_type` | string | No | `full_time`, `part_time`, `contract`, or `internship` |
| `remote` | boolean | No | Remote position? |
| `process_template_id` | integer | No | Template ID to apply hiring stages |
| `salary_min` | integer | No | Minimum salary |
| `salary_max` | integer | No | Maximum salary |
| `salary_currency` | string | No | Currency code (e.g., USD, EUR) |
| `salary_period` | string | No | Period (e.g., year, month) |

**Returns:** New posting ID, title, status (always "draft"), and edit URL.

**Requires:** Active subscription.

**Note:** This tool is currently only available through the built-in AI chatbot, not external MCP clients.

---

### Applications & Pipeline

#### hiring_list_applications

Lists submitted applications with optional date, status, and job posting filters. Use to see new applicants, pipeline breakdown by stage, or filter by date range.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `date_range` | string | No | `this_week`, `last_week`, `this_month`, `last_month`, `last_7_days`, or `last_30_days` |
| `since` | string | No | Custom start date (ISO 8601, e.g. `2025-01-01`) |
| `until` | string | No | Custom end date (ISO 8601, e.g. `2025-01-31`) |
| `status` | string | No | `active`, `rejected`, `withdrawn`, `offered`, or `all` (default: `all`) |
| `job_posting_id` | integer | No | Filter to a specific job posting |

**Returns:** Counts by status, breakdown by job posting and stage, and an array of applications with candidate name, email, job title, current stage, status, and submission time.

---

#### hiring_get_application_summary

Returns application-level context for screening: candidate info, current stage, full stage history with submissions, form responses, and candidate data field values.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `application_id` | integer | Yes | Application ID from `hiring_list_reviews` or `hiring_list_applications` |

**Returns:** Candidate details, job posting, application status, current stage, chronological stage history with submission summaries, form responses, and candidate data field values.

---

#### hiring_get_stage_details

Returns detailed, stage-type-specific information for a single stage progress. Includes offer details, interview scheduling, code assignment status, review aggregates, video recording info, and rich submission data. Use after `hiring_get_application_summary` to drill into a specific stage.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `stage_progress_id` | integer | Yes | Stage progress ID from `hiring_get_application_summary` stage history |

**Returns:** Stage metadata with status and timing, candidate and job posting context, all submissions, and stage-type-specific fields — offer terms, interview details, code assignment config, review aggregates, video recording config, questionnaire questions, or portfolio config depending on stage type.

---

#### hiring_advance_application

Advances an application to the next stage in the hiring pipeline, or to a specific stage if `stage_id` is provided. Notifications to the candidate and team are sent automatically.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `application_id` | integer | Yes | The application to advance |
| `stage_id` | integer | No | Advance to a specific stage (skips intermediate stages). If omitted, advances to the next stage in sequence. |

**Returns:** Application ID, candidate name, previous stage, new stage name and type.

**Requires:** `mcp_write` scope.

---

#### hiring_reject_application

Rejects an application. The candidate is notified by email (subject to the account's rejection email delay setting). Always confirm with the user before rejecting.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `application_id` | integer | Yes | The application to reject |
| `reason` | string | No | Internal reason for the rejection (not shown to the candidate) |

**Returns:** Application ID, candidate name, job posting title, reason, and who rejected.

**Requires:** `mcp_write` scope.

---

### Reviews

#### hiring_list_reviews

Returns your review inbox in three sections: applications needing screening, reviews in your queue, and your completed reviews.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `section` | string | No | `screening`, `my_queue`, or `completed` |

**Returns:** Three arrays (needs_screening, my_queue, completed_reviews) with candidate names, job titles, stage info, and wait times. Includes counts per section.

---

#### hiring_get_review_details

Returns everything a reviewer needs to evaluate a candidate at a specific stage: candidate info, submissions, scoring criteria, and other reviews (respecting blind-review visibility rules).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `stage_progress_id` | integer | Yes | Stage progress ID from `hiring_list_reviews` |

**Returns:** Candidate info, job posting, stage details, all submissions (form responses, code, files, video, etc.), scoring criteria with weights, review progress, your review if any, and other reviews (when visible).

---

### Talent Pool

#### hiring_list_talent_pool

Lists verified talent pool entries with compact resume extraction summaries. Paginated at 25 entries per page. Use `hiring_search_talent_pool` for filtering by skills or experience.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page` | integer | No | Page number (default: 1, 25 entries per page) |

**Returns:** Total count, pagination info, and an array of entries with email, verification date, resume extraction summary, and creation date.

---

#### hiring_search_talent_pool

Searches the talent pool by skills, experience, or email using semantic and text search. Returns detailed resume extractions for matching entries.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `query` | string | Yes | Search query (skills, experience keywords, or email) |
| `limit` | integer | No | Maximum results (default: 10, max: 25) |

**Returns:** Matching entries with email, verification date, detailed resume extraction, and creation date.

---

#### hiring_invite_talent_pool

Invites a talent pool candidate to apply for a specific job posting. Sends an email with a prefilled application link.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `talent_pool_entry_id` | integer | Yes | Talent pool entry ID from `hiring_list_talent_pool` or `hiring_search_talent_pool` |
| `job_posting_id` | integer | Yes | Job posting ID from `hiring_list_job_postings` |

**Returns:** Invitation ID, candidate email, job title, who invited, and the invitation URL.

**Requires:** `mcp_write` scope.

---

### Candidate Data Fields

Candidate data fields (metafields) let you attach structured, typed data to applications — salary expectations, visa status, years of experience, and more. Fields can be filled manually or extracted automatically from resumes and form responses by AI.

#### hiring_list_metafield_definitions

Lists all candidate data field definitions for a job posting, including field types and AI extraction configuration.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `job_posting_id` | integer or string | Yes | Job posting ID or prefix ID (e.g. `42` or `job_abc123`) |

**Returns:** Summary with total count and AI-extractable count, plus an array of definitions each with `id`, `key`, `label`, `field_type`, `position`, `required`, `placeholder`, `ai_extractable`, `ai_prompt`, and `options`.

---

#### hiring_get_metafield_values

Returns all candidate data field values for an application, with confidence scores and source attribution. Shows both AI-extracted and manually entered data.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `application_id` | integer or string | Yes | Application ID or prefix ID (e.g. `42` or `app_abc123`) |

**Returns:** Fill summary, extraction status, and an array of field entries each with `key`, `label`, `field_type`, `value`, `source`, `confidence`, `confidence_tier`, `set_at`, `human_edited`, and `original_value`.

---

#### hiring_update_metafield_value

Sets or updates a candidate data field value on an application. Use for manual data entry or corrections.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `application_id` | integer or string | Yes | Application ID or prefix ID (e.g. `42` or `app_abc123`) |
| `key` | string | Yes | The field key (e.g. `salary_expectation`, `years_experience`). Use `hiring_list_metafield_definitions` to see available keys. |
| `value` | any | Yes | The value to set (type depends on field definition) |

**Returns:** Application ID, key, label, value set, and source.

**Requires:** `mcp_write` scope.

---

#### hiring_trigger_metafield_extraction

Triggers AI extraction of candidate data field values from an application's resume and form responses. Returns immediately — extraction runs in the background.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `application_id` | integer or string | Yes | Application ID or prefix ID (e.g. `42` or `app_abc123`) |
| `force` | boolean | No | Force re-extraction even if already completed (default: false) |

**Returns:** Application ID, queued status, and whether force was set.

**Requires:** `mcp_write` scope. The job posting must have at least one AI-extractable field defined.

---

#### hiring_create_metafield_definition

Adds a new candidate data field definition to a job posting. Supports AI extraction configuration.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `job_posting_id` | integer or string | Yes | Job posting ID or prefix ID |
| `label` | string | Yes | Display label (e.g. `Years of Experience`, `Visa Status`) |
| `field_type` | string | Yes | One of: `text`, `textarea`, `number`, `date`, `select`, `boolean`, `url`, `rating`, `tags` |
| `ai_extractable` | boolean | No | Whether AI should extract this from resumes (default: false) |
| `ai_prompt` | string | No | Instructions for AI extraction (required when `ai_extractable` is true) |
| `required` | boolean | No | Whether this field is required (default: false) |
| `placeholder` | string | No | Placeholder text for the input field |

**Returns:** New definition `id`, `key`, `label`, `field_type`, `ai_extractable`, and `position`.

**Requires:** `mcp_write` scope and active subscription.

---

### Video

#### hiring_search_video_transcripts

Searches video interview transcripts by keywords using semantic and text search. Returns candidate info, video details, and relevant transcript excerpts.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `query` | string | Yes | Keywords to find in transcripts |
| `job_posting_id` | integer | No | Filter results to a specific job posting |
| `limit` | integer | No | Maximum results (default: 10, max: 20) |

**Returns:** Matching video transcripts with candidate info, video details, and relevant excerpts.

---

## Team Tools

### team_list_members

Lists all members of the current account with their roles.

**Parameters:** None

**Returns:** Array of members with name, email, roles, and owner flag.

---

### team_list_invitations

Lists all pending invitations for the current account.

**Parameters:** None

**Returns:** Array of invitations with name, email, assigned roles, who invited, and when.

---

### team_invite_member

Sends an invitation email to join your account. Only account admins can use this tool.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `email` | string | Yes | Email address to invite |
| `name` | string | Yes | Full name of the invitee |
| `admin` | boolean | No | Grant admin role (default: false) |

**Returns:** Confirmation with email, name, assigned role, and status.

**Requires:** `mcp_write` scope, admin role, and active subscription.

## Outreach Tools

These tools require the Outreach addon and an active subscription.

### outreach_list_campaigns

Lists outreach campaigns with optional status filter. Returns up to 25 campaigns.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `status` | string | No | Filter by `draft`, `active`, `paused`, or `completed` |

**Returns:** Array of campaigns with ID, name, status, prospect_count, message_count, pending_draft_count, and created_at.

---

### outreach_get_campaign

Returns full details for a specific campaign including configuration, prospect counts by status, message summary, and reply count.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `campaign_id` | string | Yes | Campaign ID from `outreach_list_campaigns` |

**Returns:** Campaign ID, name, status, full config (target volume, AI directives, sequence steps), prospect counts by status, message summary (total, pending drafts, sent), reply count, and created_at.

---

### outreach_add_prospect

Adds a prospect to a campaign. Checks for duplicates and suppressed emails unless `force` is set.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `campaign_id` | string | Yes | Campaign to add the prospect to |
| `email` | string | Yes | Prospect email address |
| `first_name` | string | No | Prospect first name |
| `last_name` | string | No | Prospect last name |
| `company_name` | string | No | Company name |
| `title` | string | No | Job title |
| `source_url` | string | No | LinkedIn profile or company URL for AI research |
| `notes` | string | No | Free-text context for the AI agent |
| `force` | boolean | No | Skip duplicate and suppression checks (default: false) |

**Returns:** Prospect ID, email, and status.

**Requires:** `mcp_write` scope.

---

### outreach_draft_email

Enqueues AI research and drafting for a specific prospect. The prospect must be in a draftable state (not already drafted or active).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `prospect_id` | string | Yes | Prospect to research and draft for |

**Returns:** Confirmation that research has been enqueued.

**Requires:** `mcp_write` scope.

---

### outreach_list_pending_drafts

Lists drafted messages awaiting approval, optionally filtered by campaign. Returns up to 25 drafts.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `campaign_id` | string | No | Filter to a specific campaign |

**Returns:** Array of drafts with ID, campaign name, prospect name, subject, body preview (200 chars), and created_at.

---

## Utility Tools

### echo

Tests MCP connectivity. Echoes your message back with account context.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `message` | string | Yes | Message to echo |

**Returns:** Your message, account name, user email, scopes, and timestamp.

---

### search_docs

Searches Kit's product documentation. Useful when you ask the assistant how a feature works.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `query` | string | Yes | What to search for |

**Returns:** Matching doc pages with title, category, and content.

---

### get_plans

Retrieves current pricing plans with features, pricing details, and billing information.

**Parameters:** None

**Returns:** Array of plans with name, description, price, currency, interval, per-seat flag, trial days, and feature list.

## Permissions Summary

| Tool | Scope Required | Write? | Notes |
|------|---------------|--------|-------|
| `echo` | — | No | |
| `search_docs` | — | No | |
| `get_plans` | — | No | |
| `hiring_get_setup_guide` | `mcp` | No | |
| `hiring_list_templates` | `mcp` | No | |
| `hiring_get_template` | `mcp` | No | |
| `hiring_create_process_template` | `mcp` | Yes | Requires active subscription |
| `hiring_list_job_postings` | `mcp` | No | |
| `hiring_get_job_posting` | `mcp` | No | |
| `hiring_create_job_posting` | — | Yes | Built-in chatbot only; requires active subscription |
| `hiring_list_applications` | `mcp` | No | |
| `hiring_get_application_summary` | `mcp` | No | |
| `hiring_get_stage_details` | `mcp` | No | |
| `hiring_advance_application` | `mcp_write` | Yes | |
| `hiring_reject_application` | `mcp_write` | Yes | |
| `hiring_list_reviews` | `mcp` | No | |
| `hiring_get_review_details` | `mcp` | No | |
| `hiring_list_talent_pool` | `mcp` | No | |
| `hiring_search_talent_pool` | `mcp` | No | |
| `hiring_invite_talent_pool` | `mcp_write` | Yes | |
| `hiring_list_metafield_definitions` | `mcp` | No | |
| `hiring_get_metafield_values` | `mcp` | No | |
| `hiring_update_metafield_value` | `mcp_write` | Yes | |
| `hiring_trigger_metafield_extraction` | `mcp_write` | Yes | Job posting must have AI-extractable fields |
| `hiring_create_metafield_definition` | `mcp_write` | Yes | Requires active subscription |
| `hiring_search_video_transcripts` | `mcp` | No | |
| `team_list_members` | `mcp` | No | |
| `team_list_invitations` | `mcp` | No | |
| `team_invite_member` | `mcp_write` | Yes | Admin only; requires active subscription |
| `outreach_list_campaigns` | `mcp` | No | Requires Outreach addon |
| `outreach_get_campaign` | `mcp` | No | Requires Outreach addon |
| `outreach_add_prospect` | `mcp_write` | Yes | Requires Outreach addon |
| `outreach_draft_email` | `mcp_write` | Yes | Requires Outreach addon |
| `outreach_list_pending_drafts` | `mcp` | No | Requires Outreach addon |

All tools are scoped to your connected account. An assistant can never see or modify data from a different account.