List environments

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond that: values are never returned, variables must be referenced as {{name}}, and secrets resolve from the developer. Only the absence of any note on environment ordering/scoping keeps it from a 5.

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 core listing behavior, followed by the value-redaction rule and the secret-resolution guidance, each of which earns its place. The final clause on --var-from-env is slightly dense but remains useful.

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?

An output schema exists, so return-value details need not be restated, and the description covers the two things an agent must know: values are redacted and how to reference variables. Complete for a zero-param listing tool, though it leaves environment scope relative to siblings implicit.

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?

The tool takes zero parameters, so the schema carries no semantics to supplement. Baseline 4 applies; nothing in the description misleads about inputs.

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 ('List the environments') and precisely describes the returned content: variable names, the active environment, and session-valued variables. An agent can distinguish this read-only discovery tool from set_environment/set_variables without opening the sibling schemas.

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 gives actionable context for its use: it notes that secret values come from the developer and instructs the agent to ask the developer to pass missing ones with --var-from-env. It stops short of explicitly naming alternatives like set_environment, so a 4 rather than a 5.

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