Server Quality Checklist

Tool Scores

• get_employer_vacanciesC
  2.9/5.0
  Behavior2/5

  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 disclosing behavioral traits. It only states 'List active vacancies', which is a basic read operation, but it does not mention behavior like pagination, the raw parameter, or how results are returned. The description adds minimal context beyond the obvious, leaving an agent uninformed about the tool's operational nuances.

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

  Conciseness4/5

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

  The description is a single, efficient sentence with no wasted words. It is front-loaded with the core action and scope. It earns high marks for conciseness, though it could be slightly more informative without losing efficiency. It does not over-eloquently expand, but it's appropriately brief for a simple tool.

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

  Completeness3/5

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

  The tool has moderate complexity with four parameters and no output schema, but the schema covers parameter details. The description lacks context on output format, pagination behavior, or the effect of the 'raw' flag, which an agent might need to know. It is adequate for a simple list tool but not fully complete without annotations.

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

  Parameters3/5

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

  Schema description coverage is 100%, so all parameters are documented in the schema itself. The description adds no extra meaning to the parameters—it only repeats the core intent. Baseline of 3 applies because the schema fully covers parameter semantics, and the description does not need to compensate.

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

  Purpose4/5

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

  The description clearly states the verb 'List' and resource 'active vacancies for a specific employer', which is specific enough to understand the tool's function. It does not explicitly differentiate from siblings like search_vacancies, but the phrase 'for a specific employer' makes the scope distinct. It falls short of a 5 because it doesn't name or contrast with any sibling tool.

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

  Usage Guidelines2/5

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

  The description provides no guidance on when to use this tool versus alternatives such as search_vacancies or get_similar_vacancies. There is no mention of use cases, exclusions, or conditions that would favor this tool. An agent is left to infer that it's for a single employer, but no explicit direction is given.

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

• get_vacancyB
  3.2/5.0
  Behavior2/5

  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.

  Conciseness4/5

  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.

  Completeness3/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines2/5

  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.

• suggest_companiesB
  3.3/5.0
  Behavior2/5

  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.

  Conciseness5/5

  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.

  Completeness3/5

  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.

  Parameters3/5

  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.

  Purpose4/5

  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.

  Usage Guidelines3/5

  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.

• get_similar_vacanciesB
  3.4/5.0
  Behavior2/5

  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.

  Conciseness5/5

  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.

  Completeness2/5

  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.

  Parameters3/5

  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.

  Purpose5/5

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

  The description clearly states the tool's 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.

  Usage Guidelines3/5

  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.

• search_vacanciesA
  3.6/5.0
  Behavior3/5

  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 discloses the return format ('compact paginated summary') and the raw:true option for full JSON, which is useful. However, it does not mention any other behavioral traits such as default sorting, pagination limits, or the fact that search is read-only. For a tool with no safety annotations, this is a moderate gap, but the mention of output format provides some transparency.

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

  Conciseness4/5

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

  The description is a single, compact sentence that front-loads the primary purpose and then mentions the return format. It is efficient with no fluff, though it lists many filters which makes it slightly long. Still, it earns a high score for conciseness and structure.

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

  Completeness3/5

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

  Given the tool's complexity (23 parameters, no output schema, no annotations), the description is relatively thin. It does not explain the contents of the 'compact summary' or any prerequisites for using certain filters (though schema descriptions cover those). For such a complex tool, the description could provide more high-level guidance, but the comprehensive schema descriptions mitigate the gap, resulting in a mid-range score.

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

  Parameters3/5

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

  Schema description coverage is 100%, meaning every parameter already has a description. The tool description adds no additional semantic meaning beyond what the schema provides; it only lists filter categories. Per the rubric, with high schema coverage, the baseline is 3, and the description does not elevate it further.

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

  Purpose5/5

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

  The description clearly states the tool's verb and resource ('Search job vacancies on hh.ru') and enumerates a comprehensive list of filters (keywords, region, professional role, industry, metro, salary, experience, employment form, work format, date range, labels). It effectively distinguishes itself from sibling tools like get_vacancy (which retrieves a specific vacancy) and search_resumes (which searches resumes), making its purpose unmistakable.

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

  Usage Guidelines3/5

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

  The description implies usage for searching vacancies but does not explicitly mention when to use alternatives such as get_vacancy when a specific vacancy ID is known, or search_resumes for resume search. No exclusions or alternative conditions are stated, leaving the agent to infer the appropriate context from the sibling tool names and the tool's own purpose.

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

• get_areas_subtreeA
  3.7/5.0
  Behavior2/5

  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.

  Conciseness5/5

  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.

  Completeness3/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• get_dictionariesA
  3.8/5.0
  Behavior3/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines2/5

  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.

• get_industriesA
  3.8/5.0
  Behavior3/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters3/5

  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.

  Purpose4/5

  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.

  Usage Guidelines4/5

  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.

• get_resumeA
  3.8/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden of behavioral disclosure. It transparently notes the authentication and paid-access requirements, which are essential for the agent to know before invoking. It does not describe error behavior or side effects, but for a simple read operation the auth context is the key behavioral trait.

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

  Conciseness4/5

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

  The description is a short two-sentence structure, with the core purpose front-loaded and the auth requirement immediately following. Every sentence adds value with no redundant phrasing. It is concise without sacrificing essential context.

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

  Completeness3/5

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

  Given no output schema and a simple get operation, the description covers the main purpose and auth needs, but it omits expected behavior details such as the default return format (summary vs raw) or error handling for invalid resume IDs. The raw parameter is mentioned in the schema but not in the description, so the agent may not know when to set it. This leaves some ambiguity for correct invocation.

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

  Parameters3/5

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

  Schema coverage is 100%, meaning the description of both parameters (raw and resume_id) is already in the schema. The description adds no extra meaning about the parameters—it only says 'full resume details,' which does not clarify the role of the 'raw' flag or the format. Baseline of 3 applies because the schema is complete.

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

  Purpose5/5

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

  The description clearly states the tool's purpose: 'Get full resume details' and enumerates what is included (experience, education, skills, contacts). It uses a specific verb and resource, and it is distinct from siblings like search_resumes which are search-focused rather than retrieval of a specific resume.

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

  Usage Guidelines3/5

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

  It mentions a critical prerequisite (EMPLOYER OAuth token and paid access) that guides when the tool can be used, but it does not explicitly address when to choose this over alternatives like get_vacancy or search_resumes. It implies the need for a resume ID but lacks exclusions or direct comparison to sibling tools.

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

• search_employersA
  3.8/5.0
  Behavior3/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines3/5

  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.

• suggest_areasA
  3.8/5.0
  Behavior3/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines3/5

  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.

• suggest_positionsA
  3.8/5.0
  Behavior2/5

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

  No annotations are provided, so the description must disclose behavioral details. It only states the basic function ('Returns matching role suggestions') without mentioning side effects, safety, rate limits, or authentication requirements. For a tool with zero annotation coverage, this is a significant gap—agents cannot infer whether this operation is safe or requires special permissions.

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

  Conciseness5/5

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

  The description is a single, efficient sentence that front-loads the core purpose. Every word adds value, with no unnecessary elaboration or repetition. It is appropriately sized for a simple tool.

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

  Completeness4/5

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

  For a simple autocomplete tool with full schema coverage and no output schema, the description is largely sufficient. It covers the primary use case and relies on schema for parameters. Minor omissions (e.g., authentication requirements) exist, but they are not critical for a read-only suggestion tool. The overall completeness is adequate.

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

  Parameters3/5

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

  Schema description coverage is 100%, meaning both parameters (text and raw) are already documented in the schema. The description adds no extra meaning beyond what the schema provides. Per the rubric, the baseline is 3 when schema covers all parameters, and the description does not compensate for any gaps.

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

  Purpose5/5

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

  The description states a specific verb ('Autocomplete') and a specific resource ('job titles / professional roles'), which clearly differentiates it from sibling tools like suggest_companies and suggest_areas. It also implies the use case of partial input, 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.

  Usage Guidelines4/5

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

  The phrase 'for partial input' provides clear context for when to use the tool, but it does not explicitly mention alternatives or when not to use it. Given the sibling tools (e.g., get_professional_roles for full lists), the description lacks explicit exclusions but still gives sufficient guidance for a straightforward autocomplete scenario.

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

