Skip to main content
Glama
deenesjakoruzh
jnot807

recruitee-mcp

by jnot807
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

Recruitee MCP

Work your Recruitee / Tellent pipeline from inside Claude. Look up a role, read a candidate and everything already recorded about them, add someone you sourced, and write your interview evaluation — without leaving the conversation.

It runs on your own machine under your own Recruitee API token, so everything it writes is filed in your name, exactly as if you had clicked it yourself.

What it can do

Fourteen tools. Nine read, five write, and every write shows you exactly what it is about to do before it does it.

Reading

Tool

What you get

rt_list_offers

Your roles with their ids, status and candidate counts. Optionally filtered by title.

rt_get_stages

One role's pipeline stages, with a live count in each.

rt_offer_candidates

Everyone on one role — their stage, whether they were disqualified, and any ratings. Genuinely scoped to that role, not the whole company.

rt_get_candidate

A full record: contact details, tags, every role they sit on, and their application answers.

rt_search_candidates

Find one person by name.

rt_source_candidates

Search your whole database, CV text included — see below.

rt_get_rating_scale

The rating scale your account is configured for, so a verdict is never guessed at.

rt_get_evaluations

Every evaluation on a candidate — rating, note, stage, reviewer and date — flattened into one list.

rt_get_notes

Notes already on a candidate, newest first.

Application answers are worth a word: salary expectations and the like are returned per role, because someone who applied to three jobs answered the question three times, and a flat list cannot tell those answers apart.

Writing

Tool

What it does

rt_create_candidate

Creates a person and places them on a role in one step. Takes email, phone, links, tags, a cover-letter block, where they came from, and a file to attach. Lands them in Sourced by default.

rt_submit_evaluation

Writes the thumbs rating and your reasoning onto a candidate for one role — the Evaluation tab of their profile.

rt_set_stage

Moves a candidate to another stage on one of their offers. Refuses a disqualified placement, so it cannot requalify anybody.

rt_attach_file

Attaches a local file to an existing candidate, optionally making it their CV.

rt_add_note

Adds a note, public or private. For context that is not a verdict — a call recap, sourcing rationale, a summary.

How the writes behave

They take names, not ids. "Dana Whitfield", "Regional Sales Manager". If a name matches two people it stops and lists them rather than picking one — filing a verdict on the wrong person is the failure that actually matters here.

Every one previews first. The first call returns exactly what would be written and writes nothing. Only after you approve does anything land. For a new candidate the preview also runs a duplicate check and tells you which details are missing, so you find out before the record exists rather than after.

Evaluations file against the candidate's real current stage, which is what an evaluation means. You can override it deliberately, but you never have to work it out.

Your paragraphs survive. Recruitee's note field takes plain text but its interface renders that text as HTML, so a note written in paragraphs would otherwise arrive as one run-on block. The line breaks are converted on the way across, and the text is escaped first so a stray < in your writing cannot be swallowed or rendered.

Ratings are checked, not rounded. Valid values depend on your configured scale — a 4-point thumbs scale has no "neutral", a 5-point one does. A value the scale does not have is rejected rather than quietly turned into a neighbour.

Related MCP server: Recruitee MCP Server

Sourcing from your own database

rt_source_candidates runs the same search the Candidates screen runs, which is a different thing from rt_search_candidates: that one matches names, this one matches everything, CV text included, with boolean operators.

query: "renewals AND churn"
query: "(SaaS OR B2B) AND \"net revenue retention\" NOT \"vice president\""

That matters because job titles are inconsistent between companies, and what somebody actually did is written in their CV. Searching for the evidence beats searching for the title.

Filters combine: offer, excludeOffer, jobStatus, stage, status, tags, sources. excludeOffer is the one that makes it a sourcing tool rather than a search box — it keeps the people already on a role out of the results when you are topping it up.

Every result carries why it matched — the actual sentences, with the HTML stripped — and every role the person is already on, with the stage and, where they were turned down, the reason. That last part is not decoration: most of an established ATS was rejected once. "Wrong location" two years ago may not apply today; "failed the assessment" still does. Nobody should be presented as a fresh find without it.

Why the filter building looks paranoid

/search/new/candidates silently ignores anything it does not recognise and returns an unfiltered result rather than an error. Four ways to get a plausible, badly wrong answer, all confirmed against a live account:

Mistake

What the API does

Unknown entity name

returns the entire database

nin instead of not_in

returns the entire database

Unknown sort

silently falls back to relevance

Two filter objects for the same entity

the second replaces the first

That last one is the nastiest: a role plus a job status sent as two objects returns everyone with that job status, and nothing anywhere says the role filter was dropped. So every constraint on an entity is merged into a single object, and no caller-supplied key ever reaches the API — names are mapped onto a vocabulary verified against the live API, and anything outside it throws.

A wrong value is safe by contrast: it returns zero, which is obviously wrong to whoever reads it. A zero result also comes back with your real stage names attached, so a mistyped stage is distinguishable from an empty one.

node sourcing-test.js checks all of it, including that the client refuses each of the four mistakes above.

Setup

Five minutes, once. You need Node 18 or newer (node -v to check) and Claude Code or the Claude desktop app.

1. Get the code and install

git clone https://github.com/jnot807/recruitee-mcp.git
cd recruitee-mcp
npm install

Every command from here runs from inside that folder.

2. Create your own API token

In Recruitee: Settings → Apps and plugins → API tokens, stay on the Personal API tokens tab, and click + Add token. It asks for your password, then shows the value once.

