de en es ko ru zh

freehire

Name: freehire
Author: strelov1

by strelov1

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

freehire MCP server

Ein MCP-Server über die freehire-Job-API. Er ermöglicht jedem MCP-Host – Claude Desktop, Claude Code oder einem kompatiblen Agenten – IT-Jobs zu suchen, zu filtern und sich zu bewerben, ohne Browser, mit Authentifizierung über einen persönlichen API-Schlüssel. Stellenausschreibungen werden direkt von den Karriereseiten der Unternehmen gecrawlt – 3.3M+ offene Rollen bei 294K Unternehmen, normalisiert in ein Schema und getaggt mit Stack, Seniorität, Region und Arbeitsmodell (Live-Zahlen).

Er spiegelt die freehire-CLI: gleiche API, gleiche Anmeldedaten, bereitgestellt als MCP-Tools statt Shell-Befehle.

Install

Keine globale Installation nötig – der Host führt es über npx aus. Fügen Sie es zur MCP-Konfiguration Ihres Hosts hinzu (Claude Desktop → Einstellungen → Entwickler → Konfiguration bearbeiten oder ~/.claude.json für Claude Code):

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

Erstellen Sie den fhk_…-Schlüssel in der Web-App (freehire.me → Kontomenü → API-Schlüssel). Wenn Sie bereits die freehire-CLI verwenden (freehire auth login), können Sie env weglassen – der Server liest dieselbe ~/.freehire/creds.json.

Related MCP server: jobfinder-mcp

Authentication

Das Token und die API-Basis-URL werden mit folgender Priorität aufgelöst: env → ~/.freehire/creds.json → Standard https://freehire.me:

Was	Quellen
Token	`FREEHIRE_TOKEN` → Creds-Datei
API-Basis-URL	`FREEHIRE_API_URL` → Creds-Datei → `https://freehire.me`

Der Server liest nur die Credentials-Datei (er schreibt sie nie – das Einloggen bleibt Aufgabe der CLI). Wenn kein Token konfiguriert ist, geben die Tools einen klaren „nicht authentifiziert“-Fehler zurück, anstatt dass der Server nicht startet.

Tools

Tool	Zweck
`whoami`	Authentifizierter Benutzer (Schlüssel verifizieren).
`facets`	Das Filter-/Skill-Vokabular: Live-Werte jedes Facets mit Zählern. Zuerst aufrufen.
`search`	Keyword- + Facet-Jobsuche; gibt Jobs mit ihrer vollständigen Beschreibung als Markdown und die Gesamtzahl der Treffer zurück.
`market_fit`	Bewertet eine Skill-Liste anhand der Live-Marktnachfrage (Abdeckung + Lücken).
`job`	Vollständiger Inhalt eines einzelnen Jobs per Slug.
`company`	Ein Unternehmen und seine offenen Jobs per Slug.
`apply`	Job als beworben markieren.
`save` / `unsave`	Lesezeichen setzen / entfernen.
`stage`	Bewerbungsphase setzen (servervalidiert).
`note`	Freitext-Notiz anhängen.
`my`	Die verfolgten Jobs des Aufrufers (alle/gesehen/gespeichert/beworben) mit Phase + Notiz.
`cv_tailor`	Tailoring für eine Stelle starten (oder wieder öffnen); gibt die CV-ID zurück, die die anderen `cv_*`-Tools erwarten.
`cv_list`	Die maßgeschneiderten CVs des Aufrufers mit der jeweiligen Stelle, für die sie erstellt wurden.
`cv_context`	Die Fit-Analyse, auf die ein maßgeschneiderter CV ausgerichtet werden sollte (missing_have vs. missing_gap).
`cv_get`	Das vollständige Dokument eines maßgeschneiderten CVs.
`cv_edit`	Eine Reihe von pfadadressierten Änderungen an einem maßgeschneiderten CV atomar anwenden (servervalidiert; nicht belegte Behauptungen werden abgelehnt).
`cv_render`	Maßgeschneiderten CV als PDF rendern, zurückgegeben als base64-`application/pdf`-Ressource.
`experience_list`	Die Erfahrungsbank des Kandidaten, mit der Herkunft jeder Leistung. `cv_edit`'s `evidence_id` stammt von hier.
`experience_add_employment` / `experience_add_achievement`	Einen Arbeitsplatz oder ein Beweisstück erfassen.
`experience_update_employment` / `experience_update_achievement`	Einen korrigieren. Feldgenau: Was Sie nicht nennen, bleibt erhalten.
`experience_remove_employment` / `experience_remove_achievement`	Einen löschen. Kein Rückgängig; ein Arbeitsplatz muss zuerst leer sein.
`submit`	Eine Stelle zur Moderation einreichen.
`my_submissions`	Die Einreichungen des Aufrufers mit Status.
`jobs_add` / `jobs_edit`	Moderator: Job erstellen / bearbeiten (403 ohne Rolle).
`submissions_pending`	Moderator: die Überprüfungswarteschlange.
`submission_approve` / `submission_reject`	Moderator: über eine Einreichung entscheiden.

