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

With no annotations, the description carries the full burden and does so well. It discloses filesystem side effects (writes raw JSON + manifest/csv under out_dir), authentication needs (HH_ACCESS_TOKEN), rate-limit/budget behavior (gated budget, max_wait_ms), pagination (cursor/remaining when truncated), and batching constraints (max). This is substantial behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Three dense sentences with no filler. The first sentence states the core workflow and outputs, the second adds constraints and return behavior, and the third gives usage preference and auth requirement. Every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex tool with no output schema, the description covers the essential workflow, outputs, constraints, pagination, and auth. It leaves some details vague, such as what 'gated budget' means precisely, how stop_on_captcha behaves, and the full return shape beyond cursor/remaining, but it is still sufficiently complete for an agent to use the tool correctly in most cases.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is high (89%), so the baseline is already 3. The tool description mentions max, max_wait_ms, and out_dir by name but adds little semantic value beyond what the schema already provides. It introduces topic_id contextually, but that is not a schema parameter, so it does not meaningfully enhance parameter understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific action and resource: walking a vacancy funnel and fetching each resume, then writing outputs. It clearly distinguishes itself from siblings by describing a batch collection/export workflow rather than a simple get or search, and even notes it should be preferred over subagent spawning.

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

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

The description provides explicit guidance by saying 'Prefer this over spawning subagents,' which tells the agent when this tool is the right choice. It does not enumerate alternative sibling tools or exclusion cases, but the context is clear enough for a batch resume collection task.

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

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

No annotations are provided, so the description must carry the full behavioral burden. It discloses the token requirement and implies a read-only operation by listing return contents, but it doesn't explicitly state that the default response is a compact summary (though the raw parameter implies this) nor does it mention pagination, rate limits, or error behavior. For a read tool this is acceptable but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is a single, well-structured sentence that leads with the tool's purpose, then the key differentiator, then the token requirement. There is zero redundancy and every phrase contributes value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Without an output schema, the description adequately summarizes the return payload (candidate, relevant experience, funnel stage, message counters). It also covers the token prerequisite and hints at the raw option. While it doesn't describe the compact vs. raw distinction in the description itself, the schema covers that. For a two-parameter read tool, this is reasonably complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for both parameters (id and raw). The description itself adds minimal extra meaning beyond the schema; it mentions 'message counters' and other card contents, but these are not parameter-level semantics. Since the schema already documents each parameter fully, the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns a 'Full application card' from the negotiations endpoint and enumerates the contents (candidate, relevant experience, funnel stage, message counters). It also explicitly distinguishes itself from get_resume for screening, making it easy for an agent to know exactly what this tool does.

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

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

The description explicitly says 'prefer over get_resume for screening', giving a direct alternative and the context for choosing this tool. It also notes the required token. However, it doesn't state when not to use it (e.g., when only messages are needed) or mention other sibling tools like get_application_messages, so it's not exhaustive but adequate.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose pagination behavior, the 50-item cap, and the HH_ACCESS_TOKEN requirement. It does not explicitly state that this is a read-only operation, describe error behavior, rate limits, or the response format, so coverage is partial.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Two short sentences that front-load the core purpose and include the essential pagination and auth details. There is no filler, and every part of the description contributes useful information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple paginated list endpoint with fully documented parameters and no output schema, the description provides purpose, scope, pagination, and auth. It leaves out the return format (compact vs raw) and does not relate this tool to get_application, though the schema's raw parameter partially covers the return format.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all four parameters are fully documented in the schema. The description adds no new parameter semantics beyond restating page/per_page and the 50 cap, which is already present in the schema's maximum constraint.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the resource as 'chat messages' scoped to an application topic, which distinguishes it from sibling tools like get_application and get_message_template. It lacks an explicit verb, but the tool name 'get' supplies that action, so the purpose is clear.

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

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

The phrase 'for an application topic' implies this tool is used when retrieving messages associated with an application, and the auth requirement provides a useful prerequisite. However, it does not mention any alternatives or when-not conditions, so usage guidance is implied rather than explicit.

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

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

No annotations are provided, so the description must carry the behavioral burden. It does disclose the default output format (compact id — name lines) and the effect of raw:true (nested JSON). However, it does not mention potential size, rate limits, or whether it's a read-only operation. For a simple getter, this is adequate but not thorough.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Two sentences with no redundancy. The first sentence describes the tool's function and output format, the second states the use case. All information is essential and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with a single optional boolean parameter and no output schema, the description is sufficient: it explains the output format and purpose. It does not mention any caveats like large response size or pagination, but this is not critical for a simple list retrieval. The description covers everything needed to call the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema documents the raw parameter fully ('Return the full raw hh.ru JSON instead of the compact id — name listing'). The description's mention ('pass raw:true for nested JSON') adds no new information beyond the schema, so it meets the baseline for high schema coverage but adds no extra semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' with a specific resource ('full tree of regions and cities') and explains the output format ('id — name lines'). It also gives the intended use case ('find area IDs for search filters'), which differentiates it from siblings like get_areas_subtree and suggest_areas.

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

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

The description explicitly states when to use it ('Use to find area IDs for search filters'). However, it does not mention alternatives or explicitly say when not to use this tool, such as when a subtree is needed (get_areas_subtree). The guidance is clear but not comprehensive.

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

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

No annotations are provided, so the description carries the full burden. It mentions performance ('lighter') but provides no behavioral detail beyond purpose: no statement that it is read-only, no description of the response format, no mention of error behavior or limits. For a simple read tool this is minimal, but given the absence of annotations, more disclosure (e.g., that it returns a tree structure, that raw toggles the format) would be expected, even though the raw parameter is covered by the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is a single efficient sentence with no redundancy. It front-loads the purpose, includes a concrete example, and conveys the comparative advantage (lighter) in a compact dash clause. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read tool with two parameters and no output schema, the description is adequate but not complete. It explains what it does and gives an example, but does not explicitly state the relationship to the sibling get_areas (only implies it) or describe the expected return shape (e.g., a nested list of regions/cities). Without annotations, an agent might not know exactly what to expect, though the tool's simplicity mitigates the gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for both parameters (area_id and raw), so the baseline is 3. The description repeats the example (113=Russia) already present in the schema but adds no new meaning or usage guidance beyond that. It does not clarify the effect of raw beyond the schema's 'full raw hh.ru JSON' vs 'compact' wording, so no extra value is contributed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Get') and resource ('regions/cities subtree') tied to a concrete example (area id 113=Russia). It differentiates from the sibling get_areas by explicitly calling out that it is 'lighter than the full /areas tree', which helps an agent select the right tool without opening schemas.

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

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

The description implies the appropriate context: use this when you need a subset of the full area tree, as it is 'lighter than the full /areas tree'. This suggests when to choose this over get_areas, though it does not explicitly state 'use this instead of get_areas when you only need a specific region' or list any exclusions. It is clear enough but not fully explicit.

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

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

No annotations are provided, so the description carries the full burden. It discloses the endpoint and the compact id—name output, but does not mention authentication, rate limits, or the raw=true behavior beyond what the schema already states. Adequate for a simple read-only list, but not deeply transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is a single sentence, front-loaded with the action and output format, and contains no filler or redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with zero required parameters and a fully documented optional parameter, the description fully covers what an agent needs to call it correctly and what the default response shape will be. No output schema is needed here.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the raw parameter is well documented. The description adds context by clarifying the default compact listing, but does not go beyond the schema for parameter semantics. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource: 'List countries' from '/areas/countries'. It also states the output shape ('id — name'), making it distinct from sibling tools like get_areas or get_areas_subtree.

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

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

The intended use is implied: this is the endpoint for a flat list of countries. However, it does not explicitly discuss when to choose this over get_areas, get_areas_subtree, or suggest_areas, nor does it mention any exclusions or prerequisites.

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

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

