panorama_push_to_devices

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

Annotations already carry destructiveHint=true and readOnlyHint=false, so the bar is lowered, and the description adds real value beyond those flags: the [MODIFIES CONFIG] tag and the explicit warning that 'This action affects live traffic on managed devices'. This tells the agent what the destruction actually impacts — production firewalls and live traffic — which is exactly the kind of context annotations cannot provide.

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?

Three short sentences with the key message front-loaded: the verb, target, and consequence appear in the first and last sentences. The [MODIFIES CONFIG] prefix is slightly redundant with the destructiveHint annotation and the final sentence, but otherwise every sentence earns its place.

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?

The safety profile and operational scope are well covered for a destructive push operation. However, with no output schema present, the description omits what the call returns or whether the push is synchronous/asynchronous — for an operation on production firewalls, a note about the expected result or follow-up verification (e.g., checking operation status) would make it complete.

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 all four parameters (firewall, description, device_group, include_template) are fully documented in the schema itself. The description only echoes device_group ('in the specified device group') and adds no syntax, default behavior, or parameter relationship details beyond the schema, matching the baseline of 3.

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 and resource — 'Pushes configuration from Panorama to managed firewall devices' — and clarifies scope as deploying policy and object changes to a specified device group. This is clear and unambiguous as to what the tool does, and its 'to managed firewall devices' target implicitly distinguishes it from siblings like commit or panorama_commit, though it never names them.

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 implies this is the deploy step after Panorama changes ('deploys policy and object changes to production firewalls in the specified device group'), so an agent can infer when to use it. However, it offers no explicit when-to-use vs when-not-to-use guidance and names no alternatives, leaving the choice between this and panorama_commit/commit to inference.

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