Filter. search, market_fit und facets teilen sich dieselben Marktfilter-Parameter: remote, region, country, city, company, category, role, seniority, employment_type, english_level, exclude_skill, salary_min, visa, plus eine generische facets-Map ({"source": "greenhouse"}) für jedes andere Facet im Vokabular. Entdecken Sie gültige Werte mit dem facets-Tool – erfinden Sie sie nicht. In search ist skills ein Filter; in market_fit ist skills die gemessene Menge.

Geografie erweitert. region, country und city sind eine ODER-Gruppe: region: ["eu"] mit country: ["IT"] bedeutet „in Europa oder in Italien“ und gibt alles zurück, was die Region allein auch tun würde. Um ein einzelnes Land zu suchen, übergeben Sie country und lassen region weg. Die drei benennen ein einziges Konzept – wo –, daher liest sich die Auswahl von zwei Orten als „entweder“, was region: ["eu"] mit country: ["BR"] („Europa oder Brasilien“) nützlich macht. Es gibt kein UND zum Einschalten: _mode=and gilt nicht für Geografie.

Unbekannte Parameter werden ignoriert, nicht abgelehnt. Ein Filter-Schlüssel, den die API nicht erkennt, lässt die Anfrage nicht fehlschlagen, sondern erweitert sie. Solche Schlüssel erscheinen in der ignored-Liste des Ergebnisses, mit did_you_mean, wenn nur die grammatische Zahl falsch war. search meldet es zusammen mit total; facets und market_fit antworten mit einem einzelnen Objekt, also verpacken sie es als {data, ignored} – und nur dann, sodass die Form eines sauberen Aufrufs unberührt bleibt. Jede Zahl aus einem Ergebnis mit ignored beantwortet eine breitere Frage als die gestellte – wiederholen Sie den Versuch mit dem vorgeschlagenen Namen, bevor Sie es melden.

Beschreibungen. search liest den Agent-Endpunkt der API, sodass jeder Treffer bereits die vollständige Beschreibung der Stelle als Markdown enthält – ein Host kann eine Ergebnismenge prüfen, ohne pro Treffer einen job-Aufruf zu machen. Beschreibungen sind lang, also halten Sie limit bescheiden.

Die Beweisregel. Jede Leistung in der Bank protokolliert, wer sie behauptet hat. cv_import, stated_in_chat und manual bedeuten, dass der Kandidat es getan hat, und dürfen in einem CV zitiert werden; agent_inferred bedeutet, dass ein Modell es in den Datensatz gelesen hat, und darf nicht zitiert werden. cv_edit lehnt jede Behauptung über den Kandidaten ohne eine evidence_id ab, die auf eine zitierbare verweist – deshalb ist experience_list das Tool, das cv_edit überhaupt erst nutzbar macht.

Das Korrigieren einer Leistung verschiebt dieses Label nicht: Eine agent_inferred-Leistung bleibt unzitierbar, egal wie sie umformuliert wird. Der einzige Weg, sie zitierbar zu machen, ist, den Kandidaten zu fragen und dann aufzuzeichnen, was sie sagen, mit experience_add_achievement.

Entfernen ist endgültig – die Bank hat kein Rückgängig. Ein Arbeitsplatz muss geleert werden, bevor er gelöscht werden kann, denn das Löschen würde jede darunter liegende Leistung mitnehmen. Das Zusammenführen zweier Leistungen zu einer, unter Beibehaltung der Zahlen beider, erfolgt auf der Website.

