MCP tool reference

The organisations you can act on, with their ids. Every other tool needs an organisationId — call this first to find it rather than asking the user for one. Returns exactly one organisation for most people: use it without asking.

This tool takes no arguments.

List an organisation's roles, optionally filtered by status. Only returns roles the token owner is allowed to see. Use status 'imported' to find ATS-synced roles awaiting adoption.

A role's current state: its details, criteria and questions, and readiness — which required details are still missing before it can be published.

Create a new draft role. The token owner becomes the hiring manager. Location and category names that don't exist in the organisation are created automatically.

Duplicate an existing role into a new draft, copying its details, settings, criteria and questions. Returns the new role's id.

Adopt a role synced from the ATS: moves it from 'imported' to a draft the team can configure and publish. Use list_roles with status 'imported' to find adoptable roles.

Update a role's details. Provide only the fields to change; everything else keeps its current value. Location and category names replace the existing sets. The response lists any fields locked to a connected ATS which kept their synced values.

Publish a role: opens it for applications, putting it live on the job board and apply page and approving any criteria still awaiting review. Also resumes a paused role and reopens a closed one, restarting progress towards any pause goal. Fails with the missing fields when the role's details are incomplete.

Pause an open role: candidates can still apply, but new applications wait to be assessed until the role is resumed with publish_role. Fails when the role is not open.

Close an open or paused role: candidates can no longer apply. Reopen it with publish_role. Fails when the role is not open or paused.

Archive a role: hides it from active lists and stops new applications. Archived roles can be restored in First. Fails when the role is already archived.

Apply changes to a role's application process: its criteria and questions. Each change is one item of the shared process-change contract, applied in order. Criteria changed on a live role may await review and are approved when the role is next published. Use get_role first to see the current criteria and questions.

Remove a criterion or question from a role's application process by process component type and subtype. For stage criteria (type 'assess-stage'), pass the specific criterionId — otherwise every stage criterion on the role would be removed.

Search the organisation's applications by name or email across every role. Only returns applications for a role the token owner is allowed to see. Use this to find a specific person by name or email address. Omit `query` to list rather than search: `list: "hired"` with no query lists hires, which is how you answer "who have we hired recently" — there is no search term that returns them all. Each row carries `hiredAt`, `shortlistedAt` and `rejectedAt`, so filter to a date window on those rather than on `createdAt`, which is when the application arrived rather than when the outcome happened. **Read `truncated` before quoting any total.** When it is true this is a partial answer — `found` is a lower bound and paging to the end will not reach the rest, so say the count is at least that rather than stating it as the number. Only when `truncated` is false is `found` the whole answer.

One application's record: which stage it has reached, when it was hired, shortlisted or rejected, where the candidate came from, and its assessment score with the criteria version behind it. Search finds the person; this says what happened to them. Returns not found for a role you are not allowed to see. Their work and education history comes back too, taken from the CV already held against the application — use this rather than the web-sourcing tools for anyone who has applied before: it costs nothing and it is their own CV, not a third-party guess at it. Pass includeProfile: false to leave it out.

Search the organisation's own indexed candidate pool for people matching a role's live criteria, and save a page of matches to the role's sourcing workspace. Choose the scope with searchType: 'radius' (near a location), 'country' (a whole country by ISO code) or 'everywhere'. Each call excludes candidates already saved for the role, so repeating it returns the next page. Add the returned candidates with add_sourced_candidates.

Add previously sourced candidates to a role as applications. The contactIds are the ids returned by a source tool. For candidates sourced from a draft role, pass the same `reference` that search used. The response lists the ids that were added; ids that no longer resolve to a saved candidate are simply absent.

Search the organisation's own indexed candidate pool against a draft role — no role required. Pass `criteriaChanges` from generate_suggested_criteria: that is what makes the search discriminate, and gathering a seniority and a few skills first is enough to generate them. A job description sharpens them further. A title on its own is a last resort — it matches anyone whose CV carries those words, so everyone scores strongly and the bands stop meaning anything. Omit `reference` on the first search and reuse the one returned for every later call — each search excludes candidates already saved to that workspace, so repeating it returns the next page. Choose the scope with searchType: 'radius', 'country' or 'everywhere'.

List every candidate saved under a sourcing `reference`. Searches only return the page they sourced, so use this to see everything accumulated so far — after losing track of a page, or before deciding who to add to a role. An empty or unknown reference returns an empty list.

Remove every candidate saved under a sourcing `reference`. This also resets what searches exclude, so a later search on the same reference can return people it had already saved. Starting a fresh reference achieves the same without discarding anything, so prefer that unless the user asks to start this one over.

Search the PUBLIC WEB for candidate profiles with a Google X-Ray query (e.g. site:linkedin.com/in with OR-grouped job titles and must-have skills). This is the ONLY tool that finds people who have never applied to this organisation — every other search reads its own candidate database. It saves nothing: pass the profiles worth keeping to save_web_candidates. There is no location parameter — put the location into the query text.

Enrich up to 10 web-sourced profiles and save them to a sourcing workspace. This is the save step for web results — the database searches already save their own. Pass the `reference` from an earlier search to keep everything in one workspace, or omit it to start one and reuse the reference that comes back.

Turn a city or place name into the coordinates a 'radius' search needs. Call this before sourcing near somewhere, then pass the coordinates as `location`. Returns found: false when the name is not an actual city (a whole country, or unrecognisable) — use geocode_country for a country, or fall back to searchType 'everywhere'.

Turn a country a recruiter named — 'United Kingdom', 'UK' or 'GB' — into the ISO 3166-1 alpha-2 code a 'country' search needs. Call this before sourcing country-wide, then pass the code as `country`. Returns found: false when the value is not a recognisable country.

Generate a role's assessment criteria from its title and job description. Returns process changes ready to source against (pass them as `criteriaChanges` to source_candidates_from_draft_role) and to apply to a role (update_role_process) — using the same set for both is what makes sourced candidates match on the requirements they are later assessed against. Nothing is created or changed: show the criteria to the user, adjust if they want, then source. `requirementsPreview` shows what the matcher will score against. ALWAYS pass `roleId` when the role already exists — when you are working on a role rather than drafting one. That is what pulls in its intake call transcripts and note-taker summaries, which say what the hiring manager actually asked for; a job description is often boilerplate. Omitting it silently generates from the description alone. Omit it only while the role is still a draft.

Research the talent market for a role — how deep the pool is, what it pays, and who else is hiring for it. Use it before committing to a hire, to sanity-check a salary, or to tell the user whether a location is realistic. Searches the web, not the organisation's candidate database (source_candidates_from_draft_role does that). Nothing is created or changed. `location` is a place as the recruiter would say it — 'London', 'the UK' — not coordinates or an ISO code. A market it finds nothing for returns found: false; say so rather than retrying.

Monthly reporting for an organisation: one row per role with application volumes (in period, total, last 7/30 days, rolling daily averages), hires and time to hire (average/median days), completion funnel percentages (started, complete, shortlisted), stalled and aged application counts, role status and whether the role uses AI assessment. Defaults to the latest available month. Use this to compare roles; use get_reporting_summary for org-wide trends and get_stage_reporting for pipeline bottlenecks.

Pipeline funnel reporting for an organisation: one row per role per pipeline stage, in pipeline order, with how many applications reached each stage and the average/median days spent in it. Use this to find where candidates drop off or wait the longest (pass-through rates, bottlenecks). Defaults to the latest available month. Months before stage metrics existed return no rows.

Organisation-level trend reporting: one row per month with totals across every role — application volumes, hires and time to hire (average/median days), completion funnel percentages, aged applications and the share of roles using AI assessment. Use this first for topline questions and month-on-month trends. from/to are inclusive YYYY-MM bounds (at most 24 months); omit both for the trailing 12 months. Months without a report are omitted.