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

Annotations mark the tool destructive and non-idempotent, and the description adds substantial context beyond them: raw values are never returned in any response, values are stored in Vault and encrypted at rest, disable is explicitly reversible while delete destroys Vault material and tombstones the metadata row. It also documents the reserved-name rejection surface and that LUMIBOT_SCHEDULED_* values are BotSpot-managed, which an agent could not infer from annotations alone.

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 per-action structure is front-loaded and scannable, but there is heavy duplication: the entire reserved-prefix block is repeated verbatim under both list and create, and 'Raw values are never returned' recurs in four separate sections. Roughly a third of the text is redundant, which costs a definition that is otherwise well organized.

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 six-action tool with a single flat schema and no output schema, the description covers what it needs to: required fields per action, returned metadata fields (displayName, keyNames, status, timestamps), what is never returned, downstream consumers of the ids, and the delete-blocking condition. An agent has everything needed to pick an action and build a valid call.

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 description coverage is 100%, so the baseline is 3, but the description adds real meaning on top: it maps each parameter to specific actions, explains that variableName may be omitted on update (existing single key name is reused), and clarifies the relationship between displayName metadata and the stored key. It does not add format or length guidance beyond the schema, which caps it below 5.

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 opening sentence names the resource (saved environment variables) and every verb the tool supports, then reinforces it with a per-action heading for each of the six operations. It also distinguishes itself from a sibling by warning against storing broker credentials when create_broker_credential can represent them, and it states downstream use of returned ids (start_deployment.envVarSetIds, backtest equivalents).

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?

Each action section states required fields and when that action is the right one, e.g. create is for 'non-broker runtime secrets such as data-provider API keys' and explicitly not for broker credentials. Exclusions and prerequisites are also spelled out: reserved prefixes are rejected, and delete is refused while any saved runtime preference still references the variable, so references must be detached first.

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