list_environments

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

Annotations already establish readOnlyHint and openWorldHint, so the description doesn't need to repeat those. It adds meaningful behavioral context: the listing covers all environments visible via global discovery, not just the current one, and includes an allowed/not-allowed marker that gates usage of other tools.

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?

Two short sentences deliver the core purpose, scope, and a critical constraint. Every word earns its place, and the 'allowed' distinction is front-loaded in the second sentence where it matters.

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 zero-parameter read-only listing tool, the description is fully self-contained: it explains what is returned, the scope of discovery, and how the result should influence subsequent tool selection. No output schema is present, but the description compensates by describing the allowed/not-allowed marking.

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 has zero parameters, so there is no parameter burden for the description to carry. The baseline of 4 applies; the description appropriately focuses on output semantics rather than input details.

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 states a specific verb ('list') and resource ('Dataverse environments'), with a clear scope: global discovery for the signed-in account. It adds the key detail that each environment is marked allowed/not allowed, which distinguishes its purpose from the sibling tools that operate within a single environment.

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 clearly implies this is the discovery/listing tool to use before other environment-specific tools, and explicitly states that only allowed environments can be used by the other tools. It does not name alternates or exclusions explicitly, but the context is strong enough for an agent to know when to call it.

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