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

Annotations already mark this as destructive, and the description adds meaningful behavioral context: changes are staged in candidate config and require a separate 'commit' to activate. This goes beyond the structured annotations and helps the agent understand the operation's lifecycle.

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 short, front-loaded with the '[MODIFIES CONFIG]' signal, and every clause adds value: what the tool creates, what the group contains, and the staging/commit behavior. There is no wasted text.

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 config-modifying tool with no output schema, the description covers the core behavior, staging, and activation requirement. It could optionally clarify what happens if the group name already exists or whether members must already exist, but the schema and annotations cover most operational essentials.

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 parameters are already well-documented. The description reinforces the 'one or more address objects' intent, which aligns with the members array's minItems constraint, but adds little beyond 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 uses a specific verb ('Creates') and a specific resource ('static address group'), and clarifies that it contains 'one or more address objects'. This clearly distinguishes it from add_address_object and add_service_group, and the 'static' qualifier separates it from any dynamic grouping behavior.

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 gives clear context: use this when creating a static address group from existing address objects. It does not explicitly name alternatives or exclusion criteria, but the staging/commit note tells the agent the follow-up action needed.

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

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

The description adds meaningful behavior beyond the annotations: it explicitly flags that this modifies config, that changes are staged in candidate config, and that commit is required for activation. This is valuable context that the annotations alone do not 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?

The description is a single compact sentence that front-loads the modification warning, states the core action, and then gives the essential commit requirement. There is 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 create operation with full schema coverage and clear annotations, the description is complete. It tells the agent that the tool mutates config and that commit is required, while schema details cover parameters. No critical operational information 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?

The input schema has 100% description coverage, including explicit value examples for the address value parameter. The description reinforces the object types but does not add substantial parameter-level meaning beyond the schema, so the baseline of 3 applies.

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 clearly states a specific verb and resource: 'Creates an address object' and enumerates the supported types (IP/netmask, IP range, FQDN). This distinguishes it from sibling tools like get_address_objects, delete_address_object, and add_address_group without needing to inspect schemas.

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 gives clear operational context: the object is 'staged in candidate config' and requires 'commit' to activate, which tells the agent when a follow-up action is needed. It does not explicitly name alternative tools or state when not to use it, so it stops short of a 5.

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

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

Annotations already mark this as readOnly=false and destructiveHint=true, and the description adds valuable context beyond that by explaining the staged-candidate-config behavior and the need to commit. This clarifies the side-effect profile and timing without contradicting the annotations.

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 one front-loaded sentence with a clear modifier tag and no wasted words. It immediately communicates purpose and critical workflow behavior.

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 schema documents all parameters and required fields, while the description adds the crucial candidate-config/commit workflow. It does not describe return values, but for a config-creation tool without an output schema, the essential information for calling it correctly is present.

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?

All four parameters have schema descriptions, so the baseline is 3. The description adds general meaning around 'members' as service object names, but does not explain the firewall parameter's role or other parameter nuances beyond what the schema already provides.

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 ('Creates') and resource ('service group'), and clarifies the group contains 'one or more service objects'. This clearly differentiates the tool from sibling operations like get_service_groups or delete_service_group.

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 provides clear operational context: the change is 'Staged in candidate config' and 'requires commit to activate'. This tells an agent when and how the tool fits into the workflow, though it does not explicitly name alternatives or exclusion criteria.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=true), the description discloses that the object is staged in candidate config and requires a commit to activate. This is critical lifecycle behavior that the agent would not otherwise know.

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 a single efficient sentence with the [MODIFIES CONFIG] marker front-loaded and the staging/commit caveat appended. Every clause earns its place with no fluff.

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 simple config-creation tool, the description captures the key operating context: it modifies config, stages changes, and requires commit. The schema covers all parameters, so no parameter details are missing; absence of an output schema is acceptable given the simple create semantics, though alternatives are not addressed.

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 schema already documents all five parameters. The description's mention of port/range and protocol adds no semantic value beyond the schema, meeting 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 uses a specific verb ('Creates') and resource ('a TCP or UDP service object') and specifies scope ('with a port or port range'). This clearly distinguishes it from sibling tools like add_service_group and add_address_object.

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 usage context by stating what object is created, but it does not explicitly define when to use this tool versus add_service_group or other add_* siblings. It does add the post-creation step ('requires commit to activate'), which is useful, but there is no when-not or alternative guidance.

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

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

Despite the annotations already declaring readOnlyHint=false and destructiveHint=true, the description adds materially useful behavior beyond them: the change is not immediately active but staged in candidate config until a commit is issued. This affects what the agent should expect after invocation and what next step is required. The '[MODIFIES CONFIG]' marker aligns with, rather than contradicts, the annotations.

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?

A single sentence with zero filler. The behavioral tag is front-loaded, followed immediately by the verb+resource, then the critical staging note. Every element 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?

For an 8-parameter mutation tool with no output schema, the description covers the core action, the target resource, and the single most important behavioral caveat (candidate config staging). Parameter details are fully carried by the schema, and the safety profile is carried by the annotations. Success/return behavior is not described, but with no output schema that gap is acceptable.

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 8 parameters are already documented in the input schema. The description adds no parameter-level detail beyond the schema, but its staging caveat gives the parameters a meaningful temporal context. Baseline 3 is appropriate when the schema does the heavy lifting.

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: 'Creates a static route in a virtual router.' This clearly distinguishes it from siblings like delete_static_route and get_static_routes based on the action word alone. The '[MODIFIES CONFIG]' prefix adds an operational category that reinforces what the tool does.

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 provides clear workflow context: 'Staged in candidate config — requires commit to activate.' This tells the agent this is a multi-step operation and that a follow-up commit call is needed, which is genuine usage guidance. It does not explicitly name alternatives or exclusion conditions, but the staging workflow implication is strong enough for an agent to sequence correctly.

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

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

Annotations already indicate this is a modifying/destructive operation, and the description reinforces this with '[MODIFIES CONFIG]'. It adds valuable behavioral context beyond the annotations by stating that the tag is staged in candidate config and not active until commit, which is important for an agent planning next steps.

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 compact, front-loaded with the operational modifier, and every sentence contributes meaningful information. The commit requirement is delivered efficiently without unnecessary elaboration.

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 simple create operation with well-documented parameters and annotations covering the safety profile, the description covers the important behavioral aspect (candidate config staging and commit requirement). Minor gaps such as duplicate-name behavior or response details are not critical enough to reduce the score further.

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% and every parameter is clearly documented in the schema, so the description does not need to repeat parameter details. The description adds general context about tags being applicable to rules and objects, but no parameter-specific semantics beyond what the schema already provides.

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 an explicit 'Creates a tag object' which is a specific verb+resource statement. It clearly distinguishes add_tag from get_tags and delete_tag, and the tag application context further clarifies what the object is for.

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 clearly implies when to use this tool—when a new tag is needed—and provides the key operational context that the change is staged in candidate config and requires a commit to activate. It does not explicitly list alternatives or exclusions, but among the sibling tools there is no other tag-creation tool, so the guidance is sufficient.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true. The description adds valuable context beyond those flags by noting the action modifies config, affects live traffic, and activates staged changes. This is exactly the risk information an agent needs, with no 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?

Three short sentences with the critical '[MODIFIES CONFIG]' marker front-loaded. Each sentence earns its place: what the tool does, how changes become active, and the live-traffic impact.

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 state-changing tool with no output schema, the description covers the key caller needs: scope of commit, relationship to prior staging operations, and safety impact on live traffic. A minor gap is not stating whether the commit is reversible or what the response/result contains.

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 three optional parameters. The tool description does not add further parameter-specific meaning, so the baseline of 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?

The description states a specific verb ('commits'), a clear resource ('all pending (staged) configuration changes'), and the target ('running firewall'). It also links to set_config/delete_config, which distinguishes this activation step from the staging steps.

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?

It clearly indicates when to use the tool: after making changes with set_config/delete_config, to activate them. It does not explicitly name alternatives such as panorama_commit or state when not to use this firewall-specific commit, so it stops short of full exclusion guidance.

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

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

Annotations already establish readOnlyHint=false and destructiveHint=true, and the description is consistent with both. Beyond the annotations, it adds genuinely useful behavior: the deletion is staged in candidate config and requires commit to take effect. This is a non-obvious behavioral trait that changes agent expectations about the call's immediate impact.

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?