No annotations are provided, so the description bears the full burden of behavioral disclosure. It indicates the tool is a read operation ('Get') and that it returns a comprehensive set of dictionaries, but it does not disclose details such as whether the response is paginated, large, or includes metadata. Since this is a simple get with no parameters, the transparency is adequate but minimal.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is a single, front-loaded sentence that immediately states the purpose and gives concrete examples. There is no fluff or repetition; every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a no-parameter tool with no output schema, this description is nearly complete. It lists several dictionaries and indicates more are included via 'and more'. The only gap is the vagueness of 'and more'—an agent might wonder what else is in the set—but it is sufficient for calling the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the baseline is 4 as per the rubric. The description adds value by listing what the returned dictionaries include, which is more than the empty schema provides. No parameter explanations are needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' and the resource 'all reference dictionaries', and enumerates specific examples (currencies, employment types, schedules, etc.). It distinguishes itself from the many specific get_* siblings (e.g., get_areas, get_professional_roles) by indicating it returns a comprehensive set of dictionaries in one call.

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

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

There is no explicit guidance on when to use this tool versus the specific dictionary endpoints like get_areas or get_professional_roles. The description implies a bulk fetch, but does not state 'use this for multiple dictionaries; use the specific endpoint if you only need one.' An agent might not know when the combined call is preferable.

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

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

No annotations are provided, so the description must carry the behavioral disclosure burden. It only says 'List districts' and mentions the optional filter, but doesn't disclose pagination, sorting, default scope (all districts vs. top-level), or the effect of the 'raw' parameter. The tool could return a large dataset or have rate limits, none of which are mentioned.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Two short sentences, front-loaded with the action and optional filter, followed by a use-case hint. No waste, but it's slightly terse given the lack of behavioral context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no annotations and no output schema, the description is too sparse. It doesn't explain what happens when area_id is omitted (e.g., returns all districts), nor does it mention any limits or response shape beyond the raw parameter. An agent could invoke it but might be surprised by the default behavior or data volume.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters are already documented in the schema. The description adds only the phrase 'optionally filtered by area_id', which echoes the schema. It doesn't add new meaning about the 'raw' parameter or how the output differs. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists districts with an optional area_id filter, and even notes a use case (address/area fine-tuning). This distinguishes it from siblings like get_areas or get_countries, which operate at different granularity.

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

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

The phrase 'Useful for address/area fine-tuning' provides a clear context for when to use the tool, but it doesn't explicitly mention when not to use it or point to alternative tools for broader area queries. It's clear enough but lacks exclusions.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states what the tool returns and the compact vs. raw distinction is left to the 'raw' parameter schema. It does not mention authentication requirements, error handling, or rate limits. The description is not misleading but offers limited depth beyond the listed fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is a single, front-loaded sentence with zero wasted words. It names the resource and its key output fields compactly, exemplifying optimal conciseness and structure.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read tool with only two parameters and no output schema, the description is sufficiently complete. It lists the key fields returned, enabling an agent to call it correctly. However, it lacks explicit mention of return format details or edge cases, but these are not critical for a straightforward get operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with both parameters ('employer_id' and 'raw') documented in the schema. The tool description adds no additional parameter semantics beyond what the schema already explains. Baseline of 3 is appropriate given complete schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('Get') and resource ('employer profile'), and enumerates the specific fields returned (description, industries, website, vacancy count). This distinguishes it from siblings like search_employers (search) and get_employer_vacancies (vacancies), making the tool's purpose unambiguous.

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

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

The description implies when to use the tool (when a detailed employer profile is needed) but does not explicitly name alternatives or state when not to use it. It provides clear context for selection but lacks direct exclusions or comparisons to sibling tools.

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

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

No annotations are provided, so the description carries the behavioral disclosure burden. It does state the auth requirement (HH_ACCESS_TOKEN) and 'List' implies a read operation with no side effects. However, it does not disclose response format, pagination, error behavior, or the impact of the raw parameter.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is two short sentences with no filler. The primary purpose is front-loaded ('List departments for an employer.') and the auth requirement is stated succinctly. Every word contributes.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter read tool, the description covers core purpose and auth, but it does not explain return values or behavior of the compact summary vs raw output beyond what the schema states. At a minimum it is adequate, but with no annotations or output schema, a bit more context would be expected.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description itself adds little parameter meaning beyond what the schema already provides; 'employer' is present in the tool name, and the schema documents employer_id and raw. No additional semantic value is contributed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific action and resource: 'List departments for an employer.' It is unambiguous and the verb 'List' plus the resource 'departments' makes the core purpose clear. However, it does not explicitly distinguish this from siblings like get_employer_vacancy_areas or list_employer_addresses.

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

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

The description offers no guidance on when to use this tool versus alternatives, no prerequisites beyond the auth token, and no mention of when not to use it. 'Requires HH_ACCESS_TOKEN' is a constraint, not usage guidance. Sibling tools with overlapping employer-scoped concerns are not addressed.

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

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

No annotations are provided, so the description carries the disclosure burden. It does disclose the auth requirement (HH_ACCESS_TOKEN) and 'Get' implies a read-only operation, adding some behavioral context. However, it doesn't describe response behavior, error behavior, or whether the manager must belong to the employer — though for a simple fetch, the disclosed context is minimally adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Two sentences with zero waste: the purpose is front-loaded and the auth requirement is a single necessary addendum. Every word earns its place for a simple single-resource lookup tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple fetch tool with 100% schema coverage and no output schema, the description covers the core need: what the tool retrieves, by what identifiers, and what auth is required. The main gaps are the missing contrast with list_employer_managers and any note about the compact-vs-raw return behavior (though the schema covers the raw flag). It is adequate but not complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%: raw, manager_id, and employer_id all have descriptions in the schema, including the raw param's behavioral note about returning full hh.ru JSON. The description adds no parameter meaning beyond the schema, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Get') and resource ('a single employer manager by id'), which is clear and unambiguous. The qualifier 'single ... by id' implicitly contrasts with the sibling list_employer_managers, though it doesn't name it explicitly, so the differentiation is functional rather than stated.

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

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

The description mentions a precondition (Requires HH_ACCESS_TOKEN) but gives no guidance on when to choose this tool over alternatives. Given the sibling list_employer_managers exists, an explicit note like 'use this for one manager; use list_employer_managers to enumerate' would be needed. No such routing or exclusion guidance is present.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It reveals the operation is a public read operation and that no authentication token is needed, which is not inferable from the schema. It does not mention default return format or pagination specifics, but those are partially covered by the parameter schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Two short sentences with no filler. The core action and scope are front-loaded, and the auth requirement is stated separately and concisely.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read/list tool, the description covers the essential context: public access, no token, employer-specific filter, and active vacancies. Pagination or return shape is not explicitly described, but the schema covers the parameters that control those, so the remaining gap is minor.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the input schema already documents all four parameters. The description only reinforces the employer_id filter and adds no new semantic detail beyond what the schema provides. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('List'), a clear resource ('active vacancies for a specific employer'), and the mechanism ('public vacancy search' with an employer_id filter). This clearly differentiates it from generic vacancy search/list sibling tools.

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

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

It clearly implies when to use the tool: when you have a specific employer_id and want active public vacancies. It also notes that no token is required. It does not explicitly name alternatives or state when not to use it, but the context is clear.

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

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

With no annotations provided, the description carries the full burden. It mentions only the token requirement and does not disclose any behavioral traits such as read-only nature, pagination, return format, or potential side effects. This is a significant gap for an agent invoking the tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is a single concise sentence, but it lacks front-loading of critical details like return behavior. It is not overly verbose, but it also does not prioritize essential information beyond the basic purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has no output schema, and the description does not explain what the returned list looks like, whether pagination is needed, or any other operational details. This leaves an agent without enough context to fully understand the tool's behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema descriptions cover both parameters completely (employer_id and raw). The tool description adds no extra meaning about parameters, so the baseline of 3 is appropriate given the high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (list) and resource (active vacancy areas) for an employer, making it easy to understand the tool's purpose. However, it does not explicitly differentiate from sibling tools like get_areas or get_areas_subtree, which also deal with areas.

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

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