While you are on that screen, note your company from the Current company details panel at the top. Either the numeric ID or the subdomain works.

This has to be your token, not a shared one. A Recruitee token acts as the person who created it, so an evaluation written with your token shows up as yours — which is the point. Never paste it into a chat, an email or a ticket.

3. Store it

npm run set-token -- <paste-your-token-here> <your-company>

Rotating a token later is just npm run set-token -- <new-token> — the company is remembered.

It is written to session/token.json, readable only by you, and gitignored. RECRUITEE_API_TOKEN in the environment overrides the file if you would rather keep it in a password manager.

4. Prove it works

npm run check

You want authenticated: true and a few of your roles.

5. Connect it to Claude

Run this from inside this folder, then restart Claude:

claude mcp add recruitee -- node "$PWD/server.js"

Using the Claude desktop app instead? Open Settings → Developer → Edit Config and add this, with your real absolute path (pwd prints it):

{
  "mcpServers": {
    "recruitee": {
      "command": "node",
      "args": ["/absolute/path/to/recruitee-mcp/server.js"]
    }
  }
}

Then ask Claude: "list the open roles in Recruitee".

What it looks like in use

You: Who's in the pipeline for Regional Sales Manager?

You: Pull up Dana Whitfield — what did she put for salary, and what evaluations are already on her?

You: Write an evaluation for her on that role. A yes: strong on renewals and expansion, ran a team of nine, no PLG experience.

Claude shows you the rating, the note, the role and the stage, and writes nothing.

You: Yes, send it.

What it deliberately cannot do

A Recruitee API token carries exactly the permissions of the person who generated it — the documentation is explicit that it can "perform the same actions as in the web or mobile application in the name of that user". There is no read-only token to issue.

So the restraint lives in this code instead. Disqualifying, requalifying, deleting, concealing and anonymising are all real, documented endpoints that this server does not implement. Not hidden behind a flag, not commented out — absent, so no instruction, prompt or bug can reach them. Rejecting a candidate stays a decision you make in the UI.

Stage moves are the one thing that is allowed. rt_set_stage advances a candidate along one offer's pipeline, because that is bookkeeping rather than a judgement, and a pipeline you cannot advance from here drifts out of step with wherever else you track it. The line is drawn at disqualification and it is enforced, not just documented: the move refuses a placement that has already been disqualified, since changing its stage would requalify the person — reversing somebody's rejection as a side effect of a bookkeeping call.

npm run smoke asserts these properties on every run: that no destructive tool is exposed, that the stage mover refuses a disqualified placement and is scoped to one offer, and that every write advertises its confirm gate. That last check derives writes from the tool schemas rather than from a list of name patterns — the earlier version silently stopped covering new tools, and waved rt_set_stage through without testing it at all.

Things worth knowing

New candidates land in "Sourced". Recruitee's create endpoint always drops people in "Applied", which would file everyone you sourced among the genuine applicants, so they are moved immediately after creation and you are told if that did not take. Pass stage to override it — "Applied" for somebody who genuinely applied, or any later stage for someone already in process. To move them afterwards, use rt_set_stage.

Setting a CV replaces the one already there. Recruitee's set_as_cv does not add a CV, it swaps the slot and demotes the previous file to a plain attachment. rt_attach_file therefore refuses to set a CV on a candidate who already has one unless you pass replaceCv — a CV on file is somebody's decision, and the only trace of overwriting it is an extra row in the attachments list.

Evaluations are filed under you. They appear as "You evaluated", indistinguishable from one clicked by hand. Never write one for a conversation you did not have or have not read, and if the judgement came from a colleague, say so in the note.

Attribution is unreliable coming back. Anything written through any API token is attributed to that token's owner, so the reviewer on an evaluation someone synced may be whoever synced it rather than whoever ran the interview. The note usually names the real one.

Questionnaire scorecards are not supported. Only the plain rating card. The API documents the per-question answers in every response but never in a request body, so the write shape would have to be observed from a real submission first. It may not matter for your account either: if /results/scorecards comes back empty for people who have been through interview stages, plain rating cards are what is in use and there is nothing missing. Worth checking before anyone invests in the questionnaire path.

Where this works

This is a local stdio MCP server — Claude launches it as a process on your machine, and your token never leaves it.

  • Claude Code (terminal, desktop app, IDE extensions) ✅

  • Claude desktop app ✅

  • claude.ai in a browser ❌ — that connects only to remote MCP servers reachable over HTTPS, which would mean hosting this and storing everyone's Recruitee tokens on that host.

Configuration

Variable

Purpose

RECRUITEE_API_TOKEN

Use a token from the environment instead of the stored one

RECRUITEE_COMPANY_ID

Use a company from the environment instead of the stored one

Troubleshooting

What you see

What to do

"No Recruitee API token"

Step 3 did not run, or ran in a different folder. cd back here and try npm run check.

"authenticated": false

The token was mistyped or revoked. Generate a new one and redo step 3.

Claude does not see the tools

Restart Claude properly — quit, don't just close the window. Check step 5 ran from inside this folder.

"That name matches two candidates"

Working as intended. Open the person in Recruitee and give Claude the number from the end of the URL.

Anything else

npm run smoke, and send whatever it prints.

Development

npm run smoke     # self-check: tool list, no destructive tools, confirm gates, one live read
npm run sourcing  # 20 checks on the search filters, including the four silent-failure modes
npm run check     # prove the token
npm start         # run the server directly (it speaks JSON-RPC on stdin/stdout)

