crpt_add_cabinet

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

The annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) are consistent with 'Add or update', and the description adds substantial context beyond them: the key is persisted into the chat transcript, a confirmation flag is mandatory, the data is stored locally at ~/.marketplace-mcp/cabinets.json with chmod 600 permissions, and credentials are never echoed. For a security-sensitive credential tool, this behavioral disclosure is exactly what an agent needs. No contradiction with 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: a purpose sentence, a critical security warning with the confirmation flag, an Args section with per-parameter detail, and storage info. Every sentence earns its place given the need to compensate for the schema and the security sensitivity. It is longer than minimal, but that length is justified; the only nit is the unresolved '{fields}' template placeholder which is slightly awkward.

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 security-sensitive tool with nested objects and 0% schema coverage, the description covers purpose, security implications, all three parameters with examples, storage location, and permissions. An output schema exists, so return-value documentation is not needed here. The minor gap is the unresolved '{fields}' placeholder and lack of failure-mode guidance (e.g., invalid credential handling), but overall the agent has 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?

With 0% schema description coverage, the description carries the full burden and delivers: credentials are explained with concrete per-service examples (Ozon: client_id/api_key; WB: token), name is documented with its fallback behavior (real shop name fetched from marketplace, else 'main'), and the confirmation flag's requirement is stated. This fully compensates for the empty schema descriptions.

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+resource: 'Add or update a cabinet (a named set of API credentials)'. This clearly distinguishes it from siblings like crpt_list_cabinets, crpt_remove_cabinet, and crpt_set_key. The 'from chat' qualifier also contextualizes the operation's environment. No ambiguity about 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?

The description explicitly flags the security-sensitive context (key enters chat transcript) and names a safe alternative ('the installer (install.py / double-click)'), which helps the agent decide when chat-based credential entry is appropriate. It also states the required precondition flag. However, it does not explicitly contrast against sibling tools like crpt_set_key or crpt_use_cabinet to explain when each is preferred, so the routing guidance is good but not exhaustive.

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