No guidance is provided on when to use this tool versus alternatives. The only extra information is the authentication requirement (HH_ACCESS_TOKEN), which is a prerequisite rather than a usage context.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the tool returns a tree with IDs and describes the raw parameter's effect on output format. However, it does not explicitly state read-only behavior or any other side effects, which is a minor gap given the simple getter nature.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Two sentences with no redundancy. The action is stated first, followed by the specific use case. Every word earns its place, making it highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple getter with one optional parameter and no output schema, the description covers the essential information: what it returns (tree with IDs) and why to use it (to find industry IDs). It is complete enough for an agent to call correctly, though it could have elaborated on the exact structure of the tree or typical response.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter 'raw' is fully documented in the input schema (100% coverage), so the description adds no extra meaning beyond what the schema provides. The baseline of 3 is appropriate since the description doesn't need to compensate for schema gaps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Get the tree of company industries with IDs') and clearly indicates its purpose for the search_vacancies industry filter. It distinguishes from siblings by focusing on the industry tree and its IDs, though it doesn't explicitly name alternatives like get_dictionaries.

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

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

The description gives explicit guidance on when to use the tool: to find industry IDs for the search_vacancies industry filter. It provides clear context but does not mention exclusions or alternatives, which would have made it a 5.

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

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

No annotations are provided, so the description carries the full burden. It discloses only the core function and default output format, but omits any mention of authentication requirements, rate limits, or the effect of the 'raw' parameter. The description does not explicitly state that the operation is read-only.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is a single concise sentence that is front-loaded with the core purpose and format. Every word earns its place, with no redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one optional parameter and no output schema, the description is mostly adequate. It covers the main function and output format, but it could be more complete by mentioning the effect of the 'raw' parameter (though schema covers it) and clarifying that this is a read-only reference list.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% because the 'raw' parameter is fully described in the schema. The description adds no extra meaning beyond the schema, so a baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (list languages) and the resource (/languages), and specifies the output format (id — name). It is specific to languages, distinguishing it from sibling tools like get_areas or get_countries, though it does not explicitly name them.

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

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

There is no guidance on when to use this tool versus alternatives such as get_areas or get_dictionaries. No context is given about typical use cases or exclusions, leaving the agent to infer when this tool is appropriate.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the HH_ACCESS_TOKEN requirement but does not describe the returned statistics, whether the result is a compact summary or raw JSON (aside from the schema's 'raw' parameter), or any error/edge-case behavior. This is insufficient for an unannotated tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is short and gets to the point in two sentences. The 'Requires HH_ACCESS_TOKEN' note is useful, though it repeats an authentication requirement rather than explaining the tool's behavior.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema and no annotations, so the description should explain what the caller receives and any important behaviors. It only identifies the resource and authentication requirement, leaving the return format, statistics scope, and failure modes unexplained. This is incomplete for a tool with similar siblings and no structured output metadata.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the input schema already documents employer_id, manager_id, and raw. The description adds no additional parameter meaning beyond what the schema provides, which is acceptable but not value-adding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action ('Get negotiations statistics') and a specific resource ('for a manager'). However, it does not differentiate this tool from the similarly named sibling 'get_negotiations_statistics', so the purpose is clear but the boundary between the two is not.

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

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

No guidance is given about when to use this tool versus alternatives such as 'get_negotiations_statistics' or 'get_preferred_negotiations_order'. The only contextual hint is 'for a manager', which implies a scope but does not explicitly address when to choose this tool.

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

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

With no annotations provided, the description carries the full disclosure burden, but it only mentions authentication. It does not describe whether this is a read-only operation, what fields or format the response contains, or how the raw parameter affects the result.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is very brief and front-loads the core purpose. It contains no filler, though it is arguably too sparse for a tool with no annotations or output schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read operation with fully documented parameters, the description is minimally adequate. However, it lacks an explanation of what 'limits' means, the default response shape, or any return-value details, which matters more because no output schema exists.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage for all three parameters, so the schema itself already explains manager_id, employer_id, and raw. The description does not add extra parameter meaning, but the baseline of 3 is appropriate because the schema carries the semantic weight.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'get', the resource 'resume-view limits', and the target 'manager'. It is specific enough to distinguish from most sibling tools, though it doesn't explicitly differentiate from similar manager-related tools.

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

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

No guidance is given about when to use this tool versus alternatives, nor any conditions or exclusions. The only added note is the HH_ACCESS_TOKEN requirement, which is an authentication prerequisite, not usage guidance.

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

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

No annotations are provided, so the description carries the full burden. It discloses the auth requirement (HH_ACCESS_TOKEN) and the raw-vs-compact output option, but it does not state whether this is a read-only operation, what happens when the template is not found, or any rate-limit/error behavior. For a GET-style tool this is a moderate gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is a single sentence that front-loads the core action and resource, then adds the optional parameters and auth requirement. It is efficient and free of filler, though the parenthetical list of optional parameters is slightly dense.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple lookup tool with a fully documented schema, the description is mostly adequate. However, with no annotations and no output schema, it does not explain the return format beyond 'compact summary' vs 'raw hh.ru JSON', nor does it clarify error cases or when the optional parameters are required. This leaves some gaps for an agent deciding how to invoke it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all five parameters. The description adds a little context by grouping topic_id with existing applications and resume_id/vacancy_id with invite templates, but it does not add substantial meaning beyond the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Get'), a resource ('negotiation message template'), and the lookup key ('by id'), with optional context parameters. It is clear enough to distinguish from siblings like get_application_messages or list_mail_templates, though it does not explicitly name a sibling alternative.

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

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

The description implies usage context by listing optional parameters (topic_id, resume_id, vacancy_id) and the auth requirement, but it does not explicitly state when to use this tool versus alternatives such as list_mail_templates or get_application_messages. The optional parameter hints provide some guidance, but no exclusions or alternative routing.

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

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

No annotations are provided, so the description carries the full burden for behavioral disclosure. It states the tool returns metro stations and lines with IDs, implying a read-only operation, but it does not explicitly mention side effects, permissions, or response structure. While minimal, it does not contradict any annotations (none exist) and the read-only nature is implied by 'get'.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Two concise sentences with no filler. The first sentence states the core function and scope, the second explains the purpose. Information is front-loaded and every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple lookup with one optional parameter and no output schema, the description provides enough context for an agent to call it correctly. It explains the purpose and scope. It could optionally mention the response format or authentication requirements, but these are not critical for a straightforward get operation given the simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description for city_id fully explains the parameter and its optionality (including examples like 1=Moscow), achieving 100% coverage. The tool description repeats this information without adding new meaning. Since the schema already documents the parameter, the description's contribution is redundant but not harmful.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves metro stations and lines with IDs, for a specific city or all cities. It also specifies the intended use ('find metro IDs for the search_vacancies metro filter'), which distinguishes it from other lookup tools like get_areas or get_dictionaries. Verb and resource are 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.

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

The description provides explicit context for when to use the tool: to obtain metro IDs for the search_vacancies metro filter. It indicates the optional city_id parameter and the behavior when omitted. However, it does not mention when not to use it or alternatives, though the named use case is sufficient for most scenarios.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the authentication requirement (HH_ACCESS_TOKEN) but does not state whether the operation is read-only, any side effects, rate limits, or what the statistics include. The sparse description leaves key behavioral traits unspecified.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is two short sentences, front-loaded with purpose and prerequisite. Every word earns its place, and there is no unnecessary filler. It is concise but perhaps slightly too spare for a tool with no other documentation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, no annotations, and only a bare description, an agent lacks information about what statistics are returned, the difference between summary and raw output, and potential error cases. The description is not complete enough to confidently invoke the tool and interpret results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and both employer_id and raw have meaningful descriptions. The tool description adds no extra parameter semantics beyond what the schema already provides, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Get') and resource ('employer-level negotiations statistics'). The qualifier 'employer-level' distinguishes it from the sibling get_manager_negotiations_statistics, making the tool's purpose clear without opening its schema.

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

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

The description only provides a prerequisite ('Requires employer_id and HH_ACCESS_TOKEN') and no guidance on when to use this tool versus alternatives. It does not mention conditions, exclusions, or how to choose between this and get_manager_negotiations_statistics. No explicit when/when-not guidance is given.

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

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

No annotations are provided, so the description must carry the behavioral burden. The description adds the auth requirement and implies a read-only retrieval via 'Get', but it does not disclose side effects, error behavior, or what the response contains beyond the tool name itself.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is two short sentences with no wasted words. The core purpose is front-loaded and the auth requirement is a necessary, non-redundant addition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple getter with only two fully documented parameters and an auth prerequisite, the description is nearly complete. It could add explicit details about the output shape, but the tool name and purpose convey the return concept sufficiently.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both 'vacancy_id' and 'raw'. The description adds the vacancy context and the raw/full-json distinction is already covered by the schema, meeting the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Get the preferred negotiations sort order for a vacancy.' This clearly identifies what the tool returns and distinguishes it from sibling tools that handle negotiations statistics or application messages.

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

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

The description gives clear context ('for a vacancy') and states the required prerequisite ('Requires HH_ACCESS_TOKEN'). It does not explicitly name alternatives or exclusion conditions, but the purpose is specific enough that an agent can infer when to use it.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses that the default response is a 'compact id — name listing' and that setting 'raw' returns the full hh.ru JSON. It also implies a tree structure. However, it does not mention authentication, rate limits, error conditions, or any side effects. For a simple read-only getter, the disclosed behavior is adequate but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Two sentences that are direct and efficient. The main action is front-loaded ('Get the tree...'), followed immediately by the use case. No filler words or redundant information. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite lacking an output schema, the description gives enough information about the return: it is a tree of roles, containing IDs, and by default comes as a compact id-name listing. The stated purpose (finding role IDs) implies the output includes the data needed for that task. For a lightweight reference tool, this is sufficient; a sample structure would make it a 5.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The only parameter 'raw' is fully documented in the input schema (100% coverage), including its effect on the response format. The description adds little beyond what the schema already explains—it mentions the compact listing, but that phrase appears in the schema description as well. Therefore, the description does not provide significant added semantic value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Get') and a distinct resource ('tree of professional roles with IDs'), and it clarifies the primary purpose ('find role IDs for vacancy/resume search and salary stats'). This clearly differentiates it from sibling tools like get_areas or get_dictionaries, which target different reference entities.

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

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

The description openly states when to use the tool ('Use to find role IDs for vacancy/resume search and salary stats'). It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to know it is the go-to for role lookups. A more explicit comparison to siblings would push it to 5, but the stated use case is sufficient.

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

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

With no annotations, the description carries the full burden, and it does add useful context by stating that the endpoint is public and requires no token. However, it does not disclose behavior like pagination defaults, the compact-summary vs raw response distinction, or what output shape to expect.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is a single concise sentence that front-loads the main purpose and then adds a relevant endpoint and authentication detail. There is no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple fetch-like tool this is mostly adequate, especially with full schema coverage and the public/no-token detail. But because there is no output schema and no annotation, the description omits return-format expectations and fails to disambiguate from get_similar_vacancies, leaving some context incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every parameter is already documented structurally (vacancy_id, page, per_page, raw). The description adds no additional parameter-level meaning beyond the schema, so a baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific action and resource: 'Find vacancies related to a given one' and identifies the exact hh.ru endpoint. It is unambiguous and immediately understandable, though it does not explicitly differentiate itself from the similar-sounding sibling get_similar_vacancies.

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

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

The description gives no guidance on when to use this tool versus alternatives. Given the presence of get_similar_vacancies and search_vacancies, an agent receives no help choosing among them; the only usage hint is 'Public, no token,' which addresses authentication context rather than selection criteria.

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

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

With no annotations provided, the description fully carries the burden of behavioral disclosure. It states the tool consumes a paid view, can trigger captcha, requires employer OAuth, and explains the difference between reading via negotiation context vs the resume database. This is comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is concise and front-loaded with the core purpose, then provides critical usage guidance. Every sentence carries essential information without fluff. Minor deduction for the mixed-language (Russian) term 'отклик' without immediate translation, but it's still understandable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (5 params, no output schema), the description covers the key behavioral context: security requirements, cost implications, and conditional parameter usage. It omits details about return structure, but that's acceptable since no output schema exists and the tool's risk profile is fully disclosed. 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.

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 significant value by explaining the functional impact of topic_id and vacancy_id (reads in context of own response vs database), which is beyond the schema. It also implies the default behavior of the unscoped read. However, it doesn't elaborate on raw or no_cache, but those are self-explanatory.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves full resume details (experience, education, skills, contacts), which distinguishes it from generic 'get_resumes' or other suggestions. However, it doesn't explicitly name a sibling for comparison, so it's clear but not maximally distinct.

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

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

The description explicitly instructs when to use topic_id (+vacancy_id) versus the unscoped read, warns about the consequences (paid view, captcha), and states the requirement for an EMPLOYER OAuth token. This is strong usage guidance that routes the agent correctly.

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

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

No annotations are provided, so the description carries the full burden. It discloses the auth requirement (HH_ACCESS_TOKEN) and the employer perspective, but it does not describe what the returned history contains, whether it is read-only, pagination behavior, or any side effects. For a data-fetching tool, this is a notable gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is a single concise sentence that front-loads the core purpose and includes the auth requirement. It is efficient, though it could add a bit more context without becoming verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no annotations and no output schema, the description must compensate, but it only covers the basic purpose and auth. It does not explain the shape of the response, the meaning of the 'raw' parameter's effect, or any filtering/pagination behavior. An agent would need to inspect the schema and possibly make assumptions about the return format.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both parameters. The description adds no parameter-level detail beyond what the schema provides, so the baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Get') and resource ('negotiation history for a resume'), and clarifies the perspective ('employer view'). It is clear what the tool does, though it does not explicitly distinguish it from sibling tools like get_negotiations_statistics or get_application_messages.

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

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

