hh-mcp

get_resumes

Fetch up to 50 hh.ru resumes sequentially with built-in rate limiting, scoped by resume and topic IDs, and optionally persist results to disk.

Instructions

Safely fetch up to 50 resumes sequentially through the resume-view budget (default ~1.5s spacing, 20 reads/60s window). Preferred input: items:[{resume_id, topic_id}] + vacancy_id for scoped reads; set require_topic:true to never read the paid database. Legacy resume_ids+topics is validated (typo'd keys fail before any request). Reads without topic_id return status unscoped. Pass out_dir to persist payloads (raw/*.json + manifest.json + negotiations.csv). stop_on_captcha default true. max_wait_ms default 90000 (cap 110000). Requires HH_ACCESS_TOKEN.

Input Schema

Name	Required	Description
`raw`	No	Return structured JSON instead of the compact Russian summary.
`items`	No	Preferred input: [{resume_id, topic_id, vacancy_id?}] (1..50). Keeps each resume with its negotiation id so a typo cannot silently turn into a paid unscoped read. Do not combine with resume_ids/topics.
`topics`	No	Legacy: map resume_id → topic_id. Every key must be one of resume_ids, otherwise the call fails before any request.
`out_dir`	No	Persist payloads to <out_dir>/raw/<resume_id>__<topic_id>.json plus manifest.json and negotiations.csv. Existing valid files are reused without a network read.
`no_cache`	No
`resume_ids`	No	Legacy input: resume ids to fetch (1..50). Prefer items.
`vacancy_id`	No	Vacancy id applied with each topic_id
`max_wait_ms`	No	Stop starting new gated reads after this many ms (hard-capped at 110000; DSH timeout is 120s). At default 1.5s spacing ≈55 resumes/call.
`require_topic`	No	Never read without topic_id: rows lacking one are returned as skipped with no network call. Recommended true.
`stop_on_captcha`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed12 schema fields changedv3.0.0Oct 1, 2026

addedInput schema / properties / items

Added value: +{
+  "description": "Preferred input: [{resume_id, topic_id, vacancy_id?}] (1..50). Keeps each resume with its negotiation id so a typo cannot silently turn into a paid unscoped read. Do not combine with resume_ids/topics.",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "resume_id": {
+        "pattern": "^[a-zA-Z0-9_-]+$",
+        "type": "string"
+      },
+      "topic_id": {
+        "description": "Negotiation (отклик) id for a scoped read",
+        "pattern": "^\\d+$",
+        "type": "string"
+      },
+      "vacancy_id": {
+        "$ref": "#/properties/items/items/properties/topic_id",
+        "description": "Overrides the top-level vacancy_id"
+      }
+    },
+    "required": [
+      "resume_id"
+    ],
+    "type": "object"
+  },
+  "maxItems": 50,
+  "minItems": 1,
+  "type": "array"
+}

addedInput schema / properties / out_dir

Added value: +{
+  "description": "Persist payloads to <out_dir>/raw/<resume_id>__<topic_id>.json plus manifest.json and negotiations.csv. Existing valid files are reused without a network read.",
+  "type": "string"
+}

addedInput schema / properties / require_topic

Added value: +{
+  "default": false,
+  "description": "Never read without topic_id: rows lacking one are returned as skipped with no network call. Recommended true.",
+  "type": "boolean"
+}

changedInput schema / properties / resume_ids / description

Previous value: -"Resume ids to fetch (1..50)"New value: +"Legacy input: resume ids to fetch (1..50). Prefer items."

addedInput schema / properties / resume_ids / items / $ref

Added value: +"#/properties/items/items/properties/resume_id"

removedInput schema / properties / resume_ids / items / pattern
```
Removed value: -"^[a-zA-Z0-9_-]+$"
```
removedInput schema / properties / resume_ids / items / type
```
Removed value: -"string"
```

changedInput schema / properties / topics / description

Previous value: -"Optional map resume_id → topic_id (negotiation id)"New value: +"Legacy: map resume_id → topic_id. Every key must be one of resume_ids, otherwise the call fails before any request."

addedInput schema / properties / vacancy_id / $ref

Added value: +"#/properties/items/items/properties/topic_id"

removedInput schema / properties / vacancy_id / pattern
```
Removed value: -"^\\d+$"
```
removedInput schema / properties / vacancy_id / type
```
Removed value: -"string"
```
removedInput schema / required
```
Removed value: -[
-  "resume_ids"
-]
```

Addedv2.2.4Sep 25, 2026

TDQS

A4.5/5.0

Behavior5/5

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

With no annotations, the description carries the full burden and delivers: rate-limit spacing (~1.5s), the 20 reads/60s window, stop_on_captcha default, max_wait_ms default and hard cap, the HH_ACCESS_TOKEN requirement, and out_dir caching semantics (existing valid files reused without a network read). It also discloses validation behavior (typo'd keys fail before any request) and that reads without topic_id return unscoped status.

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?

Dense and front-loaded: the scope and budget constraint lead, then input guidance, then defaults. The parenthetical-heavy style packs a lot per sentence, but every clause carries operational information rather than filler.

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 10-parameter, nested-object tool with no annotations and no output schema, the description covers auth, rate limits, input preference, persistence, and failure semantics. Minor gaps remain around the exact return shape (raw JSON vs compact Russian summary is only in the schema) and what a 'skipped' row looks like, but the agent has enough to call it correctly.

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 already 80%, so the baseline is 3; the description goes further by stating the preferred/legacy distinction, the require_topic guard behavior, out_dir output artifacts, and the max_wait_ms cap rationale (≈55 resumes at default spacing). It leaves raw and no_cache largely to 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?

States a precise verb and resource ('fetch up to 50 resumes') plus the defining constraint (sequential, budget-gated), which cleanly separates it from sibling get_resume (single) and search_resumes (discovery). An agent can tell what this tool uniquely does without opening the schema.

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 names the preferred input shape (items + vacancy_id) versus the legacy resume_ids+topics path, and recommends require_topic:true to avoid paid reads. It stops short of saying when to choose this over get_resume or search_resumes for a given task, so it is clear but not fully routing.

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

Deploy Server

get_resumes

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools