vk_set_key

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.