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

Goes well beyond the annotations: it discloses the security consequence (key lands in the chat transcript), the required acknowledgement flag, the on-disk destination and permissions (~/.marketplace-mcp/cabinets.json, chmod 600), and that the value is never echoed back. That is exactly the extra behavioral context the readOnly/idempotent hints cannot convey.

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?

Front-loads the action and the warning, then breaks parameters into a readable Args block — every sentence earns its place. The literal escaped newlines and doubled braces from the raw template add minor noise, but the content density is high.

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 write tool with a nested credentials object, a safety gate, and no parameter documentation in the schema, the description covers inputs, side effects, storage location and the safe alternative. With an output schema present, no return-value prose is needed, and nothing an agent requires to call this correctly 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 coverage is 0%, so the description carries the full burden and does: it defines the credentials object shape with concrete per-service examples (Ozon client_id/api_key, WB token), and explains that name is optional with a non-obvious fallback to the marketplace shop name or 'main'. The usually-inscrutable boolean is also explained as a hard gate.

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?

Specific verb+resource ('add or update a cabinet — a named set of API credentials') with an explicit scope qualifier ('from chat'), which cleanly separates it from siblings like hh_set_key, hh_list_cabinets, hh_use_cabinet and hh_remove_cabinet. An agent can route correctly without opening any 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?

It gives a clear conditional ('from chat') and names the preferred alternative path — the installer (install.py / double-click) where the key never enters the chat — which is strong when-to-use guidance. It does not, however, contrast with the closest sibling hh_set_key, so the agent still has to infer which key-writing tool to pick in a non-chat 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?

Annotations already declare readOnlyHint=false, destructiveHint=true and openWorldHint=true, yet the description adds real information beyond them: exactly which confirmation flags are required per operation class, and critically that nothing is sent unless the destructive flag is supplied. That gating contract is the key behavioral fact an agent needs before invoking.

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?

Front-loaded purpose sentence, then the confirmation rules, then a clean Args list and return-envelope line. Every sentence earns its place and the safety-critical constraint appears early rather than buried.

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 destructive annotations, an output schema, and six undocumented schema parameters, the description closes the right gaps: confirmation semantics, parameter meanings, discovery source, and response envelope. An agent has everything needed 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 0%, so the description carries the full burden, and it does so: every one of the six parameters is named with its meaning (path placeholders, query string, JSON body, and the two confirmation flags). It lacks format/type detail or example values, but the semantics are covered well enough to compensate for the empty 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 states a specific verb and resource: execute one catalog endpoint selected by operation_id, and points to the catalog-discovery sibling ({svc}_search_methods). That is clear and actionable. It does not, however, differentiate itself from the closely related hh_call_raw sibling, so sibling discrimination is left to inference.

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 establishes the workflow context (obtain an operation_id from the catalog via search_methods) and the behavioral conditions under which a call proceeds (read runs immediately, write/destructive require confirmation flags). No exclusion vs hh_call_raw is given, but the usage context is concrete rather than implied.

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 only supply a blanket destructiveHint=true; the description adds the operationally critical per-verb safety model (GET=read, POST/PUT/PATCH=write, DELETE=destructive), names the write-confirmation flags, and states the confirmation regime. This is real disclosure beyond the structured fields and tells the agent what will actually happen for a given call.

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?

Front-loaded with the core capability, then structured Args/Returns sections that are easy to scan. Slightly marred by the unresolved '{svc}' template placeholder in the sibling reference, but no wasted sentences.

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 high-risk arbitrary-endpoint tool, it covers safety inference, confirmation requirements, parameter roles, and the return envelope even though an output schema exists. Missing only peripheral context such as auth prerequisites or pagination/rate-limit behavior on the underlying API.

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 0%, so the description carries the full burden and mostly succeeds: it gives meaning and format for method (with the verb list), path (leading '/' plus a concrete example), host (override/default), and the two confirmation flags. query and body entries are closer to restatement of their titles, so it's strong but not exhaustive.

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+resource (execute ANY endpoint) and carves out an unambiguous scope distinction vs siblings: 'even ones not in the catalog (full API coverage)', which directly separates it from the catalog-bound hh_call_method / hh_describe_method. An agent can pick this tool without opening any 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?

