update_output_guardrail_workspace_exclusions

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

The description goes well beyond the annotations (which already mark destructiveHint=true and idempotentHint=true) by disclosing concrete behavioral traits: enforcement changes immediately, override_existing replaces prior states while default merge preserves unmentioned workspaces, requires an organisation service API key with organisation_exclusions.update scope, is Enterprise-gated, and returns 403 on non-Enterprise plans. It also clarifies that repeating the same states is safe. No contradiction with annotations is present.

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 description is dense but every sentence earns its place. It covers purpose, usage prerequisite, behavioral side effects, idempotency, authentication scope, enterprise gating, and expected error response—all in five concise sentences. The structure is front-loaded with the core action, followed by key behavioral nuance, then supporting operational details. No redundant or filler content.

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 potentially destructive mutation tool with an output schema present, the description is comprehensive. It covers the tool's side effects (immediate enforcement), merge/override semantics, idempotency, required auth scope, enterprise gating, and a specific error condition (403). The presence of an output schema means return-value details need not be in the description. The combination of schema coverage, annotations, and description provides a complete picture for an agent to invoke this tool correctly.

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 input schema has 100% description coverage for all parameters, which would normally set a baseline of 3. The description adds meaningful semantic detail beyond the schema: it explains that 'override_existing replaces prior states while the default merge behavior preserves unmentioned workspaces', which clarifies the interaction between the override_existing boolean and the workspaces array. This goes beyond the schema's per-parameter descriptions, so a 4 is warranted.

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 opens with 'Set workspace exclusions from organisation-wide output guardrails', which is a specific verb+resource statement. The tool name includes 'output_guardrail_workspace_exclusions' and there is a sibling 'update_input_guardrail_workspace_exclusions', so the explicit 'output guardrails' wording clearly distinguishes it from the input-guardrail alternative. The purpose is unambiguous and actionable.

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 explicitly instructs to 'Review the matching list tool first because enforcement changes immediately', providing a clear prerequisite and warning about side effects. It also notes that 'Repeating the same states is safe', which guides usage around idempotency. It does not explicitly state 'use this instead of the input guardrail tool', but the purpose clarity and context make the usage context well-defined.

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