A single front-loaded sentence with the [MODIFIES CONFIG] tag first, followed by the action, then the essential staging caveat. Every word earns its place; there is zero filler or redundancy.

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 simple 2-parameter delete tool with no output schema, the description covers the critical workflow fact — the deletion is staged and requires commit. Minor gaps remain: no mention of behavior when the group does not exist or is referenced by other configuration, and no expectation of what the call returns.

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% — both 'name' and 'firewall' are already documented in the input schema. The tool description adds no parameter-level meaning beyond what the schema provides, so the baseline 3 applies.

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 — 'Deletes an address group' — with a '[MODIFIES CONFIG]' tag that flags the operation type. This clearly distinguishes it from sibling tools like delete_address_object (address objects) and add_address_group (the inverse operation), so an agent can tell them apart without opening schemas.

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 'requires commit to activate' note provides clear operational context: deletion is staged, so the agent should follow up with the commit tool. However, there is no explicit when-to-use or when-not-to-use guidance versus alternatives such as delete_address_object, nor any mention of verifying with get_address_groups.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, but the description adds genuinely new behavioral context: the change is staged in candidate config and requires a separate 'commit' to activate. This is critical operational knowledge the agent would otherwise lack, and it aligns with (does not contradict) the destructive annotation.

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?

Two sentences, zero filler. The [MODIFIES CONFIG] flag is front-loaded, the core action follows immediately, and the staging/commit caveat earns its place as essential behavioral information. Every word contributes.

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 simple 2-parameter tool with no output schema, the description covers the purpose, the destructive nature, and the critical staging/commit behavior. The only minor gap is unaddressed edge behavior, such as what happens when the address object is referenced by an address group or what response to expect — but this is a small omission for a tool this simple.

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%, with both 'name' and 'firewall' already documented in the schema. The description adds no parameter-level detail, but at full coverage the schema carries the burden adequately, so the 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?

"Deletes an address object" is a specific verb+resource statement that precisely names the action and target. The [MODIFIES CONFIG] prefix adds operational clarity, and the sibling set (add_address_object, get_address_objects, delete_address_group) makes it easy to distinguish from related tools.

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 its usage context — call this when an address object needs to be removed — but provides no explicit when/when-not guidance or alternatives. It does not tell the agent to prefer delete_address_group for groups or delete_service_object for services, leaving the routing decision to inference from sibling names.

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

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

With annotations already declaring destructiveHint=true and readOnlyHint=false, the description adds a genuinely non-obvious behavioral trait beyond them: changes are staged in the candidate config and require a separate 'commit' to take effect. This tells the agent the deletion is not immediately effective, which is valuable context the structured fields do not convey. No contradiction with annotations.

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?

Two sentences of roughly 30 words with the [MODIFIES CONFIG] flag front-loaded for at-a-glance mutability awareness. Every clause earns its place: the first states the action and target, the second adds the essential commit-required caveat. No filler or redundant elaboration.

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 2-parameter tool with complete schema documentation and annotations already covering the destructive profile, the description supplies the one workflow fact an agent cannot derive from structured data: the staged-commit behavior. The only gap is no statement about return values or success indicators, though no output schema exists and delete operations typically yield minimal responses.

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 both parameters are already fully documented with an XPath pattern, a concrete example, and the firewall's conditional requirement. The description's 'specific XPath location' merely restates the xpath parameter's role without adding new semantic detail. Baseline 3 is appropriate since the schema carries the full burden.

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 uses a specific verb ('Deletes') tied to a precise resource ('configuration at a specific XPath location on the firewall'), making the operation unmistakable. This clearly differentiates it from siblings like get_config (read), set_config (write), and the typed delete_* family (which target specific object types rather than arbitrary XPath nodes).

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 the tool is for generic XPath-targeted deletions and conveys the workflow context that changes are staged and need a commit, which signals follow-up usage of the 'commit' sibling. However, it never explicitly states when to prefer this over the typed delete_* siblings or set_config, nor does it state any exclusions. The usage guidance is implied rather than explicit.

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

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

The description discloses a significant behavioral trait beyond the annotations: the deletion is staged in candidate config and does not take effect until 'commit' is run. This is valuable context that neither the annotations nor the schema 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?

The description is a single tight sentence that front-loads the key behavioral tag, states the action, and then provides the critical staging/commit detail. Every element earns its place with no redundancy.

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 simple two-parameter mutation tool, the description covers the action, the destructive nature, the staged-config behavior, and the required commit step. No output schema exists, but none is needed here. Minor missing context like referencing dependent objects is not essential for basic correct invocation.

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 schema already documents both 'name' and 'firewall' clearly. The description adds no additional parameter-level semantics, which matches the baseline of 3 for high schema 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?

The description states a specific verb and resource: 'Deletes a service group,' which clearly distinguishes it from sibling delete tools like delete_service_object and delete_address_group. The scope 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 implies usage through the verb and resource, but it does not explicitly state when to prefer this tool over alternatives such as delete_service_object or set_config. It provides operational context about candidate config and commit, but no exclusions or alternative routing.

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

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

Beyond the annotations, the description discloses the critical behavior that deletion is not immediately effective—it is staged in candidate config and only activated by 'commit.' This prevents the agent from assuming the delete is immediately applied, which is valuable behavioral context.

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 a single, compact sentence with the 'MODIFIES CONFIG' warning front-loaded and the activation requirement stated efficiently. There is no redundant or vague language.

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 simple two-parameter delete operation with no output schema, the description covers the essential behavioral workflow: modification, staging, and commit activation. The parameter details are fully handled by the schema, so no critical context 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?

The input schema already provides 100% coverage of both parameters, including descriptions for 'name' and 'firewall.' The description adds no parameter-specific semantics, so the baseline of 3 is appropriate given the complete schema 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?

The description states a specific verb and resource: 'Deletes a service object.' It clearly distinguishes from sibling tools like delete_service_group and delete_address_object by naming the exact object type. The staging context adds useful clarity beyond the tool name.

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?

It provides clear operational context: deletion is staged in candidate config and requires 'commit' to activate, which tells the agent about the post-call workflow. It does not explicitly name alternative tools, but the resource-specific phrasing and sibling names make the appropriate use case sufficiently clear.

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

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

Annotations already flag the operation as non-read-only and destructive, but the description adds the key behavioral fact that changes are staged in candidate config and only activate after commit. This is valuable context beyond the boolean annotations, though it does not mention error behavior or reversibility.

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 definition is a single front-loaded sentence with the [MODIFIES CONFIG] warning first, followed by the action and the critical staging note. Every part earns its place and there is no redundancy.

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 three-parameter tool with no output schema, the description covers the critical workflow facts: what is deleted, where it is staged, and the need to commit. It does not describe expected results or failure modes when the route is absent, but the parameters are fully documented in the schema.

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 schema already explains each parameter. The description's phrase 'from a virtual router' loosely echoes the virtual_router parameter but adds no new meaning beyond what the schema provides.

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 action ('Deletes') and resource ('a static route from a virtual router'), and the [MODIFIES CONFIG] tag sets expectations. This is clearly differentiated from sibling delete_* tools by the static-route resource and from add_static_route/get_static_routes by the delete verb.

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?

Usage is implied: use this tool when a static route needs to be removed. It does not explicitly say when to prefer this over add_static_route or get_static_routes, nor does it state exclusions such as requiring the firewall parameter in multi-firewall setups, leaving some selection inference to the agent.

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

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

Annotations already mark destructiveHint=true, but the description adds a critical non-obvious behavior: the deletion is staged in candidate config and requires 'commit' to activate. This qualifies the destructive nature and prevents the agent from assuming the change is immediately live.

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?

A single sentence with the config-modification warning front-loaded and the essential commit requirement included. Every word earns its place; no filler or redundancy.

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 simple delete operation with full schema coverage and appropriate annotations, the description covers the critical behavioral nuance of staging and commit. No output schema is present, and none is needed for this straightforward operation.

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 both 'name' and 'firewall' are already documented with descriptions. The tool description adds no parameter-level semantics, so the baseline of 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 ('Deletes'), a specific resource ('tag object'), and the config-staging context. This clearly distinguishes it from sibling tools like add_tag, get_tags, and other delete_* tools.

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 doesn't explicitly name alternatives, but it gives clear operational context: the deletion is staged and only activates after commit. This tells an agent how and when the change takes effect, though it stops short of explicit when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true and destructive=false, but the description adds value by naming the exact actual operation ('Exeecutes: show session info'), which lets an agent predict the firewall command and behavior. It also clarifies that the result is a count and summary rather than raw session listings. No contradictions with annotations.

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 a single efficient sentence with the read-only marker front-loaded, followed by the precise function and underlying command. Every word carries meaning and there is no repetition or 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?

