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

Annotations only say destructive/non-idempotent/open-world; the description adds substantial context beyond that: create errors on an existing identifier, update replaces each passed section wholesale while leaving omitted sections unchanged, env-var and file delivery only apply on container (re)start so running containers keep the old value, secret values are never returned, and preview changes nothing. These are exactly the behavioral traits 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?

Long but dense and well-organized into purpose, variable model, secret rule, action semantics, and preview workflow, with the purpose and the preview rule front-loaded. Almost every sentence carries operational weight; a small amount of the scope/access/source exposition overlaps with the schema, keeping it short of a 5.

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 complex 11-parameter nested tool with no output schema, the description supplies the full picture an agent needs: the object model, create-vs-update semantics, restart timing, secret handling, and the mandatory preview-confirm-commit loop. Nothing required to invoke it correctly is missing.

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%, so the baseline is 3, but the description earns above baseline by explaining the conceptual model behind the nested objects — scope (which containers receive it), access (env var/file/internal API), source (raw vs URL-fetched with optional auth) — plus the secret:true requirement and new_identifier rename semantics. It adds meaning beyond field-level descriptions, though it stops short of covering every parameter.

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 pair (create/update) and resource (scoped variable), then defines what that resource is — an environment-level value or secret injected into containers at runtime. It also explicitly carves itself out from siblings by noting it cannot delete and pointing to list_scoped_variables. An agent can distinguish this from list_scoped_variables and the delete_* tools without opening any 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 an explicit ordered workflow: call list_scoped_variables first, always call with preview:true first, get user confirmation, then call again without preview. It also names the one thing it cannot do (delete). When-to-use and the correct call sequence are both spelled out rather than left to inference.

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