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

Beyond the annotations, the description discloses that the API key is placed into the chat transcript, requires an explicit acknowledgment flag, is saved locally to ~/.marketplace-mcp/cabinets.json with chmod 600, and is 'never echoed.' These are critical security-relevant behaviors, fully fitting the add/update operation without contradicting the idempotentHint.

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 well-structured: a one-sentence purpose, a high-visibility security warning, and a compact Args block. Every sentence contributes necessary information, and the most decision-relevant fact (key goes to chat) is front-loaded.

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

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

Having an output schema reduces the need to document return values, and the description otherwise covers purpose, parameter details, storage location, permissions, transcript exposure, and alternative workflows. Nothing an agent needs to safely invoke this tool 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?

With schema description coverage at 0%, the description carries full responsibility for parameter semantics and succeeds: credentials is explained with concrete examples for Ozon and WB, name is described as an optional label with fallback behavior to shop name or 'main', and i_understand_key_goes_to_chat is documented as a mandatory gate. This is far richer than the bare input 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 begins with a specific action and resource: 'Add or update a cabinet (a named set of API credentials), from chat.' This clearly separates the tool from siblings like hh_list_cabinets, hh_remove_cabinet, and hh_use_cabinet by focusing on creating/updating a credential-storing cabinet rather than querying, removing, or selecting it.

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 explicitly tells the agent when the tool is appropriate ('from chat') and when to avoid it, naming the installer as 'the terminal-free safe alternative' where the key 'never enters chat.' The requirement that i_understand_key_goes_to_chat must be true provides a concrete condition that gatekeeps usage.

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?

The description adds useful behavioral context beyond the readOnlyHint annotation, such as 'runs without confirmation' and the return envelope '{"ok": true, "status", "data"} or the error envelope.' This tells the agent the operation is safe and what response shape to expect. There is no contradiction with the annotations.

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 tightly structured: a one-sentence purpose, a short scope note with explicit alternatives, then a clean bulleted args list. Every sentence earns its place with 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?

The description covers the target API URL, read-only scope, execution without confirmation, all argument meanings, and the response/error envelopes. It does not mention authentication specifics or endpoint-specific parameter key constraints, but the sibling tools and output schema fill most gaps. For a generic catalog-driven read executor, this is sufficiently complete.

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

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

Schema description coverage is 0%, so the description carries full weight for parameter meaning. It explains operation_id as 'id from the catalog (see hh_search_methods)', path_values as 'values for {placeholders} in the path', query as 'query-string parameters', and body as 'JSON request body (a few read endpoints take one).' This is concise and adds real value beyond the unannotated 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 READ endpoint from the catalog by operation_id.' It clearly narrows the scope to read-only operations and distinguishes itself from write/delete siblings by naming them. This goes far beyond the title 'HH read catalog method' and tells an agent exactly what the tool does.

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

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

Explicit usage guidance is provided: 'Reads only: nothing here changes data, so it runs without confirmation. To change data use hh_write_method, to delete use hh_delete_method.' It also tells the agent where to find operation_id by referencing hh_search_methods. This clearly routes the agent to the right tool for the right situation.

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?

The description goes beyond the readOnlyHint annotation by explicitly stating it does NOT reveal secret values, which prevents the agent from expecting credential contents. It also documents the JSON response shape, adding useful behavioral context.

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

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

The description is compact and front-loaded: the core purpose appears in the first sentence, the security-relevant behavior in the second, and the return format in the third. Every sentence earns its place with no redundancy.

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

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

The tool has no parameters, an output schema, and annotations indicating read-only behavior. The description fully covers what an agent needs to know: what is checked, what is not revealed, and what the result looks like.

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 zero parameters, there is nothing to explain beyond the schema. The description still adds value by clarifying what the returned fields mean, which is the relevant semantic content for this tool.

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

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

The description clearly states the tool's purpose: checking whether required credentials are present in the environment. It distinguishes itself from the sibling operations by focusing on environment readiness rather than any data access or mutation.

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 explicit when-to-use guidance is provided, nor are alternatives mentioned. The context makes it inferable that this is a prerequisite check before operations requiring credentials, but the description does not explicitly direct the agent.

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 set destructiveHint=true, but the description adds beyond that: it states the operation 'deletes or irreversibly changes data,' emphasizes that no request is sent without both confirmation flags, and discloses the JSON return envelope. This gives the agent concrete behavioral expectations beyond the annotation hints.

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 front-loaded with the destructive warning, then states the target API, required safety flags, and parameter meanings in a compact structured list. No sentence is wasted; the return format and error envelope are included without bloat.

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 destructive tool with six parameters and no schema descriptions, this is complete: it names the target API, explains each argument, enforces the confirmation flags, points to hh_search_methods for operation_id, and describes the response shape. An agent has enough context to select and invoke the tool correctly.

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

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

Schema description coverage is 0%, so the description must fully compensate. It explains all six parameters: operation_id from the catalog, path_values for placeholders, query for query-string parameters, body for JSON request body, and both confirmation booleans. This is strong coverage for every schema field.

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

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

The description clearly identifies a specific verb and resource: 'Execute one DESTRUCTIVE endpoint: deletes or irreversibly changes data.' It also ties the tool to a concrete target API and distinguishes it as the destructive counterpart to other call/write methods. The scope is unambiguous and not a tautology of the tool name.

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

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

The description makes usage conditions explicit: both confirm_write and i_understand_this_modifies_data must be true, and 'nothing is sent without both.' It also tells the agent where to obtain operation_id via hh_search_methods. It does not explicitly name sibling tools to avoid, but the destructive-purpose framing makes the appropriate context clear.

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

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

Annotations already mark destructiveHint=true and readOnlyHint=false, but the description adds essential context: the mandatory confirmation flags, the return format ('{"ok": true, "status", "data"} or the error envelope'), and the openWorld scope ('any path'). This goes beyond what annotations alone provide, though it does not explicitly warn about irreversibility beyond the confirmation requirement.

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 efficiently structured: a clear one-sentence purpose, a short note on the target API, a safety requirement line, then a bulleted Args list. It front-loads the key differentiator and the confirmation requirement, with no filler or redundancy.

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?

It provides the target API link for reference, specifies the required parameters and their values, and describes the return format. It doesn't cover error codes in detail but mentions the 'error envelope,' and given the tool's raw nature, this is reasonably complete for an agent to call it correctly.

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

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

With 0% schema description coverage, the description compensates well: it explains each parameter in the Args list—path format ('full path beginning with /'), method ('DELETE'), host override, query-string parameters, JSON body, and the two required boolean flags ('must be true'). This adds meaning that the schema titles alone lack, though it could give more detail on query/body formats.

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 ('Delete'), a resource ('data'), and a precise scope ('ANY path, including paths not in the catalog'), which clearly differentiates it from catalog-based operations like hh_delete_method. It also specifies 'DELETE only' and the target API, so an agent understands exactly what the tool does and how it differs from siblings.

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

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

The description implies when to use it: for deleting at arbitrary paths not in the catalog, and it explicitly requires confirm_write=true and i_understand_this_modifies_data=true, signaling this is for deliberate destructive operations. However, it does not explicitly name alternatives like hh_delete_method or state when NOT to use it, leaving some inference to the agent.

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?

The description adds substantial behavior beyond the annotations: it discloses auto-pagination handling of offset/last_id/cursor/page/WB lastChangeDate, that array path is resolved automatically, cursor fields are managed, and that max_items is a hard cap with a truncated flag. This is exactly the kind of behavioral disclosure annotations don't cover.

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?

It front-loads the core purpose in two sentences, then provides a compact bullet-style Args list. Every sentence adds operational value, with defaults in-line and unusual mechanics (array path, cursor handling) explicitly mentioned. 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?

Given the tool's many parameters, zero schema descriptions, and generic pagination role, the description is impressively complete. It explains expected result format, pagination style compatibility, path extraction, cursor management, and safe limits. The output schema presumably covers field details, so nothing essential is missing.

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

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

Schema description coverage is 0%, so the description carries all parameter semantics. It explains operation_id, query/body/path_values as base parameters, cursor fields being managed, items_path as the override path, limit as the page size, and max_items as the context cap. This fully compensates for the sparse 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 opens with 'Auto-paginate a read endpoint and return every row in one response', which is a specific verb+resource statement. It also enumerates the pagination styles it supports and returns envelope details, and the contrast with sibling tools like hh_call_method makes its role as a fetch-all helper clear.

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

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

The description clearly says when to use it: when you need every row from a read endpoint. It also warns about the max_items cap, which is useful guidance. However, it does not explicitly name alternatives such as a single-page call method, so there is no explicit when-not-to-use detail.

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 mark readOnlyHint=true and openWorldHint=true, but the description adds concrete behavioral detail: allowed verbs are GET/HEAD/OPTIONS, host defaults to the service default, and responses are wrapped in a JSON envelope. This adds meaningful context beyond the boolean hints, though it does not deeply discuss error or auth behavior.

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

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

The description is tightly written: a one-sentence purpose, a target API reference, a safety rule with sibling routing, and a compact parameter list. There is no filler, and the most important usage constraint (safe verbs) appears early.

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 open-world read nature, the description covers the API target, allowed verbs, all parameter semantics, and the return envelope. It also notes that the body is sometimes needed even on reads, which is a non-obvious detail. An agent has sufficient information to invoke 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 for parameter meaning. It explains all five parameters: path requires a leading '/', method defaults to GET, host is an override, query contains query-string parameters, and body is rarely needed. This fully compensates for the schema's bare titles.

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 opens with a specific verb and resource: 'Read ANY endpoint by path, including ones missing from the catalog.' It clearly distinguishes this raw read tool from catalog-based or mutation siblings by naming hh_write_raw and hh_delete_raw as the alternatives for changing/deleting data.

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

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

The description explicitly states when to use this tool: for read-only access to any endpoint by path, including uncataloged ones. It also provides direct routing guidance: 'To change data use hh_write_raw, to delete use hh_delete_raw,' and constrains usage to safe verbs only.

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 and openWorldHint, covering the safety profile. The description additionally specifies the output shape and the 'one section' scoping, which adds some value but does not discuss error handling, pagination, or edge cases. That is acceptable given the tool's simple read-only nature.

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

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

The description is two compact sentences plus a brief Args section. The purpose is front-loaded, parameter guidance is concise, and the output shape is stated in one line with no wasted words.

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 one simple parameter and an existing output schema, the description covers the essential workflow: which tool to use to get the param value, and what the result looks like. It doesn't mention invalid section behavior, but that is manage in normal MCP error messages and doesn't impair the ability to call the tool correctly.

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

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

Schema coverage is 0%, so the description carries the full burden of explaining the single `section` parameter. It compensates well by giving the meaning, an example, and a pointer to hh_list_sections for the authoritative list of values.

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 opens with 'List all endpoints in one section' – a specific verb (list), a concrete resource (endpoints), and a narrowed scope (one section). This clearly differentiates it from sibling tools like hh_describe_method (single method) and hh_search_methods (search-based).

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

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

The description gives clear context: the tool enumerates endpoints in a single section, and it explicitly points the agent to hh_list_sections for valid section names. It stops short of naming alternative tools for other use cases (e.g., hh_describe_method for one endpoint), but the implied usage is straightforward.

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, so the safe-read behavior is known. The description adds meaningful context by spelling out the return JSON shape, including the fields_needed property, and by promising 'Secret values are never returned' – a useful safety guarantee beyond the annotations.

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?

Very concise: the purpose is front-loaded in the first sentence, and the remaining two sentences describe the return format and a safety guarantee. No filler, no redundant restating of the input schema.

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

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

For a zero-parameter, read-only list tool with an output schema, the description fully covers what it returns (active, cabinets, fields_needed) and the 'secrets never returned' caution. An agent has everything it needs to call it correctly and interpret the result.

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?

No parameters exist (0 params, schema coverage 100%), so the baseline is 4. The description's mention of fields_needed in the output is a return-value detail, not parameter semantics, and the tool requires no input, so nothing more is needed.

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

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

The description states a specific verb and resource: 'List configured cabinets...' and adds the marketplace and active-cabinet scope. This clearly distinguishes it from sibling hh_list_sections (a different resource) and from the cabinet-mutation siblings (hh_add_cabinet, hh_remove_cabinet, hh_use_cabinet).

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

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

Usage context is implied: use this to see configured cabinets and which is active. However, it never explicitly contrasts with hh_list_sections or states exclusions/alternatives, leaving the when-not-to-use guidance 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 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?

The description discloses key behavioral traits beyond the readOnlyHint annotation: it explains the output for no args ('the whole map') and with an entity ('list every method of one entity'). It also hints at the output structure ('you are here') and the utility as an orientation aid. This adds meaningful context about how the tool behaves without contradicting the annotations.

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

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

The description is two concise sentences with the core purpose front-loaded ('The big picture...') and usage details in the second. Every clause earns its place, providing purpose, behavior, and usage guidance without redundancy.

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 one-optional-parameter tool with an output schema, the description is largely complete. It explains the purpose, the parameter's behavior, and when to use it. It doesn't detail the output format or error handling, but the output schema covers the structure, and for a read-only map tool, this is sufficient. Minor gaps remain, such as what happens with an invalid entity, but these are not critical.

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

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

The schema provides no description for the 'entity' parameter, but the description compensates by explaining its effect: passing an entity filters the map to that entity's methods, and omitting it returns the whole map. It gives concrete examples ('reviews' or stocks/prices/orders) and clarifies the optional nature. This meaningfully adds to the schema.

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

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

The description clearly states the tool's function: it provides 'the big picture: business entities this API covers and the go-to methods for each.' It differentiates from siblings by positioning itself as an orientation/discovery tool, explicitly saying 'Use this before guessing.' The optional entity parameter is explained, distinguishing it from listing or execution tools.

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

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

The description gives a direct usage guideline: 'Use this before guessing — it orients you fast.' It also demonstrates usage patterns: calling with no args for the whole map, or passing an entity to list methods for that entity. While it doesn't name specific sibling tools as alternatives, the intent is clear that this is for initial orientation rather than specific operations.

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 mark the tool as destructive (destructiveHint: true), so the description's 'Delete' is consistent. It adds a valuable behavioral detail: 'If it was active, another becomes active,' which is not evident from annotations. This gives the agent insight into side effects beyond the destructive action, earning above baseline.

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

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

The description is extremely concise: one sentence plus an argument explanation. There is no fluff; every word earns its place. The main action is front-loaded, and the parameter clarification follows immediately. This is ideal for an agent to parse quickly.

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

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

For a single-parameter delete operation with an output schema available, the description covers the essential information: what it does, the effect on active status, and the parameter meaning. It does not need to explain return values since the output schema exists. The description is complete enough for an agent to invoke it correctly without additional context.

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

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

The input schema provides only 'name' as a string with a title, no description. Schema description coverage is 0%, so the description must compensate. The line 'name: the cabinet to remove' clarifies exactly what the parameter refers to, adding meaning beyond the schema. It is concise but sufficient.

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 ('Delete') and resource ('stored cabinet'), making the tool's purpose unambiguous. It clearly distinguishes this from siblings like hh_add_cabinet and hh_use_cabinet without needing to reference them. The action is clear: removing a cabinet.

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 clearly indicates when to use the tool: when a cabinet needs to be deleted. It does not explicitly name alternatives or conditions for not using it, but the context (deleting a cabinet) is self-evident given the sibling list. The absence of explicit exclusions is acceptable for a simple delete operation.

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 mark readOnlyHint=true and openWorldHint=false, so the safety profile is known. The description adds value by disclosing the bilingual search capability, result ordering (best first), and that it returns a JSON list.

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

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

The description is compact, front-loaded with the main purpose, and uses a clear Args block. Every sentence contributes useful information without redundancy.

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

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

For a two-parameter read-only search tool, the description covers purpose, parameter semantics, language behavior, result format, and ordering. An output schema exists, so detailed return fields are not required here.

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

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

Schema coverage is 0%, so the description carries full parameter documentation. It explains query as free text with concrete examples and defines limit as max results with a 1-50 range, both beyond what the bare schema provides.

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?

Description states a specific verb (search) and resource (endpoint catalog) with clear scope: keyword-based search in Russian and English. It differentiates itself from siblings like hh_list_sections and hh_describe_method by being the search-oriented tool.

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 makes the use case clear: find endpoints by keyword when you don't know the exact endpoint. However, it does not explicitly mention alternatives or when not to use this tool, leaving some routing 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?

Beyond the annotations, the description discloses that the key enters the chat transcript, requires a confirmation flag, is validated against the marketplace, is saved locally with chmod 600, and is never echoed back. This is rich behavioral context that materially informs an agent about side effects and security implications.

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 longer than average but every section earns its place: the warning, alternative guidance, argument semantics, and success behavior. The security caveat is front-loaded, and the Args section is cleanly separated, though the placeholder '{fields}' adds a small blemish.

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?

Covering security caveats, defaults, validation, local persistence, and a terminal-free alternative, this description leaves little for an agent to infer. The presence of an output schema covers return details, and the description still adds expected success behavior (shop name reported).

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 explain 'cabinet' defaults and the safety flag, but the sole required parameter 'credentials' is only described as 'dict with the required fields ({fields})' — a placeholder that leaves the actual required fields unresolved.

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 opens with a specific action, 'Change / rotate the API key from chat,' which clearly identifies the resource and mode of operation. It also distinguishes itself from sibling tools by explicitly contrasting with the installer alternative and naming the context (expired/leaked 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?

The description explicitly says when to use the tool ('e.g. the old one expired or leaked') and points to the safer alternative (the installer) where the key never enters chat. It also advises rotating scoped keys in the seller cabinet if exposed, giving the agent clear routing 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 idempotentHint=true and readOnlyHint=false. The description adds useful behavioral context: that it changes the active cabinet and that credentials are applied to subsequent calls. It does not contradict annotations and provides value beyond them, though it doesn't mention edge cases like error handling or persistence.

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

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

The description is exceptionally concise and well-structured. The purpose is stated in the first line, followed by a one-sentence explanation of the effect. The parameter documentation is minimal but clear, and there is no wasted verbiage.

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 one-parameter tool with an output schema (which presumably documents any return value), the description covers everything an agent needs: what it does, what the parameter means, and where to find valid values. It is complete for its scope.

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

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

The schema only defines 'name' as a string with no description. The description explains that 'name' is the cabinet to activate and points to hh_list_cabinets for valid values, adding meaningful guidance beyond the schema. With 0% schema coverage, this compensation is sufficient, though it could specify format or case-sensitivity.

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

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

The description clearly states the verb 'Switch' and the resource 'active cabinet', and it explains the consequence (subsequent API calls use its credentials). This distinguishes it from siblings like hh_list_cabinets, hh_add_cabinet, and hh_remove_cabinet, so an agent knows exactly what this tool does.

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

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

It implies usage context by stating that subsequent calls use the cabinet's credentials, which tells the agent when to invoke this tool (before calling methods that need a specific cabinet). It references hh_list_cabinets for valid names, but does not explicitly state when not to use it or name alternative tools. This is clear context but lacks explicit exclusions, so a 4 is appropriate.

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

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

The description goes beyond the annotations by disclosing the critical safety behavior that no request is sent unless confirm_write=true. It also clarifies the tool is for create/update rather than destructive actions, aligning with destructiveHint=false, and describes the response envelope including the error case. There is no contradiction with the annotations.

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 well-structured: it front-loads the core purpose, then gives safety guidance, sibling routing, a concise argument list, and return format. Every sentence serves a purpose and there is no fluff.

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 generic write dispatcher, the description covers the essential operational details: target API, confirmation requirement, sibling tool boundaries, argument semantics, and response shape. It also points to hh_search_methods for discovering operation_id, making the tool usable without external documentation.

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 so by explaining operation_id as the catalog id, path_values as placeholder values, query as query-string parameters, body as JSON request body, and confirm_write as required true. This adds meaningful context beyond the raw schema, though it could be slightly more specific about exact formats or examples.

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

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

The description clearly states the tool executes one WRITE endpoint from the catalog to create or update data. It also differentiates itself from sibling tools by explicitly naming hh_delete_method for irreversible operations and hh_call_method for reads, so an agent can distinguish it immediately.

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 explicit usage guidance: requires confirm_write=true, nothing is sent without it, and routes irreversible operations to hh_delete_method and reads to hh_call_method. It also directs the agent to hh_search_methods for operation_id lookup, which tells the agent exactly how to use this tool in the broader 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=false and destructiveHint=false, so the basic safety profile is known. The description adds value by requiring confirm_write=true, which indicates a deliberate confirmation mechanism for writes, and it mentions the return envelope. It does not disclose potential side effects or failure modes beyond the error envelope, but it does not contradict annotations.

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 front-loaded with the core purpose in the first sentence, followed by concise details. The Args list is necessary because the schema lacks descriptions, and it is structured and readable. It is not overly verbose; every sentence contributes, though the list makes it slightly longer than a purely minimal description.

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 6 parameters, no schema descriptions, but an existing output schema, the description covers all essential information: method, path format, host, query, body, confirm flag, and the return JSON shape. It also points to the target OpenAPI spec. It does not elaborate on error handling beyond 'error envelope', but the output schema already provides that structure, so overall completeness is high.

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 schema description coverage at 0%, the description fully compensates by listing each parameter with meaningful constraints: method is restricted to POST/PUT/PATCH, path must be a full path beginning with '/', host and query are optional overrides, body is JSON, and confirm_write must be true. This goes far beyond the bare schema types and gives clear behavioral requirements.

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 opens with 'Create or update data at ANY path, including paths not in the catalog.' This is a specific verb (create/update), a clear resource (data at any path), and it distinguishes itself from catalog-scoped tools by explicitly covering non-catalog paths, which differentiates it from siblings like hh_write_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?

The description provides clear context: it states acceptable HTTP methods (POST, PUT, PATCH), requires confirm_write=true, and specifies the path must begin with '/'. While it does not explicitly name alternatives or exclusion cases, the 'any path' scope implies it is the general write tool, giving sufficient context for when to use it.

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