set_firewall_policy_enabled

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

With only idempotentHint in annotations, the description carries the behavioral burden and earns it: it declares the operation is mutating, applied immediately, persisted on the console, and that predefined controller policies have special toggle-but-not-delete semantics. This goes well beyond what idempotentHint alone communicates, without contradicting it.

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 purpose is front-loaded in the first line, followed by a compact two-sentence behavioral paragraph. The Args block is somewhat redundant with the schema descriptions, which costs a point, but the overall size is appropriate with no 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?

Given four fully documented parameters and an idempotentHint, the description covers the essentials: operation semantics, timing, persistence, ID sourcing, and post-state inspection via get_firewall_policies. It doesn't describe the return value, but since there is no output schema and it directs agents to get_firewall_policies to verify state, this is a minor gap.

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 description coverage is 100%, so the baseline is 3. The Args block restates the schema descriptions nearly verbatim (e.g., 'True to enable, False to disable'; 'Defaults to "default"') and adds only marginal context like the policy_id provenance from get_firewall_policies, which is already present in the schema.

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 a specific verb+resource pair ('Enable or disable a zone-based firewall policy') and immediately differentiates from siblings by noting predefined controller policies can be toggled but not deleted, which clearly separates this from delete_firewall_policy and create_firewall_policy.

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 tells the agent to target policies by id from get_firewall_policies and to inspect state with get_firewall_policies, establishing the read-before-toggle workflow. The 'not deleted' clause hints at delete_firewall_policy as an alternative, but it doesn't explicitly name it or state when to prefer it.

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