Jedes Tool gibt die rohen API-data als JSON-Text zurück; ein API-Fehler wird zu einem isError-Ergebnis mit dem HTTP-Status (eine 401 fügt einen Auth-Hinweis hinzu).

Develop

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

License

MIT – siehe LICENSE. Das freehire-Backend und die CLI sind ebenfalls MIT.

Available Tools

19 tools

applyB

Idempotent

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

ParametersJSON Schema

Name	Required	Description	Default
`slug`	Yes	The 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

Name	Required	Description	Default
`slug`	Yes	The 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

Name	Required	Description
`city`	No	City slugs.
`role`	No	Role facet values, e.g. senior_backend.
`visa`	No	Only jobs offering visa sponsorship.
`facets`	No	Any other facet param as key→value(s), e.g. {"source": "greenhouse"}. Discover valid keys and values with the `facets` tool.
`region`	No	Region codes (OR within): global\|ru\|cis\|central_asia\|eu\|us.
`remote`	No	Only remote jobs (sets work_mode=remote).
`company`	No	Company slugs.
`country`	No	ISO-3166 country codes, e.g. BR, US.
`category`	No	Role categories: backend\|frontend\|fullstack\|devops\|ml_ai\|qa\|...
`seniority`	No	Seniority: intern\|junior\|middle\|senior\|staff\|principal\|lead\|c_level.
`salary_min`	No	Minimum salary (enrichment.salary_min).
`english_level`	No	English level, e.g. a2, b1, b2, c1.
`employment_type`	No	Employment 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

Name	Required	Description	Default
`slug`	Yes	The 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

Name	Required	Description
`url`	Yes	The posting URL — the dedup key. Required.
`title`	Yes	Job title. Required.
`remote`	No
`source`	No	The posting's real origin (defaults to 'manual' server-side).
`company`	Yes	Company name. Required.
`location`	No
`posted_at`	No	RFC3339 timestamp.
`description`	No	Stored 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

Name	Required	Description
`slug`	Yes	The job's public slug (from search or facets results).
`title`	No
`remote`	No
`company`	No
`location`	No
`posted_at`	No	RFC3339 timestamp.
`description`	No	Stored 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

Name	Required	Description
`city`	No	City slugs.
`role`	No	Role facet values, e.g. senior_backend.
`visa`	No	Only jobs offering visa sponsorship.
`facets`	No	Any other facet param as key→value(s), e.g. {"source": "greenhouse"}. Discover valid keys and values with the `facets` tool.
`region`	No	Region codes (OR within): global\|ru\|cis\|central_asia\|eu\|us.
`remote`	No	Only remote jobs (sets work_mode=remote).
`skills`	Yes	The candidate's skills to measure (canonical slugs). One value probes a single skill.
`company`	No	Company slugs.
`country`	No	ISO-3166 country codes, e.g. BR, US.
`category`	No	Role categories: backend\|frontend\|fullstack\|devops\|ml_ai\|qa\|...
`seniority`	No	Seniority: intern\|junior\|middle\|senior\|staff\|principal\|lead\|c_level.
`salary_min`	No	Minimum salary (enrichment.salary_min).
`english_level`	No	English level, e.g. a2, b1, b2, c1.
`employment_type`	No	Employment 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

Name	Required	Description	Default
`limit`	No
`filter`	No	Which tracked jobs to list.	all
`offset`	No

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

Name	Required	Description	Default
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

Name	Required	Description	Default
`note`	Yes	Free-text note to store on the job.
`slug`	Yes	The 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

Name	Required	Description	Default
`slug`	Yes	The 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.

searchA

Read-only

Search open jobs by keyword with optional facet filters. Returns matching jobs (title, company, location, public_slug) and the total match count. Use the returned slug with job, apply, save, etc.

ParametersJSON Schema

