Skip to main content
Glama
AndreyTepaykin

hh-mcp

by AndreyTepaykin
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

list_applications

Retrieve job applications for a specific vacancy, filtering by collection, sub-collection, or update status. Supports pagination and sorting to manage candidate pipelines.

Instructions

List applications for a vacancy by collection or sub_collection (id/name), with optional with_updates_only (scans collection pages for has_updates; page/per_page are the filtered stream; capped by HH_MAX_SCAN_PAGES), page/per_page/order_by. raw:true returns one unfiltered upstream page. Defaults collection to response. Requires HH_ACCESS_TOKEN.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
rawNoReturn the full raw hh.ru JSON instead of the compact summary.
pageNoPage number (0-based). With with_updates_only, pages the filtered match stream (not a single hh.ru API page).
order_byNoSort order (e.g. created_at, relevance, last_change_time_except_employer_inbox). Use get_preferred_negotiations_order for the vacancy default.
per_pageNoResults per page. With with_updates_only, size of each filtered page (scan uses up to 50 items per upstream request).
collectionNoCollection id or sub-collection id from list_application_collections (e.g. "response", "invited", or "response_107261719"). Defaults to "response" when sub_collection is not set.
vacancy_idYesVacancy ID
sub_collectionNoSub-stage id ("response_107261719"), bare funnel-stage id ("107261719"), or a name / name substring ("Подходят"), case-insensitive; account-specific — see list_application_collections.
with_updates_onlyNoIf true, return only items with has_updates by scanning collection pages (capped by HH_MAX_SCAN_PAGES, default 10). page/per_page apply to the filtered stream. raw:true still returns one unfiltered upstream page.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv2.2.3
    • changedInput schema / properties / page / description
      Previous value: -"Page number (0-based)"New value: +"Page number (0-based). With with_updates_only, pages the filtered match stream (not a single hh.ru API page)."
    • changedInput schema / properties / per_page / description
      Previous value: -"Results per page"New value: +"Results per page. With with_updates_only, size of each filtered page (scan uses up to 50 items per upstream request)."
    • changedInput schema / properties / with_updates_only / description
      Previous value: -"If true, keep only items with has_updates after fetch. Header shows filtered/total split."New value: +"If true, return only items with has_updates by scanning collection pages (capped by HH_MAX_SCAN_PAGES, default 10). page/per_page apply to the filtered stream. raw:true still returns one unfiltered upstream page."
  2. Changed4 schema fields changedv2.2.2
    • changedInput schema / properties / collection / description
      Previous value: -"Collection id from list_application_collections (e.g. response, invited)"New value: +"Collection id or sub-collection id from list_application_collections (e.g. \"response\", \"invited\", or \"response_107261719\"). Defaults to \"response\" when sub_collection is not set."
    • addedInput schema / properties / sub_collection
      Added value: +{
+  "description": "Sub-stage id (\"response_107261719\"), bare funnel-stage id (\"107261719\"), or a name / name substring (\"Подходят\"), case-insensitive; account-specific — see list_application_collections.",
+  "type": "string"
+}
    • addedInput schema / properties / with_updates_only
      Added value: +{
+  "default": false,
+  "description": "If true, keep only items with has_updates after fetch. Header shows filtered/total split.",
+  "type": "boolean"
+}
    • changedInput schema / required
      Previous value: -[
-  "collection",
-  "vacancy_id"
-]New value: +[
+  "vacancy_id"
+]
  3. First observedv2.2.0

TDQS

A4.1/5.0
Behavior4/5

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

With no annotations, the description carries the full burden. It transparently discloses key behavioral traits: the scanning and capping behavior of with_updates_only (HH_MAX_SCAN_PAGES), that page/per_page apply to the filtered stream, that raw:true returns one unfiltered upstream page, and the default collection. It does not cover error handling or output format of the compact summary, but the disclosed traits are the most operationally important.

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 dense but efficient, covering the main purpose, key options, default behavior, and requirement in two sentences. It front-loads the core action and then details modifiers. It is not verbose, though a slight paragraph break could improve readability.

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 tool with 8 parameters, no output schema, and no annotations, the description covers the critical operational details: the filtering, pagination, raw mode, defaults, and the access token requirement. It omits the compact summary's output shape, but that is inferable from the raw mode description and the parameter semantics. Given the complexity, this is nearly 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 coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining how with_updates_only interacts with pagination (filtered stream), what raw:true returns, how sub_collection matching works (id/name, case-insensitive), and the default for collection. This adds genuine value for correct invocation.

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 applications for a vacancy') and the primary dimensions (collection or sub_collection, id/name), which immediately distinguishes it from single-application tools like get_application or collection-listing tools like list_application_collections. It is specific and unambiguous.

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

Usage Guidelines3/5

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

The description implies when to use the tool (listing applications) but does not explicitly contrast it with alternatives such as get_application for single records or list_application_collections for discovering collection ids. It mentions a default behavior ('Defaults collection to response') and a requirement (HH_ACCESS_TOKEN) but gives no explicit when-not-to-use guidance.

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

Deploy Server

Other Tools