Two implementation notes, both found by probing rather than from the docs:

  • File upload is undocumented. The reference describes a JSON body carrying a server-side path it never explains how to obtain. A plain multipart POST works, with the file part named attachment[file] — a bare file returns 500, and passing the candidate id as a query parameter creates an attachment linked to nobody. Promoting a file to the CV slot replaces it with a new id and a generated filename, so uploads are verified against the candidate's CV URL rather than the id that was just uploaded.

  • /search/new/candidates ignores its own query parameter and returns every record in the company, so name search goes through /candidates?query= instead. Pipeline stages come from /offers/{id}/placements, grouped by stage, not from /offers/{id}/pipeline_templates, which lists templates available to a role without their stages.

Available Tools

14 tools
rt_add_noteA

Add a note to a candidate. Use for context that is not a verdict — an assessment summary, sourcing rationale, or a call recap. Accepts a name or an id. Two-call gate.

Visibility "public" means anyone with access to the candidate can read it, which is usually what you want for a shared hiring record.

ParametersJSON Schema
NameRequiredDescriptionDefault
bodyYes
confirmNo
candidateYesFull name, or a candidate id.
visibilityNoDefault public.

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden and largely delivers. It discloses a notable behavioral trait ('Two-call gate') and explains the visibility semantics for shared hiring records. It drops a point because 'two-call gate' is cryptic — the agent isn't told what the two calls are or how confirm factors into them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tightly written sentences with front-loaded purpose and no fluff. Each sentence contributes new information. Slight deduction because 'Accepts a name or an id' restates candidate param detail, and the cryptic 'Two-call gate' fragment could have been replaced with a half-sentence explanation at no length cost.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 4-parameter tool with no annotations and no output schema, the description covers a lot: purpose, usage boundaries, a behavioral quirk, and visibility implications. Gaps remain — no return value discussion, no explanation of the two-call flow or when confirm is needed — but the most decision-critical context is present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 50%, so the description must compensate for body and confirm. It adds 'Two-call gate' (a hint at confirm's role) and 'Accepts a name or an id' (redundant with the candidate param). Body is never addressed, and confirm's role is only hinted at. Partial compensation, so a 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description leads with a specific verb+resource pair, 'Add a note to a candidate', and immediately carves out scope with 'context that is not a verdict'. The examples (assessment summary, sourcing rationale, call recap) clearly distinguish it from the sibling rt_submit_evaluation, so the agent can differentiate at a glance.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance with concrete examples and an exclusion clause ('not a verdict') that points toward when NOT to use it. While it doesn't name the sibling tool (rt_submit_evaluation) directly, the 'not a verdict' contrast plus the visibility default explanation gives clear decision context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

rt_attach_fileA

Attach a local file to an existing candidate — a CV, or a summary document. Set asCv to make it their CV rather than a plain attachment; a record with no CV shows "No CV or resume yet" in Tellent.

Setting a file as the CV REPLACES any CV already on file, demoting theirs to a plain attachment — so that is refused unless you pass replaceCv.

Only ever attach a file the user named. Never go looking for one, and never substitute a different file if the named one is missing. Two-call gate: preview, then confirm.

The upload is verified against the candidate afterwards; if it comes back unlinked, say so rather than reporting it as attached.

ParametersJSON Schema
NameRequiredDescriptionDefault
asCvNoMake it the candidate's CV. Default false.
confirmNo
filePathYesAbsolute path to the local file.
candidateYesFull name, or a candidate id.
replaceCvNoAllow replacing a CV already on file. Default false — setting a CV REPLACES the existing one and demotes it to a plain attachment, so that needs saying out loud.

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does so thoroughly. It discloses the destructive CV replacement behavior, the requirement for replaceCv, the two-call confirmation gate, and the post-upload verification expectation: "if it comes back unlinked, say so rather than reporting it as attached."

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, then covers side effects, safety rules, and verification behavior. Every sentence earns its place, and the structure moves from high-level action to specific constraints without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutating tool with no annotations and no output schema, the description is impressively complete: it covers the key side effect, required confirmation flow, file-source restriction, and post-verification behavior. It does not detail file-type limits or exact response shapes, but those are not essential for safe invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Even though schema coverage is 80%, the description adds meaningful semantics beyond the schema: it explains asCv's role, replaceCv's side effect of demoting an existing CV, and the confirm parameter via the "preview, then confirm" gate. This goes well above the baseline for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource: "Attach a local file to an existing candidate — a CV, or a summary document." It clearly distinguishes itself from sibling tools like rt_add_note or rt_create_candidate by focusing on file attachment and the CV-vs-plain-attachment distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear procedural context: attach only files the user named, never substitute files, and use a two-call gate (preview, then confirm). It does not explicitly name alternatives or say when not to use the tool, but the usage boundaries are well implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

rt_create_candidateA

Create a candidate in Recruitee/Tellent AND place them on a role, in one call. Works entirely from what you are told here — nothing has to exist anywhere else first.

WHAT YOU NEED. Required: the role (its title is enough, e.g. "VP of Customer Success") and the person's full name. Strongly recommended, because a record without them is close to useless to a recruiter: email, and either a LinkedIn URL or a CV file. Optional: phone, tags, a coverLetter block for their background and why they are worth a look, and where they came from. If the user has not given you the recommended fields, ASK for them before creating — the preview call lists exactly what is missing.

TWO-CALL GATE, ALWAYS. The first call (confirm omitted or false) returns what would be created, what is missing, and any existing candidates with the same name — and writes nothing. Show that to the user. Only call again with confirm true once they have approved THIS person for THIS role. One person per confirmation.

