Skip to main content
Glama
deeneskoruzh
strelov1

freehire

by strelov1
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

freehire MCP server

An MCP server over the freehire job API. It lets any MCP host — Claude Desktop, Claude Code, or a compatible agent — search, filter, and apply to IT jobs without a browser, authenticating with a personal API key. Postings are crawled straight from company career boards — 3.3M+ open roles across 294K companies, normalized into one schema and tagged with stack, seniority, region and work mode (live figures).

It mirrors the freehire CLI: same API, same credentials, exposed as MCP tools instead of shell commands.

Install

No global install needed — the host runs it via npx. Add it to your host's MCP configuration (Claude Desktop → Settings → Developer → Edit config, or ~/.claude.json for Claude Code):

{
  "mcpServers": {
    "freehire": {
      "command": "npx",
      "args": ["-y", "freehire-mcp"],
      "env": { "FREEHIRE_TOKEN": "fhk_xxxxxxxx" }
    }
  }
}

Create the fhk_… key in the web app (freehire.me → account menu → API keys). If you already use the freehire CLI (freehire auth login), you can omit env — the server reads the same ~/.freehire/creds.json.

Related MCP server: witness-mcp

Authentication

The token and API base URL resolve with precedence env → ~/.freehire/creds.json → default https://freehire.me:

What

Sources

Token

FREEHIRE_TOKEN → creds file

API base URL

FREEHIRE_API_URL → creds file → https://freehire.me