The description implies usage context by specifying 'employer view' and requiring HH_ACCESS_TOKEN, which suggests it is for employer-side operations. However, it does not explicitly state when to use this tool versus alternatives such as get_negotiations_statistics or get_application_messages.

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

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It reveals rate limiting (sequential, ~1.5s spacing), timeout handling (max_wait_ms, DSH 120s), captcha behavior (stop_on_captcha), and authentication requirement (HH_ACCESS_TOKEN). These are critical operational traits beyond what the schema exposes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is dense but front-loaded with the core purpose ('Safely fetch up to 50 resumes sequentially'). Each sentence carries operational detail, though it could be slightly streamlined. It is not verbose, but packs many numbers and constraints that are useful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 7 parameters, nested objects, and no output schema, the description covers the essential operational aspects: rate limiting, timeouts, captcha handling, scoped reads, and auth. It does not explicitly describe the default return format (though it implies a Russian summary via the raw parameter), nor error handling for partial failures, but overall it is quite complete for the complexity level.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 71% (5 of 7 parameters have descriptions), but the description adds valuable semantics: it explains the topics map and vacancy_id for scoped reads, and details max_wait_ms behavior with the spacing calculation. This goes beyond the schema's basic descriptions, justifying a score above the baseline of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool fetches up to 50 resumes sequentially, specifying the resource (resumes) and the action (fetch). It distinguishes from siblings like get_resume (single) and search_resumes (search) by emphasizing the batch, sequential nature and the resume-view budget.

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

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

The description gives specific parameter usage instructions (topics map, vacancy_id, stop_on_captcha, max_wait_ms) but does not explicitly compare to alternatives or state when not to use this tool. It implies it is for fetching known resume IDs but lacks explicit exclusions or guidance on when to prefer search_resumes or collect_vacancy_resumes.

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

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

No annotations are present, so the description must carry all behavioral disclosures. It transparently notes the fallback to vacancy sampling is biased, which is crucial. It also explains the 401/403/404 triggers. However, it does not mention that the operation is read-only or any potential rate limits, and it doesn't describe the output format, so some transparency gaps remain.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is about three sentences, front-loaded with the main purpose. It efficiently packs the two-mode logic without excessive verbosity. It's concise but not overly terse, and the structure flows logically from purpose to mode details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (9 parameters, no output schema, no annotations), the description explains the two modes and parameter roles but does not describe the return value or any formatting. It also lacks guidance on typical use cases or examples. The biased fallback is mentioned, but error handling beyond the fallback is omitted. This leaves some gaps for an agent deciding whether and how to call the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already documents all parameters, so baseline is 3. The description adds valuable semantic context: it clarifies that speciality, employee_level, industry, and extend_sources are only for the paid bank, and that text maps to position_name. It also explains area_id's dual role. This goes beyond the schema's individual descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool provides salary distribution for a role/region, distinguishing it from sibling tools like search_vacancies or get_vacancy_stats. It also explains the dual mode (paid bank vs fallback), which adds specificity. However, it doesn't explicitly name alternative tools, so it's slightly less clear on differentiation, but the purpose is unmistakable.

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

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

The description explains when the paid bank is attempted (with token and area_id) and when fallback occurs (on errors or missing token/area). It implies this tool is for salary statistics, but doesn't explicitly contrast with alternatives like get_negotiations_statistics or search_vacancies. It gives context on parameter usage but no exclusions.

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

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

With no annotations, the description carries the behavioral burden. It discloses the authentication requirement, which is useful, and the verb 'Get' implies a non-destructive read. However, it does not explicitly confirm read-only behavior, error conditions, or rate limiting, leaving gaps in transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is two short sentences with no filler. It front-loads the core purpose and adds the essential auth note, both of which earn their place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-by-id tool with fully documented parameters, the description is largely sufficient. It explains the operation and auth requirement, and the schema covers the raw/summary distinction. It could mention what a saved resume search is or common error cases, but these are minor given the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents both parameters. The description adds no parameter-specific meaning beyond what is present in the schema, matching the baseline for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Get') and resource ('saved resume search') plus the identifier ('by id'), making the purpose unambiguous. However, it does not explicitly differentiate from siblings like list_saved_resume_searches, though the singular nature is implied.

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

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

The description gives no guidance on when to use this tool versus alternatives such as list_saved_resume_searches or search_resumes. The only extra note, 'Requires HH_ACCESS_TOKEN', is a prerequisite rather than usage context, so an agent receives no decision support.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'Find vacancies similar,' which implicitly indicates a read operation, but it does not mention any side effects, return format, pagination behavior, or authentication requirements. For a tool with no annotation coverage, this is a significant gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is two sentences with no wasted words. The primary action is front-loaded, and the second sentence adds contextual value (use case). Both sentences earn their place, making it appropriately concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has no output schema and no annotations, so the description must compensate. It does not mention the response structure (list of vacancies), pagination details, or that the 'raw' parameter affects output format. An agent would lack key information about what to expect when invoking this tool, making it incomplete for reliable invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond what the schema already provides for parameters like vacancy_id, page, per_page, and raw. It doesn't elaborate on format or edge cases, but the schema is sufficient, so the description need not compensate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Find vacancies similar to a given one.' It names the verb (find), the resource (vacancies), and the distinguishing constraint (similar to a given one). This differentiates it from siblings like search_vacancies (general search) and get_vacancy (single vacancy retrieval) without ambiguity.

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

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

The description gives a use case ('Useful for expanding a candidate's job search') which implies when to use it, but it does not explicitly contrast with search_vacancies or state when not to use it. The guidance is implied rather than explicit, and no exclusions or alternative routing is provided.

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

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

No annotations are provided, so the description must carry the behavioral disclosure. It mentions the endpoint, the range of ids, and the effect of the raw parameter (full JSON vs compact listing). It does not cover error cases or rate limits, but these are typical for a read operation and not required for basic use. The description gives a solid behavioral overview.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Two sentences with no filler. The primary action and endpoint are front-loaded, and the usage alternative follows naturally. Every word contributes.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with only two parameters and no output schema. The description explains what it returns (skill names) and the raw option, plus the prerequisite for using suggest_skill_set. All necessary information for correct invocation is present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds value by contextualizing the id parameter (skill ids to resolve) and pointing to suggest_skill_set for name-based discovery, which is not in the schema. The raw parameter is already well-described in the schema, but the description's guidance compensates slightly beyond baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb-resource pair ('Resolve skill names by id') and explicitly names the endpoint /skills. It differentiates itself from suggest_skill_set by clarifying the discovery direction (ids vs names), making it easy to distinguish from sibling tools without inspecting schemas.

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

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

Provides explicit guidance: 'Use suggest_skill_set to discover ids by name first.' This tells the agent when to use this tool vs the alternative. Also specifies the id range (1–50), setting a clear precondition for invocation.

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

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

Annotations are absent, so the description carries the full behavioral disclosure burden. It does not state that this is a read-only operation, nor does it mention rate limits, error scenarios, or the effect of the 'raw' parameter. The description only lists content fields without revealing operational behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is a single, front-loaded sentence that efficiently communicates the purpose. It is concise with no fluff, but could arguably include a bit more context about the raw parameter without becoming verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with two parameters and no output schema. The description covers the main content of the response but omits the raw parameter toggle and does not describe the response format. For a get-by-ID tool, this is adequate but not fully complete, especially since no output schema exists to fill the gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% since both parameters (vacancy_id and raw) have descriptions. The tool description adds no extra semantics about these parameters; it does not explain the difference between compact and raw output, nor provide any usage hints beyond what the schema already states. The baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' and the resource 'full vacancy details', then enumerates the specific content (description, requirements, key skills, contacts, employer info). This makes the tool's purpose unambiguous and differentiates it from siblings like search_vacancies and get_similar_vacancies.

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

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

No guidance is given on when to use this tool versus alternatives such as search_vacancies or get_similar_vacancies. There is no mention of prerequisites like having a vacancy_id, nor any indication that this is the tool for retrieving a specific vacancy by ID.

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

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

With no annotations, the description carries the behavioral burden. It does add useful context by stating the token requirement and current-employer scoping, but it does not disclose read-only semantics, the shape of the compact summary, or potential error/limitation behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is one functional sentence followed by an essential auth note. It front-loads the verb and resource and contains no filler or redundant wording.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Adequate for a simple tool with one optional parameter and no required inputs, but with no output schema the agent must guess what the compact summary or raw response contains. A brief note on typical return content would round it out.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The only parameter, 'raw', is fully documented in the input schema with 100% coverage, so the description need not repeat it. It adds no additional parameter-level meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly identifies the operation ('Get') and the resource ('vacancy publication conditions / constraints') scoped to the current employer. This is reasonably distinguishable from siblings like get_vacancy or get_employer_vacancies, though 'conditions / constraints' remains somewhat open-ended.

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

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, no mention of related sibling tools, and no exclusions. The HH_ACCESS_TOKEN note is a prerequisite, not a use-case selector.

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

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

With no annotations, the description carries the behavioral disclosure burdenable. It does disclose a key auth requirement and employer-facing scope, which is useful. However, it does not explicitly state that the operation is read-only, nor describe rate limits, failure behavior, or side effects, so transparency is only partially complete.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Two short sentences with no filler; the primary purpose is front-loaded and the token requirement is the only added necessary invocation context. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter, simple RPC-like tool, the invocation is almost fully specified by the description plus schema. However, there is no output schema and several sibling stats tools exist, so the response shape is only loosely indicated and the agent gets no selection differentiators.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%; both vacancy_id and raw are documented in the schema. The description does not add meaning beyond those schema descriptions, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Get'), a resource ('vacancy statistics'), and a parenthetical list of stat categories ('views/responses/invitations'), so it is not a tautology. It does not explicitly distinguish itself from sibling tools like get_vacancy_visitors or get_negotiations_statistics, which keeps it from a 5.

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

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

No when-to-use guidance is provided beyond implying applicability to a specific vacancy. It does not name alternatives, exclusions, or conditions that would help an agent choose between this and the many sibling stats/vacancy tools; the HH_ACCESS_TOKEN note is a prerequisite, not a usage guideline.

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

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

No annotations are provided, so the description carries the behavioral disclosure burden. 'List' signals a read-only operation, and the explicit 'Requires HH_ACCESS_TOKEN' is a useful behavioral/access requirement. It does not mention response structure, ownership restrictions, or potential pagination implications, but for a simple list operation this is a reasonable baseline.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is two short sentences with no filler. The core action is front-loaded, and the auth requirement is the only additional necessary statement.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The schema fully documents parameters including page, per_page, raw, and vacancy_id, so there are no parameter gaps. However, there is no output schema and the description does not clarify employer/ownership constraints or provide sibling routing context, leaving a clear gap in overall completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the input schema already documents all four parameters well. The description adds no parameter-level semantics beyond what the schema provides, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('List') and resource ('visitors who viewed a vacancy'), which is clear and distinct from siblings like get_vacancy, get_vacancy_stats, and get_vacancy_conditions. It does not explicitly name a sibling to differentiate from, but the resource itself is distinctive.

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

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

No guidance is given about when to use this tool versus alternatives such as get_vacancy_stats or get_vacancy. The 'Requires HH_ACCESS_TOKEN' note is an auth prerequisite, not a routing or exclusion criterion. Among the many sibling tools, the agent gets no when-to-use vs. when-to-use-this-tool information.

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

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

No annotations exist, so the description carries the behavioral transparency burden. It does disclose meaningful context: the tool makes no network requests, reads locally gated data, and reports several specific state categories. It doesn't fully explain what 'gated-read' means or exactly how each reported value behaves, but it goes well beyond a bare description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is one compact sentence, front-loads the core category ('Local diagnostics'), itemizes the contents, and ends with a crucial safety constraint ('No network'). There is no filler or redundancy; every part earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple—one optional parameter, no output schema—and the description lists the major content areas and the default vs JSON output formats. It is mostly complete for an agent to decide whether and how to invoke it, though the meaning of 'gated-read ledger' and 'captcha breaker state' remains somewhat opaque without further detail.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the score lands at the baseline of 3. The single boolean parameter 'raw' is well described in the schema as choosing JSON over the compact Russian summary. The description itself adds no extra parameter semantics, but none are needed given the schema's clarity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description makes the tool's purpose clear: it provides a local diagnostics summary of specific things—ledger/log entries, captcha breaker state, resume budget, and cache hit counts. 'No network' clearly differentiates it from the many sibling tools that call remote HH APIs, though there is no explicit verb like 'returns' or 'summarizes'.

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

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

Usage context is implied rather than explicit. Saying 'Local diagnostics' and 'No network' signals the agent to use this for local state inspection rather than remote API calls, but the description doesn't explicitly say when to use it versus alternatives or when not to use it. There are no named sibling tools or exclusion conditions.

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

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

No annotations are provided, so the description carries the full burden. It meaningfully discloses that the tool requires HH_ACCESS_TOKEN, targets only published/active vacancies, and is scoped to the authenticated employer account. It does not disclose the response shape or possible errors, but the auth requirement and scoping are significant behavioral context beyond the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is two sentences with no filler. It front-loads the core action and resource, includes the endpoint, states the auth requirement, and names the alternative – every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations and no output schema, the description covers the essential invocation context: what is listed, for whom, auth needs, and the endpoint. It does not describe the response structure, but the schema's raw and pagination parameters already hint at output behavior, so the definition is sufficiently complete for an agent to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all parameters (raw, page, per_page, employer_id). The description adds no parameter-specific meaning beyond referencing the endpoint path; it does not explain the raw/compact distinction or pagination defaults beyond what the schema provides, so the baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource: 'List published (active) vacancies for the authenticated employer account' and points to the exact endpoint. It further differentiates itself from the sibling get_employer_vacancies by scope, so an agent can distinguish the two without opening schemas.

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

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

The description explicitly states when to use this tool (active vacancies for the authenticated employer account) and directs the agent to an alternative: 'For any employer's public vacancies use get_employer_vacancies.' This provides clear when-to-use and 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.

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

With no annotations, the description carries the full burden. It discloses the authentication requirement (HH_ACCESS_TOKEN) and the kind of data returned. However, it does not explicitly state read-only behavior, side-effect absence, rate limits, or response shape. Some transparency is present, but not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is compact and front-loaded, with the core purpose stated first. The additional sentences about list_applications, employer_states, and auth each add value. It is slightly list-like but remains efficient and scannable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list-style tool with no output schema, the description provides enough information to understand what will be returned and how it fits into the broader workflow. It could be improved by naming the response structure or field names, but it covers the essential context for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the input schema already documents vacancy_id and raw well. The description adds workflow context about sub-collection ids but does not need to explain parameter meanings further. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description is specific about what the tool returns: vacancy application funnel counters per stage and sub-stage, unread counts, and employer_states. It also distinguishes itself from the sibling list_applications by explaining that sub-collection ids from this tool feed into list_applications.

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

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

The description gives explicit workflow guidance: 'Start here before list_applications' and notes that sub-collection ids are inputs for list_applications. It does not list exclusions or alternatives beyond list_applications, but the sequencing guidance is clear enough for an agent to know when to call it.

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

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.

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.

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.

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.

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.

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.

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the auth requirement (HH_ACCESS_TOKEN) but does not disclose pagination behavior, rate limits, or what 'archived' means in terms of vacancy state. The description adds minimal behavioral context beyond the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is a single concise sentence that front-loads the core action and resource. It includes the essential auth requirement without waste. It could add a bit more context, but it is appropriately sized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a list tool with a fully documented schema, the description is mostly adequate. However, with no annotations and no output schema, it does not explain what the compact summary vs raw JSON contains, nor does it clarify pagination defaults beyond the schema. The auth requirement is mentioned, which is useful, but the description could be more complete about the tool's behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds no additional parameter semantics beyond the auth requirement, which is not a parameter. Baseline 3 is appropriate since the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('List') and resource ('archived vacancies for an employer'), which clearly distinguishes it from siblings like list_hidden_vacancies and get_employer_vacancies. It could be slightly more explicit about the hh.ru context, but the resource and scope are clear.

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

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

The description implies usage for listing archived vacancies and mentions the required auth token, but it does not explicitly state when to use this tool versus alternatives like list_hidden_vacancies or get_employer_vacancies. The context is clear enough for an agent to infer, but no exclusions or alternative routing are provided.

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

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

No annotations are provided, so the description carries the full burden. It mentions the auth requirement (HH_ACCESS_TOKEN) but doesn't disclose other behavioral traits like pagination, rate limits, or what the compact summary vs raw response contains. For a read operation, this is a moderate gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is a single sentence that is concise and front-loads the action. It includes the auth requirement, which is useful, but could be slightly more structured with the auth note separated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool with 2 parameters and full schema coverage, the description is mostly adequate. However, with no output schema and no annotations, it would benefit from mentioning what the response contains (e.g., address fields) or any pagination behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both parameters. The description adds no extra meaning beyond the schema, but the baseline of 3 applies because the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear verb ('List') and resource ('addresses for an employer'), which distinguishes it from most sibling tools. However, it doesn't explicitly differentiate it from other employer-related list tools like get_employer_vacancies or list_employer_managers, though the resource is specific enough.

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

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

The description implies usage context (listing addresses for an employer) but provides no explicit when-to-use guidance or alternatives. It doesn't mention when to prefer this over other employer-related tools, but the resource is clear enough that an agent can infer the use case.

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

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

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It only mentions a prerequisite (employer_id and HH_ACCESS_TOKEN) but does not disclose the return type (list), pagination behavior, or any side effects. For a read operation, it could be safe, but the description does not confirm that.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is a single sentence with no wasted words, but it is under-specified rather than appropriately concise. It lacks structure and does not front-load key differentiators. It is short but not well-rounded for agent decision-making.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is relatively simple, but the description is incomplete for effective selection. It does not explain the difference from get_employer_manager, does not mention that it returns a list, and provides no context on when to use it among many sibling tools. The absence of an output schema and annotations makes the description the only source of context, which is insufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all parameters are already documented with descriptions in the input schema. The tool description adds no extra meaning beyond mentioning employer_id and the auth token, which are already implied by the schema. The baseline of 3 is appropriate since the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'List managers for an employer account.' The action is clear, and the resource is unambiguous. However, it does not differentiate from the sibling tool get_employer_manager (singular), which likely fetches a single manager, so the agent might not know which to use without additional context.

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

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 like get_employer_manager or other employer-related tools. The description only states a requirement (employer_id and HH_ACCESS_TOKEN) but does not mention any distinguishing conditions or exclusions.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It adds the meaningful precondition that HH_ACCESS_TOKEN is required, which is useful beyond the schema. However, it does not disclose the response shape, pagination behavior, or what 'hidden' means in API terms.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is two short sentences with no redundant filler. The core action is front-loaded and the token requirement is stated efficiently.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple paginated list operation with fully documented parameters, the description is minimally adequate. Still, it lacks an output-format note, any guidance on when hidden vacancies are relevant, and does not differentiate from similar sibling tools, leaving some contextual gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the input schema fully documents employer_id, raw, page, and per_page. The description adds no extra parameter semantics, but since the schema already covers this, the baseline score applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'List hidden vacancies for an employer.' This cleanly identifies the operation. It does not explicitly contrast itself with sibling tools like list_archived_vacancies or get_employer_vacancies, but 'hidden vacancies' is a distinct enough scope.

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

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

The only usage guidance is 'Requires HH_ACCESS_TOKEN,' which is an authentication prerequisite rather than guidance about when to choose this tool over alternatives. No exclusions or comparisons to sibling vacancy-listing tools are provided.

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

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

With no annotations, the description must carry the behavioral disclosure burden. It explicitly mentions the HH_ACCESS_TOKEN requirement and 'List' makes the read-only nature apparent, but it does not cover pagination, response shape, or list-specific quirks.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is two short sentences with no filler, and the core action is front-loaded. It wastes no words, though it is so brief that it omits useful usage context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool this is minimally adequate: the description plus schema covers the required employer_id and the raw-output option. There is no output schema, and the description does not mention pagination or what the returned templates contain, leaving a modest completeness gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%: employer_id and raw are already documented in the input schema, so the description adds no new parameter-level meaning. The baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ('List employer mail templates'), which clearly conveys the operation and the employer scoping. This distinguishes it from sibling tools like get_message_template, which is aimed at a single template.

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

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

The intended use is implied: list all mail templates for an employer, given employer_id and access token. However, it does not explicitly state when to choose this over alternatives such as get_message_template or any exclusions, so usage guidance is only implicit.

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

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

With no annotations, the description carries the burden of behavior disclosure. It responsibly states the auth requirement (HH_ACCESS_TOKEN) and employer-account scoping, and 'List' implies a read operation. It does not go deeper into error conditions, rate limits, or role requirements, but for a simple list operation 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.

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

Two short sentences, front-loaded with the core verb and resource, then the essential auth requirement. No filler and every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a paginated list with three optional parameters and no output schema, the description plus schema gives an agent enough to invoke it correctly. It could be more complete by mentioning the distinction from get_saved_resume_search, but nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with raw, page, and per_page each documented. The description adds no parameter-level nuance beyond what the schema already provides, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the resource ('saved resume searches') and the operation ('List'), scoped to 'current employer account.' It is clear and specific, though it does not explicitly contrast with the singular sibling get_saved_resume_search, so it stops short of full sibling differentiation.

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

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

The context is clear: use it to list saved resume searches for the current employer account, and it notes a required token. However, it gives no explicit guidance about when to prefer this over get_saved_resume_search or other alternatives; the usage is mostly implied by the resource name.

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

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

No annotations are provided, so the description must carry the full burden. It does disclose that the tool returns company info and open vacancy count, which is a useful behavioral trait. However, it doesn't mention pagination behavior (though page/per_page params exist), authentication requirements, or what constitutes 'company info'. It is adequate but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is a single, compact sentence that front-loads the action and resource, then specifies the output. Every word earns its place with no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple search tool with fully documented parameters and no output schema, the description covers the essential purpose and return type. It could be improved by noting that it returns a list of matching companies rather than a single result, and by mentioning typical use cases or limitations, but it is largely sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all parameters are already well-documented in the schema. The description adds only that the search is 'by name', which maps directly to the 'text' parameter. It does not provide any additional nuance beyond the schema, so the baseline score of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (search) and the resource (companies/employers on hh.ru), and specifies the input (by name) and output (company info and open vacancy count). It distinguishes itself from get_employer (which presumably fetches by ID) and get_employer_vacancies (which fetches vacancies for a known employer) by focusing on name-based search.

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

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

The description implies that this tool is for searching employers when you don't have an ID, but it never explicitly states when to prefer it over siblings like get_employer or suggest_companies. No exclusions or alternative routing are given, so the agent must infer the appropriate context.

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

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

No annotations are present, so the description carries the full burden of disclosure — and it delivers: it states the required credential type and the concrete failure mode (403 for applicant/anonymous tokens. It doesn't cover rate limits or response-shaping behavior (the compact-summary vs raw distinction lives in the schema), but the disclosed access-control trait adds real behavioral value beyond the action itself.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Two sentences with zero waste: the purpose and filter scope are front-loaded, and the second sentence carries the high-value access constraint and 403 warning. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter search tool with full schema coverage and no output schema, the description plus schema cover the operation scope, all parameters, and the access gate. The only notable gap is the absence of explicit routing to alternatives (e.g., get_resume for fetching a single resume), but nothing an agent needs to avoid a failed call is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already fully documents all 8 parameters. The description's filter list (keywords, region, professional role, salary, experience) maps onto text/area/professional_role/salary/experience but adds no meaning beyond what the schema provides. Baseline 3 is correct.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ('Search candidate resumes') and enumerates the filter dimensions (keywords, region, professional role, salary, experience). This cleanly distinguishes it from sibling tools like search_vacancies and search_employers without needing to open any schemas.

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

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

The description gives clear context for when the tool is usable: it requires an EMPLOYER OAuth token (HH_ACCESS_TOKEN) plus a paid resume-database subscription, and warns that applicant/anonymous tokens fail with 403. It doesn't explicitly name alternatives or state when-not-to-use, but the resource (resumes vs vacancies) plus the access gate provide solid operational guidance.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool returns 'a compact paginated summary' and that passing raw:true yields full JSON, which is useful behavioral context. However, it does not mention whether the operation is read-only, any authentication requirements, rate limits, or side effects. For a search tool that is inherently read-only, the absence of a read-only hint is acceptable but not explicitly stated. The return format disclosure is the main value added beyond the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is a single, tightly packed sentence that conveys the core purpose, the breadth of filters, and the return format option. Every phrase earns its place; there is no fluff or repetition. It is front-loaded with the action and includes the key caveat about raw JSON. This is an excellent example of concise, efficient writing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (23 parameters, no output schema), the description provides adequate context for an agent to understand what the tool does and what it returns. It mentions the filter types and the return summary. However, it does not explain the pagination mechanics (though page and per_page are in the schema), nor does it clarify mutually exclusive parameter groups (period vs date range) — though these are also in the schema. For a search tool with full schema coverage, the description is sufficient but could have added a note about the relationship between filters and the need for area/role IDs from helper tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so each of the 23 parameters already has a descriptive comment. The description lists filter categories but adds no extra meaning beyond what the schema provides. For instance, it mentions 'labels' but the schema already explains the label enum. The description does not clarify any parameter interdependencies (e.g., period vs date range) beyond what is in the schema. Thus, it adds minimal value over the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Search job vacancies on hh.ru' with a comprehensive list of filter dimensions (keywords, region, professional role, industry, metro, salary, etc.). It uses a specific verb and resource, and the inclusion of many distinct filter categories distinguishes it from sibling tools like get_vacancy (which retrieves a single vacancy) or search_employers (which searches a different entity). The purpose is unambiguous.

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

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

The description indicates the tool is for broad vacancy searching but does not explicitly state when to prefer it over alternatives like get_vacancy (for a specific vacancy ID) or get_similar_vacancies (for similarity-based results). It also doesn't mention any exclusions or conditions. While the name and filter list imply broad search usage, the lack of explicit guidance on alternatives leaves room for agent confusion among the many sibling tools.

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

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

With no annotations provided, the description must carry the behavioral burden. It states the core behavior ('Returns matching area suggestions') but does not disclose details such as result limits, ordering, case sensitivity, or output format beyond what the parameter schema covers. While adequate for a simple autocomplete, it lacks depth on any potential side effects or limitations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is a single, efficient sentence that front-loads the primary action and resource. It contains zero waste and every word adds value, making it easy for an agent to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the low complexity (2 params, no output schema), the description is largely complete for an autocomplete tool. It states the purpose and the return behavior. However, it could be more complete by mentioning how this differs from get_areas or suggest_positions, and by clarifying that the 'raw' parameter controls output format (though that is in the schema). Overall, it is close to sufficient but not fully explicit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters ('text' and 'raw') are already fully described in the input schema. The description adds no additional parameter semantics—it only mentions 'partial input' which corresponds to the 'text' parameter but does not elaborate on the 'raw' parameter or how the two interact. Baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific verb ('Autocomplete') and resource ('region/city names'), and additionally says it 'Returns matching area suggestions for partial input.' This makes the tool's function unambiguous and distinguishes it from siblings like get_areas (which likely lists full areas) and get_areas_subtree (which likely returns hierarchical subtrees).

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

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

The description implies usage for partial input ('for partial input') but does not explicitly contrast this tool with alternatives like get_areas or suggest_positions. It lacks 'when not to use' guidance or mention of sibling tools, leaving the agent to infer appropriate usage from context alone.

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

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

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It states that matching employer suggestions are returned for partial input, which is a minimal behavioral trait. However, it does not disclose potential rate limits, result limits, authentication requirements, or the effect of the 'raw' parameter on output. Given the absence of annotations, this is insufficient for a production tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is exceptionally concise with two sentences that convey the essential action and output. It is front-loaded with the verb 'autocomplete' and the object 'company names', with no redundant boilerplate. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple autocomplete tool with two parameters and no output schema, the definition covers the core function but lacks usage guidance and deeper behavioral transparency. The description doesn't explain the response format beyond 'matching employer suggestions', nor does it clarify the difference between compact and raw output. It is adequate for basic invocation but incomplete for nuanced decision-making.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% since both 'text' and 'raw' have descriptions in the schema. The tool description adds no parameter-specific information beyond what the schema already provides. Per the baseline for high schema coverage, a score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: autocomplete company names and return employer suggestions for partial input. This distinguishes it from sibling tools like suggest_positions and suggest_areas which handle different entities. However, it doesn't explicitly differentiate from search_employers, which could also return employer matches, so it's not fully distinct.

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

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

The phrase 'for partial input' implies this is meant for typeahead/autocomplete scenarios, but there is no explicit guidance on when to prefer this over suggest_positions, suggest_areas, or search_employers. No alternatives are mentioned, so usage context is only implied, not stated.

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

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

No annotations are provided, so the description carries the behavioral burden. It communicates the main trait: the operation is non-destructive read/autocomplete and returns either compact id–name listings or raw JSON based on the 'raw' flag. It doesn't disclose rate limits, auth token requirements, or default response behavior, but for a simple autocomplete tool the core behavior is sufficiently clear.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is one sentence, front-loaded with the action and resource, and includes a precise sibling disambiguation. No wasted words; every part earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple autocomplete tool with two well-documented parameters and no nested objects/output schema, the description plus schema is largely complete. The main missing piece is response shape (the compact listing format isn't detailed), but since no output schema exists, the description should have revealed a bit more about what the compact output looks like. Still, it's adequate for an agent to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds little beyond the schema—it mentions 'free-form job titles / positions' and the raw flag in the schema already says 'Return the full raw hh.ru JSON instead of the compact id—name listing.' The description adds no new parameter semantics, so 3 is correct.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Autocomplete free-form job titles / positions via /suggests/positions') and explicitly differentiates from sibling suggest_professional_roles by saying this is not for role IDs. An agent can distinguish it from the many sibling suggest_* tools and other listing tools.

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

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

The description explicitly names the sibling tool for the alternative case ('use suggest_professional_roles for those'), which gives a clear when-not-to-use signal. It doesn't elaborate on other contexts (e.g., when to choose it over other autocomplete tools), but the schema and sibling names provide enough context.

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

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

With no annotations, the description carries the behavioral transparency burden. It conveys that the tool returns professional roles with IDs, which is useful, but it does not describe response shape, text length constraints, or other runtime behavior. This is enough for a basic understanding but not rich disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is two short sentences with no filler. The core behavior is front-loaded in the first sentence, and the usage guidance is delivered concisely in the second. Every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter autocomplete tool with full schema coverage, the description plus schema gives an agent enough to call it correctly. It states the endpoint, the purpose, and the use cases. It could add a bit more about expected output, but the ID mention partially covers that.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds little beyond the schema: it does not elaborate on 'text' or 'raw' parameters, though it does reinforce that the result is ID-based. The schema itself documents both parameters sufficiently.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific action ('Autocomplete professional roles with IDs') and names the endpoint (/suggests/professional_roles). It is not a tautology and conveys the tool's resource and purpose, though it does not explicitly differentiate from nearby siblings like get_professional_roles.

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

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

The description gives explicit usage contexts: 'Use for vacancy/resume search filters and salary stats.' This tells an agent when the tool is relevant, though it does not state when to prefer an alternative or when not to use it.

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

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