THIS CREATES A REAL RECORD FOR A REAL PERSON, visible to the whole hiring team and counted in reporting. The preview always runs a duplicate check; if it finds a match, resolve that with the user rather than creating a second record that splits their history.

DO NOT INVENT DETAILS. An empty field beats a guessed one.

STAGE. Defaults to "Sourced", which is right for anyone we went looking for. Pass stage: "Applied" only for someone who genuinely applied. Recruitee's create endpoint has no stage parameter, so this moves them immediately after creation and tells you if that did not take.

ParametersJSON Schema
NameRequiredDescriptionDefault
asCvNoTreat the attached file as their CV rather than a plain attachment. Default true when attachFile is a CV.
nameYesFull name.
tagsNo
emailNoStrongly recommended — without it nobody can contact them from the ATS.
linksNoProfile URLs, e.g. their LinkedIn.
offerYesRole title or offer id, e.g. "VP of Customer Success" or 2683651.
phoneNo
stageNoStage name. Default "Sourced".
confirmNoFalse/absent = preview only.
sourcesNoWhere they came from, e.g. ["LinkedIn"].
attachFileNoAbsolute path to a local file to attach — a CV, or a summary document.
coverLetterNoFree text: their background, and why they are worth looking at.

TDQS

A5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden and does so effectively. It discloses that this creates a real, visible record affecting reporting, always runs a duplicate check in preview, moves the stage immediately after creation, and reports if that stage change fails. It also warns against inventing details, providing a clear safety profile for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but exceptionally well structured with clear headings (WHAT YOU NEED, TWO-CALL GATE, etc.) and front-loaded purpose. Every sentence provides actionable information—no filler or repetition. The length is justified by the tool's complexity and the absence of annotations or output schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the 12 parameters, no annotations, and no output schema, the description covers all critical operational context: prerequisites, recommended fields, the preview/confirm workflow, duplicate handling, stage behavior, and fallback when the stage move fails. An agent has everything needed to invoke the tool correctly and avoid common pitfalls.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is high (83%), but the description adds substantial meaning beyond it: 'offer' can be title or ID, 'confirm' false/absent means preview only, 'stage' defaults to 'Sourced' with rationale, and it explains the interplay between attachFile/asCv and the recommended fields. This helps the agent map user intent to parameters accurately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific and complete statement: 'Create a candidate in Recruitee/Tellent AND place them on a role, in one call.' This clearly names the resource (candidate), the action (create + place on role), and the composite nature that distinguishes it from single-action siblings like rt_set_stage or rt_attach_file.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit when-to-use and how-to-use guidance: required vs. recommended fields, asking for missing info before creating, the two-call gate (preview then confirm), when to pass stage 'Applied' vs. default 'Sourced', and handling duplicate candidates. It also explains the composite action's benefit over separate calls, though it doesn't name sibling tools directly.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

rt_get_candidateA

Full record for one candidate: contact details, tags, every placement with its stage, and their application answers. Salary answers live in groupedOpenQuestionAnswers and are PER OFFER — read the offer id on each, because someone who applied to several roles carries several answers and the flat list cannot tell them apart.

ParametersJSON Schema
NameRequiredDescriptionDefault
candidateIdYes

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must reveal behavior. It warns about per-offer salary answers and the need to read the offer id, which is a subtle but critical nuance. It doesn't explicitly state read-only, but a 'get' operation implies that. The extra context about the flat response is valuable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences: the first lists the returned content, the second flags a caveat. No filler, front-loaded purpose. Excellent structure.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers what is returned and highlights a tricky aspect of the data shape (per-offer answers). It doesn't explain the response envelope, but with no output schema present, the description could mention the return format. Still, it's fairly complete for a single-record GET.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has one required parameter (candidateId) with type number, and the description does not elaborate on it. While the meaning is obvious from context, the description adds no parameter detail, and schema coverage is 0%. A brief mention of what to pass would raise this.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states 'Full record for one candidate' and enumerates the contents (contact details, tags, every placement, application answers). This clearly distinguishes it from sibling tools like rt_get_notes or rt_search_candidates.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies this is the tool to use when a complete single-candidate snapshot is needed)Skip. It doesn't explicitly contrast with alternatives, but the

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

rt_get_evaluationsA

Every evaluation on a candidate: rating, note, stage, reviewer and date, flattened into one list, newest last.

READ THIS BEFORE WRITING ONE, so you build on what other interviewers recorded instead of duplicating it.

IF YOU ARE COPYING THESE SOMEWHERE ELSE, carry the evaluation id across so a second sync updates the same row instead of duplicating it.

ATTRIBUTION IS UNRELIABLE COMING BACK. Recruitee files everything written through an API token under the token owner, so reviewer may be the token holder rather than whoever ran the interview. The note usually names the real one. Do not present the reviewer as fact when the note disagrees with it.

