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

Beyond the annotations, the description discloses that the tool is additive, that it returns only a status object rather than the VM's tag list, and that tag-based group membership may shift after NSX re-evaluation. These are meaningful behavioral details not visible in readOnlyHint, destructiveHint, or idempotentHint.

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 action comes first, followed by the exact return shape and workflow, then the side-effect warning. Every sentence contributes information that is not already present in the 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?

With no output schema, the description compensates by specifying the return shape. It also covers the necessary ordering, verification steps, and a non-obvious side effect. For a write operation with well-documented parameters, this is sufficient for an agent to 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?

The input schema already documents all four parameters with 100% coverage, including the source of vm_id, the optional target, and the meanings of tag_scope and tag_value. The description adds little parameter-specific meaning beyond noting the vm_id source, which the schema already states, so the baseline value 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 action ('Apply an NSX tag') on a specific resource ('a virtual machine'), which clearly distinguishes it from siblings like list_vm_tags and remove_vm_tag. The return-value note also reinforces that this is not a retrieval operation.

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 workflow guidance: use list_vm_tags first to obtain the vm_id and again afterward to observe the result, and check get_group for group-membership effects. It does not explicitly contrast with remove_vm_tag, but the usage context and sequencing are clear enough for an agent to proceed.

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 signal this is a write operation (readOnlyHint=false) and not idempotent. The description adds value beyond annotations by stating the return shape ('created policy dict', else error/hint) and the empty-container behavior. No contradiction with annotations. It could mention duplicate-id behavior, but the current disclosure is solid for a creating 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?

Two tightly packed sentences deliver the action, the write marker, the return contract, and the crucial empty-container/rule-sequencing note. No filler or repetition. The most important behavioral caveat 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?

All 7 parameters are fully covered by the schema, and the description explains the return value and the important empty-container behavior. There is no output schema, so mentioning the return dict fills a real gap. Minor omissions like duplicate-ID handling are not critical given the openWorldHint and idempotentHint annotations.

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 every parameter including defaults and enum meanings. The description does not need to add parameter-level detail; its mention of return keys like id, path, and category is incidental. Baseline 3 is appropriate because the description adds no extra parameter semantics 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+resource pair ('Create a new DFW security policy') and clarifies the resource's nature ('empty container'), which distinguishes it from rule-level tools like create_dfw_rule without needing to open schemas. The [WRITE] tag reinforces the action type. This is clear and unambiguous.

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: the policy starts empty and rules must be added afterwards with create_dfw_rule. This tells an agent how to use the tool in a multi-step workflow. It does not explicitly mention alternatives like update_dfw_policy, but for a create operation the intended use is well implied.

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 exact return shape for success and failure, error hints for invalid enums, overwrite semantics for duplicate rule_id, and the immediate-enforcement behavior unless disabled=True. These are behavioral details not available in the schema or 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?

Three sentences carry all the essential guidance with no filler, and the purpose is front-loaded in the first sentence. Each sentence earns its place: return shape, overwrite behavior, and sibling routing.

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 15-parameter write tool with no output schema, the description covers return value, error format, validation hints, upsert semantics, prerequisite discovery, and alternative tools. Nothing essential for selecting and invoking this tool 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 schema already documents all 15 parameters (100% coverage), so the baseline is 3. The description adds useful semantics by explaining that policy_id must come from list_dfw_policies and that reusing rule_id overwrites the existing rule, enriching the meaning of those parameters beyond their schema descriptions.

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, 'Create a firewall rule under an existing DFW security policy,' which immediately distinguishes it from update_dfw_rule, delete_dfw_rule, and create_dfw_policy. The sibling tools are explicitly named where relevant, reinforcing the 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?

It instructs the agent to pick policy_id with list_dfw_policies first, and explicitly names update_dfw_rule and delete_dfw_rule as the alternatives for editing and removal. The PUT-semantics warning about overwriting on reused rule_id also tells the agent when creation acts as an upsert.

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 annotations, it discloses the return value (created group dict with id, path, expression), the ORing of criteria, and the NSX constraint that AND is only permitted between same-member-type Conditions. This materially clarifies what the tool does and its limitations.

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?