• search_resumesA
  3.9/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the full burden. It discloses the authentication requirement and the 403 outcome, and hints at a raw vs compact response via the 'raw' parameter. However, it does not describe the compact summary format, pagination behavior, or any other side effects. The added details are useful but insufficient for full transparency.

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

  Conciseness5/5

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

  Two concise sentences. The first states the purpose and criteria, the second lists the access requirements. Every word earns its place, and the most critical information is front-loaded.

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

  Completeness3/5

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

  As an 8-parameter tool with no output schema, the description is somewhat thin. It covers authorization and the raw flag, but does not explain the default compact response, pagination semantics, or potential error scenarios beyond 403. While the essential callable information is present, more detail on response behavior would improve completeness.

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

  Parameters3/5

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

  Schema coverage is 100%, so the baseline is 3. The description lists the search criteria, which map directly to the parameters, and adds a useful pointer that professional_role IDs come from get_professional_roles. This adds slight value but does not substantially elaborate on parameter formats or constraints beyond the schema.

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

  Purpose5/5

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

  The description begins with 'Search candidate resumes by' and enumerates specific search criteria (keywords, region, professional role, salary, experience). This clearly defines the verb, resource, and scope, and implicitly distinguishes it from sibling tools like search_vacancies and get_resume.

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

  Usage Guidelines4/5

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

  It specifies a critical usage prerequisite: requires an EMPLOYER OAuth token and a paid subscription, and notes that applicant/anonymous tokens get 403. This is practical guidance for when the tool can be used, though it does not explicitly contrast with alternatives or state when not to use it beyond the token requirement.

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

• get_areasA
  4/5.0
  Behavior3/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• get_employerA
  4/5.0
  Behavior3/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

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

  The description implies when to use the tool (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.

• get_metroA
  4/5.0
  Behavior3/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• get_professional_rolesA
  4/5.0
  Behavior3/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• get_salary_statisticsA
  4/5.0
  Behavior3/5

  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 honestly discloses the sampling bias and that sampling is done client-side, but does not mention potential side effects like multiple API calls (implied by sample_pages parameter) or error behavior. It conveys the most important limitation but lacks depth beyond that.

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

  Conciseness5/5

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

  The description is two sentences, with the primary purpose stated first, followed by the key limitation. It is concise, front-loaded, and contains no fluff while conveying the essential information in a compact form.

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

  Completeness4/5

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

  The description explains the output (median, P25/P75, min/max), the method (sampling client-side), and the bias, which is sufficient for a simple estimation tool. It doesn't describe errors or detailed return formatting, but the schema covers formatting options. It could mention how to find role/area IDs, but the schema already points to get_professional_roles and get_areas.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema fully documents all parameters (raw, text, area_id, sample_pages, professional_role_id) with their meaning and hints on finding IDs. The tool description adds no additional parameter-level detail, so it meets the baseline without adding extra value.

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

  Purpose5/5

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

  The description clearly states the tool estimates salary distribution (median, P25/P75, min/max) for a professional role in a region, specifying the action (estimate), resource (salary distribution), and scope (role+region). It distinguishes itself from sibling tools like search_vacancies and get_vacancy by focusing on statistical salary estimates, not individual vacancies.

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

  Usage Guidelines4/5

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

  The description provides context that the estimate is based on a biased sample (only vacancies disclosing salary) and explicitly says it is 'not official market data', which implicitly guides when to use it (for quick estimates) and when not to (for authoritative figures). However, it does not name specific alternative tools, so it falls short of explicit when-to-use guidance.

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

• validate_tokenA
  4/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the burden of behavioral disclosure. It clarifies that the tool makes a call to /me and returns the user role, which is useful. However, it does not state whether the operation is read-only or describe error behavior (e.g., what happens with an invalid token). The behavior is implied but not fully elaborated.

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

  Conciseness5/5

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

  The description is two sentences, with the core purpose front-loaded and the usage context provided immediately. 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.

  Completeness4/5

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

  The tool is simple: one optional boolean parameter, no output schema. The description explains the purpose (validate token, report role) and the usage context (diagnose resume-search access). It does not describe error handling or the exact response format, but for a validation tool this is not a critical gap; an agent can infer the outcome from the description.

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

  Parameters3/5

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

  The only parameter, 'raw', has a clear description in the schema: 'Return the raw /me JSON instead of the summary.' Schema coverage is 100%, so the description adds no additional parameter-level meaning beyond what the schema already provides. The baseline of 3 is appropriate.

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

  Purpose5/5

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

  The description states a specific verb ('Check'), a specific resource ('HH_ACCESS_TOKEN via /me'), and a clear purpose ('diagnose resume-search access'). It also identifies the output (user role). This clearly distinguishes it from sibling tools like search_vacancies or get_resume, which are about querying data rather than validating auth.

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

  Usage Guidelines4/5

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

  The description explicitly provides a use case: 'Use to diagnose resume-search access.' This gives the agent clear context on when to invoke the tool. However, it does not mention any circumstances where the tool should not be used, or alternatives to consider, though no obvious alternative exists for token validation.

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