ParametersJSON Schema
NameRequiredDescriptionDefault
offerIdNoScope to one role. Recommended.
candidateIdYes

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full disclosure responsibility. It reveals the output ordering (newest last), flattening behavior, and critically warns that reviewer attribution is unreliable due to API token ownership, advising to rely on the note field. This goes beyond a simple read operation and provides valuable 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.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the main purpose in the first sentence, then adds critical usage warnings in subsequent blocks. It is somewhat verbose with repeated advice about duplication and syncing, but each sentence provides actionable information. The structure is organized and not unnecessarily padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool with two parameters and no output schema, the description covers the essential aspects: what data is returned, ordering, and key caveats. It also includes practical usage guidance. The lack of pagination or limit details is a minor gap, but overall it is sufficiently complete for effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema describes offerId but leaves candidateId without a description (50% coverage). The tool description mentions 'candidate' but does not elaborate on parameter semantics or constraints. It adds minimal meaning beyond the schema; candidateId is implied as the key but not explicitly explained, so it only partially compensates for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves all evaluations for a candidate, listing specific fields (rating, note, stage, reviewer, date) and the output format (flattened list, newest last). This is a specific verb+resource combination that distinguishes it from siblings like rt_get_notes (notes only) and rt_submit_evaluation (writing).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly instructs users to read this before writing an evaluation, implying it should be used before rt_submit_evaluation to avoid duplication. It also advises carrying the evaluation ID when syncing to prevent duplicates. While it doesn't name alternative tools, the context clearly indicates when to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

rt_get_notesA

Notes already on a candidate, newest first.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
candidateIdYes

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions that notes are returned 'newest first', which is a behavioral detail. However, it does not disclose whether this operation is read-only or destructive, or if it requires authentication, or if there are any side effects. For a simple 'get' operation, it might be safe to assume it's read-only, but the description doesn't explicitly state that. The lack of annotations means the description should have provided more safety context, but it does add the sorting behavior. Since it does not contradict annotations (none exist) and discloses a behavior, a 3 is reasonable. Adding 'read-only' or 'does not modify' would elevate it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is one sentence: 'Notes already on a candidate, newest first.' It is highly concise, front-loaded with the purpose, and includes a key sorting detail. No wasted words. Perfectly sized for a simple tool. This is a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple: it retrieves notes for a candidate. With 2 params, no output schema, and no nested objects, the description is almost sufficient. It provides the sorting order. However, it lacks any information about the output format (though no output schema exists), and does not mention whether it returns all notes or if pagination is implied. Also, it doesn't clarify what 'notes' are in this system—are they internal notes? Since there is a sibling 'rt_add_note', it likely are notes added by users. The description could have added a bit more context about the notes' source or content, but given the simplicity, a 3 is appropriate. It gives the essential purpose and sorting, but lacks some depth.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for parameter documentation. It does not mention any parameters in the description: candidateId is required but its semantic is obvious from its name; limit is also self-explanatory as a numeric limit. The description does not explicitly state that candidateId identifies the candidate whose notes are retrieved, but that's implied by the tool name and description. Since there are only 2 parameters and both are fairly clear from their names, the description doesn't need to elaborate much. However, because coverage is 0%, the description could have added a sentence like 'Provide candidateId to fetch notes, and optionally set limit to cap the result count.' That would improve it. Given the simplicity, a 3 is acceptable.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states what the tool does: it retrieves notes for a candidate, sorted newest first. It clearly identifies the resource (notes) and the subject (candidate). It does not explicitly distinguish from siblings like rt_add_note or rt_get_candidate, but the verb 'get' and resource 'notes' are clear. Slight ambiguity: 'Notes already on a candidate' implies it's a read operation, but it doesn't explicitly say 'retrieve' or 'list'. However, the meaning is clear enough. Not quite a 5 because it doesn't differentiate from rt_get_evaluations or others that might also be about candidate details, but it's specific to notes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not provide explicit guidance on when to use this tool vs alternatives. It implies it is for reading notes, but without context on when to choose this over rt_add_note or rt_get_candidate. It lacks any mention of prerequisites, ordering, or alternatives. However, the tool name 'rt_get_notes' and description are self-explanatory enough for a simple read operation. A 3 is appropriate for a description that gives basic context but no explicit when-to-use alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

rt_get_rating_scaleA

The rating scale this company is configured for. Read it BEFORE writing an evaluation: the valid rating values differ per tenant (a 4-point thumbs scale has no "neutral", a 5-point one does), and guessing files the wrong verdict on a real person.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the transparency burden. It discloses that rating values vary by tenant and warns that incorrect guessing can file a wrong verdict, adding meaningful behavioral context. However, it does not explicitly note that the tool is read-only or describe the return structure, which is a minor gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the core purpose, followed by a concise justification. No wasted words; every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, no-output-schema tool, the description is fully sufficient. It states what it returns, why it's critical to use it before evaluations, and gives an example of tenant-specific differences. It covers the essential context for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the baseline is 4. The description adds no parameter-specific information, but none is needed. It doesn't clutter with unnecessary param talk.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool retrieves the company's configured rating scale. It uses an implicit 'get' verb and specific resource ('rating scale'), distinguishing it from sibling tools like rt_get_stages or rt_get_notes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly instructs when to use it: 'Read it BEFORE writing an evaluation.' It also explains why (rating values differ per tenant), giving clear context for selection and timing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

rt_get_stagesA

The pipeline stages of one offer, with their ids. Needed before writing an evaluation, because an evaluation is filed against a stage.

ParametersJSON Schema
NameRequiredDescriptionDefault
offerIdYesFrom rt_list_offers.

TDQS