Four compact sentences front-load the primary purpose and [WRITE] signal, then each sentence adds a distinct, necessary detail: return value, criteria combination, and usage sequencing. 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 create operation with 8 parameters and no output schema, the description covers the return shape, membership semantics, constraint on combining criteria, and the recommended call sequence with siblings. Nothing essential for correct 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?

Schema already covers parameter descriptions at 100%, but the description adds the essential combination semantics: tag_scope/tag_value match VMs by tag, ip_addresses match IPs/CIDRs, segment_paths match every VM on segments. This is meaning an agent cannot derive from the schema alone.

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 ('Create an NSX security group') and scopes it with optional membership criteria, so the resource and verb are unambiguous. It also distinguishes the tool from adjacent siblings by explicitly referencing create_dfw_rule and get_group rather than describing generic 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?

It gives direct sequencing guidance: 'Use it before create_dfw_rule' and 'confirm members with get_group.' This tells the agent when to call this tool relative to related operations, and the membership-criteria explanation helps decide whether this is the right group-creation path.

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 destructiveHint annotation, the description discloses the return shape on success and error, and the conditional refusal behavior with active rules. This gives the agent realistic expectations for invoking 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 compact and front-loaded with the operation type and resource. Every sentence delivers useful information: return values, error shape, and prerequisite cleanup steps.

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-parameter tool with no output schema, the description covers return format, error behavior, and prerequisite workflow. The schema covers parameter semantics, so nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%: policy_id is described as 'ID of the policy to delete' and target as 'Optional NSX Manager target from config.' The description adds no extra parameter detail, 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 opens with '[WRITE] Delete a DFW security policy,' naming the verb and resource precisely. It clearly distinguishes this tool from siblings like list_dfw_policies, create_dfw_policy, and update_dfw_policy.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly warns that deletion is refused while active rules exist and instructs the agent to list_dfw_rules and delete_dfw_rule first. This provides concrete when-to-use and prerequisite guidance beyond the bare schema.

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 critical behavioral context: the delete is irreversible and immediate, traffic falls through to lower-priority rules or the policy default, and there is no guard against deleting rules while a policy still contains them. It also discloses the success and error return shapes, which is valuable since there is no output schema.

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 information-dense yet well organized: action and result first, then irreversibility and consequences, then prerequisite checks and safer alternatives, then sibling differentiation. Every sentence earns its place and no content 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?

For a destructive, non-idempotent mutation tool with no output schema, this description covers the essential context: return values, irreversibility, impact on traffic, prerequisite verification, safer alternative, and the distinction from the policy-level delete. An agent has enough guidance to call this tool correctly and avoid common mistakes.

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?

Input schema coverage is 100%, so the schema already documents all parameters including origins from list_dfw_rules and list_dfw_policies. The description reinforces rule_id confirmation and policy membership but does not add substantial meaning 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?

Description opens with a specific verb and resource: 'Permanently delete one DFW rule from its parent security policy.' It clearly distinguishes from delete_dfw_policy and update_dfw_rule by name and behavior, so an agent can tell exactly which operation this is.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use this tool: confirm the rule with list_dfw_rules, check recent hits with get_dfw_rule_stats, and prefer update_dfw_rule with disabled=True when the rule may be needed again. It also contrasts delete_dfw_policy, which refuses while rules remain, versus this tool, which has no such guard.

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 (destructiveHint=true, idempotentHint=false), the description discloses important behavior: the tool refuses deletion if the group is referenced, fails safe if the reference check itself fails, and returns a specific status or error shape. This substantially exceeds what annotations alone convey.

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 dense, with the core action and return behavior front-loaded. Each sentence adds useful information: usage trigger, refusal semantics, fail-safe behavior, and remediation. No filler or redundant restatement of the 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?

Despite having no output schema, the description explains the success and error return shapes and covers the main operational edge cases (referenced groups, check failure, DFW rule remediation). This gives an agent enough context to invoke the tool correctly and interpret its 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?

Schema description coverage is 100%, so both parameters are already documented. The description does not add further parameter-level detail beyond what the schema provides, such as additional constraints or format guidance for group_id or target. 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 opens with 'Delete an NSX security group', a specific verb and resource that clearly states the tool's function. It is easily distinguished from siblings like create_group, get_group, delete_dfw_policy, and delete_dfw_rule, so an agent can select it correctly.

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 an explicit trigger condition: 'Use it once get_group shows the group is unwanted.' It also provides a clear alternative path when deletion is blocked, naming update_dfw_rule and delete_dfw_rule as follow-up actions, which is strong practical 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, idempotentHint, and destructiveHint=false. The description adds useful behavior beyond annotations: the return shape ('one policy object, not an envelope'), the specific fields returned, and the workflow ordering with list_dfw_policies and list_dfw_rules. No annotations are contradicted.

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 front-load the read intent and the key return shape, then provide usage chain and a constraint. Every sentence earns its place, with no fluff 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 single-resource read tool with no output schema, the description covers the return content, the correct input source, the input constraint, and the follow-up action. Combined with the covering annotations and complete input schema, an agent has everything needed to call 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%, so the baseline is 3. The description adds meaningful parameter semantics beyond the schema by specifying that policy_id must be an id, 'never a display name,' and that it should come from list_dfw_policies. This clarifies how to supply the required parameter.

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: 'Get full details of a single DFW security policy.' It explicitly contrasts with list_dfw_policies by saying it returns one policy object, not an envelope, so an agent can clearly distinguish this from the sibling list operation.

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 direct when-to-use guidance: 'Use it once list_dfw_policies has narrowed to one id — never a display name.' It also names the next step, 'Then call list_dfw_rules for the rules inside,' and implicitly excludes display-name lookup. No inference 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?

Annotations already indicate a safe read operation, and the description adds meaningful behavioral context beyond that: counters are cumulative, may read zero on a new rule, and the response is a flat stats object rather than an envelope. This helps the agent interpret results correctly.

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, each earning its place: purpose, return shape, usage context, and ID source. The [READ] prefix and action-oriented opening make the tool's role immediately clear.

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?

Despite having no output schema, the description compensates by listing all returned fields and explaining counter semantics. It also covers where IDs come from and when to call this tool, making it self-sufficient for correct invocation and interpretation.

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 schema already explains all parameters. The description adds minimal parameter-level meaning beyond noting that IDs come from list_dfw_rules, which is useful but not deeply elaborated. 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 ('Get') and resource ('packet/byte hit-count statistics for a DFW rule'), and clarifies the return shape by listing the exact fields. This makes it easy to distinguish from sibling tools like get_dfw_policy or get_idps_status.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly directs when to use the tool: before update_dfw_rule or delete_dfw_rule to check whether a rule still matches traffic. It also points to list_dfw_rules as the source for identifiers, giving the agent actionable 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?

Beyond the readOnlyHint and idempotentHint annotations, the description discloses that members is a truncated envelope of at most 50 items, that truncated indicates withheld members, and that member_count reflects the real size while members.items is only a sample. It also reveals the eventual-consistency behavior around recently applied VM tags.

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?

Every sentence in the description earns its place: purpose, return envelope semantics, counting guidance, and usage preconditions. The most important scoping line is front-loaded, and the additional detail is compact and non-repetitive.

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 present, the description sufficiently describes the return object: expression rules, member_count, and the members envelope with truncation semantics. It also covers practical pitfalls and eventual consistency, making the tool fully callable without external documentation.

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 target and group_id are already documented in the input schema. The description reinforces the group_id usage context by referring to narrowing to one id, but it does not add new parameter-level syntax or format details 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 opens with '[READ] Get details of a security group including membership criteria and effective members,' which names a specific verb, the resource, and the distinguishing content. This clearly separates get_group from sibling tools like list_groups, create_group, and delete_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?

It explicitly states when to call this tool: 'Use it once list_groups has narrowed to one id,' naming the prerequisite sibling directly. It also provides operational timing guidance about NSX membership evaluation and tag propagation latency, helping the agent decide when results are trustworthy.

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 readOnly, openWorld, idempotent, and non-destructive hints, but the description adds meaningful behavioral context: it returns a single bundle rather than an envelope, names the returned fields, and warns that 'signature_status' may be empty where IDS was never enabled. This is exactly the kind of nuance structured hints cannot convey.

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 '[READ] Get IDPS signature status and global IDS settings.' Every subsequent sentence adds value: return shape, field names, usage order, caveats, and exclusions. There is 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?

Despite having no output schema, the description adequately explains the return bundle, its fields, a possible empty state, and how this tool fits into the broader workflow. The combination of annotations, schema, and description gives an agent everything needed to 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?

The only parameter is target, and the input schema already describes it as 'Optional NSX Manager target from config' with 100% coverage. The description does not need to add parameter 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?

Description states a specific verb and resource: 'Get IDPS signature status and global IDS settings.' It also distinguishes itself from siblings by explicitly noting it has no per-signature or per-event detail and that list_idps_profiles should be used for profiles.

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 explicit usage guidance: 'Use it first to confirm IDS is on and current, then list_idps_profiles for the profiles.' It also clarifies what the tool does not provide, which helps an agent avoid using it for the wrong purpose.

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 readOnly, idempotent, openWorld, and non-destructive. The description goes further: it discloses the operation_state enum, the observations' structure typed by resource_type, that Dropped* observations include reason and acl_rule_id, and the critical server-side behavior that a completed traceflow is deleted and its id 404s. This is valuable behavioral context beyond the annotations and no output schema exists to carry the load.

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?

Four sentences, every one earns its place: purpose, usage timing, return payload detail, and the surprising 404 lifecycle. It is front-loaded with the verb and resource, then details, then caveat. No filler or repetition of schema 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?

Even without an output schema, the description conveys what the agent needs: how to obtain the id (from run_traceflow), what operation states to expect, what fields appear in observations, and how to interpret a 404 for completed traceflows. For a simple read-poll tool with rich annotations, nothing essential 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%: traceflow_id is already described as 'Traceflow ID from a previous run_traceflow call' and target as 'Optional NSX Manager target from config'. The description adds no param-specific detail beyond this, so the baseline 3 applies. No parameter is left unexplained by 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?

States a specific verb ('Get'), a clear resource ('existing Traceflow'), and the result ('current state and observations'). It is instantly distinguishable from siblings like run_traceflow, which starts a traceflow, and list/get policy tools, which operate on unrelated resources. The [READ] prefix reinforces the read nature.

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?

Explicitly instructs 'Use this to check a previously initiated traceflow without waiting', which defines the exact moment an agent should call it. The lifecycle note about completed traceflows being deleted server-side and 404ing prevents an agent from misinterpreting a 404 as an error, and implicitly tells it not to use this tool to start traceflows.

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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) are greatly extended with critical behavioral detail: the return envelope shape, the members_error trap ('not an empty group, so do not read it as one'), the 'scope' variant semantics ('system exclusions are NOT in the answer' under user), and that an empty list is not proof of absence — reinforcing openWorldHint. 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?

The description is long but every sentence earns its place: purpose first, then invocation trigger, datapath semantics, return shape, scope caveat, and pagination. There is no filler, and the most correctness-critical warnings (members_error, scope variant, empty-list semantics) are front-loaded before the pagination 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?

With no output schema and 0 required params, the description carries the entire burden of explaining outputs — and it does: envelope, per-row fields, members_error semantics, scope behavior, and pagination. An agent has everything needed to call the tool correctly and interpret results correctly, including edge cases that could otherwise cause false conclusions about VM protection.

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 baseline is 3, and the description adds genuine value: the pagination termination condition ('stop when it is null') and the practical ceiling 'at most 100 groups,' which prevents an agent from over-fetching via limit on a list that never exceeds 100. While the schema already documents next_offset→offset, the description contributes the stop condition and expected page count.

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 '[READ] List the DFW exclusion list — the members no distributed-firewall rule reaches,' a specific verb+resource+scope that instantly distinguishes this from the sibling policy, rule, and group listers. The resource is unambiguous and the semantic definition of an exclusion is stated in one clear clause.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly directs the agent: 'Read this before answering any question about a VM being micro-segmented or protected by DFW policy,' an unambiguous when-to-use trigger. It further clarifies that rules, groups, and policies still exist but 'none of them apply,' informing correct interpretation, though it stops short of naming a specific alternative tool or a when-not-to-use condition.

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 idempotentHint annotations, the description discloses the envelope structure, the meaning of truncated, the null rule_count caveat, and the side effects of name_filter. It also warns against misinterpreting null rule_count as 'no rules,' which is critical behavioral context an agent would otherwise lack.

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: entry-point advice, return envelope semantics, pagination rules, and null-value pitfalls. The most important orientation is front-loaded in the first sentence, and the later paragraphs add essential nuance without 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?

With no output schema present, the description sufficiently explains the return envelope, pagination contract, and null rule_count behavior. It also handles the open-world concern by explicitly warning not to treat a truncated page as the complete answer. For a read-only list tool with four self-documenting parameters, nothing required for correct 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 already provides 100% description coverage for parameters. The tool description adds meaningful operational detail: offset should carry next_offset, limit rejects invalid values, and name_filter makes counts null through the Policy Search API. This is a solid addition above the schema baseline, though the schema already carries the basic parameter meanings.

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 ('List'), a concrete resource ('DFW security policies'), and a scope ('default domain'). It also positions itself as the starting point and names get_dfw_policy and list_dfw_rules as follow-up tools, making it distinguishable from 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?

It explicitly says 'Start here,' then directs the agent to get_dfw_policy for detail and list_dfw_rules for rules. It also provides precise pagination guidance using next_offset and explains when not to treat a page as complete, which fully covers when and how to use this tool versus 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 substantially enriches the annotations by explaining pagination behavior: 'total' is always null, a full page reports truncated=true, offset-based paging is required, and one policy can hold thousands of rules. It also explicitly warns not to loop on 'truncated' and says to stop when 'next_offset' is null, which is valuable behavioral detail beyond the readOnly/openWorld/idempotent hints.

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 purpose and read-only intent, then covers return envelope, pagination semantics, and related sibling tools in a logical order. Despite its length, every sentence adds necessary operational detail, especially around the non-obvious 'truncated' 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?

For a paginated read-only list tool with no output schema, the description is complete: it explains the return envelope fields, the pagination contract, the policy_id source, the sibling for rule statistics, and the special 'total is always null' behavior. Nothing critical is missing for an agent to 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 coverage is 100%, so the schema already documents all four parameters well. The description adds extra meaning by telling the agent where policy_id comes from (list_dfw_policies), reinforcing that offset is fed by 'next_offset', and clarifying the termination rule for pagination. This goes slightly beyond the baseline 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 opens with '[READ] List rules in a DFW security policy', giving a specific verb, resource, and scope. It clearly distinguishes the tool from siblings like list_dfw_policies (lists policies) and get_dfw_rule_stats (rule hit counts), so an agent can select it correctly without inspecting 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 usage context: get the policy_id from list_dfw_policies, then list its rules, and use get_dfw_rule_stats when rule hit counts are needed. It does not explicitly state exclusions for create/update/delete siblings, but the read-only framing and rule-list purpose make the intended use unambiguous.

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, idempotentHint, and destructiveHint=false, and the description reinforces this with '[READ]'. It goes beyond the annotations by fully describing the response envelope fields and the pagination contract, including the critical caveat that 'truncated' is not a loop condition and that a page may not be the whole answer. This is exactly the kind of behavioral context an agent needs in the absence of an output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but every sentence earns its place: it states the operation, describes the return envelope, gives paging rules, and routes deeper work to get_group. The most important scoping and pagination warnings are front-loaded, and there is no filler or repetition of schema content. The structure is well suited to the tool's 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?

Despite having no output schema, the description fully covers the return envelope and pagination semantics, which are the non-obvious parts of this tool. It also tells the agent when to redirect to get_group for deeper detail, covering the main follow-up need. For a read-only list tool with fully documented parameters, nothing essential 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 schema already documents all four parameters. The description adds meaningful semantics by explaining how name_filter and offset are intended to be used together, and by explicitly tying offset to the next_offset field from a previous response. It reinforces the schema's parameter descriptions rather than merely repeating them, though the schema already carries most of the parameter 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 opens with a specific verb-resource pair, 'List NSX security groups in the default domain,' making the tool's core purpose unmistakable. It also distinguishes itself from get_group by pointing to that sibling for a single group's criteria and effective members, and from mutation siblings like create_group and delete_group by the explicit '[READ]' marker. An agent can tell this tool apart from its siblings without opening 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 description provides direct usage guidance: narrow with name_filter, page with offset, and never treat a single page as complete. It explicitly names get_group as the alternative when one group's criteria and effective members are needed. It also warns against looping on 'truncated' and explains the correct next_offset walk, which is actionable and unambiguous.

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 readOnly, idempotent, and non-destructive, and the description builds on that by explaining the list envelope semantics, truncation behavior, and the critical pagination trap ('Do not loop on truncated'). This goes well beyond the annotations and saves the agent from a common 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?

Dense and well-organized: the READ marker and core purpose come first, followed by return shape, then actionable pagination/filtering guidance. Every sentence carries operational value; 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?

With no output schema, the description fully explains the response envelope and field semantics. It also covers the only genuinely tricky behavior (offset/truncated pagination) and routes to the relevant sibling tool. Nothing needed for correct 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?

Schema coverage is 100%, so the baseline is 3. The description adds valuable parameter context by tying offset to next_offset and name_filter to narrowing, which goes beyond the schema's individual descriptions.

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 ('List'), a resource ('IDPS profiles'), and scope ('configured in NSX'), and details exactly what the returned items contain. It also names the sibling get_idps_status for related-but-different data, making it easy to distinguish.

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?

Explicitly instructs when to use this tool ('List IDPS profiles'), when not to treat a page as complete, how to narrow results (name_filter), and redirects to get_idps_status for status/settings. Pagination usage is fully explained with concrete next_offset 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 read-only, idempotent, and non-destructive behavior, and the description adds substantial context: the response envelope (items, vm_id), the always-false truncated guarantee, empty-items semantics, the deprecated 'tags' alias, and error behavior for zero or multiple matches. This goes well beyond what the annotations 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?

Dense but efficient: every sentence covers a needed fact — read nature, response shape, truncation guarantee, deprecation, and error cases. Front-loaded with the action and then systematically explains return behavior without waste.

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 fully owns response documentation and covers items, vm_id, truncated, deprecated alias, and error conditions. It also explains the tool's role as a prerequisite for tag mutations, so nothing needed for correct 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?

Schema description coverage is 100% and already documents vm_display_name as exact, case-sensitive, no-wildcards. The description adds no new parameter syntax, though it does clarify that multiple matches produce an error; baselined at 3 because the schema carries the parameter documentation 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?

Opens with '[READ] List all NSX tags applied to a virtual machine' — a specific verb, resource, and scope. This clearly separates it from sibling mutation tools apply_vm_tag/remove_vm_tag and from policy/group 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?

Explicitly states this tool must be called first to obtain vm_id for apply_vm_tag/remove_vm_tag, and the schema notes that this skill does not enumerate VMs — directing the agent to vmware-monitor's list_virtual_machines when a display name is needed. This gives clear when-to-use and when-not-to-use guidance with named 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?

Annotations already mark this as destructive and non-readonly, and the description adds high-value behavioral context: the return-value shape (and that remaining tags are NOT returned), exact-pair-only deletion, and the immediate side-effect that dynamic group membership changes. The '[WRITE]' marker and 'Remove' wording align with readOnlyHint=false, so no contradiction exists.

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 dense sentences, each earning its place: core action first, return-value clarification second, side-effect plus mitigation third. There is no filler and no redundant restating of schema 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?

With no output schema, the description compensates by spelling out the exact return value and what it does NOT return — essential for correct agent interpretation. It also covers prerequisites, the destructive membership consequence, and verification steps, making it complete for a mutation tool of this complexity.

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 schema descriptions are already rich (vm_id sourced from list_vm_tags, scope/value examples), so the schema carries the parameter burden. The description adds modest value by emphasizing 'exact scope/value pair' removal but does not add anything about the optional 'target' parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource statement, 'Remove an NSX tag from a virtual machine,' and then sharpens it with exact-match semantics: 'Only the exact scope/value pair is removed — other tags survive.' This makes it immediately distinguishable from siblings like apply_vm_tag and list_vm_tags without needing to inspect 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 provides explicit workflow guidance: 'Use list_vm_tags first to confirm the pair' as a precondition and 're-check with get_group' to verify the post-condition. It omits an explicit when-not statement naming apply_vm_tag as the inverse alternative, though the tool name and sibling list make that inference easy.

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?