For a simple, read-only, one-optional-parameter tool, the description is complete: it states what is retrieved, names the underlying command, and the schema already covers the firewall parameter. No output schema exists, but the description adequately indicates the result ('count and summary'), so no critical information 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 description coverage is 100%: the lone 'firewall' parameter is already documented with when it is required/optional. The tool description adds no additional parameter meaning, so the baseline of 3 applies.

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 uses a specific verb ('Retrieves') and resource ('ctive session count and summary from the firewall'), and the stated CLI command 'show session info' makes the tool's function unmistakable. It is clearly distingushed from sibling get_* diagnostic tools by focusing on session info.

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 gives no explicit when-to-use guidance, comparison with alternatives, or exclusions. While it is obviously intended for checking active session information, it does not state conditions or direct agents toward or away from any sibling tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the config path and a potential filtering qualifier, which is useful context beyond the annotation. However, it does not clarify the return shape, whether the 'contain multiple address objects' phrase is a filter, or any edge-case behavior.

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 only two short sentences with no filler. The read-only marker and primary action are front-loaded, and the config path is a useful, compact addition.

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 simple read-only tool with one optional parameter and no output schema, the description gives enough information to invoke it: what it retrieves and where it reads from. The ambiguous wording about 'multiple address objects' and the lack of return-format detail are minor gaps.

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 single firewall parameter is fully described in the schema with 100% coverage, so the description does not need to add parameter details. The description also adds no extra semantics about the parameter or how it affects the result, so the baseline of 3 applies.

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 action ('Retrieves') and resource ('address groups'), and further identifies the config path. It is clearly distinct from sibling tools like get_address_objects and get_service_groups. The qualifier 'that contain multiple address objects' is slightly ambiguous, but it does not obscure the core purpose.

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?

No guidance is given about when to use this tool versus siblings such as get_address_objects, get_service_groups, or add/delete_address_group. The read-only marker implies safe querying, but there are no explicit exclusions, prerequisites, or alternative conditions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context by naming the config path it reads from and specifying the object types returned, but it does not disclose behavior such as pagination, response size, or handling when no address objects exist. This is adequate but not rich.

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 one compact, informative sentence plus a useful config path reference. It front-loads the core behavior and avoids unnecessary filler. The redundant '[READ-ONLY]' marker is minor and does not hurt clarity.

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 low-complexity, single-optional-parameter read-only tool with annotations covering safety and schema covering params, the description is largely complete. It explains what is retrieved and where the data comes from. Since there is no output schema, slightly more detail about the return format would be ideal, but the core context is sufficient for an agent to call it safely.

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%, and the only parameter, firewall, is documented in the schema with guidance about when it is required. The description adds no additional parameter semantics beyond that, which is acceptable because the schema already carries the meaning.

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 clearly states the action ('Retrieves all address objects') and the resource ('defined on the firewall'), and clarifies that address objects include IP addresses, ranges, and FQDNs. This distinguishes it from siblings like get_address_groups or add/delete address-object operations.

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 gives no explicit guidance on when to use this tool versus alternatives. It does not mention when not to use it, nor does it compare against related siblings such as get_address_groups or get_config. The read-only label implies a safe listing operation, but no concrete selection criteria are provided.

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

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

Annotations already establish read-only and non-destructive behavior, so the bar is lower. The description adds useful behavioral context beyond annotations by stating that the tool reads a specific config path: /config/.../vsys/entry/application-filter. This helps the agent understand the data source and hierarchical scope.

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 compact and front-loaded: read-only marker, exact tool purpose, and config path in one efficient sentence. There is no filler or repetition of structured data.

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 simple read-only tool with one optional parameter and no output schema, the description provides enough context: what it retrieves, why it is used, and where the data lives. It does not describe the return shape in detail, but that is a minor gap for such a focused getter.

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 single optional 'firewall' parameter is fully documented in the schema. The description itself does not repeat or expand on parameter semantics, but it does not need to because the schema already explains when the parameter is required.

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: 'Retrieves application filters used for application-based policy rules.' This clearly distinguishes it from sibling getters like get_routing_table or get_zones. The read-only prefix and config path add further precision.

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 gives clear context for when the tool is relevant: when working with application-based policy rules and needing application filters. It does not explicitly name alternatives or exclusions, but the purpose statement is sufficient for tool selection among the many sibling getters.

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

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

The description adds the exact command executed ('show arp entry all') beyond the annotations, giving the agent concrete insight into the underlying operation. The [READ-ONLY] prefix reinforces the annotation, and there is no contradiction or hidden side effect disclosed or omitted.

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?

Two short, efficient sentences with no redundant filler. The read-only indicator and purpose are front-loaded, and the exact command is provided in the second sentence.

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 simple read-only tool with one optional parameter, no output schema, and safety annotations already present, the description is sufficiently complete. It could mention the returned fields or format, but that is not critical given the straightforward nature of the operation.

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 single 'firewall' parameter is already fully documented in the schema. The description adds no additional parameter-specific meaning, which is acceptable given the baseline for full schema 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: 'Retrieves ARP table entries from the firewall.' It clearly identifies the data being fetched and is distinct from all sibling tools, none of which target ARP tables.

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 makes it clear this tool is for reading ARP table entries from a firewall. It does not explicitly name alternatives or exclusions, but the purpose is specific enough that an agent can select it appropriately among the get_* siblings.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false; the description reinforces this with '[READ-ONLY]' and 'Does not modify anything' without contradicting the annotations. It adds genuine behavioral context beyond the annotations: the candidate-buffer vs committed-config distinction and the dirtyId="2" admin="admin" attribute heuristics for spotting uncommitted state.

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 three sentences and front-loaded with the [READ-ONLY] marker and core action. The dirtyId/admin parenthetical is the longest part but earns its place as an actionable verification hint. Slightly dense, but nothing is wasted.

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?

With no output schema, the description relies on the schema's param docs (format metadata_only) and its own usage hints to convey behavior. It covers the primary use cases (verifying staged candidate changes and reading committed config) and the safety profile. Minor gaps remain around error behavior for nonexistent paths and response size/pagination, but for a simple read tool these are not critical.

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%, placing the baseline at 3. All five parameters (xpath, format, firewall, metadata_only, redact_secrets) are already well documented in the schema with examples and enums. The description itself adds no parameter-level detail beyond the behavioral hints, which is acceptable given the schema's completeness.

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 and resource: 'Reads configuration XML at a specific XPath location from the firewall/Panorama candidate buffer.' This clearly distinguishes it from write operations like set_config/delete_config and from sibling read tools like get_config_logs and get_routing_table, which target different data. The scope ('candidate buffer' vs committed config) is explicit.

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 gives concrete use context: 'Use this to verify staged candidate changes... or to read committed config.' It also implies an exclusion with 'Does not modify anything.' However, it does not explicitly name alternative tools or state when-not-to-use it, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's '[READ-ONLY]' prefix adds no new safety information. The description does add that it uses the PanOS log API with type=log and that results are 'recent,' which is modest behavioral context. No rate limits, pagination, or return format details are provided, but annotations cover the main safety profile.

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 a single, front-loaded sentence that conveys purpose, API context, filtering, and result limiting without fluff. The '[READ-ONLY]' prefix is redundant with the annotations, which keeps it from being flawless, but the overall structure is compact and effective.

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 simple read-only log retrieval tool with fully documented parameters and safety annotations, the description covers the essential purpose and capabilities. The main missing piece is return-format or time-window context, but no output schema exists and the description does not mislead. It is sufficient for an agent to select and invoke the tool correctly in most cases.

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 schema fully documents all three parameters: nlogs, query, and firewall. The description's mention of 'filtering by query and limiting result count' aligns with the query and nlogs parameters but does not add meaning beyond the schema. 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?

The description uses a specific verb ('Retrieves') and resource ('recent configuration change logs from the firewall') with an explicit API context ('PanOS log API type=log'). This clearly distinguishes it from sibling log tools like get_system_logs, get_traffic_logs, get_threat_logs, and get_url_filter_logs.

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 provides clear context: use this for configuration change logs from a firewall. It mentions filtering by query and limiting result count, which gives practical invocation guidance. It does not explicitly name alternatives or state when not to use it, but the resource type itself makes the intended use clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only behavior is covered. The description adds the exact command executed, which is helpful context, but it does not disclose return format, whether output can be large, or any filtering/pagination behavior. That is acceptable for a simple read-only command, but no extra behavioral context beyond the annotation is added.

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 compact and information-dense: one sentence states purpose, read-only nature, and the exact CLI command. It is front-loaded and avoids unnecessary detail, though it could have added a brief note about expected output.

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 one-parameter read-only tool, the definition is complete enough to invoke correctly, but there is no mention of possible response shape or how many leases might be returned. Since there is no output schema, a brief hint about the return data (e.g., lease list with IP/MAC) would improve completeness.

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 schema has one optional parameter (firewall) with a clear description, and schema description coverage is 100%. The description does not need to add much; it correctly implies the firewall parameter is only required when multiple firewalls are configured, matching the schema's optional-required condition.

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 clearly identifies the tool as retrieving DHCP server lease information, specifies a read-only nature, and names the exact firewall command executed. It distinguishes itself from sibling tools like get_arp_table / get_routing_table in that it targets DHCP leases specifically.

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 usage for querying DHCP lease info and the schema clarifies when the firewall parameter is needed. However, it does not explicitly state when to choose this over alternatives, nor does it mention that no write/mutation is involved, though the READ-ONLY prefix partially covers that.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with '[READ-ONLY]' and the exact config path. It does not disclose error behavior, permissions, or output format, but for a simple read operation with these annotations, the description adds adequate context.

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 two short, front-loaded sentences with no filler. It states the operation type, the resource, and the relevant config path without unnecessary detail.

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 read-only tool with one optional parameter and a fully documented schema, the description plus annotations are sufficient to invoke it correctly. The lack of an output schema and the broad term 'configuration' leave some ambiguity about the exact return fields, so it is not quite a perfect 5.

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 provides 100% coverage for the single optional parameter, including the conditional requirement when multiple firewalls exist. The tool description itself does not add parameter semantics beyond the schema, so the baseline score of 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?