A4.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. It implies a read operation via 'get' but does not explicitly state it is non-mutating or side-effect-free. The description adds minimal behavioral context beyond the basic retrieval.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is exceptionally concise—two sentences that front-load the purpose and usage. Every word contributes value, with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read tool with one parameter and no output schema, the description is sufficiently complete. It explains what is returned (stages with IDs) and why it is needed, covering all necessary context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already fully describes the parameter ('From rt_list_offers'), and the description adds no additional parameter-level detail. With 100% schema coverage, the description does not need to compensate, so a baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves pipeline stages for a specific offer, including their IDs. It also explains its role as a prerequisite for evaluations, distinguishing it from sibling tools like rt_set_stage or rt_get_evaluations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states when this tool is needed ('Needed before writing an evaluation'), providing clear usage context. It does not explicitly mention alternatives or when not to use, but the context sufficiently guides the agent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

rt_list_offersA

List the roles (offers) in Recruitee/Tellent with their ids, status and candidate counts. Start here — every other tool is keyed on an offer id.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMax offers (default 50).
queryNoFilter by title, e.g. "Customer Success".

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It clearly indicates a read/list operation that returns ids, status, and candidate counts, implying no side effects. It also subtly reveals that the response contains offer ids needed elsewhere, but it does not detail pagination or return envelope.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero filler. The first sentence states purpose and outputs; the second provides navigational guidance. Everything earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple (two optional params, no output schema). The description sufficiently covers what it returns and why it should be used first. It lacks explicit return format details, but given the schema and the description's scope, it is nearly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already describes both parameters (limit and query) with 100% coverage. The description adds no additional parameter-level nuance, so baseline 3 is appropriate; it does not compensate beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the specific verb 'List' and names the resource 'roles (offers) in Recruitee/Tellent' with the exact fields returned (ids, status, candidate counts). It also distinguishes itself as the starting point, making its role clear among sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Start here — every other tool is keyed on an offer id' is explicit guidance on when to use this tool first and why: to obtain offer ids for the other tools. This effectively tells the agent to use this tool before any other tool that requires an offer id.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

rt_offer_candidatesA

Everyone on ONE offer, with their stage, disqualification state and ratings — genuinely scoped to that offer rather than the whole company database.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMax candidates (default 100).
offerIdYesFrom rt_list_offers.

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. It discloses the scope (single offer) and the data returned (stage, disqualification, ratings), but does not mention pagination behavior, default limit, or any side effects. Since it's a read operation, the lack of mutation warnings is acceptable, but more detail on output structure would improve transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that packs essential information: scope, data returned, and differentiation from broader queries. No fluff, front-loaded with the key purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (2 params, no output schema), the description is sufficient. It explains the core functionality and scope. However, it could mention that the output includes a list of candidates and possibly pagination, but the schema covers the limit parameter, so the description is adequate for the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for both parameters. The description adds context that the tool is scoped to one offer, which clarifies the offerId parameter's role. The limit parameter is self-explanatory, so the description adds minimal extra value, but the scoping note enhances understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns candidates for a single offer, including stage, disqualification state, and ratings. It explicitly distinguishes itself from a company-wide database query, which differentiates it from sibling tools like rt_search_candidates or rt_get_candidate.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for retrieving candidates scoped to a specific offer, and the schema notes offerId comes from rt_list_offers, providing a clear prerequisite. However, it does not explicitly state when not to use it or mention alternatives, though the scoping hint helps.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

rt_search_candidatesB

Find candidates by name or keyword across the company.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoDefault 25.
queryYes

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description gives minimal behavioral detail. It does not mention whether the operation is read-only, any side effects, return format, pagination, or ordering, leaving the agent uncertain about the tool's effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that is front-loaded with the core action. No unnecessary words or details, making it easy to parse and understand.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description lacks essential context such as the return structure, whether results are paginated, or any error/edge case behaviors. Without an output schema, the agent cannot anticipate what the tool returns, making the description incomplete for effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The query parameter's semantics are partially clarified by the description ('by name or keyword'), but the limit parameter is not described. The schema only provides type and default, so its meaning (e.g., maximum number of results) is not explicitly stated.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: to find candidates by name or keyword. It distinguishes itself from sibling tools like get_candidate by indicating a search across the company rather than a specific lookup.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when searching by name or keyword, but does not explicitly contrast with alternatives such as get_candidate or list_candidates. There is no direct guidance on when to prefer this tool over others.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

rt_set_stageA

Move an existing candidate into another pipeline stage on ONE of their roles — to advance them, or to mirror a move already made wherever your pipeline is tracked. Scoped to an offer because a candidate can sit on several pipelines at once.

Call rt_get_stages first if you do not know the offer's stage names; an unknown name is refused and the real ones are listed back. If you are mirroring a move from another system, do not assume the two name stages the same way — ask which stage is meant rather than picking the nearest word.

THIS IS NOT A REJECTION TOOL. It cannot disqualify anyone, and it refuses to move a candidate who has already been disqualified, because that would requalify them. Only move somebody because a person moved them or told you to — never because a meeting was booked, a score looked good, or the pipeline seemed stale.

Two-call gate: preview, then confirm. The move is verified by re-reading the candidate afterwards; if it did not land, that is reported rather than claimed as done.