Discloses that a FINISHED traceflow is deleted server-side and its id 404s, and that only one still IN_PROGRESS at timeout_seconds survives for get_traceflow_result to poll. This goes beyond the annotations and clearly explains side effects, lifecycle, and the non-idempotent nature of the operation.

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 contributes: purpose, return values, use case, follow-up tool, and lifecycle. There is no filler or unnecessary repetition of schema details, and the key 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?

Even without an output schema, it describes return fields (traceflow_id, operation_state, hop-by-hop observations with Dropped* details), the follow-up workflow, and the server-side cleanup behavior. This covers what an agent needs to invoke the tool and process the result 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 baseline is 3. The description adds meaningful context for src_lport_id (VM NIC attachment UUID, how to obtain it) and timeout_seconds (survival for polling), elevating the semantic guidance 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 states 'Run a Traceflow to trace a packet's path through the NSX overlay' with a specific verb, resource, and goal, and the [WRITE] prefix signals mutation. It is clearly distinct from the DFW policy/rule sibling tools and complements get_traceflow_result by describing the run action versus polling.

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?

Explicitly directs the agent: 'Use it to find which DFW rule drops a flow, then get_dfw_rule_stats on that rule,' and describes the polling condition for get_traceflow_result. It also points to vmware-nsx's get_segment_port_for_vm to obtain a source port, providing an alternative for a prerequisite.

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 that this is a partial update where only provided fields change, omitted fields keep their values, and the updated policy dict is returned. This goes well beyond the annotations, which only indicate write/non-readonly semantics and do not describe PATCH 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 compact and front-loaded with the operation type and PATCH semantics. Every sentence adds value: partial-update behavior, return value, prerequisite read, and the sibling tool alternative. 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 6-parameter mutation tool with no output schema, the description covers the essential behavioral contract: what changes, what doesn't, what is returned, and how to distinguish this from the rule update sibling. The schema already documents each parameter individually, so the description is complete enough for an agent to use 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 the baseline is 3. The description adds useful parameter-level context by explaining that omitted arguments retain their existing values and should be read first, which clarifies how the optional parameters behave beyond the schema's individual field descriptions.

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 a clear verb-resource pair: 'Partially update a DFW security policy' with PATCH semantics. It distinguishes itself from the sibling update_dfw_rule by explicitly saying it is for the policy itself, not rules inside it.

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 usage guidance: use it to rename or re-prioritise the policy, and use update_dfw_rule instead for changing a rule inside the policy. It also advises reading the policy with get_dfw_policy first, providing clear context for safe invocation.

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 convey readOnlyHint=false and destructiveHint=false. The description adds meaningful context: [WRITE], PATCH semantics, returned updated rule dict, and that omitted arguments keep their values. It does not contradict annotations and gives enough behavioral information beyond them.

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 efficient sentences: one for the PATCH verb and scope, one for the return/value-preservation behavior, one for usage routing. Every sentence earns its place and there is no 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 12-parameter mutating tool with no output schema, it covers the main operational guidance: return type, prerequisite read, and sibling routing. The only notable gap is the unclear behavior of explicitly passing null vs omitting a parameter, which matters for nullable fields in a PATCH.

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 each parameter having a short description like 'New firewall action.' The main added semantic is that omitted arguments keep their values, but the description does not clarify the null-vs-omitted distinction for clearing fields. The schema carries most of the parameter 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?

States a specific verb and resource: 'Partially update a DFW rule (PATCH — only provided fields change)' and distinguishes it from create/delete alternatives. This is unambiguous and can't be confused with list_dfw_rules or update_dfw_policy.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to use it ('retarget, re-prioritise or disable a rule') and names alternatives ('to add one use create_dfw_rule, to remove one delete_dfw_rule'). Also tells the agent to read current values with list_dfw_rules first, which is essential for a PATCH.

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