ym_add_cabinet

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

The description adds substantial value beyond the annotations: it warns that the key enters the chat transcript, states the save location (~/.marketplace-mcp/cabinets.json) with chmod 600, and notes that the key is never echoed. This is exactly the kind of behavioral context the agent needs for a credential-handling write operation, and it does not contradict the annotations (readOnlyHint=false, idempotentHint=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?

The description is well-structured: the critical warning is front-loaded, arguments are clearly listed, and there is no unnecessary fluff. It is a bit longer than necessary due to the placeholder and examples, but overall it is efficient and scannable.

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 omits essential details for correct use: it does not specify the required credential fields for Yandex Market (the '{fields}' placeholder is never filled), nor does it explicitly state which marketplace this tool serves. Given that this is a write operation storing sensitive data, an agent would not be able to construct valid credentials without additional information.

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

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

With 0% schema description coverage, the description must explain all parameters. It does explain credentials (dict), name (optional with fallback), and the boolean flag. However, the credentials parameter uses a placeholder '{fields}' and only provides examples for Ozon and WB, not for the actual Yandex Market service this tool targets. This is a significant omission that prevents correct invocation.

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 adds or updates a cabinet (a named set of API credentials) from chat. The verb-resource pair is specific, but it fails to differentiate from sibling add_cabinet tools for other marketplaces (e.g., wb_add_cabinet, ozon_add_cabinet) — it doesn't mention Yandex Market and even gives examples for Ozon and WB, which could mislead the agent.

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 an explicit alternative (the installer) and a usage condition (requires i_understand_key_goes_to_chat=true), which helps the agent decide when to use this tool. However, it does not mention when to use this specific tool versus the other marketplace-specific add_cabinet tools, so the guidance is partial.

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