ParametersJSON Schema
NameRequiredDescriptionDefault
offerYesRole title or offer id — which pipeline to move them along.
stageYesTarget stage name (or id) on that offer, e.g. "P&C Interview".
confirmNo
candidateYesFull name, or a candidate id.

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses that the tool refuses to move disqualified candidates, cannot disqualify anyone, requires a preview-then-confirm two-call gate, and verifies the move by re-reading the candidate afterward. This is rich behavioral context beyond any structured field.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is longer than average but every sentence earns its place. It is front-loaded with the core action, then systematically covers prerequisites, mirroring caveats, non-goals, and the confirmation flow. There is no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's mutation risk, the absence of annotations, and no output schema, the description is remarkably complete. It covers prerequisites, failure behavior, safety constraints, confirmation requirements, and post-move verification. It leaves little ambiguity for an agent deciding whether and how to invoke the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 75%, with the `confirm` parameter lacking a description. The description compensates by explaining the two-call gate ('preview, then confirm'), which gives meaning to `confirm`. It also clarifies stage-name behavior ('an unknown name is refused and the real ones are listed back'), adding value beyond the schema's basic parameter descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource: 'Move an existing candidate into another pipeline stage on ONE of their roles.' It clearly distinguishes itself from sibling tools like rt_get_stages (read-only stages) and explicitly disclaims rejection functionality, making its scope unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance: advance a candidate or mirror an external move. It also provides alternatives and exclusions: call rt_get_stages first if stage names are unknown, ask which stage is meant when mirroring across systems, and never use as a rejection tool. This is exemplary usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

rt_source_candidatesA

SEARCH THE WHOLE CANDIDATE DATABASE — every person who ever applied or was added, not just one role. This is the sourcing tool: use it to find people already in the ATS before going out to LinkedIn, because someone who applied to a similar role last year is the cheapest good candidate there is.

IT SEARCHES CV TEXT, not just names and titles. query takes boolean operators exactly as the Recruitee search bar does: "renewals AND churn", "(SaaS OR B2B) AND expansion". Every result carries whyMatched — the actual sentences that matched — so a coincidental hit can be dismissed without opening the profile.

SEARCH FOR THE EVIDENCE, NOT THE JOB TITLE. Titles are inconsistent between companies; what someone DID is written in their CV. Prefer "quota AND renewals" over "Account Manager", and run several narrow searches rather than one broad one.

MOST OF THIS DATABASE WAS REJECTED ONCE. Every result lists each role the person sits on with its stage and, where they were turned down, the reason. Read it before you suggest anybody: "wrong location" two years ago may not apply now, "failed the assessment" still does. Never present someone as a fresh find without saying they have been through the process before, and for which role.

excludeOffer keeps people already on a role out of the results, which is what you want when topping one up. Combine filters freely — they AND together.

ParametersJSON Schema
NameRequiredDescriptionDefault
pageNoFor paging past the first set.
tagsNoTag names. An unknown tag throws and lists the real ones.
limitNoMax 100, default 25.
offerNoLimit to people on this role (title or id).
queryNoFull-text, boolean, across CV and profile. e.g. "renewals AND churn".
stageNoPipeline stage name, e.g. "Applied". A stage this company does not have returns nothing and lists the real ones.
sortByNorelevance_desc (default) | created_at_desc | created_at_asc | last_activity_at_desc.
statusNoqualified | disqualified | new | viewed | overdue.
sourcesNoSource names, e.g. "linkedin.com".
jobStatusNopublished | archived — the status of the role they are on.
excludeOfferNoExclude people already on this role (title or id).

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations given, the description carries the full burden of behavioral disclosure. It explains that the tool searches CV text, that results include whyMatched for validation, that it lists role stages and rejection reasons, and that filters AND together. It even warns about interpretation: 'wrong location' two years ago may not apply now, 'failed the assessment' still does. This is rich, useful behavioral context beyond what schema or annotations would provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is longer than average, but every sentence earns its place. It is front-loaded with the core purpose, then progressively adds query syntax, result interpretation, rejection history caution, and filter combination advice. The structure is clear and easy to scan, and despite the length, it is not verbose—each paragraph introduces new, useful information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 11 parameters, no output schema, and no annotations, this description is remarkably complete. It covers the tool's scope (whole database), search semantics (boolean, CV text), output characteristics (whyMatched, role history), filtering behavior (AND combination, excludeOffer), and provides actionable best practices. It leaves minimal gaps for the agent to infer incorrectly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description adds extra meaning for 'query' by specifying boolean operator support and giving examples, and for 'excludeOffer' by explaining its intended use case. However, it does not add such depth to every parameter, though all are already documented in the schema. This is a good increment over the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens by clearly stating 'SEARCH THE WHOLE CANDIDATE DATABASE — every person who ever applied or was added, not just one role.' This distinguishes it from the sibling tool rt_search_candidates (which likely targets a single role). It also labels itself as 'the sourcing tool,' giving it a clear role within the offer lifecycle.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

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 it: 'use it to find people already in the ATS before going out to LinkedIn.' It also explains when NOT to use it or how to narrow down: 'excludeOffer keeps people already on a role out of the results, which is what you want when topping one up.' It advises on query syntax and search strategy ('Search for the evidence, not the job title'), and warns about rejection history.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

rt_submit_evaluationA

Write an evaluation (a thumbs rating plus a note) onto a candidate for one role — the "Evaluation" tab of their profile.

WORKS BY NAME. Give the person's name and the role title and the text; ids are not needed. If a name matches more than one candidate it refuses and lists them rather than guessing — filing a verdict on the wrong person is the failure that matters here.

THE STAGE IS AUTOMATIC. It files against wherever the candidate actually sits on that role, which is what an evaluation means. Only pass stage to override that deliberately.

TWO-CALL GATE, ALWAYS. First call previews, second call with confirm true writes.

IT IS FILED IN THE TOKEN OWNER'S NAME. Confirmed in practice: it appears in Tellent as "You evaluated", indistinguishable from one clicked by hand. So never write one as though it were another interviewer's verdict, and never write one for a conversation the token owner did not have or has not read. If the judgement came from someone else, say so in the note.

