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

Annotations already declare destructive=true, idempotent=true and readOnly=false, yet the description still adds substantial value: irreversibility, the two hard preconditions, the downstream effect on game servers resolving the configuration by alias, and that the deletion executes immediately rather than being staged for approval. This is exactly the kind of blast-radius detail 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?

Front-loaded with the action, then consequences, then preconditions, then the reason requirement — a logical order with no filler. "This cannot be undone from here" and "The delete happens when this runs" are close in intent (irreversibility vs synchronous execution) but read slightly redundant.

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 destructive, no-output-schema operation this covers timing, failure preconditions and side effects well. It omits permission/authorization requirements and what an error response looks like when a precondition blocks the delete, which an agent handling failures would want.

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; the description goes slightly beyond by telling the agent to always populate reason and that it is recorded with the change, complementing the schema's note that it is shown to the approver. projectId, environment and configurationId are left entirely to the schema, which is acceptable given full coverage.

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 ("Delete a configuration") plus its scope ("from this project environment"), which clearly distinguishes it from get_configuration, list_configurations, update_configuration and create_configuration. An agent can identify the operation without opening the 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 explicit when-not conditions: the primary configuration and configurations backing a scheduled or running experiment are off limits, and it supplies the remediation path ("make another one primary first"), implicitly pointing at set_primary_configuration. It does not reference sibling tools by name (e.g. preview_configuration_change, search_configuration for finding an id), so routing is inferred rather than spelled out.

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