There are no annotations, so the description carries the full burden of behavioral disclosure, and it adds almost nothing beyond the action and endpoint. It does not say what the tool returns, whether it is a read-only operation, how pagination or raw output behaves, or what error/edge behavior to expect, leaving the agent to infer this from the schema alone.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is one short sentence with no filler or redundant boilerplate. The core action is front-loaded and the endpoint reference is minimal, so it earns a high conciseness score.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple and the schema is well documented, but there is no output schema and the description does not describe the expected response shape beyond the raw parameter's hint at compact versus raw JSON. It is minimally adequate but lacks the extra context an agent would ideally have.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the schema already explains both params, so the description does not need to repeat them. The description adds no extra parameter context, which matches the baseline for full schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb, 'Autocomplete', and a specific resource, 'resume-search keywords', which makes the tool's core purpose immediately clear. It does not explicitly contrast it with suggest_vacancy_search_keyword, so it stops short of a 5, but the resource qualifier already separates it from the vacancy-search sibling.

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

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

'Autocomplete resume-search keywords' communicates the exact situation in which the tool is useful: when the agent needs suggested keywords for resume search. It does not list excluded cases or alternative suggestion tools, but the use context is clear enough for an agent to select it over search_resumes or suggest_vacancy_search_keyword.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'Autocomplete skills via /suggests/skill_set' and does not describe what the response looks like, any authentication requirements, rate limits, or edge cases. For a suggestion tool, the lack of output format details is a significant gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is a single, short sentence that directly states the action and endpoint. It is efficient and front-loaded, but it is also under-specified, sacrificing completeness for brevity. It earns its place but could be expanded without losing conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and no annotations, the description should provide context about the tool's return behavior, any limitations, and how to use it effectively. It does none of this. The description is minimal and leaves the agent without crucial information about what the tool actually returns, making it incomplete for a tool with these characteristics.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100%, so both parameters (text and raw) are already documented in the schema, including the meaning of raw ('Return the full raw hh.ru JSON instead of the compact id — name listing'). The tool description adds no additional semantic value beyond what the schema provides, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool autocompletes skills, which is a specific resource. It is distinguishable from sibling suggest tools (positions, companies, areas, etc.) based on the skill domain, though it does not explicitly differentiate itself. The verb 'autocomplete' and resource 'skills' are clear, but the description adds little beyond the tool name.

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

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

There is no guidance on when to use this tool versus alternative suggest tools like suggest_positions, suggest_companies, or suggest_professional_roles. The description does not mention any conditions, exclusions, or when not to use it. It simply states the function without providing context for selection.

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