The description uses a specific verb ('Retrieves') and a specific resource ('DNS proxy configuration'), and it adds the config path. No sibling tool targets DNS proxy specifically, so it is clearly distinguishable.

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 gives no guidance on when to use this tool versus alternatives such as get_config. The only usage-related hint appears in the schema's parameter description about the firewall parameter, which addresses parameter requirements, not tool selection.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description reinforces this with the 'READ-ONLY' label and adds the exact command executed ('show system info'), which is useful context. It does not discuss auth or rate limits, but for a read-only informational command with no side effects, the disclosure is sufficient. No contradiction with the annotations.

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 two tight sentences with no fluff. The read-only marker is front-loaded, the purpose is stated in the first sentence, and the underlying CLI command is provided in the second. Every word 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?

This is a simple one-parameter, read-only tool with no output schema. The description names the returned fields, the schema fully defines the optional target parameter, and the annotations cover the safety profile. Nothing essential for an agent to invoke this tool 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_description_coverage is 100%, so the parameter is fully explained in the input schema: 'Target firewall name (from firewalls.json). Required when multiple firewalls are configured; optional otherwise.' The tool description itself adds no additional parameter detail, which maps to the baseline 3 for high schema 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?

The description states a specific verb and resource: 'Retrieves system information ... from the PanOS firewall' and enumerates the exact fields (hostname, model, serial, software version). This clearly distinguishes it from siblings like get_system_resources or get_config, and it adds the concrete command 'show system info' to remove any ambiguity.

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?

It gives clear context: use this tool when you need identifying system information from a PanOS firewall. The schema further documents when the single parameter is required ('Required when multiple firewalls are configured'). However, it does not explicitly name alternatives or exclusion conditions compared with sibling read-only tools such as get_system_resources or list_firewalls, so it misses the fifth point.

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

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

Annotations already disclose read-only and non-destructive behavior, and the description adds context beyond them by naming the exact underlying command ('show high-availability state') and the returned information (state and peer information). It does not detail output format, but the described behavior is clear and consistent with annotations.

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?

Two compact sentences, with the read-only nature flagged first, then purpose, then the exact command. No filler or redundancy.

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 simple one-parameter read-only tool is well described: purpose, target, exact command, and general return content. No output schema exists, but 'state and peer information' gives an agent enough expectation, and the optional firewall parameter is covered by the schema.

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 schema fully covers the only parameter (firewall) with a clear description. The tool description adds no parameter-specific detail, but with 100% schema coverage the baseline 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 ('Retrieves'), the resource ('high-availability (HA) state and peer information'), and the target ('the firewall'). This differentiates it from nearby get_* and panorama_* siblings, and it names the exact command executed.

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 clearly establishes the intended use for reading HA state and peer information from a firewall, and the read-only flag sets expectations. It does not explicitly name alternatives or exclusions, but there is no obvious HA-status sibling and the firewall context is explicit.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with a [READ-ONLY] prefix. It adds meaningful behavioral context by exposing the exact executed command and the kind of data returned, which goes beyond the annotation defaults.

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 compact and front-loaded: the read-only tag, the purpose, the returned data, and the underlying command all appear in two concise sentences. There is no filler or redundant restatement of the tool name.

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 simple read-only tool with one optional parameter and no output schema, the description covers the returned fields (status, IP addresses, configuration) and the execution behavior. Nothing essential is missing for an agent to select and 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?

Schema description coverage is 100%, and the firewall parameter is already documented in the input schema. The description does not add extra semantics about the parameter, but it also does not need to because the schema fully covers validation and purpose.

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 uses a specific verb and resource: 'Retrieves all network interfaces with their status, IP addresses, and configuration.' This is immediately distinguishable from sibling tools like get_routing_table or get_vlans. Adding the exact underlying command 'show interface all' further reinforces what the tool does.

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 clearly conveys that this is the tool for retrieving interface-level information, which is enough context for an agent facing many get_* siblings. It does not explicitly mention alternatives or when-not-to-use cases, but no closer alternative exists in the sibling list.

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

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

The annotations already mark it read-only and non-destructive; the description adds a '[READ-ONLY]' confirmation and, more valuably, reveals the exact command executed ('show routing route'), giving the agent concrete knowledge of device-side behavior. The description is fully consistent with the annotations — no 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?

Two compact sentences that front-load the purpose and follow with the exact device command. The '[READ-ONLY]' prefix is a minor redundancy with readOnlyHint, but otherwise every element 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?

For a read-only tool with a single optional parameter and no output schema, this is reasonably complete: the agent knows what is retrieved and which command runs. The only notable omission is any indication of the return shape or volume, which would also help differentiate it from get_static_routes.

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 schema alone fully documents the optional firewall parameter, including when it is required. The description therefore does not need to add parametric detail; it only loosely mirrors the target via 'from the firewall.' 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+resource: 'Retrieves the current routing table from the firewall,' and discloses the underlying device command 'show routing route,' which pins down the exact operation. It does not explicitly contrast itself with the sibling get_static_routes, though the phrase 'routing table' plus the show command makes the distinction largely inferable.

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?

Provides no guidance on when to use this tool versus the many get_* siblings, notably get_static_routes, which is the most likely confusable alternative. The agent must infer selection criteria from the tool name alone; the description never states the condition for choosing this tool over alternatives.

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

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

The description reinforces the read-only annotation with a [READ-ONLY] prefix and adds a concrete config path ('/config/.../vsys/entry/service-group'). This provides useful behavioral context beyond the annotations, though it does not describe return format or pagination.

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?

One compact sentence communicates the operation, scope, and config path with no wasted words. The read-only marker is front-loaded for immediate safety recognition.

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 simple read-only tool with one optional parameter and no output schema, the description and annotations are sufficient for an agent to select and invoke it correctly. The lack of return-format detail is a minor gap but not critical for this operation.

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%, and the single optional 'firewall' parameter is already well documented in the schema. The description adds no additional parameter semantics, but none are needed given the schema's completeness.

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 ('Retrieves') and resource ('service groups'), and clarifies the scope ('all service groups that contain multiple service objects'). It is clearly distinguishable from siblings like get_service_objects, add_service_group, and delete_service_group.

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?

No guidance is given about when to prefer this tool over alternatives such as get_service_objects or the add/delete service group tools. The description implies a read operation but does not state exclusions or selection criteria.

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

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

Annotations already provide readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds value by disclosing the config path ('/config/.../vsys/entry/service') and emphasizing the read-only nature, giving an agent useful context about what is being accessed.

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 two short sentences with no filler. The safety prefix and core purpose are front-loaded, and the config path is a useful addition that 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?

For a simple read-only list operation with one optional parameter and full schema coverage, the description is nearly complete. It could be improved by briefly noting that this returns service objects as opposed to service groups, but nothing critical is missing for making the call.

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 sole parameter 'firewall' has full schema description coverage, including 'Required when multiple firewalls are configured; optional otherwise.' The description adds no additional parameter semantics, but since the schema covers 100% of the parameter meaning, the baseline score of 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?

The description states a specific verb ('Retrieves'), a clear resource ('all service objects'), and clarifies the domain with 'port/protocol definitions'. This distinguishes it from sibling tools like get_service_groups and get_address_objects by object type and scope.

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 intended use is implied: call this when you need the full list of service objects from the firewall. However, the description does not explicitly contrast it with alternative or related tools such as get_service_groups, nor does it state when not to use it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with '[READ-ONLY]'. It adds a config path detail, which provides mild implementation context, but it does not explain return format, pagination, or behavior when no routes exist.

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?

