kv_put

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

Annotations already provide readOnlyHint, destructiveHint, idempotentHint, openWorldHint. The description adds crucial context about the human-approval gate (confirm:true) and that without it, the tool returns a preview only. This goes beyond annotations by explaining the gating mechanism and non-executing preview behavior.

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 two sentences long, front-loaded with the core action, and contains no unnecessary words or phrases. Every sentence earns its place.

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 tool with 6 parameters and no output schema, the description covers the key action, optional TTL, and the confirmation gate. It mentions the preview return but lacks details on the preview format or success response. Overall, it is fairly complete but could elaborate on output behavior.

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?

Schema coverage is 100% with descriptions for all 6 parameters. The description adds value by highlighting the optional TTL and the confirm parameter as a safety gate, contextualizing their roles beyond the individual 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 clearly states the action ('Write a value to a key in a KV namespace') and specifies optional TTL. It distinguishes from sibling tools like kv_get, kv_delete, and kv_list_keys by indicating this is for writing/creating data.

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 implies usage for writing KV values, but does not explicitly say when to use this tool versus alternatives (e.g., kv_delete for removal, kv_get for reading). No when-not or alternative tools are mentioned.

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