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

Goes well beyond the annotations: it warns that the credential enters the chat transcript, states the exact bypass flag required, documents the storage location, permissions (chmod 600), and that the value is never echoed back. The idempotentHint=true is corroborated by the 'add or update' framing.

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 destructive caveat before anything else, then structured Args with no filler. Given the 0% schema coverage, the parameter detail is load-bearing rather than redundant.

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 described. For a write tool that persists secrets, the warning, flag requirement, storage path, and per-service credential shapes are all present — nothing an agent needs to invoke it safely 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 the full burden and does so: it explains credentials as a service-dependent dict with concrete examples for Ozon and WB, describes name's default-name fallback behavior, and states that the acknowledgement flag must be true.

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 precise verb pair (add/update) on a well-defined resource, and even defines the resource inline as 'a named set of API credentials'. That definition cleanly separates it from siblings like vk_use_cabinet, vk_remove_cabinet, and vk_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?

Gives explicit prerequisites (i_understand_key_goes_to_chat=true) and names a genuine alternative path (the installer, where the key never enters chat). It does not, however, contrast the tool against its closest siblings (vk_set_key / vk_use_cabinet) when choosing between them.

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 and openWorldHint=true, but the description adds the actual gating protocol (confirm_write for writes, plus i_understand_this_modifies_data for destructive, and that nothing is sent otherwise) which the annotations cannot express. It also discloses the error-envelope behavior. It stops short of describing rate limits, auth prerequisites (cf. vk_check_auth), or idempotency.

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?

Tightly front-loaded: the core action is the first sentence, gating rules follow, then an Args block with one line per parameter, then a one-line return contract. No filler 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?