Two short sentences with no filler. The read-only marker and primary action are front-loaded, making the purpose immediately visible.

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 simple read-only tool with fully documented optional parameters and no nested objects, the description plus annotations are almost sufficient. The only minor gap is that no return format is described, but the nature of the tool makes this a limited concern.

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 both parameters (firewall and virtual_router) are already fully documented in the schema. The description adds no additional meaning beyond referencing the virtual-router config path.

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 clearly states a specific verb and resource: 'Retrieves static routes from a virtual router.' The mention of static routes distinguishes it from related siblings like get_routing_table, add_static_route, and delete_static_route without ambiguity.

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?

There is no guidance about when to use this tool versus alternatives, such as get_routing_table for a broader view or the add/delete route tools for modifications. The reader must infer usage from the name and the basic description.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description need not repeat safety. It adds useful context such as 'recent' logs, PanOS log API type=log, filtering, and count limiting. However, it does not disclose details like pagination, log entry structure, or any rate-limiting behavior.

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?

A single, front-loaded sentence with the READ-ONLY marker first, followed by the core action and key capabilities. There is no fluff or repetition of schema details.

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 read-only, zero-required-parameter tool with a fully documented schema, the description provides sufficient operational context: source, API type, recency, filtering, and count limiting. It does not describe return format, but no output schema exists and this is a simple log retrieval tool, so the core context is adequately covered.

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 schema already documents nlogs, query, and firewall with descriptions. The description adds only a general mention of 'filtering by query and limiting result count,' which maps to the schema but does not add deeper semantic meaning beyond it.

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 clearly states a specific verb and resource: 'Retrieves recent system logs from the firewall using the PanOS log API (type=log).' It also mentions filtering and result count limiting. It does not explicitly distinguish itself from sibling log tools like get_traffic_logs, though the resource name 'system logs' provides implicit differentiation.

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 tool is for retrieving system logs and has filtering capabilities, but it gives no explicit guidance about when to choose this tool over get_traffic_logs, get_threat_logs, get_config_logs, or get_url_filter_logs. No alternative tools or exclusionary conditions are mentioned.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, and the description adds value beyond them by disclosing the exact underlying command (show system resources) and the data categories returned. The leading [READ-ONLY] marker reinforces the annotations rather than contradicting them. It does not describe the response format, but this is secondary given the safety profile is already declared.

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?

Two compact sentences carry the safety signal, the purpose, the data dimensions, and the underlying command with zero filler. The most important information is front-loaded.

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 simple read-only tool with one optional parameter and no output schema, the description names the returned dimensions (CPU, memory, disk) and the command executed. It could clarify the output shape further, but nothing essential for correct selection and invocation 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?

The input schema documents the only parameter (firewall) at 100% coverage, including the condition for when it is required (multiple firewalls configured). The tool description adds no parameter-level detail, but with high schema coverage the baseline of 3 applies.

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 pairs a specific verb (Retrieves) with a concrete resource (system resource utilization) and enumerates the dimensions covered (CPU, memory, disk usage). This is clearly distinct from sibling get_* tools that target other resources like routing tables or ARP tables, though it does not name an alternative explicitly.

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?

No guidance is given on when to choose this tool versus alternatives such as get_firewall_info or get_interfaces, and there are no exclusion criteria or prerequisites stated. Usage context is only implicit in the tool name and the schema's note about when the firewall parameter is required.

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

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

It explicitly says it reads config at /config/.../vsys/entry/tag, adding behavioral context beyond the readOnlyHint annotation. It does not discuss auth, rate limits, or pagination, but for a read-only getter those are less critical.

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?

Two compact sentences with no filler; the read-only marker and config path each earn their place. It is front-loaded with the most important identification of the tool.

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 a single optional parameter and no output schema, the description is adequate: scope, config path, and read-only nature are covered. It does not state return shape, but for an 'all tags' getter this is predictable.

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 one parameter, firewall, is fully documented in the schema with 100% coverage, including its optionality. The description adds no parameter-level detail, so the baseline of 3 applies.

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 names a specific verb and resource ('Retrieves all tags defined on the firewall') and clarifies scope with the config path. This is distinct from sibling add_tag/delete_tag and the other get_* read tools.

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?

No when-to-use or alternate-tool guidance is given. With many sibling get_* and tag mutation tools, an agent must infer from the name and path when this is the right call.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with a [READ-ONLY] prefix. It adds a useful detail about using the PanOS log API type=log, but does not disclose specifics like time window limits, pagination behavior, or response format. The annotations carry most of the safety disclosure burden.

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?

Two compact sentences front-load the read-only nature and core purpose, then summarize the main parameter capabilities. There is no fluff or repetition; every phrase adds information.

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 the simple parameter set and fully covered schema, the description is mostly complete for calling the tool correctly. The only notable gap is clarifying what 'recent' means and whether there are any default time-window constraints, but this is a minor omission for a query-based log fetch.

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 three parameters (nlogs, query, firewall) are already fully documented with types, bounds, defaults, and examples. The description adds a brief high-level mention of filtering and result limiting, but does not need to add more since the schema is comprehensive.

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 clearly states the action (retrieves), the resource (recent threat logs), and the underlying mechanism (PanOS log API type=log). This is specific enough to distinguish it from sibling log-retrieval tools like get_traffic_logs or get_system_logs without needing to inspect 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?

The scope is implicitly clear: use this tool when threat logs are needed and filtering or count limiting is desired. However, it does not explicitly mention alternatives or when not to use it, which would be valuable given the sibling tools for traffic, system, config, and URL filtering logs.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with '[READ-ONLY]'. It adds useful context about using the PanOS log API and supporting filtering/limiting, but it does not disclose details such as the time window behind 'recent' or the output structure. With annotations covering the safety profile, the extra disclosure is adequate but not rich.

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 one tightly written sentence that leads with the read-only marker and the core verb 'Retrieves', followed by the resource and key capabilities. There is no filler or repetition of schema details.

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?

This is a relatively simple tool with three optional parameters, all fully described in the schema, and annotations already establish the read-only safety profile. The description covers purpose, filtering, and result limiting, which is sufficient for an agent to call it correctly. A minor gap is the absence of any detail about the default/possible time range for 'recent', but this does not block correct invocation.

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 input schema already documents nlogs, query, and firewall clearly. The description adds only a high-level mention of 'filtering by query and limiting result count', which maps to query and nlogs but does not add meaning beyond the schema. 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?

The description uses a specific verb and resource: 'Retrieves recent traffic logs from the firewall using the PanOS log API (type=log)'. The term 'traffic logs' clearly distinguishes it from sibling log retrieval tools such as get_threat_logs, get_system_logs, and get_url_filter_logs.

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 provides clear context by specifying that this tool retrieves traffic logs, which is the right category for firewall traffic-related log queries. It does not explicitly name alternative tools for other log types, but the scope is unambiguous enough for an agent to select it appropriately among the sibling log tools.

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

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

Annotations already declare readOnlyHint and destructiveHint, and the description adds a [READ-ONLY] marker and concrete behavioral details: it uses the PanOS log API with type=log&log-type=url and returns URL categories and actions like allow/block/continue/override. This goes beyond the annotation and helps the agent understand what the call does and returns.

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 a single focused sentence plus a read-only prefix, front-loading the key safety and purpose information. Every clause adds value: API call type, log subtype, and the output content. No filler or redundant repetition of title or schema.

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 read-only log retrieval tool, the description covers the query mechanism, the specific log stream, and the output semantics. It lacks an explicit statement of time range or response structure, but the schema describes the filtering controls and no output schema exists, so the description is reasonably complete for the tool's simplicity.

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%: all three parameters (nlogs, query, firewall) have meaningful descriptions. The description itself does not add parameter-specific semantics, but with full schema coverage the parameters are already well documented, 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?

Description states specific verb+resource: retrieves recent URL filtering logs from a firewall via PanOS log API with log-type=url. It clearly identifies the domain (URL filtering) and output content (URLs and actions), distinguishing it from sibling log tools like traffic or threat logs.

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 usage context by specifying URL filtering logs and the API log type, but it does not explicitly state when to choose this over get_traffic_logs, get_threat_logs, or get_system_logs. There is no when-not or alternative routing guidance, leaving the agent to infer appropriateness from the tool name and description.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false; the description repeats read-only intent and adds the config source path. It does not disclose output format, pagination, or any other behavioral detail, but for a simple read-only getter the annotation plus source path is adequate.

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?

One efficient sentence front-loads the read-only nature and the core action. The config path is useful context, though the '[READ-ONLY]' prefix slightly duplicates the annotation.

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 single-parameter, read-only getter with no output schema, the description is largely sufficient: it identifies the resource and the config location. It could describe the return shape, but the operation's simplicity and annotations compensate.

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 one parameter 'firewall' is already fully documented. The description offers no additional parameter guidance, which is acceptable given the schema 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?