CALL rt_get_rating_scale IF UNSURE. Valid ratings depend on the configured scale. This company is on a 4-point thumbs scale: strong_no, no, yes, strong_yes ("yes" scores 4/5, 75%). A value the scale does not have is rejected rather than rounded.

PUT THE REASONING IN ratingNote. A bare rating nobody can audit is not worth writing. Where the verdict came from a screen or interview, say which.

Structured questionnaire scorecards (per-question answers) are NOT supported — only the rating card. If a role uses a questionnaire template, say so rather than flattening a multi-question scorecard into a single rating.

ParametersJSON Schema
NameRequiredDescriptionDefault
offerYesRole title, or an offer id.
stageNoOptional override. Defaults to where they actually are.
ratingYesstrong_no | no | yes | strong_yes.
confirmNoFalse/absent = preview only.
candidateYesFull name, or a candidate id.
ratingNoteNoThe reasoning, in the words that should stand on the record.

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It does so excellently: it reveals that the tool operates by name, refuses ambiguous matches to avoid mis-filing, automatically determines the stage, requires a two-call gate with explicit confirmation, and files in the token owner's name (with practical implications). It also notes that structured questionnaires are not supported, which is critical behavioral context. 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.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is verbose but highly dense with critical usage constraints. It uses all-caps headings for key points, making it scannable despite length. However, some repetition exists (e.g., the two-call gate is mentioned multiple times, and the 'IT IS FILED IN THE TOKEN OWNER'S NAME' section is extensive). It could be more concise without losing essential details, but the structure aids comprehension.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's high complexity (6 parameters, critical safety implications, no output schema or annotations), the description is remarkably complete. It covers the purpose, usage criteria, behavioral constraints, parameter uses, and edge cases (ambiguous names, unsupported questionnaires). The lack of an output schema is compensated by explaining the two-call preview/write flow, making the behavior fully predictable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers all parameters descriptively (candidate, offer, rating, ratingNote, stage, confirm), but the description goes further by clarifying the meaning of 'offer' (role title or id, not an offer object) and 'candidate' (full name, not id). It also emphasizes that ratingNote should contain auditable reasoning. Although it doesn't detail every parameter's syntax, the high schema coverage (100%) reduces the need. The description adds value by explaining the two-call gate and the confirmation semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool writes an evaluation (rating + note) onto a candidate for a role, targeting the 'Evaluation' tab. It explicitly distinguishes it from sibling tools like rt_get_evaluations (which reads) and rt_add_note (which likely writes a generic note, not an evaluation). The purpose is specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides extensive usage guidance: it explains when to use this tool (to file an evaluation), when not to (never for conversations the token owner didn't have), and explicitly directs to call rt_get_rating_scale if unsure about ratings. It also names sibling tools (rt_get_rating_scale) and clarifies the two-call gate pattern, leaving no ambiguity on when to invoke this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 14 tool updatesv1.0.0
    • First observedrt_add_note
    • First observedrt_attach_file
    • First observedrt_create_candidate
    • First observedrt_get_candidate
    • First observedrt_get_evaluations
    • First observedrt_get_notes
    • First observedrt_get_rating_scale
    • First observedrt_get_stages
    • First observedrt_list_offers
    • First observedrt_offer_candidates
    • First observedrt_search_candidates
    • First observedrt_set_stage
    • First observedrt_source_candidates
    • First observedrt_submit_evaluation
Deploy Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.9/5.0

Scored across 14 tools

Disambiguation3/5

rt_search_candidates and rt_source_candidates both search the candidate database with substantial overlap; source is a superset with CV-text boolean search and rejection history, which can cause confusion about which to use. Other read and write tools are clearly separated by resource and action, making the pair the main source of ambiguity.

Naming Consistency4/5

All tools share the rt_ prefix and most follow a consistent verb_noun pattern (list_offers, get_stages, create_candidate, submit_evaluation). Two deviations exist: rt_offer_candidates is a noun-noun phrase rather than an action, and rt_source_candidates uses the domain-specific verb 'source' instead of a generic search verb, but the overall pattern remains predictable.

Tool Count5/5

14 tools is well-scoped for an ATS server: candidate lifecycle, pipeline stages, evaluations, notes, attachments, offers, search, and rating scale are each covered. No tool feels redundant, and none is missing enough to make the count feel thin or bloated.

Completeness4/5

Core recruiting workflows are covered: sourcing, creating candidates, moving them through stages, filing evaluations, adding notes, attaching files, and reading offer/candidate data. Obvious gaps are the lack of a candidate profile update tool and no explicit rejection/disqualification operation, but the design deliberately scopes set_stage away from rejection, and the rest of the lifecycle is well supported.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Recruitee MCP Server

    pepuscz
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables extraction and analysis of candidate profiles from Recruitee recruitment pipelines, optimized for LLM evaluation with clean, bias-free data.
    3
    MIT

  • Ashby MCP

    JakeTeagle
    A
    license
    Not graded
    quality
    D
    maintenance
    Connects your Ashby recruiting data to Claude, enabling natural language queries and management of candidates, applications, jobs, interviews, offers, and team information.
    16
    MIT

  • zoho-recruit

    yogeshsraju-max
    F
    license
    B
    quality
    C
    maintenance
    Enables Claude to manage Zoho Recruit ATS operations including candidates, jobs, interviews, analytics, email, and AI-assist through natural language.
    20
    -