Name	Required	Description
`city`	No	City slugs.
`role`	No	Role facet values, e.g. senior_backend.
`visa`	No	Only jobs offering visa sponsorship.
`limit`	No	Max results to return.
`query`	Yes	Keyword query, e.g. 'golang backend'. Empty string matches all.
`facets`	No	Any other facet param as key→value(s), e.g. {"source": "greenhouse"}. Discover valid keys and values with the `facets` tool.
`offset`	No	Pagination offset.
`region`	No	Region codes (OR within): global\|ru\|cis\|central_asia\|eu\|us.
`remote`	No	Only remote jobs (sets work_mode=remote).
`skills`	No	Filter to jobs listing these skills (canonical slugs from the `facets` tool).
`company`	No	Company slugs.
`country`	No	ISO-3166 country codes, e.g. BR, US.
`category`	No	Role categories: backend\|frontend\|fullstack\|devops\|ml_ai\|qa\|...
`seniority`	No	Seniority: intern\|junior\|middle\|senior\|staff\|principal\|lead\|c_level.
`salary_min`	No	Minimum salary (enrichment.salary_min).
`english_level`	No	English level, e.g. a2, b1, b2, c1.
`employment_type`	No	Employment 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 adds context beyond the readOnlyHint annotation by specifying that it returns open jobs, the fields returned (title, company, location, public_slug), and the total match count. It does not contradict annotations and provides useful behavioral details.

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 main purpose, and contains no redundant information. Every sentence adds value.

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 (17 parameters, no output schema), the description covers the core functionality, return value, and integration with siblings. It does not explicitly mention pagination (limit/offset) but the schema covers that. Overall, it is fairly complete.

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 value by explaining how to use the returned slug and directing users to the `facets` tool for the `facets` parameter. This enhances understanding of parameter usage.

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 'Search', the resource 'open jobs', and what is returned (matching jobs with specific fields and total count). It also differentiates from sibling tools by explaining how the returned slug is used with other tools like `job`, `apply`, `save`.

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 provides context on when to use the tool (searching open jobs) and hints at using the returned slug with other tools. It also directs users to the `facets` tool for discovering valid facet values. However, it does not explicitly state when not to use this tool or compare to alternatives.

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

Name	Required	Description	Default
`slug`	Yes	The job's public slug (from search or facets results).
`stage`	Yes	Application 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

Name	Required	Description	Default
`id`	Yes	The 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

Name	Required	Description	Default
`id`	Yes	The submission id.
`reason`	No	Optional 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

Name	Required	Description	Default
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

Name	Required	Description
`url`	Yes	The posting URL — the dedup key. Required.
`title`	Yes	Job title. Required.
`remote`	No
`source`	No	The posting's real origin (defaults to 'manual' server-side).
`company`	Yes	Company name. Required.
`location`	No
`posted_at`	No	RFC3339 timestamp.
`description`	No	Stored 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

Name	Required	Description	Default
`slug`	Yes	The 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

Name	Required	Description	Default
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.

19 tool updatesv0.1.0Jul 11, 2026
- 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

Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

A3.8/5.0

Scored 2026-07-11 20:00 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

ActivitySlowing

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

nü people Job Server A
io.github.nu-people
Public MCP server for discovering open jobs. Search, filter, and get application links.
Search
52
Resume Booster Job Board A
work.resumebooster
Job search over employers' own hiring systems. Search with no key; a free key opens every read tool.
Search
151
Startup Jobs A
io.github.killbridge
Search live startup jobs from Claude, Cursor, or ChatGPT via MCP. Free, no account needed.
Search
81
nextrole A
io.github.hyperdrift-io
A job-search companion: tailor your CV to a role, score fit, fix ATS issues. Also via MCP.
Search Workplace & Productivity
52

Related MCP Servers

job-monitor
Search Web Scraping
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.
Updated 17 days ago (2026-09-22 23:45 UTC)
MIT
jobfinder-mcp
Search
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.
Updated 2 months ago (2026-08-02 18:45 UTC)
6
20
-
Job Board MCP Server
Search
Danialesss
F
license
A
quality
B
maintenance
Enables searching and retrieving job listings from multiple platforms through MCP.
Updated a month ago (2026-09-10 03:59 UTC)
2
-
LANDTHATROLE Jobs
Search
nonitguydoingai
A
license
Not graded
quality
C
maintenance
Enables searching and retrieving tech job listings in the US and Canada from MCP-compatible apps, with tools for job search, full job details, and category browsing.
Updated 16 days ago (2026-09-24 16:13 UTC)
MIT