States a specific verb and resource: 'Retrieves VLAN configuration from the firewall.' The config path adds concrete detail. It does not explicitly distinguish itself from sibling get_* tools, but the resource is clear enough.

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?

No guidance about when to use this tool instead of siblings like get_config, get_interfaces, or get_zones. Usage must be inferred entirely from the tool name and the generic purpose statement.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with '[READ-ONLY]'. It adds some useful context by pointing to the config path, but does not disclose output format, pagination, or any edge-case behavior, so it only moderately exceeds the annotations.

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 very concise, with two short sentences that front-load the purpose and then provide a useful config-path detail. Every sentence earns its place and there is no redundant 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?

For a simple read-only retrieval tool with one optional parameter, the description is largely complete: it states what is retrieved and where the data is read from. It does not describe the return format, but the simplicity of the tool and the explicit read-only annotations reduce the need for additional detail.

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 single 'firewall' parameter is already fully documented in the input schema. The description does not add meaningful detail beyond the schema, so it meets the baseline but does not enhance parameter understanding.

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 uses a specific verb ('Retrieves') with a clear resource ('all security zones configured on the firewall'), making the tool's purpose immediately obvious. It also provides the config path, which helps distinguish it from sibling getters like get_vlans or get_interfaces.

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?

No explicit guidance is given about when to use this tool versus sibling tools such as get_vlans or get_routing_table. The usage context is only implied by the resource name and description, with no alternatives or exclusions mentioned.

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

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

Annotations already cover read-only and non-destructive behavior. The description adds meaningful behavioral detail beyond the annotations: it explicitly states the limited return set ('name, host, and verify_ssl') and makes a safety-relevant guarantee that 'API keys are never included.' This is useful, concrete transparency.

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 a single, tight sentence that front-loads the read-only nature, states the action, defines the resource, and discloses the output fields. Every phrase adds value and no filler or redundant detail is present.

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 zero-parameter list tool, this description is complete: it explains what is listed, which fields are returned, and what is intentionally excluded. There is no output schema, so the explicit enumeration of return fields is especially valuable and sufficient for an agent to invoke the tool and interpret the result.

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 zero parameters with 100% schema description coverage, so the baseline is 4. The description does not need to explain parameters but reinforces that no inputs are required by framing the tool as a simple listing operation.

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 starts with a specific verb and resource: 'Lists configured firewall targets'. It further clarifies the purpose by noting these targets 'can be selected by name,' which distinguishes this list operation from the many get_* sibling tools that inspect firewall state or configuration.

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 phrase 'can be selected by name' clearly implies this tool is the way to discover available firewall target identifiers for later use in other operations. It does not explicitly name an alternative or say when not to use it, but the intended context is clear enough for an agent to route correctly.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false; the description reinforces this with the [DESTRUCTIVE] marker and adds a non-obvious behavioral constraint: 'Candidate configuration only; no commit or push is performed.' This meaningfully clarifies scope and side effects beyond the annotations.

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 three short sentences, front-loaded with the destructive warning. Each sentence adds distinct value: the action, the required arguments, and the critical scope limitation. There is no filler or repetition.

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 mutation tool with no output schema and three parameters, the description covers the essential facts: what is applied, what identifiers are needed, and the candidate-only scope. It does not document return values or error conditions, but the action is simple enough that these are lower priority. It could mention how to obtain plan_id/plan_hash, but that is implied by the BGP planning workflow.

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 only 33%: only the optional 'firewall' parameter is described. The description merely states that plan_id and plan_hash are required, without explaining what they represent, where they come from, or why the hash is needed. With such low schema coverage, the description fails to compensate for the missing parameter documentation.

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 names a specific verb ('Applies'), a distinct resource ('approved BGP plan'), and the exact target ('candidate configuration'). This clearly differentiates it from siblings like panorama_apply_ipsec_candidate (IPsec, not BGP) and panorama_remove_bgp_candidate (remove, not apply).

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 the intended context—applying an approved BGP plan to the candidate configuration before any commit or push—but does not explicitly state when to prefer this tool over alternatives, nor does it name exclusions or alternative tools. The usage context is inferable but not spelled out.

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

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

Annotations already mark this destructive and non-read-only, and the description adds substantial behavioral detail: PSKs are accepted as-is with no strength check, supplied PSKs transit as redacted secrets, and no commit/push is performed. This goes well beyond the annotation flags and warns about the client-history risk.

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 compact and front-loaded with the destructive marker and core action. Each sentence contributes unique information: prerequisites, PSK handling, no-commit scope, and risk. The phrasing is somewhat telegraphic, especially 'Direct PSK client-history risk on apply,' but there is no redundancy or wasted 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 destructive tool with no output schema, the description covers the essential call semantics: what is applied, what inputs are required, how PSKs are handled, and what side effects do not occur. It does not describe the return value or post-apply status/follow-up, which is a minor gap given the sibling operation-status tools.

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 the description still adds value by explaining that plan_id and plan_hash must come from a prior plan call and that PSKs are keyed per secret slot with one direct PSK per tunnel. It does not elaborate on the optional firewall parameter, but the schema already documents that adequately.

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: 'Applies an approved IPsec plan to the candidate configuration.' Clearly distinguishes itself from siblings by scope ('candidate configuration only') and by the explicit 'no commit or push' boundary, so it is not confused with commit/push or BGP apply tools.

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?

Describes prerequisites clearly: an approved plan, plan_id, plan_hash, and operator-supplied PSKs. It also clarifies the tool does not commit or push, which tells the agent that further steps would be required for persistence. It does not explicitly name alternative tools or when-not-to-use conditions, but the usage context is strong enough.

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

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

Annotations already flag readOnlyHint=false and destructiveHint=true, and the [MODIFIES CONFIG] prefix reinforces them without contradiction. The description adds useful behavioral context beyond the annotations: the exact scope of mutation (device groups, templates, shared objects) and the critical non-push boundary that prevents misuse.

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 no filler: the action is front-loaded, the [MODIFIES CONFIG] flag is first, the workflow pointer is second, and the exclusion closes it out. 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?

For a simple tool with three optional parameters, full schema coverage, and safety annotations, the description covers the essential decisions: what it does, what it affects, when in the workflow to call it, and what it won't do. It doesn't mention that the commit may be tracked or verified via operation-status siblings (e.g., panorama_get_operation_status, panorama_verify_candidate_operation), but that's discoverable context for the broader workflow rather than a blocking 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 schema already documents firewall, description, and partial_admin with meaningful descriptions. The description doesn't add parameter-level detail beyond the schema, which is acceptable at the baseline 3 for high-coverage schemas.

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 action (commits pending configuration changes) on a specific resource (Panorama) and scopes it precisely to device groups, templates, and shared objects. The explicit 'does NOT push to managed firewalls' line distinguishes it from sibling panorama_push_to_devices and the generic commit tool without requiring schema inspection.

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 gives an explicit workflow rule: 'Use this before panorama_push_to_devices' — clearly stating when this tool fits into a sequence. It also names the alternative (panorama_push_to_devices) and states the negative case (committing on Panorama is not pushing to firewalls), so an agent knows when not to use it.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description adds meaningful behavioral detail: it says the tool inspects existing IKE gateways and loopback units, it previews the loopback choice, and it explicitly states no commit or push is performed. It also labels the operation as candidate-only, giving the agent a clear mental model of side effects.

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 three tightly written sentences. The read-only marker is front-loaded, the primary action follows immediately, usage guidance and safety guarantees are provided without redundancy, and every sentence adds value.

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 read-only detection tool with rich schema annotations and 100% parameter coverage, the description covers purpose, triggering condition, relation to the next step, behavior, and safety. No critical gap remains for an agent to select and invoke the 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?

Schema description coverage is 100%, so the input schema fully documents all six parameters. The description does not add parameter-specific guidance for its own parameters, but it does reference 'localInterface/localAddress' from the related planning tool, which helps contextualize when detection is needed. Baseline 3 is appropriate because the schema carries the parameter documentation weight.

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 names a specific verb ('Auto-detects') and resource ('WAN loopback interface/address an IPsec IKE gateway should reference') and explains the method ('inspecting existing IKE gateways and loopback units'). It also identifies the sibling it feeds into ('panorama_plan_ipsec'), making it easy to distinguish from other tools.

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 gives an explicit usage condition: 'Use before panorama_plan_ipsec when localInterface/localAddress are omitted.' It also clarifies the scope of the result by stating that only candidate configuration is produced and no commit or push is performed, which helps an agent decide when this tool is appropriate.

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

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