The server only reads the credentials file (it never writes it — logging in stays the CLI's job). If no token is configured, tools return a clear "not authenticated" error rather than the server failing to start.

Tools

Tool

Purpose

whoami

Authenticated user (verify the key).

facets

The filter/skill vocabulary: every facet's live values with counts. Call first.

search

Keyword + facet job search; returns jobs with their full description as markdown and the total match count.

market_fit

Score a skill list against live market demand (coverage + gaps).

job

A single job's full content by slug.

company

A company and its open jobs by slug.

apply

Mark a job applied.

save / unsave

Bookmark / remove a bookmark.

stage

Set the application stage (server-validated).

note

Attach a free-text note.

my

The caller's tracked jobs (all/viewed/saved/applied) with stage + note.

cv_tailor

Start (or reopen) tailoring for a vacancy; returns the CV id the other cv_* tools take.

cv_list

The caller's tailored CVs with the vacancy each was written for.

cv_context

The fit analysis a tailored CV should reframe toward (missing_have vs missing_gap).

cv_get

A tailored CV's full document.

cv_edit

Apply a batch of path-addressed edits to a tailored CV, atomically (server-validated; uncited claims are refused).

cv_render

Render a tailored CV to a PDF, returned as a base64 application/pdf resource.

experience_list

The candidate's experience bank, with each achievement's provenance. cv_edit's evidence_id comes from here.

experience_add_employment / experience_add_achievement

Record a place, or one piece of evidence.

experience_update_employment / experience_update_achievement

Correct one. Field-level: what you do not name is kept.

experience_remove_employment / experience_remove_achievement

Delete one. No undo; a place must be empty first.

submit

Submit a vacancy for moderation.

my_submissions

The caller's submissions with status.

jobs_add / jobs_edit

Moderator: author / edit a job (403 without the role).

submissions_pending

Moderator: the review queue.

submission_approve / submission_reject

Moderator: decide on a submission.

Filters. search, market_fit, and facets share the same market-filter parameters: remote, region, country, city, company, category, role, seniority, employment_type, english_level, exclude_skill, salary_min, visa, plus a generic facets map ({"source": "greenhouse"}) for any other facet in the vocabulary. Discover valid values with the facets tool — do not invent them. In search, skills is a filter; in market_fit, skills is the measured set.

Geography widens. region, country and city are ONE OR-group: region: ["eu"] with country: ["IT"] means "in Europe or in Italy" and returns everything the region alone would. To search a single country, pass country and omit region. The three name a single concept — where — so picking two places reads as "either", which is what makes region: ["eu"] with country: ["BR"] ("Europe or Brazil") useful. There is no AND to switch on: _mode=and does not apply to geography.

Unread params are ignored, not refused. A filter key the API does not recognize does not fail the request, it widens it. Such keys come back in the result's ignored list, with did_you_mean when only the grammatical number was wrong. search reports it alongside total; facets and market_fit answer a single object, so they wrap it as {data, ignored} — and only then, leaving a clean call's shape untouched. Any number from a result carrying ignored answers a broader question than the one asked — retry with the suggested name before reporting it.

Descriptions. search reads the API's agent endpoint, so every hit already carries the posting's full description rendered as markdown — a host can screen a result set without a job call per hit. Descriptions are long, so keep limit modest.

The evidence rule. Every achievement in the bank records who asserted it. cv_import, stated_in_chat and manual mean the candidate did, and may be cited on a CV; agent_inferred means a model read it into the record, and may not. cv_edit refuses any claim about the candidate without an evidence_id pointing at a citable one, which is why experience_list is the tool that makes cv_edit usable at all.

Correcting an achievement does not move that label: an agent_inferred one stays uncitable however it is reworded. The only way it becomes citable is to ask the candidate, then record what they say with experience_add_achievement.

Removing is final — the bank has no undo. A place must be emptied before it can go, because deleting one would take every achievement under it. Folding two achievements into one, keeping the numbers from both, is on the site.

Each tool returns the raw API data as JSON text; an API error becomes an isError result carrying the HTTP status (a 401 adds an auth hint).

Develop

npm install
npm test        # vitest: config, client (mock server), facets, tool dispatch
npm run build   # tsc → dist/

License

MIT — see LICENSE. The freehire backend and CLI are MIT too.

Available Tools

19 tools
applyB
Idempotent

Mark a job as applied for the authenticated user. Idempotent.

ParametersJSON Schema
NameRequiredDescriptionDefault
slugYesThe job's public slug (from search or facets results).

TDQS

B3.4/5.0
Behavior3/5

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

Description adds 'Idempotent' but this is already declared in annotations via idempotentHint=true. No additional behavioral context like authentication requirements, side effects, or error conditions. With annotations present, the description adds minimal value.

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, no fluff. Every word earns its place. Exceptionally concise and to the point.

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 tool with one parameter and no output schema, the description covers the essential purpose and idempotency. Could mention the return behavior (e.g., success/failure indicators) but not strictly necessary given the tool's simplicity.

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?

Single parameter with full schema coverage (description in schema). Description adds no extra meaning beyond what the schema provides. Baseline score of 3 is appropriate.

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?

Clearly states the verb 'Mark' and resource 'job', and mentions idempotency. Could be more specific about the effect (e.g., creating an application) but overall clear. No differentiation from siblings like 'submit' or 'save'.

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

Usage Guidelines2/5

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

No guidance on when to use this tool vs alternatives. Does not explain prerequisites (e.g., must be authenticated) or when not to use (e.g., if already applied). The only behavioral note is idempotency, which is already annotated.

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

companyA
Read-only

Fetch a company and its open jobs by company slug.

ParametersJSON Schema
NameRequiredDescriptionDefault
slugYesThe company slug (from a job's company_slug).

TDQS

A4/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true; the description adds that the tool also returns open jobs beyond the company info. It does not mention pagination or data limits, but for a simple fetch this is acceptable.

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?

A single, front-loaded sentence that earns its place with no filler. Every word adds meaning.

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 retrieval tool with one parameter and no output schema, the description provides sufficient high-level information. It does not detail the output structure, but that is acceptable given the tool's simplicity.

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 100% and the parameter 'slug' is described in both schema and description. The description reiterates the role of slug ('by company slug'), adding no new semantic detail 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 clearly states the verb ('Fetch'), the resource ('a company and its open jobs'), and the method ('by company slug'). It distinguishes from sibling tools like 'job' and 'search' by specifying the combined fetch.

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 a company slug is available and one wants company details plus open jobs, but it does not explicitly compare with siblings or state when not to use it. Absence of usage guidance is a gap.

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

facetsA
Read-only

List the market's filter vocabulary: every facet's live values with a vacancy count each, plus the skills list and numeric ranges. Call this FIRST to discover real values for search and market_fit — do not invent facet values.

ParametersJSON Schema
NameRequiredDescriptionDefault
cityNoCity slugs.
roleNoRole facet values, e.g. senior_backend.
visaNoOnly jobs offering visa sponsorship.
facetsNoAny other facet param as key→value(s), e.g. {"source": "greenhouse"}. Discover valid keys and values with the `facets` tool.
regionNoRegion codes (OR within): global|ru|cis|central_asia|eu|us.
remoteNoOnly remote jobs (sets work_mode=remote).
companyNoCompany slugs.
countryNoISO-3166 country codes, e.g. BR, US.
categoryNoRole categories: backend|frontend|fullstack|devops|ml_ai|qa|...
seniorityNoSeniority: intern|junior|middle|senior|staff|principal|lead|c_level.
salary_minNoMinimum salary (enrichment.salary_min).
english_levelNoEnglish level, e.g. a2, b1, b2, c1.
employment_typeNoEmployment type, e.g. full_time, contract.

TDQS

A4.7/5.0
Behavior5/5

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

The description aligns with the readOnlyHint annotation, indicating a read-only operation. It adds behavioral context by specifying that the tool returns live values with counts, which is beyond the annotation. No contradiction.

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 long, front-loading the purpose and output, followed by usage guidance. Every sentence earns its place 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?

Despite no output schema, the description sufficiently explains the return (facet values, counts, skills, ranges) and how to use the tool. For a parameter-rich tool, this context is complete enough for an agent to select and invoke it correctly.

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 100% with each parameter described adequately. The tool description does not add significant new meaning beyond the schema, but it contextualizes parameters as filter vocabulary. Baseline 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's purpose: listing filter vocabulary with live facet values, vacancy counts, skills list, and numeric ranges. It distinguishes itself from siblings like 'search' and 'market_fit' by positioning itself as the first call to discover real values.

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 explicitly directs the agent to call this tool FIRST before 'search' and 'market_fit', and warns against inventing facet values. This provides clear usage guidance and context for alternatives.

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

jobA
Read-only

Fetch a single job's full content by slug (title, company, location, posting URL, description).

ParametersJSON Schema
NameRequiredDescriptionDefault
slugYesThe job's public slug (from search or facets results).

TDQS

A4.2/5.0
Behavior4/5

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

Annotations already show readOnlyHint=true, so the agent knows this is a safe read. The description adds value by listing the fields returned (title, company, location, posting URL, description), providing behavioral specifics beyond annotations without contradiction.

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 sentence, 14 words, with the verb and key action front-loaded. Every word serves a purpose, and there is no redundant or filler content.

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?

With only one parameter and no output schema, the description adequately covers what the tool does and what it returns. It does not mention error handling or slug existence, but for a simple fetch-by-id tool, this is sufficient and not a significant gap.

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 100% and already describes the slug parameter as 'The job's public slug (from search or facets results).' The description merely repeats 'by slug' without adding any new semantic detail, so baseline 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 uses 'Fetch' as the verb, specifies the resource as 'a single job', and identifies the key identifier 'slug'. It also enumerates the returned content fields, distinguishing this from sibling tools like 'search' which return lists, and 'apply', 'save', etc. which perform other actions.

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 when a slug is available (e.g., from search or facets results) and provides clear context for retrieving full job details. However, it does not explicitly state when not to use this tool or name alternatives, leaving some room for inference.

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

jobs_addA
Idempotent

Moderator: create a hand-curated job. URL is the dedup key — re-adding the same URL updates the posting. description is stored and rendered as HTML. Requires the moderator role (403 otherwise).

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesThe posting URL — the dedup key. Required.
titleYesJob title. Required.
remoteNo
sourceNoThe posting's real origin (defaults to 'manual' server-side).
companyYesCompany name. Required.
locationNo
posted_atNoRFC3339 timestamp.
descriptionNoStored and rendered as HTML.

TDQS

A4.5/5.0
Behavior5/5

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

Discloses key behaviors: URL as dedup key (idempotent update), description stored as HTML, and auth requirement. Annotations already indicate idempotentHint, but description adds how idempotency is achieved.

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?

Three sentences with front-loaded purpose. No redundancy, every sentence provides unique value.

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?

Lacks return value information despite no output schema. Otherwise covers purpose, behavior, and auth. Moderate complexity with 3 required params.

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?

With 75% schema coverage, description adds meaning for critical params: 'url' dedup key and 'description' HTML storage. Other params are sufficiently described in 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?

Description clearly states 'create a hand-curated job' with specific verb and resource. Distinguishes from sibling 'jobs_edit' and others via dedup key behavior and moderator role.

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?

Explicitly states 'Requires the moderator role (403 otherwise)' indicating when to use. No explicit alternatives mentioned, but the context of hand-curated and sibling list provides implicit guidance.

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

jobs_editA
Idempotent

Moderator: partially update a manual job by slug. Only the provided fields change; the URL identity is not editable. Requires the moderator role (403 otherwise).

ParametersJSON Schema
NameRequiredDescriptionDefault
slugYesThe job's public slug (from search or facets results).
titleNo
remoteNo
companyNo
locationNo
posted_atNoRFC3339 timestamp.
descriptionNoStored and rendered as HTML.

TDQS

A4.1/5.0
Behavior4/5

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

Annotations show readOnlyHint=false and idempotentHint=true. The description adds critical context: partial update semantics and 403 error for non-moderators. This exceeds what annotations alone 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?

Two sentences, each adding unique value: purpose + constraint, then role requirement. No redundancy or fluff.

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?

With 7 parameters and no output schema, the description is minimal. It explains partial updates and role requirement but omits side effects, success response, or distinction between manual and other jobs. Could be more 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?

Schema coverage is 43%, so the description should compensate. It adds context for the slug parameter (not editable) and general partial update behavior, but does not elaborate on other parameters beyond schema descriptions. Adequate but not rich.

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 states 'Moderator: partially update a manual job by slug', specifying the action (update), resource (manual job), and identifier (slug), clearly distinguishing it from sibling tools like 'jobs_add'.

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 clarifies partial update behavior and role requirement ('Requires the moderator role'), but does not explicitly compare with alternatives (e.g., 'jobs_add' for creation). The implication is present but not explicit.

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

market_fitA
Read-only

Score a skill list against the live open-vacancy market for a filtered role: headline coverage (% of vacancies listing ≥1 skill), must-have skills held, and the missing skills that unlock the most vacancies. Here skills is the MEASURED set, not a filter — use facet params to define the role. One skill probes that skill's demand.

ParametersJSON Schema
NameRequiredDescriptionDefault
cityNoCity slugs.
roleNoRole facet values, e.g. senior_backend.
visaNoOnly jobs offering visa sponsorship.
facetsNoAny other facet param as key→value(s), e.g. {"source": "greenhouse"}. Discover valid keys and values with the `facets` tool.
regionNoRegion codes (OR within): global|ru|cis|central_asia|eu|us.
remoteNoOnly remote jobs (sets work_mode=remote).
skillsYesThe candidate's skills to measure (canonical slugs). One value probes a single skill.
companyNoCompany slugs.
countryNoISO-3166 country codes, e.g. BR, US.
categoryNoRole categories: backend|frontend|fullstack|devops|ml_ai|qa|...
seniorityNoSeniority: intern|junior|middle|senior|staff|principal|lead|c_level.
salary_minNoMinimum salary (enrichment.salary_min).
english_levelNoEnglish level, e.g. a2, b1, b2, c1.
employment_typeNoEmployment type, e.g. full_time, contract.

TDQS

A4.4/5.0
Behavior4/5

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

The description details the tool's behavior: computing headline coverage, identifying must-have and missing skills. This goes beyond the readOnlyHint annotation by explaining the analytical nature. It could mention data freshness or potential limitations, but overall it provides sufficient 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 concise with two informative sentences. It front-loads the main purpose and then adds critical usage nuance. No redundant or filler content.

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 complexity (14 parameters, 1 required, no output schema), the description covers the tool's functionality well. It explains the conceptual output but could be more explicit about the exact return structure. Still adequate for a read-only analysis 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?

The description adds crucial semantics beyond the schema, such as clarifying that 'skills' is the measured set (not a filter) and that using a single skill probes demand. With 100% schema coverage, this extra context justifies a score above baseline 3.

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: 'Score a skill list against the live open-vacancy market for a filtered role' and lists specific output metrics (headline coverage, must-have skills, missing skills). It distinguishes itself from sibling tools by focusing on market fit analysis, not job search or CRUD operations.

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 explains that 'skills' is the measured set and that facet parameters define the role, providing clear guidance on how to use the tool. It also states that a single skill probes that skill's demand. However, it does not explicitly mention when not to use this tool or provide alternatives, slightly limiting completeness.

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

myA
Read-only

List the caller's tracked jobs (viewed/saved/applied) with their stage and note. Filter narrows the set.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
filterNoWhich tracked jobs to list.all
offsetNo

TDQS

A3.6/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true, so the description adds limited behavioral context beyond that. It mentions that the tool returns stage and note, and that filter narrows results, but does not disclose pagination behavior (offset/limit) or authentication details. For a read-only operation, this is adequate but not extensive.

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 a single concise sentence that conveys the main purpose. It is appropriately front-loaded but could benefit from mentioning pagination or parameter details to improve completeness without sacrificing brevity.

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 readOnly annotations and no output schema, the description covers the key aspects: what is listed (caller's tracked jobs), what fields are included (stage, note), and how to filter. However, it lacks guidance on pagination (offset/limit) which is part of the input schema, slightly reducing completeness.

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?

Schema description coverage is only 33% (filter has a description), and the main description does not add meaning for limit or offset beyond what the schema provides. It mentions that filter narrows the set but does not elaborate, leaving two parameters undocumented in both schema and description.

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 lists the caller's tracked jobs (viewed/saved/applied) with stage and note, using a specific verb and resource. It is easily distinguished from sibling tools like 'my_submissions' which lists submissions.

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 for listing tracked jobs but does not provide explicit guidance on when to use this tool versus alternatives like 'my_submissions' or 'search'. No exclusions or when-not-to-use information is given.

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

my_submissionsA
Read-only

List the caller's own vacancy submissions with their moderation status.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.1/5.0
Behavior3/5

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

The description aligns with the 'readOnlyHint' annotation by stating 'List'. However, it adds no further behavioral details (e.g., pagination, sorting) beyond what the annotation already conveys.

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, efficient sentence with no extraneous words. It delivers maximum information in minimal space.

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 zero parameters, the readOnly annotation, and no output schema, the description sufficiently covers what the tool does and what it returns (moderation status). No gaps.

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?

There are zero parameters, so the description has no parameter details to add. The description does not need to compensate for missing schema documentation. Baseline 4 applies.

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 action ('List'), the resource ('the caller's own vacancy submissions'), and the specific information returned ('moderation status'). It distinguishes from siblings like 'submissions_pending' or 'submission_approve'.

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 for listing the caller's own submissions, but it does not explicitly state when not to use it or mention alternative tools for different scopes (e.g., 'submissions_pending' for pending ones).

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

noteA
Idempotent

Attach a free-text note to a tracked job (overwrites the existing note).

ParametersJSON Schema
NameRequiredDescriptionDefault
noteYesFree-text note to store on the job.
slugYesThe job's public slug (from search or facets results).

TDQS

A4/5.0
Behavior4/5

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

Annotations already indicate idempotentHint=true and readOnlyHint=false, so the description does not need to reiterate safety. It adds value by explicitly stating the overwrite behavior, which is not in annotations. 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.

Conciseness5/5

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

Single sentence, front-loaded with verb, no filler. Every word earns its place, making it efficient and easy to parse.

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 simplicity of the tool (2 parameters, no output schema), the description covers the core action and overwrite behavior well. Could mention note length limits, but overall sufficient for a small tool.

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 100%, providing clear parameter descriptions for 'slug' and 'note'. The description reinforces these but does not add new constraints or format details beyond the schema, maintaining a baseline score.

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 attaches a free-text note to a tracked job, specifying the verb 'attach', the resource 'free-text note to a tracked job', and the distinguishing behavior 'overwrites the existing note'. This differentiates it from sibling tools like jobs_edit which modify broader job details.

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 for adding or updating notes on tracked jobs, but provides no guidance on when to use this tool versus alternatives (e.g., jobs_edit) or when not to use it. It lacks explicit context on exclusions or alternatives.

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

saveA
Idempotent

Bookmark a job for later. Idempotent.

ParametersJSON Schema
NameRequiredDescriptionDefault
slugYesThe job's public slug (from search or facets results).

TDQS

A3.6/5.0
Behavior3/5

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

The description mentions 'Idempotent', which is already declared via annotations. Other behavioral traits (e.g., side effects, auth needs) are not disclosed, but annotations cover the safety profile minimally.

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 short sentences with no wasted words. The key action and idempotency are front-loaded.

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 idempotent bookmark tool with one parameter and no output schema, the description is adequately complete. It could optionally mention reversal via 'unsave', but not essential.

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 100% and describes the slug parameter well. The description adds no extra meaning about the parameter, so baseline 3 applies.

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 'Bookmark a job for later' uses a specific verb (bookmark) and resource (job), clearly distinguishing it from sibling tools like 'apply' or 'unsave'.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives (e.g., 'apply' or 'unsave') is provided. The description only states the action without contextual usage.

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

stageA
Idempotent

Set a job's application stage. The server validates the value; valid stages are applied/screening/responded/interview/offer/accepted/rejected/withdrawn.

ParametersJSON Schema
NameRequiredDescriptionDefault
slugYesThe job's public slug (from search or facets results).
stageYesApplication stage, e.g. interview, offer, rejected.

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already indicate readOnlyHint=false (modifies) and idempotentHint=true (safe retry). The description adds the list of valid stages and mentions server validation, providing useful behavioral context beyond annotations. No contradiction.

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 sentence, 17 words, with no redundant information. Every word earns its place.

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 description is adequate for a simple tool with two parameters and annotations, but lacks information about return values or prerequisites (e.g., application must exist). Could be more complete to guide the agent fully.

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%, but the description adds a list of valid stages not present in the schema (which has no enums). This adds significant value by enumerating allowed values.

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 a specific verb 'Set' and resource 'job's application stage', and lists all valid stages, making it clear what the tool does and distinguishing it from siblings like 'apply' or 'submit'.

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 for updating an existing application's stage by listing valid values, but does not explicitly state when to use this tool versus siblings like 'apply' (new application) or 'submission_approve' (approve submission).

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

submission_approveA

Moderator: approve a pending submission, minting a live job. Requires the moderator role (403 otherwise).

ParametersJSON Schema
NameRequiredDescriptionDefault
idYesThe submission id.

TDQS

A4.4/5.0
Behavior4/5

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

Adds role requirement and error code beyond annotations (readOnlyHint=false). Describes write action and outcome.

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?

Single sentence with essential info. No filler. Front-loaded with role and action.

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?

Adequate for simple action. Lacks output info or side effects, but role requirement and outcome are clear.

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 covers 100% of parameter description. Description adds context by linking id to approval action, though no extra detail on format.

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?

Clear verb 'approve' and specific resource 'pending submission' with outcome 'minting a live job'. Distinguishes from siblings like submission_reject.

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?

States required moderator role and 403 error otherwise. Implicitly indicates when to use based on pending status and role.

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

submission_rejectA

Moderator: reject a pending submission with an optional reason. Requires the moderator role (403 otherwise).

ParametersJSON Schema
NameRequiredDescriptionDefault
idYesThe submission id.
reasonNoOptional rejection reason.

TDQS

A4/5.0
Behavior3/5

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

The description indicates a mutation action ('reject') consistent with annotations (readOnlyHint=false), but does not disclose side effects (e.g., status change, notifications) beyond the role requirement.

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, front-loaded sentence that efficiently conveys purpose and usage without unnecessary words.

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?

With only two parameters and no output schema, the description covers purpose and role requirement adequately, but lacks details on return value or explicit state change.

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 100%, and the description merely restates the schema's parameter details (id, optional reason) without adding new semantic information.

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 verb 'reject' and the resource 'pending submission', distinguishing it from sibling tools like 'submission_approve'.

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 specifies the required moderator role and the error response (403) for unauthorized use, but does not explicitly mention when not to use or alternatives like 'submission_approve'.

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

submissions_pendingA
Read-only

Moderator: list the pending submission review queue. Requires the moderator role (403 otherwise).

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.6/5.0
Behavior5/5

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

The description adds critical behavioral context beyond the 'readOnlyHint' annotation by specifying the authentication requirement ('Requires the moderator role (403 otherwise)'). This informs the agent about authorization constraints and error behavior.

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 conveys both the purpose and the prerequisite role requirement. No extraneous information is present.

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 (0 parameters, readOnlyHint annotation, no output schema), the description adequately covers purpose and auth. However, it could be enhanced by hinting at the format or content of the returned list, but this is not critical.

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?

With 0 parameters and 100% schema description coverage, the description does not need to add parameter details. Based on the scoring rule, a baseline of 4 is appropriate since the schema already fully covers the parameters.

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 'list the pending submission review queue' using a specific verb ('list') and resource ('pending submission review queue'). This purpose is distinct from sibling tools like 'submission_approve' and 'submission_reject', which perform actions, and 'my_submissions', which likely lists user's own submissions.

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 states the requirement for the moderator role and notes that 403 is returned otherwise, providing clear guidance on who should use this tool. However, it does not explicitly mention when not to use it or contrast it with alternatives like 'my_submissions' for non-moderators.

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

submitB

Submit a vacancy for moderation. The server stores it as pending and returns it. URL (the dedup key), title, and company are required.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesThe posting URL — the dedup key. Required.
titleYesJob title. Required.
remoteNo
sourceNoThe posting's real origin (defaults to 'manual' server-side).
companyYesCompany name. Required.
locationNo
posted_atNoRFC3339 timestamp.
descriptionNoStored and rendered as HTML.

TDQS

B3.2/5.0
Behavior3/5

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

The description adds context beyond annotations by stating the server stores the submission as pending and returns it. Annotations already indicate write operation (readOnlyHint=false), so the description provides marginal additional behavioral insight.

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, front-loaded with the core action, no filler. Every sentence is essential.

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?

Given the tool has 8 parameters and no output schema, the description lacks details on return values, error handling, or formatting requirements, making it incomplete for a submission tool.

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 high (75%), so the description adds only minor value by noting 'dedup key' for URL. It does not significantly enhance understanding of parameters beyond the schema.

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 clearly states the tool submits a vacancy for moderation, with a specific verb and resource. However, it does not explicitly differentiate from sibling tools like 'jobs_add' or 'jobs_edit', so it's slightly below a 5.

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

Usage Guidelines2/5

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

The description mentions required fields but provides no guidance on when to use this tool over alternatives, nor any when-not-to-use scenarios.

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

unsaveA
Idempotent

Remove a job's bookmark. A no-op if it was not saved.

ParametersJSON Schema
NameRequiredDescriptionDefault
slugYesThe job's public slug (from search or facets results).

TDQS

A4.2/5.0
Behavior4/5

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

Annotations indicate idempotentHint=true; description reinforces this by stating it's a no-op if not saved. Adds value beyond annotations.

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?

Single sentence, front-loaded with action verb, no wasted words. Efficiently conveys purpose and behavior.

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 tool with one parameter and no output schema, the description covers purpose and idempotency. Lacks details on error handling (e.g., invalid slug), but overall adequate.

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 100%, so baseline is 3. Description does not add any additional parameter information beyond what the schema already provides.

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?

Description clearly states the verb 'remove' and the resource 'job's bookmark', and distinguishes from the sibling tool 'save'. The no-op note adds clarity for edge case.

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?

Context is clear: use to unsave a job. The no-op note implicitly advises it's safe to call even if not saved. However, it lacks explicit when-not-to-use or alternatives beyond the sibling context.

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

whoamiA
Read-only

Return the authenticated freehire user (verifies the API key). Call this to confirm auth before other tools.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true, so the description's role is to add context. It adds value by specifying it returns user info and verifies the API key, with 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.

Conciseness5/5

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

Two sentences, front-loaded with purpose, 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 simple tool with no parameters and no output schema, the description is complete: it states functionality and usage context.

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 0 parameters, so baseline is 4. No parameter information needed in description.

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 verb 'return' and resource 'authenticated freehire user', and explicitly calls out it verifies the API key. It distinguishes itself from sibling tools by focusing on auth confirmation.

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 says 'Call this to confirm auth before other tools', providing clear usage context. While it doesn't mention when not to use it, the simplicity of the tool makes this sufficient.

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. 19 tool updatesv0.1.0
    • First observedapply
    • First observedcompany
    • First observedfacets
    • First observedjob
    • First observedjobs_add
    • First observedjobs_edit
    • First observedmarket_fit
    • First observedmy
    • First observedmy_submissions
    • First observednote
    • First observedsave
    • First observedsearch
    • First observedstage
    • First observedsubmission_approve
    • First observedsubmission_reject
    • First observedsubmissions_pending
    • First observedsubmit
    • First observedunsave
    • First observedwhoami
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.8/5.0

Scored across 19 tools

Disambiguation5/5

Each tool targets a distinct action or resource. User interactions (apply, save, unsave, note, stage, my), moderator actions (jobs_add, jobs_edit, submission_*), data retrieval (job, company, search, facets, market_fit), and auth (whoami) are clearly separated with no significant overlap.

Naming Consistency3/5

Naming is inconsistent: single-word verbs (apply, save, note) mix with compound underscore names (jobs_add, market_fit, submission_approve) and a noun-only style (company, facets, job, my). While readable, there is no single predictable pattern.

Tool Count4/5

With 19 tools, the server covers user, moderator, and search functionality thoroughly. This is slightly above the ideal 3-15 range but still well-scoped and each tool earns its place.

Completeness4/5

The tool surface covers core workflows: job browsing, searching, applying, tracking, and moderation. Minor gaps exist, such as no explicit job deletion or submission withdrawal, but these are not critical for typical usage.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • job-monitor

    oleg-pevzner
    A
    license
    Not graded
    quality
    C
    maintenance
    Searches LinkedIn, Indeed, USAJobs, and Google Jobs from the command line, deduplicates across sources, and optionally finds hiring manager emails; also runs as an MCP server for AI agents.
    MIT

  • witness-mcp

    Zetetic-Dhruv
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables to interact with job application workflows through MCP, allowing users to find jobs, generate non-trivial applications with proof-maps, and build offline dashboards, all without auto-submitting.
    Apache 2.0

  • jobstack-mcp

    IsaiahDupree
    F
    license
    Not graded
    quality
    C
    maintenance
    Enables searching and retrieving job postings from multiple job boards (USAJOBS, Adzuna, Jooble, The Muse, Reed, and ATS) through the JobStack API, exposing search_jobs and get_job as MCP tools.
    -

  • jobfinder-mcp

    juanzjck
    F
    license
    A
    quality
    C
    maintenance
    Enables searching job listings, tracking applications, managing resumes, and tailoring resumes to job posts, all locally via MCP.
    20
    -