A
licenseNot graded
qualityC
maintenanceSearches 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
freehire
by strelov1
freehire MCP servidor
Un servidor MCP sobre la API de empleos de freehire. Permite que cualquier host MCP — Claude Desktop, Claude Code o un agente compatible — busque, filtre y postule a empleos de TI sin navegador, autenticándose con una clave API personal. Las ofertas se extraen directamente de los portales de empleo de las empresas: más de 3,3 millones de puestos abiertos en 294 000 empresas, normalizados en un único esquema y etiquetados con stack, seniority, región y modalidad de trabajo (cifras en vivo).
Refleja el CLI de freehire: misma API, mismas credenciales, expuesto como herramientas MCP en lugar de comandos de shell.
Instalación
No se necesita instalación global: el host lo ejecuta mediante npx. Añádelo a la configuración MCP de tu host (Claude Desktop → Configuración → Desarrollador → Editar configuración, o ~/.claude.json para Claude Code):
{
"mcpServers": {
"freehire": {
"command": "npx",
"args": ["-y", "freehire-mcp"],
"env": { "FREEHIRE_TOKEN": "fhk_xxxxxxxx" }
}
}
}Crea la clave fhk_… en la aplicación web (freehire.me → menú de cuenta → Claves API). Si ya usas el CLI de freehire (freehire auth login), puedes omitir env — el servidor lee el mismo ~/.freehire/creds.json.
Related MCP server: jobfinder-mcp
Autenticación
El token y la URL base de la API se resuelven con precedencia env → ~/.freehire/creds.json → predeterminado https://freehire.me:
Qué | Fuentes |
Token |
|
URL base de la API |
|
El servidor solo lee el archivo de credenciales (nunca lo escribe; iniciar sesión sigue siendo tarea del CLI). Si no se configura ningún token, las herramientas devuelven un error claro de "no autenticado" en lugar de que el servidor falle al iniciar.
Herramientas
Herramienta | Propósito |
| Usuario autenticado (verifica la clave). |
| El vocabulario de filtros/habilidades: valores en vivo de cada faceta con recuentos. Llama primero. |
| Búsqueda de empleos por palabra clave + facetas; devuelve empleos con su descripción completa en markdown y el total de coincidencias. |
| Evalúa una lista de habilidades contra la demanda del mercado en vivo (cobertura + brechas). |
| Contenido completo de un empleo por slug. |
| Una empresa y sus empleos abiertos por slug. |
| Marca un empleo como postulado. |
| Marcar / quitar marcador. |
| Establece la etapa de postulación (validado por el servidor). |
| Adjunta una nota de texto libre. |
| Empleos de seguimiento del llamante (todos/vistos/guardados/postulados) con etapa + nota. |
| Inicia (o reabre) el ajuste para una vacante; devuelve el id de CV que usan las otras herramientas |
| CVs personalizados del llamante con la vacante para la que se escribieron. |
| El análisis de contexto que un CV debe reencuadrar (missing_have vs missing_gap). |
| Documento completo de un CV personalizado. |
| Aplica un lote de ediciones direccionadas por ruta a un CV personalizado, atómicamente (validado por el servidor; las afirmaciones sin citar se rechazan). |
| Renderiza un CV personalizado a PDF, devuelto como recurso |
| El banco de experiencia del candidato, con la procedencia de cada logro. El |
| Registra un lugar o una pieza de evidencia. |
| Corrige uno. A nivel de campo: lo que no se nombra se conserva. |
| Elimina uno. Sin deshacer; un lugar debe estar vacío primero. |
| Envía una vacante para moderación. |
| Las presentaciones del llamante con estado. |
| Moderador: crear o editar un empleo (403 sin el rol). |
| Moderador: la cola de revisión. |
| Moderador: decide sobre una presentación. |
Filtros. search, market_fit y facets comparten los mismos parámetros de filtro de mercado: remote, region, country, city, company, category, role, seniority, employment_type, english_level, exclude_skill, salary_min, visa, más un mapa facets genérico ({"source": "greenhouse"}) para cualquier otra faceta del vocabulario. Descubre los valores válidos con la herramienta facets — no los inventes. En search, skills es un filtro; en market_fit, skills es el conjunto medido.
La geografía amplía. region, country y city son un grupo OR: region: ["eu"] con country: ["IT"] significa "en Europa o en Italia" y devuelve todo lo que la región sola devolvería. Para buscar un solo país, pasa country y omite region. Los tres nombran un único concepto — dónde — por lo que elegir dos lugares se lee como "o", lo que hace útil region: ["eu"] con country: ["BR"] ("Europa o Brasil"). No hay AND que activar: _mode=and no se aplica a la geografía.
Los parámetros no reconocidos se ignoran, no se rechazan. Una clave de filtro que la API no reconoce no hace fallar la solicitud, la amplía. Estas claves aparecen en la lista ignored del resultado, con did_you_mean cuando solo el número gramatical era incorrecto. search lo informa junto a total; facets y market_fit responden un único objeto, por lo que lo envuelven como {data, ignored} — y solo entonces, dejando intacta la forma de una llamada limpia. Cualquier número de un resultado que contenga ignored responde a una pregunta más amplia que la planteada — reintenta con el nombre sugerido antes de informarlo.
Descripciones. search lee el endpoint de agente de la API, por lo que cada resultado ya incluye la descripción completa de la oferta como markdown — un host puede revisar un conjunto de resultados sin una llamada job por cada uno. Las descripciones son largas, así que mantén limit moderado.
La regla de evidencia. Cada logro en el banco registra quién lo afirmó. cv_import, stated_in_chat y manual significan que el candidato lo hizo, y pueden citarse en un CV; agent_inferred significa que un modelo lo leyó en el registro, y no puede. cv_edit rechaza cualquier afirmación sobre el candidato sin un evidence_id que apunte a uno citable, por lo que experience_list es la herramienta que hace que cv_edit sea utilizable.
Corregir un logro no cambia esa etiqueta: uno agent_inferred permanece no citable aunque se reformule. La única forma de que sea citable es preguntar al candidato y luego registrar lo que él diga con experience_add_achievement.
Eliminar es definitivo — el banco no tiene deshacer. Un lugar debe vaciarse antes de poder eliminarse, porque eliminarlo llevaría todos los logros que contiene. Fusionar dos logros en uno, conservando los números de ambos, se hace en el sitio.
Cada herramienta devuelve los data crudos de la API como texto JSON; un error de la API se convierte en un resultado isError que lleva el estado HTTP (un 401 añade una pista de autenticación).
Desarrollo
npm install
npm test # vitest: config, client (mock server), facets, tool dispatch
npm run build # tsc → dist/Licencia
MIT — ver LICENSE. El backend y el CLI de freehire también son MIT.
Available Tools
19 toolsapplyBIdempotent
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.
companyARead-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.
facetsARead-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 | Default |
|---|---|---|---|
| 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.
jobARead-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_addAIdempotent
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 | Default |
|---|---|---|---|
| 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_editAIdempotent
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 | Default |
|---|---|---|---|
| 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_fitARead-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 | Default |
|---|---|---|---|
| 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.
myARead-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_submissionsARead-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.
noteAIdempotent
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.
saveAIdempotent
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.
searchARead-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 | Default |
|---|---|---|---|
| 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.
stageAIdempotent
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_pendingARead-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 | Default |
|---|---|---|---|
| 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.
unsaveAIdempotent
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.
whoamiARead-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 updates
v0.1.0- First observed
apply - First observed
company - First observed
facets - First observed
job - First observed
jobs_add - First observed
jobs_edit - First observed
market_fit - First observed
my - First observed
my_submissions - First observed
note - First observed
save - First observed
search - First observed
stage - First observed
submission_approve - First observed
submission_reject - First observed
submissions_pending - First observed
submit - First observed
unsave - First observed
whoami
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
ActivitySlowing
ResponsivenessNo issues
Related MCP Connectors
Public MCP server for discovering open jobs. Search, filter, and get application links.
Job search over employers' own hiring systems. Search with no key; a free key opens every read tool.
Search live startup jobs from Claude, Cursor, or ChatGPT via MCP. Free, no account needed.
A job-search companion: tailor your CV to a role, score fit, fix ATS issues. Also via MCP.
Related MCP Servers
- FlicenseAqualityCmaintenanceEnables searching job listings, tracking applications, managing resumes, and tailoring resumes to job posts, all locally via MCP.620-
- FlicenseAqualityBmaintenanceEnables searching and retrieving job listings from multiple platforms through MCP.2-
- AlicenseNot gradedqualityCmaintenanceEnables 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.MIT