Beyond the readOnlyHint=true annotation, the description discloses the precise safety boundary: it returns only a safe target label/hash and never returns snapshot XPath values, restore XML, or secret metadata. This is meaningful behavioral context that helps the agent trust and safely use the tool.

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 two tight sentences with the READ-ONLY marker front-loaded and the safety guarantee stated immediately. Every sentence adds value and there is no redundancy or fluff.

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 simple read-olny status lookup with full schema coverage and readOnly/destructive annotations, the description provides enough information to invoke the tool correctly. The output schema is absent, but the safe-output boundary in the description sufficiently covers what the agent can expect.

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%, covering operation_id and firewall semantics clearly. The description adds no additional parameter details, but since the schema already documents both parameters, the baseline score of 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?

The description states a specific verb and resource: it returns lifecycle metadata for one active Panorama candidate operation. It also differentiates itself from destructive or heavier operations by explicitly saying it returns only safe metadata and never snapshot XPath, restore XML, or secrets.

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?

No explicit guidance on when to choose this tool over siblings like panorama_verify_candidate_operation or panorama_list_active_operations. The only implied context is that an operation_id exists from an apply call and the operation is active, but alternatives and exclusions are not addressed.

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

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

Annotations already provide readOnlyHint=true and destructiveHint=false, and the description adds meaningful context beyond that by listing exactly what is and is never returned: safe target label/hash only, never plan/candidate hashes, XPath values, mutation XML, or secret slot names. This is valuable behavioral disclosure for an agent deciding whether the tool is safe to invoke.

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 concise and front-loaded: the READ-ONLY marker and the first sentence immediately establish purpose. There is minor redundancy in repeating 'Returns safe', but overall every clause earns its place and the text is easy to scan.

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?

With no output schema, the description provides a useful high-level statement of the return value (safe target label/hash) and explicitly lists exclusions. It could define what 'lifecycle metadata' concretely includes, but for a read-only status tool with fully documented parameters, this is sufficient for an agent to select and call it 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?

Schema description coverage is 100%, so both plan_id and firewall are already documented structurally. The description does not add parameter-specific detail, which is acceptable given the schema fully covers the parameters.

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 ('returns') and a specific resource ('safe lifecycle metadata for one active Panorama provisioning plan'), which distinguishes it from list-style and operation-style siblings at a high level. It does not explicitly name sibling alternatives such as panorama_list_active_plans or panorama_get_operation_status, so differentiation is implied rather than explicit.

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?

There is no explicit guidance on when to use this tool versus alternatives. The safety framing ('READ-ONLY', 'never returns...') implies it is appropriate for safe status checks, but it does not say when to prefer it over related plan/operation tools.

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

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

The description explicitly says '[READ-ONLY]', 'Static playbook', 'Performs no API calls and mutates nothing.' This goes beyond the readOnlyHint annotation by clarifying there are no side effects and no actual API interaction, which is important for an agent deciding whether calling it is safe.

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 front-loaded with the most important facts: READ-ONLY, static playbook, and call-first guidance. The long 'Covers...' sentence is dense and could benefit from bullet-style structuring, but every listed item adds useful information for an agent evaluating the tool.

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 that this is a static guide with no parameters and no output schema, the description is remarkably complete. It covers the workflow sequence, key constraints, human-vs-auto responsibilities, naming conventions, and explicitly states when to call it, leaving no critical context 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?

The tool has zero parameters and an empty input schema, so there are no parameter semantics to explain. The description compensates by clarifying that the tool takes no input and performs no operations, which is sufficient.

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 clearly states this is a 'static playbook for provisioning IPsec + BGP-over-IPsec on any Panorama the server is connected to.' It uses a specific verb/resource pair and differentiates itself from sibling operational tools by explicitly noting it performs no API calls and mutates nothing.

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 gives explicit when-to-use guidance: 'Call this first in a session to learn the workflow without trial-and-error.' It also enumerates the required tool sequence, effectively mapping when each sibling tool should be used relative to this guide, and clarifies that the playbook itself performs no API calls.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful behavioral constraints beyond that, explicitly stating it 'never returns snapshot XPath values, restore XML, or secret metadata,' which helps an agent understand the safety scope of the returned data.

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?

Two sentences, front-loaded with the READ-ONLY signal, and zero filler. Every sentence contributes either to scope or to behavioral safety transparency.

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 simple, read-only list tool with one optional parameter, the description is largely complete. It gives a high-level view of the return content ('safe target labels/hashes') and explicitly notes what is excluded, which partially compensates for the lack of an output schema.

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% for the single optional 'firewall' parameter, which already explains when it is required and what it references. The description adds no additional parameter semantics, so the baseline score of 3 applies.

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: 'Lists safe lifecycle metadata for active Panorama candidate operations.' This is clear and identifies an object type distinct from sibling tools like panorama_list_active_plans or panorama_get_operation_status, though it does not explicitly name or contrast those siblings.

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 usage context is implied: use this tool to list active Panorama candidate operation metadata. However, there is no explicit guidance about when not to use it or how it compares to alternatives such as panorama_list_active_plans or panorama_get_operation_status.

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

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

Annotations already provide readOnlyHint=true and destructiveHint=false, so the description's added value comes from concrete behavioral exclusions: no plan/candidate hashes, XPath values, mutation XML, or secret slot names. This meaningfully shapes expectations beyond the annotation; minor lack of return-structure detail keeps it from a 5.

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?

Two sentences with no filler: the READ-ONLY marker and core action are front-loaded, and the second sentence adds a precise safety boundary. Every clause 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?

For a tool with one optional parameter, no output schema, and strong read-only annotations, the description adequately defines scope, safety, and exclusions. The main ambiguity is the exact shape of the returned 'lifecycle metadata,' but the safe/unsafe boundary is clear enough for correct invocation.

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 schema covers the single optional 'firewall' parameter at 100%, including when it is required. The description does not add parameter-level information, but the schema already carries that burden, so 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?

The description uses a specific verb ('Lists') and resource ('safe lifecycle metadata for active Panorama provisioning plans'), and it explicitly enumerates what it never returns (plan/candidate hashes, XPath values, mutation XML, secret slot names). This clearly distinguishes it from sibling plan/candidate mutation and status tools.

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 read-only framing plus the 'never returns' clause communicates a clear when-to-use and when-not-to-use context for agents seeking safe metadata. It does not explicitly name an alternative tool for retrieving full plan or candidate details, so it stops short of full explicit routing.

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

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

Beyond the readOnlyHint/destructiveHint annotations, the description discloses substantial behavioral details: it only plans mutations without committing or pushing, it returns a legacy plan wrapper plus planId/planHash/summary metadata, it preserves legacy policy behavior with a warning when policyMode is omitted, and it rejects peers without a local-address. These are non-obvious traits that materially affect how an agent uses the tool.

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: purpose, policyMode semantics, return shape, IPsec prerequisite, addressing constraint, safety boundary, and verification caveat. It is front-loaded with the core purpose and remains compact despite the tool's 15-parameter complexity.

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 complex nested-object tool with no output schema, the description covers the essential operational context: what the plan contains, what it returns, what must exist before calling it, what constraints apply to peer addressing, and that it does not mutate the live firewall. Combined with the high-coverage input schema, an agent has enough to decide when and how 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?

Schema description coverage is 80%, so most parameters are already documented. The description adds meaningful semantic value beyond the schema by explaining policyMode's intentionality behavior, the IPsec-derived addressing requirement for local-address and peer-address, and the PAN-OS rejection of peers without a local-address. This is important context the schema alone does not provide.

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 and resource: 'Plans ordered BGP candidate mutations' and enumerates exactly what those mutations cover (global enable, router-id, local-as, peer group, peers, import/export rules). It also distinguishes this from apply/commit tools by stating 'Candidate configuration only; no commit or push is performed,' making the tool's role in the sibling pipeline clear.

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 gives strong usage context: it requires a prior IPsec apply, describes the addressing constraint, and warns that runtime verification needs a prior manual commit and push. It does not explicitly name alternative sibling tools or state when not to use this tool, but the prerequisites and candidate-only behavior effectively scope when it should be invoked.

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

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

Annotations already mark it read-only, but the description adds valuable behavioral context beyond that: it returns plan metadata (planId, planHash, requiredSecretSlots), performs no commit or push, and requires a prior manual commit/push for runtime verification. There is no contradiction with the annotations.

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 four sentences, each earning its place: what the tool plans, what it returns, the critical sibling ordering, and the candidate-only/no-commit behavior. It is front-loaded with the READ-ONLY marker and purpose.

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 complex planning tool with no output schema, the description provides useful return-value context and operational caveats. It could say a bit more about how the returned planId is consumed, but the guidance about BGP ordering and candidate-only behavior is sufficient for an agent to proceed 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?

Schema description coverage is 78%, so the input schema already carries most parameter meaning. The description adds high-level context about what resource categories are planned, but it does not add detailed parameter semantics beyond the schema, which is acceptable given the high 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?

