set_virtual_service_enabled

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

Annotations already flag destructiveHint=true, readOnlyHint=false and openWorldHint=true, so the safety profile is partly covered. The description nonetheless adds real behavioral value the annotations cannot: the preview/blast_radius contract, the 'noop' result for already-in-state VS, and the refusal condition. One soft tension: the 'noop' idempotency language sits awkwardly beside idempotentHint=false, though it is not a flat contradiction.

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 '[WRITE]' prefix and the opening verb+resource sentence front-load the essentials, and the remaining sentences each carry a distinct rule (preview, user decision, noop, refusal). It is somewhat long and the 'they have not seen what it changes yet' clause is a mild restatement, but no sentence is pure filler.

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?

No output schema exists, yet the description explains the return contract (blast_radius contents, 'noop' action), the preview/apply split, and the refusal precondition. For a destructive mutation tool with annotations already covering safety, nothing an agent needs to call 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% and documents name, enable, confirm (preview vs apply) and the deprecated confirmed alias clearly, so the description is not required to carry parameter meaning. It mainly restates the confirm semantics and adds the user-decision rule, which is usage guidance rather than new parameter detail. Baseline 3 is appropriate.

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 ('Enable or disable a Virtual Service') plus the consequence of the disable path ('stops all traffic to it'). It also distinguishes itself from the read-only sibling get_virtual_service_status by naming it as a prerequisite for checking state.

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 workflow: without confirm=True it previews only, the agent must show blast_radius to the user and get an explicit decision, and must not set confirm=True on its own. It also names the fallback path ('Use get_virtual_service_status first') for the refusal case, leaving nothing to inference.

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