With an output schema present, the description needn't enumerate return fields, yet it still sketches the success/error envelope shape. For a generic dispatcher tool this covers gating, argument sourcing, and failure mode sufficiently 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% and there are 6 parameters, so the description carries the full burden and does: it defines operation_id, path_values, query, body, and the two confirmation booleans with their exact usage conditions. An agent can populate every argument from the description alone.

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: 'Execute one catalog endpoint by operation_id.' This is a precise, self-contained statement that distinguishes it from siblings like vk_search_methods (discovery), vk_describe_method (metadata), and vk_call_raw (substituting the sibling's role in the catalog flow).

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 clear operational routing: read endpoints run immediately, write and destructive endpoints are gated behind explicit confirmation flags. It also points to {svc}_search_methods as the source of operation_id. It does not explicitly contrast itself with vk_call_raw, which is the sibling an agent would most plausibly confuse it with.

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 flag readOnlyHint=false and destructiveHint=true; the description adds real value beyond them by explaining the per-verb safety model (GET=read, POST/PUT/PATCH=write, DELETE=destructive) and the confirmation parameters. It does not conflict with annotations (the global destructive flag is simply conservative), but it omits auth requirements and rate-limit/pagination behavior for a very open-ended tool.

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

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

Purpose is front-loaded, followed by the safety model, an Args block, and a one-line Returns note. Structure is clean and scannable; the 'Returns JSON' line is minor redundancy given an output schema exists, but nothing is egregiously wasteful.

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 7 parameters, 0% schema coverage, and a present output schema, the description covers parameters and return shape adequately and need not re-explain return values. It stops short of stating authentication/prerequisite requirements, which is the main missing piece for a tool that can hit arbitrary endpoints.

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 burden, and it does: method (with accepted verbs), path (with a concrete path example), host (defaults to service host), query, body, and the two confirmation flags. The confirmation parameters are only described as 'confirmations' without stating when each is required, which is the only meaningful 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 concrete verb and resource ('Execute ANY endpoint') and immediately scopes it with 'even ones not in the catalog (full API coverage)', which distinguishes the raw escape hatch from the catalog-based siblings like vk_call_method/vk_describe_method. An agent can tell what this tool is for without opening the schema.

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

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

The '(even ones not in the catalog)' clause implies when to reach for this over the catalog tools, and it points to a confirmation-rules sibling. However it never explicitly says 'use this instead of vk_call_method when the endpoint is unlisted', and the referenced '{svc}_call_method' placeholder is unresolved, so the routing is left partly 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 declare readOnlyHint and openWorldHint=false, lowering the bar. The description adds meaningful context beyond that: it will not reveal secret values, and it specifies the exact return shape (ready/missing/required), which is a valuable security-relevant disclosure for a credential tool.

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

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

Three short, front-loaded lines: purpose, behavioral caveat, return format. 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 no-arg, read-only check with an output schema present, the description covers purpose, safe behavior, and return shape. Nothing an agent needs to call it 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?

Zero parameters, so baseline is 4. The description correctly requires no arguments, aligning with 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?

States a specific verb (Check) and resource (required credentials in the environment), and the follow-up sentence clarifies the exact behavior (reports presence, not values). Among siblings, it's the only pre-flight/validation tool, so it is clearly distinguishable from call/section/cabinet 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?

Implied usage (verify before calling methods), but the description never states when to use it vs alternatives or that it should precede other VK calls. No explicit routing guidance is given.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds that the full catalog record is returned (method, host, path, scope, safety level, pagination, rate limit), but says nothing about whether an unknown operation_id errors or what happens for non-catalog endpoints.

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 dense sentence front-loads the purpose and the returned field list. It is efficient, though the long comma-separated field list is slightly list-heavy.

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-value detail is not required, and the field enumeration gives a useful preview. The main gap is guidance on selecting this tool over its siblings and the operation_id's provenance.

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 operation_id parameter is undocumented, so the description could have compensated but does not explain where an operation_id comes from or its format. Baseline 3 for a one-param 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?

Clear verb+resource: 'Return the full catalog record for one endpoint', and the enumerated fields make its scope concrete. It does not explicitly distinguish itself from vk_get_section or vk_search_methods, so it falls short of a 5.

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

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

Usage is implied by being the per-endpoint detail lookup against siblings like vk_list_sections and vk_search_methods, but there is no explicit when-to-use, when-not-to-use, or named alternative.

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 readOnlyHint=true and openWorldHint=true, so the safety profile is already covered. The description adds useful context: the max_items hard cap to protect context, automatic array-path detection, and the supported pagination styles. However, it doesn't disclose rate-limit behavior, error handling on mid-pagination failures, or what happens when truncated=true.

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, then structured Args section explaining each parameter, then a Returns line. Efficient and well-organized. The Returns line could be considered slightly redundant given an output schema exists, but it adds concrete field names in one compact sentence.

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, the description needn't explain return values in depth, yet it does list the return fields concisely. The parameter explanations cover all 7 params despite 0% schema coverage. The only gap is lack of explicit guidance on error handling during pagination and what 'truncated' means operationally.

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 provides meaningful semantics for each parameter: operation_id is 'a read endpoint from the catalog,' items_path overrides the default array path, limit is page size, max_items is a hard cap with default 10000. This adequately compensates for the empty schema descriptions across all 7 parameters.

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: 'auto-paginate a read endpoint and return every row in one response.' This clearly distinguishes it from the sibling vk_call_method, which presumably calls a single page. No explicit sibling differentiation by name, but the pagination-oriented purpose is unambiguous.

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

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

The description implies usage (when you need every row, use this instead of single-call alternatives) but never explicitly says 'use this instead of vk_call_method when you need all pages' or states exclusions. The parenthetical '(cursor fields are managed)' hints that some arguments are off-limits, but no explicit when-not guidance is provided.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safe-read profile is covered. The description adds that section names originate from the sibling list tool and sketches the return fields, but does not describe pagination, error behavior, or ordering.

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: the purpose leads, followed by a short Args block and a one-line Returns. Every element earns its place, though the Returns line partly duplicates the output schema.

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

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

An output schema exists, so the return-value explanation is not strictly needed, but the description still supplies the key calling context (where section names come from, an example value). For a single-parameter read tool 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 coverage is 0%, so the description must carry the burden, and it does: it identifies the parameter, explains it is a section name sourced from {svc}_list_sections, and gives a concrete example ('statistics'). It stops short of describing invalid-section behavior.

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 ('List all endpoints in one section'), which is clear and distinguishable from vk_list_sections (lists sections, not endpoints) and vk_describe_method. It doesn't explicitly name a sibling to differentiate, keeping it just below a 5.

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

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

The description gives implied usage by pointing to {svc}_list_sections for obtaining a valid section name, which is genuinely useful routing. However, it never states when to prefer this over vk_search_methods or vk_describe_method, 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 readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations by stating the return JSON shape and that secret values are never returned, which is important for an agent handling cabinet configuration.

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 purpose, followed by the return shape and a crucial security note. No wasted words; every sentence adds value.

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

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

For a simple read-only list tool with no parameters, full annotation coverage, and an output schema, the description is complete enough. It states purpose, return shape, and that secrets are not returned, giving an agent 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?

The tool has zero parameters, so the baseline is 4. The description appropriately does not invent parameter semantics and instead documents the return structure.

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 (List) and resource (configured cabinets for this marketplace) plus the extra detail of which one is active. This clearly distinguishes it from sibling tools that add, remove, or use cabinets, and from section/method listing tools.

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

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

Usage is implied by the purpose: call it to see configured cabinets and the active one. However, it does not explicitly state when to use this versus alternatives like vk_add_cabinet or vk_use_cabinet, nor does it mention prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds a useful behavioral detail — that each section is returned with an endpoint count — but says nothing about ordering, pagination, scope, or authentication needs, which for a discovery tool would be worth mentioning.

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 clause with zero waste, front-loading the verb and resource and appending the one piece of return-shape context that matters. Nothing could be cut without losing information.

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

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

A no-argument read tool with an output schema, so return values need not be described. The description is sufficient to invoke correctly, though it omits how this sections list relates to the sibling vk_get_section and vk_search_methods in the discovery workflow.

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 and schema coverage is 100%, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter-level claims are made 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?

The description states a specific verb and resource ('List API sections') plus the payload ('how many catalog endpoints each contains'), which is more informative than the bare tool name. It does not, however, differentiate itself from the closely named sibling vk_get_section or explain the catalog/section model, so an agent must infer the relationship.

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 mention of alternatives such as vk_get_section for drilling into a single section or vk_search_methods for finding endpoints. The agent is left to infer the intended first-step role of this tool.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral context: what calling with no args returns (the whole map, 'you are here') and what passing an entity returns (every method of that entity). No auth or rate-limit detail, but for a read-only discovery call this is informative.

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 tight sentences that front-load the purpose, then the two call modes, then the payoff. No filler, and the most important orientation cue ('you are here') is placed 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?

An output schema exists, so return shape need not be restated. For a low-complexity, parameterless-by-default discovery tool the description covers both invocation modes and its positioning. Only the relationship to the other discovery siblings 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 coverage is 0%, so the description carries the burden for the single entity param. It explains both modes: empty/no-arg returns the full map, while entity="reviews" (or stocks/prices/orders) scopes to one entity's methods, with concrete example values the schema lacks.

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 resource ('business entities this API covers and the go-to methods for each') with the verb of discovery implied by 'see the whole map'. An agent can tell it is an orientation/map tool, distinct from the action siblings like vk_call_method. It does not explicitly name which discovery sibling it supersedes (vk_list_sections, vk_search_methods), so it falls short of a 5.

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

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

'Use this before guessing — it orients you fast' gives a clear condition for when to reach for it, and the no-arg vs entity= usage is spelled out. No explicit exclusions or named alternatives (e.g. vs vk_search_methods) are provided, keeping it from a 5.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuine value beyond that by disclosing the cascading effect: if the deleted cabinet was active, another becomes active. It still doesn't say whether deletion is reversible or what happens on a missing 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?

The description is short, front-loaded with the action, and the Args block is minimal. It is close to optimal, though the args restatement adds little beyond the 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?

An output schema exists, so return values need not be described, and annotations cover the destructive profile. Combined with the active-cabinet cascade note, this is nearly complete; only error/precondition behavior is unaddressed.

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% for the single 'name' parameter, so the description must carry the burden. It does define the parameter as 'the cabinet to remove', but that only restates the field name without format, casing, or lookup semantics.

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

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

States a specific verb and resource ('Delete a stored cabinet'), which clearly separates it from siblings like vk_add_cabinet and vk_use_cabinet. The behavior is unambiguous, though it does not name an alternative or scoping condition explicitly.

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 when-to-use guidance, no prerequisites (e.g., must the cabinet exist, does it need to be inactive first), and no mention of alternatives such as vk_use_cabinet. The usage context is left entirely 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 declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds that queries work in Russian and English and that results are returned best-first, which is genuinely useful. It does not disclose anything further about the catalog's size, latency, or failure modes, so it sits at a solid-but-not-rich level.

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 purpose sentence is front-loaded, followed by a compact Args block and a one-line return note. 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?

An output schema exists, so return values need not be explained, yet the description still notes a JSON list of matching endpoints. Both parameters are documented and the language coverage is called out. The main gap is the absence of any pointer to the natural next step (vk_describe_method) after a search hit.

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, and it largely does: query is described as free text with concrete examples in both supported languages, and limit is bounded as 1-50 with its role as a max-result cap. It omits the limit default (15) that only the schema supplies, but the added meaning is substantial.

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: 'Search the endpoint catalog by keyword'. It also names the catalog scope and the bilingual capability, which distinguishes it from the sibling catalog tools. It stops short of explicitly contrasting itself with siblings like vk_describe_method or vk_list_sections, but the purpose is unambiguous.

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

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

Usage is implied — an agent would use this to find an endpoint before describing or calling it. However, there is no explicit statement of when to prefer this over vk_list_sections or vk_get_section, nor any prerequisites or exclusions. The 'best first' ordering hints at intent but does not define a 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?

Beyond the annotations (readOnly=false, idempotent=true), it discloses security-relevant behavior: the key enters the chat transcript and requires i_understand_key_goes_to_chat=true, the key is validated against the marketplace, saved locally with chmod 600, and never echoed back. This is rich context an agent cannot get from the annotations alone.

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

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

Front-loads the purpose and a prominent warning, then uses a structured Args section and a success-behavior line. Slightly long but every section earns its place; the unfilled '{fields}' placeholder is the only sloppy artifact.

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 description still covers validation, local persistence, and non-echo behavior. It is nearly complete, held back only by the unresolved credentials field list for the sole required parameter.

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 coverage the description must carry parameter meaning, and it does well for 'cabinet' (default = active cabinet, with fallback naming logic for shop name or 'main') and the comprehension flag (must be true). However 'credentials' is only described as 'dict with the required fields ({fields})' where the placeholder was left unfilled, leaving the most important required parameter's fields unspecified.

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 from chat') and immediately scopes the trigger ('old one expired or leaked'). It is clearly distinguishable from sibling cabinet tools like vk_add_cabinet and vk_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?

Gives explicit when-to-use ('my key expired'), an alternative path (the installer where the key never enters chat), and a security recommendation to use scoped keys and rotate in the seller cabinet if exposed. 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 provide readOnlyHint=false, openWorldHint=false, and idempotentHint=true, covering safety and idempotency. The description adds the key behavioral note that subsequent API calls use the new cabinet's credentials, but does not mention side effects like preserving or invalidating prior credentials or error conditions.

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: one main sentence plus a single arg note. Front-loaded with the action. The reference to {svc}_list_cabinets is slightly awkward with the placeholder but efficient.

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

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

With an output schema present, return details are covered. The description explains the core effect (credential switch) but omits what happens on invalid name, whether the active cabinet is changed permanently, and any required prerequisites. For a state-changing operation, more behavioral context would help.

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 must compensate. It says 'name: the cabinet to activate (see {svc}_list_cabinets)', which clarifies the parameter's meaning and points to a source for valid values. However, it doesn't specify format, case sensitivity, or whether the name must already 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: switch the active cabinet, and clarifies the effect on subsequent calls. This distinguishes it from siblings like vk_add_cabinet or vk_remove_cabinet, though it could more explicitly state what it is not (e.g., not adding or removing).

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 use when you need to change the active cabinet, but does not explicitly state when to use this versus vk_add_cabinet or vk_set_key. It references vk_list_cabinets for name lookup, which is a helpful pointer but not a full usage guideline.

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