Gives a clear usage condition (raw/uncatalogued endpoints) and points to a confirmation-behavior precedent ('Same confirmation rules as {svc}_call_method'). It stops short of an explicit 'prefer hh_call_method when the endpoint IS in the catalog' exclusion, so the routing rule is implied rather than 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the description adds the valuable guarantee that secret values are never revealed and only set/unset status is reported. It also sketches the return shape, though the output schema already carries that detail.

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 short lines, front-loaded with the core purpose, then the security constraint, then the return shape. Every sentence earns its place and nothing is padded.

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 zero parameters, full annotation coverage, and an output schema present, the description is nearly complete: purpose, secrecy behavior, and return keys are all stated. The only gap is not tying the result to a next action (e.g., how to populate missing variables), which is a usage concern rather than a completeness failure.

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 takes no parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No parameter meaning is added or 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?

States a specific verb (check) and resource (required credentials in the environment), making the tool's job unambiguous. It is easily distinguished from siblings like hh_set_key or hh_call_method, which act on credentials or methods rather than reporting their presence.

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 is implied (run this before credential-dependent calls to see if the environment is ready), but the description never states when to use it, what to do when 'ready' is false, or how it relates to siblings such as hh_set_key. Adequate but leaves the agent to infer the workflow.

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 already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds that the record includes scope, safety level, pagination style and rate limit, which hints at what the agent learns, but it discloses nothing about auth requirements, error behavior, or whether unknown operation_ids are handled.

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?

A single front-loaded sentence with no filler. It is efficient, though the trailing field list is somewhat padded given an output schema already enumerates the return shape.

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 one-parameter read-only lookup with an output schema, the description covers the purpose but leaves the parameter unexplained and offers no routing guidance relative to its many siblings. Adequate but with a clear gap around how to obtain a valid operation_id.

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 0% and the single required parameter (operation_id) is never mentioned. The phrase 'for one endpoint' loosely implies an endpoint identifier, but nothing explains where an operation_id comes from (e.g., hh_search_methods) or its expected format.

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 (Return) and resource (full catalog record for one endpoint) and enumerates the record's contents, so an agent can tell it apart from hh_search_methods or hh_call_method. It stops short of naming a sibling explicitly, so it is clear but not fully differentiated.

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 sentence about when to use this over hh_search_methods (find endpoints) or hh_get_section (browse a section). The agent must infer that this is the pre-call inspection step from the purpose alone; no conditions, prerequisites, or alternatives are 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?

Annotations (readOnlyHint, openWorldHint) already cover the safety profile, but the description adds real behavioral value: it enumerates the pagination styles handled (offset, last_id, cursor Ozon v4/v5, page, WB lastChangeDate), the auto-derived array path, and a max_items hard cap to protect context. Truncation behavior is disclosed, though rate-limit/retry behavior is not.

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?