The description names a specific verb ('Plans') and a specific resource ('ordered IPsec candidate mutations'), and enumerates the object types covered. It clearly distinguishes the planning role from sibling functions like panorama_plan_bgp, panorama_apply_ipsec_candidate, and the verification tools.

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 gives explicit sequencing guidance: 'Run this BEFORE panorama_plan_bgp' and explains why BGP peers need the tunnels to exist first. It also states when it is not the right step: 'Candidate configuration only; no commit or push is performed' and that runtime verification requires a prior manual commit and push.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces them with a leading '[READ-ONLY]' marker. Beyond the annotations, it adds genuinely useful context: the specific validation checks performed and the explicit 'does not commit or push' qualifier, which clarifies this step has no side effects even though it sits in a workflow whose siblings do commit and push.

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?

Two tight sentences with the safety qualifier front-loaded, followed by the workflow trigger, the check inventory, and the side-effect guarantee. Every clause earns its place; there is no repetition of schema content or annotation data beyond the necessary '[READ-ONLY]' safety marker.

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 6-parameter tool with 100% schema coverage, a safety profile carried by annotations, and no output schema, the description covers the critical invocation knowledge: when to call, what it verifies, and that it is side-effect free. The only minor gap is that it does not hint at the shape of the result (e.g., pass/fail status or an issue report), which an agent might want when deciding how to consume the preflight outcome.

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 schema already documents all six parameters thoroughly, including serial auto-resolution, the deployment ownership boundary, and the virtualRouter fallback. The description's mention of 'managed serial/template/vsys/vr_root' loosely maps to parameters but adds no semantic detail beyond what the schema provides, so the 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?

The description names a specific verb ('Validates'), a resource ('deployment context'), and a precise workflow position ('before IPsec or BGP planning'). It enumerates exactly what is checked — Panorama endpoint, serial/template/vsys/vr_root, Legacy Virtual Router mode, PAN-OS 11.1.x compatibility — which is enough to distinguish it from sibling planning, validation, apply, and commit tools without opening any 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?

'Before IPsec or BGP planning' gives clear contextual positioning relative to the planning siblings (panorama_plan_ipsec, panorama_plan_bgp), and 'Candidate only; does not commit or push' tells the agent it is a safe early gate rather than a terminal operation. It does not explicitly name alternatives or state when-not-to-use, so it falls short of a 5.

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

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.

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

The [DESTRUCTIVE] prefix aligns with destructiveHint=true and readOnlyHint=false, and the description adds important behavioral context beyond annotations: two-phase safety, plan_id/plan_hash requirements, failure on unowned peers with disable_global, and candidate-only scope with no commit or push.

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 tightly written sentences front-load the destructive warning and cover the core workflow, safety condition, and operational scope. Every sentence adds value 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?

For a destructive 10-parameter tool with no output schema, the description covers the essential lifecycle and safety guardrails. It conveys that the plan returns a removal plan and that apply needs plan_id/plan_hash, though the exact apply response shape is not described.

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 description adds key meaning for mode, plan_id, plan_hash, and disable_global beyond the schema, including the plan/apply sequence and the ownership-safety condition. Schema coverage is 70% and the schema itself provides useful parameter descriptions, so the description effectively supplements rather than carries everything.

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 operation ('two-phase removal of owned BGP resources') and clearly distinguishes it from related candidate tools like panorama_remove_ipsec_candidate and restoration/apply tools. The plan/apply mode detail makes the tool's role unmistakable.

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 gives clear usage context: plan first to get a removal plan, then apply using the returned plan_id and plan_hash, and optionally add disable_global. It does not explicitly name alternatives or state when not to use this tool, but the workflow guidance is strong.

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

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

Annotations already declare destructiveHint=true, and the description adds substantial context beyond that: it discloses that only 'owned' resources are deleted, that a snapshot is taken before deletion with auto-restore on failure, and that the change remains in candidate config with no commit or push. This gives the agent a complete safety profile for a destructive operation — far beyond the bare annotation.

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 sentences with zero filler, and the destructive warning plus core purpose are front-loaded in the first sentence. Every clause carries distinct information: ownership scoping, snapshot/auto-restore behavior, candidate-only scope. Nothing is redundant with the schema or annotations.

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 two-phase tool with 12 parameters and no output schema, the description covers the critical workflow contract and safety behavior well. Minor gaps: it doesn't describe the shape of the returned removal plan (relevant since no output schema exists), and it doesn't state what to do after a successful apply beyond implying commit/push is a separate step. These are small given the strong 83% schema coverage of parameters.

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 high at 83%, setting the baseline at 3, and the description adds genuine value by explaining the coupling between mode, plan_id, and plan_hash — the plan/apply contract that the schema only hints at with 'Required for mode apply'. It also clarifies what each mode returns or requires. The remaining params (deployment as ownership boundary, serial auto-resolution) are already richly documented in the schema, so no compensation is needed.

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 — 'Two-phase removal of owned IPsec resources' — with the destructive nature flagged up front. The two modes are spelled out (plan returns a plan; apply deletes with plan_id/plan_hash), making it clearly distinguishable from siblings like panorama_apply_ipsec_candidate and panorama_plan_ipsec without opening their schemas.

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 clearly explains the within-tool workflow: run mode 'plan' first, then mode 'apply' with the returned plan_id and plan_hash. 'Candidate configuration only; no commit or push is performed' tells the agent this is a middle step in a pipeline, not a final action. It stops short of explicitly naming alternative siblings (e.g., pointing to a commit tool for the follow-up push), so it doesn't earn a 5.

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

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

The description matches the destructiveHint annotation and adds valuable behavioral detail: reversal happens in reverse order, only captured XPath values are restored, unrelated changes are untouched, and a valid operation_id is required. This goes beyond the bare annotation and gives an agent a realistic model of the tool's behavior.

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 four short sentences with no filler. The destructive marker and core action are front-loaded, followed by scope constraints and a prerequisite. 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?

For a two-parameter tool with destructive annotations and no output schema, the description covers the essential behavioral contract: scope, ordering, exclusions, and required input. It could optionally mention error behavior for an invalid operation_id, but that is not a critical 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%, with both operation_id and firewall documented. The description reinforces operation_id's role but does not add meaningful semantics beyond the schema, so the baseline of 3 applies.

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 clearly states a specific verb ('restores'), the resource ('XPath values captured for one operation_id'), and explicitly distinguishes itself from a global candidate revert. This makes it easy to tell apart from siblings like panorama_verify_candidate_operation or remove candidate tools.

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 gives clear operational context: use it to restore a single prior operation by operation_id, and it explicitly says it does not perform a global revert or touch unrelated changes. It does not name an alternative tool or provide an explicit when-not-to-use condition, but the scope is well constrained.

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

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

Beyond the annotations, the description discloses that suggestions are scoped rather than global guarantees, that human verification is required, that WAN loopback detection is also returned, and that BGP policy choices requiring human intent are flagged. It also explicitly states no commit or push is performed, aligning with and enriching the read-only annotation.

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 three sentences with no filler: the READ-ONLY tag is front-loaded, and each sentence contributes distinct information about the operation, limitations, additional outputs, and lack of commit/push. For a tool with 9 parameters and a somewhat complex role, this is appropriately dense.

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?

With no output schema, the description does name the key return categories: bare tunnel interfaces, /30 near/far pairs, WAN loopback detection, and BGP policy flags. It could go further by describing the response structure or error conditions, but for a suggestion-stage read-only tool the essential agent-facing behavior is covered.

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 parameters are already well documented. The description adds broad context about template resolution and scoped collision avoidance, but it does not add specific parameter semantics beyond what the input schema already provides. 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?

The description states a specific verb and resource: it suggests bare tunnel interfaces and /30 near/far pairs after resolving template context and inspecting existing tunnel/BGP link-local state. It also clearly marks itself as read-only and candidate-only, which separates it from apply, validate, commit, and remove siblings.

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 gives clear context for when to use it: during the pre-commit suggestion stage, where human and merged/effective-config verification is still required. It does not explicitly name alternative tools or state when not to use it, but the read-only candidate-only positioning is enough to route an agent appropriately.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's [READ-ONLY] and 'no commit or push' add little beyond reinforcing the candidate-only scope. It does not disclose response behavior, failure semantics, or validation results, which would add value beyond the annotations.

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 a single, front-loaded sentence with no filler. It communicates purpose, side-effect negation, and required inputs compactly. The small redundancy in repeating 'no commit or push' is negligible.

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 tool has no output schema and low parameter coverage, yet the description does not state what the validation returns or how success/failure is signalled. It adequately covers why and when to use the tool, but leaves plan_id/plan_hash semantics and response expectations unspecified.