ym_add_cabinet

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

Beyond annotations, the description discloses critical behaviors: the key goes into the chat transcript, confirmation is required, the cabinet is saved to ~/.marketplace-mcp/cabinets.json with chmod 600, and credentials are never echoed. This goes well beyond the annotations and is highly valuable for safe use.

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: purpose, warning, safe alternative, args, and persistence details. It front-loads the most important risk. The placeholder and off-service examples add some noise, but overall it is appropriately sized and organized.

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 safety, storage, naming fallback, and the confirmation flag well. However, it lacks the actual resolved credential fields for YM and does not clarify how 'update' matches an existing cabinet. For a credential-writing tool, those are important gaps.

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 description documents all three parameters: credentials as a dict, name as optional with a fallback naming behavior, and the required confirmation flag. However, the central credentials field still contains an unresolved placeholder '{fields}', and the examples are for Ozon and WB, not YM. Since the schema only has additionalProperties with no descriptions, an agent still cannot reliably construct valid YM credentials.

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+resource: 'Add or update a cabinet (a named set of API credentials), from chat.' This is specific and understandable. However, it does not explicitly differentiate itself from sibling tools like ym_set_key or ym_use_cabinet, which could overlap with 'update' behavior.

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: this is the chat-based path for adding/updating credentials, and it warns that the key enters the chat transcript. It names a safe alternative (install.py / double-click) for when that is not acceptable. It does not enumerate sibling-tool alternatives, but the when-not guidance is explicit.

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