diadoc_set_key

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

Annotations only cover the safety profile (readOnly=false, idempotent=true, destructive=false); the description adds the substantive traits: the key lands in the chat transcript, a boolean acknowledgement is mandatory, the key is validated against the marketplace on success, the shop name is reported, and the secret is stored locally with chmod 600 and never echoed back. It also flags the security trade-off, which annotations cannot express.

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 purpose, then a warning block, then Args, then success behavior — a sensible scan order with little filler. The unresolved '{fields}' artifact and the mixing of warning prose into the arg list are minor structural blemishes.

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 mutation tool with a security caveat, the definition covers the required acknowledgement, the error mode (key validated against the marketplace), storage location and permissions, and the non-echo guarantee. An output schema exists, so return values needn't be spelled out.

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 all meaning, and it documents the cabinet defaulting behavior and the acknowledgement flag well. However, the required nested credentials object is described only as 'dict with the required fields ({fields})' — an unresolved template placeholder, so the agent still cannot learn which fields are required.

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') plus the scope ('from chat'), which separates it from siblings like diadoc_add_cabinet and diadoc_use_cabinet. An agent can identify the operation 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?

Gives explicit triggers ('the old one expired or leaked'), an explicit alternative ('the safe, terminal-free alternative is the installer, where the key never enters chat'), and follow-up advice (use a scoped key, rotate in the seller cabinet if exposed). This is the when/when-not/alternatives pattern done well.

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