Purpose is front-loaded in the first sentence, followed by a compact Args block and a Returns line. The pagination-style sentence is dense but earns its place; structure is easy to scan with no 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 7-param tool with an output schema and read-only annotations, the description covers purpose, pagination mechanics, parameter roles, and the truncation/cap contract. Nothing essential to a correct invocation 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 0%, so the description must carry the load, and it documents all 7 parameters including the key default behaviors (items_path defaults to the endpoint's own path, max_items defaults to 10000, cursor fields auto-managed). It omits the limit default of 1000, so it is strong but not exhaustive.

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 opening sentence gives a precise verb+resource: it auto-paginates a read endpoint and returns every row in a single response. It clearly implies a pagination-wrapper role distinct from one-shot callers like hh_call_method, though it never names a sibling to sharpen that contrast.

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 signals that the target must be a read endpoint from the catalog and notes that cursor fields are managed for the caller, which implies when to reach for it. However, it never states when NOT to use it or explicitly points to hh_call_method/hh_call_raw as the non-paginating alternatives.

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 already cover the safety profile (readOnlyHint=true, openWorldHint=false), so the description's remaining duty is to add context. It discloses the return shape ('JSON list of {operation_id, method, path, safety, summary}'), which is a useful signal, but says nothing about output size, rate limits, or that safety fields are pre-computed.

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 docstring-style Args/Returns layout is front-loaded with the one-line purpose, then the parameter, then the return shape. Every element is relevant, though the Args/Returns scaffolding is mildly verbose for a one-parameter 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 read-only, single-parameter listing tool with an output schema present, the description covers purpose, parameter meaning, and child-section discovery adequately. The absence of any guidance on when this beats sibling retrieval tools is the main remaining 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 0%, so the description carries the full burden for the single parameter, and it does compensate: it names the field ('section'), explains what a section is, points to a discovery tool, and gives a concrete example ('statistics'). It stops short of documenting format constraints (e.g. case sensitivity), keeping it from a 5.

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 all endpoints in one section'), which is clearly narrower than the sibling hh_list_sections (which enumerates sections, not endpoints). It does not, however, explicitly contrast itself with routing-relevant siblings like hh_search_methods or hh_map, leaving that distinction to inference.

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 reference to '{svc}_list_sections' implies the workflow for discovering valid section names, giving implied usage guidance. There is no explicit statement of when to prefer this over hh_search_methods, hh_map, or hh_describe_method, and 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?

Annotations already establish readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds value beyond that by disclosing the secret-handling boundary ('Secret values are never returned') and the response shape, which reassures an agent about data exposure.

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; the purpose is front-loaded and the return-shape plus secret note follow compactly. No filler or repetition.

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 an output schema present and annotations covering the read-only/finite-world profile, the description is nearly sufficient as written. It could still note the relationship to hh_use_cabinet or that the list reflects this marketplace's configuration, but nothing required to call it correctly is absent.

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 takes zero parameters, so the baseline is 4 — there is nothing for the description to disambiguate. No parameter semantics are missing because none exist.

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 configured cabinets') scoped to 'this marketplace', and adds the distinguishing detail of which cabinet is active. Against siblings like hh_add_cabinet, hh_use_cabinet, and hh_remove_cabinet the read-only listing intent is unambiguous without opening any 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?

Usage is only implied: the verb 'List' signals a read-only inspection call, and the mention of an 'active' cabinet hints this is a prerequisite check before hh_use_cabinet. No explicit when-to-use statement, no named alternative, and no conditions are spelled out.

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 already establish read-only and non-open-world behavior. The description adds useful return context that each section includes an endpoint count, but it omits auth, pagination, or ordering details; with an output schema present, the added behavioral value is modest.

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?

A single front-loaded sentence with no wasted words. Every clause contributes distinct information: the resource type and the per-section endpoint count.

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 low-complexity list tool with no parameters, read-only annotations, and an output schema, the description is largely complete. It could still mention any authentication or scope prerequisite implied by the presence of hh_check_auth.

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 there is no parameter documentation burden. The baseline for zero-parameter tools is 4, and no semantic gaps exist.

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: listing API sections, plus the distinguishing detail that each section includes a catalog endpoint count. It is clear, but it does not identify sibling boundaries such as hh_get_section or hh_search_methods.

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 no when-to-use guidance, no prerequisites, and no alternatives. The list verb implies discovery usage, but nothing tells an agent when this is preferable to sibling tools like hh_get_section.

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 already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds valuable orientation context ('you are here', 'orients you fast') and usage hints, but doesn't describe the output format beyond the output schema's existence. It could mention whether the map is static or dynamic, but the added context is still useful.

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: the first sentence states the purpose, the second gives usage, the third gives a recommendation. No wasted words, and the structure is easy to parse.

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 role as an orientation map, the description is complete: it tells the agent what it gets, how to call it, and why to call it. With an output schema present, return details needn't be explained. The description sufficiently covers the tool's purpose and usage.

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 0%, so the description must compensate. It does: it explains that the single parameter 'entity' is optional (call with no args) and provides examples ('reviews', 'stocks/prices/orders'). It doesn't list all possible entities or mention the default value (empty string), but it gives enough to use the parameter correctly.

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 what the tool does: it provides a map of business entities and the go-to methods for each. It distinguishes itself from siblings like hh_search_methods or hh_describe_method by being a high-level orientation tool ('the big picture'). The verb+resource is specific: 'map' (verb) of 'business entities and methods' (resource).

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 when to use it: 'Use this before guessing — it orients you fast.' It also gives concrete usage patterns: call with no args to see the whole map, or pass entity='reviews' to list methods of one entity. This provides clear alternatives to other discovery tools like hh_search_methods.

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 already declare destructiveHint=true, so the safety profile is known. The description adds a genuinely non-obvious behavioral consequence: deleting the active cabinet promotes another to active, which the annotations cannot convey. It still omits irreversibility/recoverability and behavior for a nonexistent name.

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?

Front-loaded with the core action in one short sentence, then the side effect. The Args block is slightly redundant with the schema, but the overall size is appropriate and waste is minimal.

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?

An output schema exists, so return values need not be explained, and the tool is simple with one required param. However, the description says nothing about failure modes (unknown name), permanence of deletion, or auth requirements, leaving gaps for a destructive 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 coverage is 0% and the single parameter is undocumented in the schema, so the description must carry it. It only restates 'name: the cabinet to remove' with no format, lookup, or matching semantics (e.g., case sensitivity, whether name must match list_cabinets output). Marginal compensation for the coverage gap.

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+resource: 'Delete a stored cabinet.' It is distinguishable from add_cabinet, list_cabinets, and use_cabinet by the deletion framing, though it never explicitly contrasts itself with siblings such as use_cabinet or set_key.

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, no prerequisites, and no routing to alternatives. An agent gets no signal about whether removing an active cabinet is safe or whether use_cabinet should be called first. The only conditional provided ('if it was active, another becomes active') describes a side effect, 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuine context beyond that: bidirectional Russian/English search, a best-first result ordering, and the 1-50 limit bound. It does not mention pagination or result truncation behavior, a minor 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?

Compact and front-loaded, leading with the core action before the Args block. The Args block format is slightly boilerplate but each line 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?

With an output schema present, return-value detail is not required, and the description still notes the JSON list shape and ordering. Combined with the readOnly annotations, an agent has what it needs to call the tool correctly; only the missing default and pagination caveats hold it below 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?

Schema coverage is 0%, so the description carries the full burden and does so well: 'query' is defined as free text with three concrete examples, and 'limit' is described as max results with an explicit 1-50 range. It does not mention the default value of 15, which the schema supplies.

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 (search) and resource (endpoint catalog) and notes the keyword works in both Russian and English. This distinguishes it from siblings like hh_call_method or hh_list_sections, though it never explicitly contrasts with the other lookup tool hh_describe_method.

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 is implied: use it to find endpoints by keyword when you know a term but not the exact method. There is no explicit statement of when to prefer this over hh_describe_method, hh_list_sections, or hh_map, and no exclusions are 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?

Annotations already declare this is a non-read-only, idempotent, non-destructive write, and the description is consistent with that. It adds substantial context the annotations cannot convey: the key is written into the chat transcript, it is validated against the marketplace on success, the shop name is reported, and the file is saved locally with chmod 600 and never echoed back.

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?

Front-loaded with the core action and a prominent warning, then structured into Args and success sections; nearly every sentence earns its place. The security aside about scoped keys and the seller cabinet is useful but slightly beyond what is needed to invoke the 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 write tool with annotations and an output schema, the description covers the safety model (chat-exposure warning, confirmation flag), the side effects (local save, permissions), and the success signal (validation + reported shop name). The only gap, credentials field detail, is a schema/templating defect rather than a missing concept.

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?

With 0% schema description coverage the description must carry the load, and it does well for two of three params: cabinet defaulting to the active cabinet (with the shop-name/'main' fallback) and the mandatory boolean flag are both explained. However, the required credentials param is described only as 'dict with the required fields ({fields})' — an unsubstituted template placeholder that leaves the most important parameter undocumented.

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 ('Change / rotate the API key') and explicitly scopes it to a chat-driven rotation scenario. It also names the alternative path (the installer) and the sibling tools that handle non-key cabinet work, so an agent can distinguish it from hh_add_cabinet/hh_use_cabinet at a glance.

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?

Gives the triggering conditions ('the old one expired or leaked'), a required precondition (i_understand_key_goes_to_chat=true), and a named alternative (the installer, where the key never enters chat) plus remediation advice for exposed keys. Nothing is left to inference.

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 declare non-read-only, non-open-world, idempotent behavior, and the description adds the crucial stateful effect: the switch persists and changes credentials for all later calls. It does not cover failure modes (e.g. unknown cabinet name) or whether prior session state is discarded.

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 its consequence; the Args note is minimal and non-redundant. Nothing is wasted.

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?

An output schema exists, so return values need no explanation. The description covers action, side effect, and value sourcing for a one-parameter tool; only edge-case behavior (invalid name, effect on the previously active cabinet) is left implicit.

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 0%, so the description must carry the parameter. It does define the single param as the cabinet to activate and points to hh_list_cabinets as the source of valid values, which is the key semantic an agent needs.

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 ('Switch the active cabinet') and immediately names the consequence. It is clearly distinguishable from siblings like hh_list_cabinets, hh_add_cabinet, and hh_set_key, which manage rather than activate cabinets.

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 workflow context ('Subsequent API calls use its credentials') and routes the agent to hh_list_cabinets for valid names. It stops short of stating exclusions or error conditions, but the activation step's place in the sequence is clear.

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