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

Annotations already mark the call as non-read-only, but the description adds context: it is a write that only changes BGP settings, will not establish peering, and returns the updated config dict or an error/hint. This goes beyond the annotations by clarifing the exact scope of side effects and follow-up 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?

Three sentences, front-loaded with [WRITE] and the core action, with no redundant phrasing. Every sentence earns its place: what it does, prerequisite workflow, and follow-up.

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 multi-step BGP configuration tool with no output schema, the description covers prerequisite, scope, return shape, and follow-up check. The openWorldHint/idempotent annotations plus reference to siblings complete the picture, so no critical missing guidance.

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 parameter names, types, defaults, and descriptions. The desdescription adds only light context, such as confirming tier0_id via get_tier0_gateway and naming the settings fields, which matches 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 a specific operation: configure BGP settings on a Tier-0 gateway's locale-service, and immediately distinguishes itself by noting it sets BGP settings only, not neighbor creation. The verb 'configure' plus resource clearly separates it from read-only siblings like get_tier0_gateway and get_bgp_neighbors.

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 presribes a workflow: confirm tier0_id with get_tier0_gateway first, then configure, then check get_bgp_neighbors for session state. It also states when not to rely on it—neighbor creation is separate and peering will not come up from this call alone—so the agent can choose alternatives 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?

The description explains key runtime behaviors beyond the annotations: the same pool_id overwrites via PUT, partial failure semantics where the pool may exist even if subnet creation failed, and what error formats to expect. The write nature is already visible from readOnlyHint=false, but the description adds valuable failure/cleanup 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 dense but every sentence adds value: operation type, purpose, precondition, constraint, overwrite semantics, return behavior, and verification/inverse actions. It is front-loaded with the write marker and primary action.

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 write operation with no output schema, the description fully covers what the agent needs: return shape, partial failure mode, error structure, verification step, and inverse tool. This is a complete, self-contained description for a complex multi-step tool.

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 each parameter. The description adds the crucial constraint that start_ip and end_ip must both fall inside cidr, and that pool_id acts as the PUT identifier, which is not evident 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 clearly identifies the operation as creating an IP address pool with a static subnet and allocation range, using a specific verb and resource. It distinguishes itself from sibling tools by naming list_ip_pools, get_ip_pool_usage, and delete_ip_pool.

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 guidance on when and how to use the tool: run list_ip_pools first to avoid overlapping ranges, verify with get_ip_pool_usage, and notes that delete_ip_pool is the inverse. This goes beyond implied usage and routes the agent 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 only convey write and non-idempotent hints; the description adds meaningful behavior: the same rule_id overwrites, the gateway must have an edge cluster and TIER1_NAT advertisement for NAT to be realized, and returns the created rule dict or an error shape. This is exactly the kind of context that helps an agent anticipate 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 front-loaded with the purpose, then provides operational warnings, prerequisites, return expectations, and follow-up steps. Every sentence earns its place, and the length is appropriate for a tool with 7 parameters.

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 tool with no output schema, it is complete: it explains prerequisites, id-clash behavior, return/error shape, and confirmation step. An agent can confidently invoke and verify the result. Nothing critical 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 value beyond the schema by warning that reusing a rule_id overwrites the existing rule, and by pointing to list_tier1_gateways as the source of tier1_id. That extra meaning justifies a 4.

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 'Create a NAT rule on a Tier-1 gateway's USER NAT section', which is a specific verb, resource, and scope. It clearly distinguishes itself from sibling create tools like create_static_route and create_segment, and from list_nat_rules/delete_nat_rule.

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 concrete prerequisites and workflow: run list_tier1_gateways for tier1_id, run list_nat_rules to avoid an id clash, verify with list_nat_rules, and delete_nat_rule is the inverse. It lacks an explicit 'when not to use' exclusion, but the context is 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?

The description discloses useful behavior: it is a write operation, same segment_id overwrites via PUT, it returns the created segment dict or an error/hint, and a gateway-less segment is isolated. However, it contradicts the annotation idempotentHint=false by describing a PUT-style overwrite with the same segment_id, which implies idempotent upsert 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: it states the action first, then packs prerequisites, parameter selection, overwrite behavior, return shape, and follow-up workflow into a few sentences. Every sentence contributes an operational fact 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 write operation with no output schema, the description covers the return contract (created segment dict, otherwise error/hint), the required precondition, the key parameter disambiguation, and the post-creation gateway workflow. It is appropriately complete 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?

Schema description coverage is 100%, so the baseline is 3. The description adds cross-parameter meaning not in the schema: transport_zone_path decides whether subnet or vlan_ids applies, and the wrong one is rejected. It also reinforces that segment_id becomes the /infra/segments/<segment_id> 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 states a specific verb and resource: 'Create an overlay or VLAN-backed NSX network segment.' It also opens with [WRITE], making the operation's nature explicit. It clearly distinguishes this from sibling tools like list_segments, get_segment, update_segment, and delete_segment.

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 a concrete prerequisite ('Run list_transport_zones first for transport_zone_path'), explains the conditional parameter choice ('subnet or vlan_ids applies — the wrong one is rejected'), and outlines the follow-up workflow ('link it with create_tier1_gateway, then verify with get_segment'). It does not explicitly contrast with update_segment, but the guidance is otherwise clear and actionable.

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 important behavioral details: the same route_id overwrites via PUT, the risk of an id clash, the advertisement prerequisite for Tier-0 route propagation, the return shape (created route dict or error/hint), and the recommended confirmation via list_static_routes. This goes well beyond what readOnlyHint/idempotentHint/destructiveHint 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 well-structured and front-loaded with the core purpose, then packs critical caveats and workflow guidance into a few purposeful sentences. No sentence is redundant; each one adds operational 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?

Given that there is no output schema, the description compensates by telling the agent what to expect in return. It covers when to use the tool, what to check before calling, overwrite behavior, an advertisement prerequisite, and how to verify the result, making the call sequence 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 the schema already documents all six parameters. The description adds operational context around route_id because it warns about overwriting with the same id, but it does not add substantially new parameter-level 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 opens with a specific verb and resource: 'Create a static route on a Tier-0 or Tier-1 gateway via the Policy API.' This clearly identifies the tool's purpose and distinguishes it from sibling tools like create_nat_rule, create_segment, and list_static_routes.

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 says when to use the tool ('for destinations not covered by connected or advertised routes') and provides a precondition: run list_static_routes first to avoid an id clash. It also references update_tier1_gateway for advertisement settings and delete_static_route as the inverse, giving clear routing among 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?

The description discloses useful behavior: write semantics, reachability caveat without route_advertisement, PUT-style overwrite for the same tier1_id, return shape, and verification via get_tier1_gateway. However, it contradicts the annotations: the description calls the operation a PUT overwrite, implying idempotency, while idempotentHint is false. Per rules, a contradiction forces a score of 1.

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 and scannable: the [WRITE] tag is front-loaded, followed by purpose, usage prerequisites, behavioral caveat, overwrite semantics, return value, and verification. Every sentence earns its place; there is 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?

For a mutating tool with 6 parameters and no output schema, the description covers prerequisites, failure return shape, verification via get_tier1_gateway, overwrite behavior, and route advertisement side effects. This is complete enough for an agent to select and invoke the tool correctly, aside from the annotation contradiction already flagged.

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 each parameter. The description adds value beyond the schema by explaining where to obtain tier0_path and edge_cluster_path, and by describing the connectivity consequence of omitting route_advertisement. That extra context lifts it above 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 (Create) and resource (Tier-1 gateway to route segments, optionally uplinked to Tier-0). It clearly differentiates from create_segment by saying to use it before create_segment when routing is needed, and from update_tier1_gateway by noting route advertisement can be set later via that sibling.

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 provides when-to-use guidance: use before create_segment when the segment needs routing. It also names prerequisites (get tier0_path from list_tier0_gateways, edge_cluster_path from list_edge_clusters) and identifies update_tier1_gateway as an alternative for setting route advertisement later.

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, but the description adds substantial behavioral context beyond that: the two-phase preview/confirm flow, the refusal conditions (allocated IPs in Policy or NSX pool_usage, including TEP addresses), the irreversibility, and the exact return shape. It also discloses failure modes with the error/hint/blast_radius response. This is rich, non-redundant behavioral disclosure.

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 front-loads the core action and constraint, then explains the preview/confirm flow, refusal conditions, and return format in a compact, well-structured way. The use of quoted keys and a clear conditional structure makes it easy to parse. 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 tool with no output schema, the description is remarkably complete. It covers the action, the safety mechanism, the exact conditions under which deletion is refused, the return values for both success and failure, and the required user-decision workflow. An agent has everything needed to invoke this tool correctly and 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%, so the baseline is 3. The description adds meaning beyond the schema by explaining the semantics of confirm: 'False (default) returns the blast radius and changes nothing. True applies it.' It also clarifies that pool_id comes from list_ip_pools, which is already in the schema but reinforced. The description doesn't add much about target, but the schema already covers it. Overall, the description adds meaningful value on top of the schema.

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

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

The description opens with a specific verb and resource: 'Permanently delete an IP address pool' and immediately adds the key constraint 'refuses while IPs are allocated.' This clearly distinguishes it from sibling tools like create_ip_pool, list_ip_pools, and get_ip_pool_usage. The [WRITE] prefix and the explicit irreversibility statement leave no ambiguity about 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 gives explicit when-to-use and when-not-to-use guidance: it instructs the agent to first run without confirm=True to preview the blast radius, show that to the user, and get their decision. It explicitly warns against setting confirm=True on the agent's own initiative even if the user previously asked to delete. This is model behavior for usage 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 mark destructiveHint=true, and the description adds substantial context: irreversibility, immediate traffic-break impact, preview versus delete behavior, blocker/unmeasured details, and error conditions. It goes far beyond the annotation 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 dense but every sentence earns its place, with the core action and irreversibility front-loaded. Later sentences cover preview semantics, user-decision requirement, refusal conditions, and return format without 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?

Despite having no output schema, the description fully specifies return shape, error shape, blast_radius contents, and guardrail behavior. An agent has everything needed to invoke the tool safely and interpret results.

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 extra meaning by explaining the confirm parameter's preview/apply flow, the error when rule_id is not on the gateway, and the provenance of tier1_id and rule_id from list endpoints.

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 'Permanently delete a NAT rule from a Tier-1 gateway's USER NAT section,' using a specific verb and resource. This clearly distinguishes it from create_nat_rule, list_nat_rules, and delete_tier1_gateway.

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: confirm=False previews blast radius, the agent must show it to the user and get their decision, and confirm=True must not be set unilaterally. It does not explicitly name alternative tools or exclusion cases, 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 flag destructiveHint=true and readOnlyHint=false, and the description goes well beyond that: it states the operation is irreversible, explains that preview mode deletes nothing, describes what blast_radius contains, and warns that attached ports are never disconnected automatically. It also covers the error/refusal path when ports cannot be read. 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 well structured: action, key safety warning, preview mode, user-decision guidance, confirm behavior, and return shape. Every sentence earns its place, and the most important safety guidance is front-loaded. Despite being longer than average, it is appropriately detailed for a destructive 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?

For a destructive tool with no output schema, the description is complete: it explains the preview result, the return payload shape, when deletion is refused, why the confirmation step exists, and how the agent must interact with the user. Nothing needed to call it safely 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 substantial meaning beyond the schema by explaining the confirm workflow: without confirm=True it only previews, and confirm=True re-measures and refuses if ports are attached. This is more than the schema's terse 'True applies it.' It does not describe the target parameter in prose, but the schema already covers it sufficiently.

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: "Delete a network segment" and immediately adds a distinguishing behavior: "refuses while any port is attached." This makes it clear this is the deletion tool for network segments and not a generic or softer operation, especially alongside siblings like update_segment and create_segment.

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 and when-not-to-use guidance: preview first without confirm=True, show the blast radius to the user, and never set confirm=True unilaterally even if the user previously asked to delete. It also states the refusal condition attached ports and explains the safe invocation flow, so an agent knows exactly how 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?

The annotations already mark destructiveHint=true and readOnlyHint=false, but the description goes far beyond that by explaining irreversibility, immediate traffic fallback/drop, the preview-versus-apply behavior of confirm, refusal when routes cannot be read, and the return shape. This fully discloses the tool's behavioral 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 dense but every sentence earns its place. It front-loads the core action, immediately states irreversibility, then explains the preview workflow, user-decision requirement, error conditions, and return format. Nothing is redundant 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 destructive tool with five parameters and no output schema, the description is complete: it covers the operation, the required user-decision workflow, the blast radius contents, error behavior, and the exact return shape including the preview/deleted distinction. An agent has everything needed to invoke 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 coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: confirm=True versus false is tied to preview/apply behavior, gateway_type must match where the route lives, and a route_id not on that gateway is an error. These are critical semantics not fully expressed in the schema.

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

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

The description states a specific verb and resource: 'Permanently delete a static route from a Tier-0 or Tier-1 gateway.' It clearly distinguishes this from sibling create/list tools and from deleting whole gateways. The scope is 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 when-to-use and when-not-to-use guidance: without confirm=True it previews the blast radius and deletes nothing; the agent must show the user the blast radius and get a decision; it must not set confirm=True on its own even if the user previously asked to delete. It also warns that gateway_type must match the route's gateway. This is exceptional usage 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?

The annotations already mark it destructive, but the description goes well beyond them: it explains irreversibility, preview mode, re-measurement, refusal conditions, that dependents are never removed, the deletion order, and the exact return/error shapes. This is substantial value beyond the structured 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 carries essential safety or behavioral information. It is front-loaded with [WRITE], irreversibility, and the preview/confirm distinction, then systematically explains the confirm=True path and return values 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?

For a destructive, dependency-sensitive operation with no output schema, the description is remarkably complete: it covers preview output, refusal conditions, deletion behavior, return payloads, and error responses. An agent has enough context to invoke the tool safely and 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 tier1_id, confirm, and target. The description reinforces confirm's meaning (preview vs. apply) and tier1_id's origin, but does not add significant parameter-level detail beyond the 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?

States a specific verb and resource ('Delete a Tier-1 gateway') and immediately distinguishes its destructive, dependency-aware behavior. It is clearly differentiated from sibling create/update/list/get tools by its explicit deletion and refusal semantics.

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 clear and actionable usage context: confirm=False is a preview, the user must see the blast radius first, and the agent must not set confirm=True unilaterally. It does not explicitly name alternative tools for resolving dependencies, but the dependency-refusal guidance effectively tells the agent when deletion is not possible.

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 non-destructive behavior. The description goes further by disclosing the return shape ('one dict, not the list envelope'), the first-locale-service limitation, and that a gateway with none 'returns a hint, not an error.' This is valuable behavioral context 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 well-structured and front-loaded: a one-sentence purpose, a usage sentence, return details, edge-case behavior, and cross-references to related tools. Every sentence earns its place and none are redundant.

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?

There is no output schema, so the description compensates by listing the returned fields (tier0_id, locale-service info, BGP config, neighbors, session status). It also covers edge cases and provides fallback guidance to related tools. Given the simple two-parameter schema and rich annotations, nothing important 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 tier0_id and target. The description does not add new parameter details beyond what the schema provides; it only references the tier0_id source ('as returned by list_tier0_gateways'), which is also in the schema. Thus 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 a specific verb and resource: 'Get BGP configuration and neighbor status for a Tier-0 gateway.' It clearly distinguishes this from sibling tools like configure_tier0_bgp (write operation), get_tier0_gateway (general gateway info), and list_static_routes (static route listing).

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 the tool: 'verify dynamic routing after configure_tier0_bgp, or when troubleshooting north-south connectivity.' It also routes to alternatives: 'check get_edge_cluster_status' if sessions are down and notes static routes are covered by list_static_routes.

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 read_only/destructive/idempotent annotations, the description discloses the return shape ('Returns one dict (not the list envelope)'), the exact fields, and the important limitation that it reports member status only, routing degradation reasoning to another tool. The '[READ]' label also matches 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 four sentences, front-loaded with purpose and usage, then the output contract, then a boundary against a sibling. Every sentence earns its place with 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?

With only two parameters, full schema coverage, read-only annotations, and no output schema, the description provides sufficient context: when to call, what it returns, and where to get related information. No essential detail for invoking it 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 baseline is 3. The description adds meaningful context beyond the schema by indicating that cluster_id is obtained from list_edge_clusters and by clarifying the output is a dict rather than a list. This is a slight enhancement over the schema, though not critical.

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] Check status of an edge cluster (member health, overall status)', which names a specific verb and resource. It clearly distinguishes this tool from siblings like get_transport_node_status and list_edge_clusters by stating its scope and explicitly noting what it does not cover.

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?

Gives explicit conditions for use: 'Use this after list_edge_clusters when north-south traffic, NAT or BGP looks broken — Tier-0/Tier-1 stateful services run on these members.' It also points to the alternative for deeper diagnostics: 'why a member is degraded comes from get_transport_node_status.' This is direct, actionable guidance for 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 provide readOnly/idempotent safety, and the description adds valuable behavioral context: return shape is a single dict (not a list envelope), empty allocations list means unused rather than failure, and failure returns a specific {'error', 'hint'} structure. This goes well 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 well-structured and front-loaded with the core purpose, followed by usage context, return format, and error semantics. Every sentence adds meaningful information with 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?

With no output schema, the description compensates by specifying the returned dict fields (pool_id, allocation_count, allocations with id/display_name/allocation_ip), the meaning of an empty list, and the error format. It also covers the prerequisite list_ip_pools and the delete_ip_pool interaction, making it fully actionable.

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 target and pool_id documented in the input schema. The tool description does not add parameter-specific meaning beyond what the schema already provides, 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?

Description states a specific verb ('Get') and resource ('IP allocations for one IP address pool'), clearly distinguishing this from listing all pools. It explicitly says it returns a single dict, not the list envelope, which differentiates it from sibling list_ip_pools.

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: 'Use this after list_ip_pools' to check consumption, for diagnosing TEP address exhaustion, or before delete_ip_pool. It also explains the prerequisite relationship and why it matters, making the invocation context 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 mark this as readOnly, idempotent, and non-destructive, but the description adds important behavioral context beyond them: it explains the returned fields, the 50-port limit, the lack of a single UP/DOWN flag in NSX, and the health criterion of realized bindings on at least one transport node. This meaningfully 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?

The description is front-loaded with the action, then a usage paragraph, a return-value paragraph, a critical NSX semantic clarification, and a fallback pointer. Every sentence earns its place and there is minimal 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?

With no output schema, the description carries the burden of explaining return values, and it does so explicitly: admin_state, attachment, realized_bindings_count, transport_node_ids, and the health interpretation. It also flags the 50-port truncation and provides a next-step tool when bindings are missing, making the definition complete for a read-only inspection tool.

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 segment_id and target. The description confirms segment_id is the port-inspection scope but adds no additional parameter-level syntax or format details, matching the baseline for fully covered 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?

Description opens with a specific verb and resource: 'Check realized state of all ports on a segment', and immediately scopes it to the first 50 ports. It distinguishes itself from siblings by explaining when to use it relative to get_segment_port_for_vm and delete_segment, and contrasts with get_transport_node_status for the binding-missing case.

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?

Explicit guidance covers both when to use and when not to use: 'Use this after get_segment_port_for_vm' and 'before delete_segment to see whether ports are still attached.' It also names the alternative path: 'If bindings are missing everywhere, check get_transport_node_status.' This is strong routing behavior for an 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?

Beyond the readOnlyHint/idempotentHint annotations, the description discloses important behavior: the return shape is a single dict rather than the typical list envelope, and it explicitly states that only online nodes are listed, so a missing node means down. This is critical non-obvious context that helps an 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?

The description is compact, front-loaded with the purpose and usage directive, and every sentence adds value. It includes return fields, a behavioral caveat, and a pointer to the next logical tool without any 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?

With no output schema, the description fully compensates by enumerating the returned fields and explaining the meaning of missing nodes. It also provides the recommended invocation context and follow-up action. Nothing essential is missing for an agent to call and interpret 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% for the single optional target parameter, so the schema already explains it adequately. The description adds nothing about parameters, but none is needed given one optional parameter with a clear default. This matches the baseline score 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 names a specific verb and resource: 'Get NSX Manager cluster status', specifying node health and control/management plane health. The '[READ]' prefix reinforces the operation's nature. This clearly distinguishes it from sibling status tools like get_edge_cluster_status or get_transport_node_status by targeting the manager cluster 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 explicitly instructs to 'Start any NSX health check here' and explains why: if the manager cluster is degraded, other readings are suspect. It also names a sibling tool, list_nsx_alarms, as the follow-up for actual firing alarms, giving a clear when-to-use and when-to-move-on 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?

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond that: it states the exact return shape ('one dict, not the list envelope'), enumerates returned fields, discloses a truncation boundary ('first 50 ports only'), and warns that attached ports affect deletion. This is rich behavioral disclosure that helps an agent predict consequences.

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 but information-dense. Every sentence serves a purpose: scoping the operation, specifying the return contract, describing output fields, noting the truncation limit, and routing to related tools. It is front-loaded with the core purpose and does not waste words.

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 compensates by enumerating return fields and the response style. It covers usage sequence, related tools, deletion implications, and behavioral limits. For a simple read-by-id tool with strong 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%, so the schema already documents segment_id and target. The description reinforces that segment_id comes from list_segments, but this is largely already present in the schema. It does not add substantial new parameter-level semantics beyond that, 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 opens with a specific verb and resource: 'Get full details for one network segment, including its attached ports.' It clearly distinguishes this tool from list_segments by scoping it to a single segment, and the title/name are not merely restated.

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 'Use after list_segments to inspect one segment' and provides direct routing to alternatives: 'For per-port realized state use get_logical_port_status; to change the segment use update_segment.' It also gives a practical precondition involving delete_segment, so an agent knows exactly when to use this tool versus 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?

Beyond the read-only annotations, the description discloses the return shape ('one dict, not the list envelope'), the exact-looking matching on display name, and the important empty-result semantics: empty matched_ports means no VIF is attached, not that the VM is missing. It also outlines the lookup/fetch/match mechanics.

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: the READ label, usage trigger, uniqueness claim, return format, matching rule, empty-result caveat, next step, and explicit exclusion. It is front-loaded with the core purpose and avoids 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 tells the agent what the returned dict contains and its structure. It also covers common interpretation pitfalls and routes the agent to the right follow-up tool, making the description complete for correct invocation and result handling.

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 covers vm_display_name and target with 100% coverage, so the baseline is 3 from the schema. The description adds meaningful semantic value by emphasizing exact display-name matching and explaining what a missing match means, which helps the agent interpret the parameter's output behavior.

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 and resource: exactly which segment port(s) a VM maps to via VIF attachments. It also differentiates itself from siblings by calling itself 'the only tool mapping a VM name onto NSX topology.'

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 frames when to start: 'Start here for "why can this VM not reach the network?"' It also tells the agent what to do next with get_logical_port_status, and explicitly excludes VM power/placement concerns by directing to vmware-aiops.

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 adds meaningful behavioral detail beyond that: it returns a single dict rather than a list envelope, enumerates the returned fields, and explicitly notes that current forwarding state is not included. There is 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 compact and efficiently front-loaded with the core purpose, followed by usage context, a sibling alternative, and return-shape details. Every sentence adds actionable information with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no output schema, the description compensates well by listing the exact returned fields and the response shape. It also covers the key operational context: when to call it, how it relates to sibling tools, and its static-config limitation. An agent has enough information to invoke and interpret 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 coverage is 100%, so the baseline is 3. The description adds extra meaning by explaining why tier0_id matters (it is needed to construct tier0_path for create_tier1_gateway) and reinforces that the ID comes from list_tier0_gateways. This goes slightly beyond the schema's own parameter 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 starts with a specific verb and resource: 'Get configuration details for one Tier-0 gateway', and adds the clarifying parenthetical 'north-south edge router'. It clearly distinguishes this from list_tier0_gateways (plural listing) and get_tier1_gateway (different resource).

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 after list_tier0_gateways, use it to inspect HA configuration or build the tier0_path for create_tier1_gateway, and use get_bgp_neighbors instead for BGP peering state. It also states the limitation that this is static config only, so an agent knows not to use it for forwarding 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?

Beyond the readOnlyHint/idempotentHint annotations, the description discloses return format (single dict not list envelope), the exact fields returned, and what is deliberately omitted. It also explains the update workflow dependency, providing meaningful behavioral context an agent cannot derive from annotations alone.

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 well-structured: a READ marker, a one-line purpose, usage ordering, return details, and a pointer to a sibling tool. Every sentence earns its place and no unnecessary filler 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 simple two-parameter, no-output-schema tool with rich annotations, the description covers purpose, ordering, return shape, included fields, and exclusions. Nothing an agent needs to invoke it 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 schema fully documents both target and tier1_id. The description reiterates that tier1_id comes from list_tier1_gateways, which the schema already says, so it adds little semantic value beyond the structured definition.

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?

Clearly states a specific verb and resource: 'Get detailed info for one Tier-1 gateway.' It distinguishes itself from list_tier1_gateways by specifying a single detail dict rather than the list envelope, and from list_segments by noting attached segments are not included. The purpose is unambiguous and differentiates 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?

Explicitly provides a usage sequence: use after list_tier1_gateways and always before update_tier1_gateway, with the rationale that update is a PATCH requiring current values. It also names list_segments for attached segments, giving clear when-to-use and 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?

Beyond the safely annotations, the description discloses that it returns one dict rather than a list envelope, enumerates the status fields, and warns that the data is 'Point-in-time only — no history'. This goes well beyond what readOnlyHint and idempotentHint already communicate.

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 core operation, then compactly covers when to use it, what it returns, and when to switch to a sibling tool. Every sentence earns its place and nothing repeats 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?

Even though no output schema exists, the description tells the agent exactly what the return dict contains, that it is point-in-time, and which sibling tools cover broader or segment-specific diagnossis. Given the annotations and 100% schema coverage, an agent has everything needed to invoke 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 schema already covers both parameters at 100%, so the baseline is strong. The description adds useful meaning by clarifying that node_id refers to an ESXi host or Edge node and by directing the agent to list_transport_nodes as the source of valid IDs. The default target parameter needs no extra explanation.

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 operation and resource: 'Get realized runtime status of one transport node (ESXi host or Edge node)'. It also distinguishes itself from get_edge_cluster_status and get_logical_port_status, so an agent can select it 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?

It gives explicit triggers ('Use after list_transport_nodes when a node looks degraded or overlay tunnels are suspect'), an explicit alternative ('for cluster-wide edge health use get_edge_cluster_status instead'), and a follow-up instruction for segment-local tunnel failures. Usage guidance is complete.

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 readOnly/idempotent annotations, the description discloses pagination mechanics: check truncated, pass next_offset back as offset, stop when next_offset is null, and do not loop on truncated. It also warns that limit values 0 or negative are rejected, adding operational behavior not visible in 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 detailed but every sentence serves a purpose: purpose, pagination, truncated semantics, workflow, and a dependency warning. It is front-loaded with the core read operation and then layers protocol details without 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?

With no output schema, the description compensates by explaining the result envelope, truncated, next_offset, and the stop condition for pagination. It also provides the cross-tool context about cluster_id and Tier-1 NAT, making the tool's role in a multi-step workflow clear.

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 covers limit, offset, and target with useful descriptions, so the baseline is 3. The description adds the '0 or negative is rejected' constraint and clarifies the offset walk pattern with next_offset and the null stop condition, which is extra semantic value 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] List all edge clusters with member count and deployment type,' naming a specific verb, resource, and output fields. It clearly differentiates from get_edge_cluster_status and other sibling tools by framing this as the collection-listing entry point.

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 to use this tool first to resolve a cluster_id and then call get_edge_cluster_status for health, and it explains the relationship to create_tier1_gateway's edge_cluster_path. This gives the agent concrete routing guidance among siblings rather than leaving usage 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?

Beyond the readOnly/idempotent annotations, it discloses pagination semantics: checking truncated, passing next_offset back as offset, stopping when null, and why not to loop on truncated. It also notes the summary does not reveal individual address allocations, which is a material behavioral limitation.

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 core purpose, then structured into pagination and workflow guidance. Each sentence carries operational value and 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?

With no output schema, the description still covers the essential return envelope fields (truncated, next_offset), pagination, and the relationship to sibling tools. An agent has everything needed to call it correctly and interpret the response.

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 already 100%, and the description adds operational meaning: limit is the page size with rejection of 0/negative values, offset is rows to skip, and next_offset should be passed back. This is more than the schema's field descriptions 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 '[READ] List all IP address pools with subnets and usage summary,' giving a specific verb, resource, and scope. It later contrasts with get_ip_pool_usage and create_ip_pool, so an agent can distinguish it from the closest 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 to use this first to resolve a pool_id before get_ip_pool_usage, and to run it before create_ip_pool to avoid overlapping ranges. This provides clear when-to-use guidance and names 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 read-only, idempotent, and non-destructive. The description goes further by disclosing the result envelope, the meaning of `truncated`, the pagination contract via `next_offset`, and the caution not to loop on `truncated`. This is exactly the kind of behavioral context that structured fields 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 dense but every sentence earns its place: purpose, envelope note, pagination instructions, and workflow guidance. The most critical usage information is front-loaded, and the formatting separates distinct concerns for easy parsing.

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 there is no output schema, the description compensates by explaining the result envelope and pagination fields. It also provides the required prerequisite (`tier1_id` from list_tier1_gateways) and situates the tool among its siblings. Nothing an agent needs to call it 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?

The schema already covers every parameter with descriptions (100% coverage), so the baseline is 3. The description adds substantial meaning beyond the schema by explaining the pagination loop: pass response `next_offset` back as `offset`, stop when it is null, and do not use `truncated` as a loop condition. It also documents edge cases like 0/negative limit rejection.

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: list NAT rules on a Tier-1 gateway, and scopes it to the USER section. It also distinguishes itself from create_nat_rule and delete_nat_rule by referencing their placement in the workflow.

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 tells the agent when to use the tool: after obtaining tier1_id from list_tier1_gateways, before create_nat_rule to avoid id clashes, and before delete_nat_rule to confirm rule behavior. It also states a clear exclusion: only the USER section is listed, not NSX-internal NAT.

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 read-only, idempotent, and non-destructive; the description goes beyond them with the exact-match severity behavior, pagination semantics, the warning not to loop on `truncated`, and the default-of-1000 tradeoff. This gives an agent critical operational knowledge it could not infer from annotations or 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 long but every sentence serves a purpose: purpose, envelope caveat, exact-match caveat, paging rules, default rationale, and the health-check workflow. It is front-loaded with the intent and then layered with operational warnings in logical order.

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?

There is no output schema, so the description compensates by disclosing the envelope, `truncated` field, `next_offset`, and the fields returned (feature, description, entity). It also ties the tool into the health-check workflow, making it complete enough for an agent to call and interpret 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 baseline would be 3, but the description adds meaning beyond the schema: 0/negative `limit` is rejected, `offset` receives the prior `next_offset`, stop when `next_offset` is null, and `severity` must be called per exact value. This directly impkeys correct invocation.

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 the exact verb, resource, and scope: 'Get active NSX alarms at one severity, with feature, description, and entity.' It also clarifies the severity filter is exact-match, which distinguishes the behavior from a typical 'severity or higher' list 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?

It gives explicit orchestration guidance: start at get_nsx_manager_status, then call this tool, then drill into the entity with get_transport_node_status or get_edge_cluster_status. It also tells the agent to call once per severity to build a full picture, and explains how to page with `next_offset`, so there is no ambiguity about when or how 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 cover read-only, open-world, idempotent, and non-destructive nature, so the bar is lower, but the description adds substantial behavioral context beyond annotations: the result envelope shape (items, returned, limit, total, truncated, hint), the meaning of `truncated`, and the `next_offset` pagination walk including the warning 'Do not loop on `truncated`'. This materially changes how an agent interprets results.

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?

Front-loaded with the READ marker and core purpose, then the envelope contract, then pagination details, then routing guidance. Every sentence earns its place; the pagination warnings prevent real misuse. Despite the length, it is tightly organized and readable.

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 documents the return envelope and the critical `truncated` semantics. It covers pagination, stop conditions, parameter defaults, and relationships to sibling tools. For a list/pagination tool with this complexity, nothing an agent needs to call it 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 coverage is 100%, so baseline is 3. The description adds meaningful behavior beyond the schema: how `offset` should be fed from the previous response's `next_offset`, that `limit` is the page size with rejection of 0/negative values, and the termination condition for a paginated walk. It doesn't just repeat property names; it explains the lifecycle of these 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 ('List') and resource ('all NSX network segments') with the exact fields returned: type, subnet, admin state, and port count. The [READ] prefix and naming of sibling tools like get_segment and get_logical_port_status distinguish it from alternatives. No ambiguity remains about what this 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?

Explicitly says 'Use this first to resolve a segment_id, then get_segment...' and clarifies that distributed firewall rules belong in vmware-nsx-security. It also tells when not to use it and names the exact sibling alternatives. This is model guidance for 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 mark readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral detail: pagination semantics, truncated's meaning, how to stop on null next_offset, the empty-list-not-error behavior for wrong tier, and the exclusion of BGP-learned routes. There is 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 front-loaded with the core purpose and then delivers dense, non-redundant guidance about pagination, usage context, tier matching, and BGP exclusion. Every sentence earns its place; 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 explains the result envelope and key fields like truncated and next_offset. It also covers edge cases, provides usage context relative to sibling tools, and leaves no ambiguity an agent would need resolved before calling it.

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?

Even though schema coverage is 100%, the description adds meaning beyond the schema: it explains the pagination contract for limit/offset/next_offset, states that zero or negative limit is rejected, clarifies that tier1_id may be a Tier-0 or Tier-1 ID depending on gateway_type, and warns about wrong-tier behavior. This is genuinely useful parameter guidance.

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 static routes on a Tier-0 or Tier-1 gateway,' giving a specific verb, resource, and scope. It clearly distinguishes itself from sibling create/delete route tools and from get_bgp_neighbors by noting BGP-learned routes are not included.

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 says when to use this tool: before create_static_route to avoid ID clashes and before delete_static_route to confirm destination and next hops. It also warns that gateway_type must match where the route lives and directs users to get_bgp_neighbors for BGP routes.

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, openWorldHint, idempotentHint, destructiveHint), the description discloses important runtime behavior: the response is a result envelope, `truncated` must be checked, and `next_offset` drives pagination. It warns not to loop on `truncated`, which is a subtle and valuable behavioral detail not visible 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?

The description is dense but every sentence earns its place: purpose is front-loaded, pagination rules are grouped, and sibling routing is in the final paragraph. No content is redundant with the schema or annotations, and the structure makes the operational contract easy to follow.

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, this description fully compensates by explaining the result envelope, `truncated`, `next_offset`, and how to detect the end of a paginated walk. It also tells the agent what fields are available (HA mode, transit subnets) and how the result connects to downstream tool calls, making the tool callable correctly without external knowledge.

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 value by explaining pagination semantics clearly: `limit` is page size, 0 or negative is rejected, `offset` is rows to skip, and `next_offset` should be passed back as the next `offset`. It also clarifies when to stop paging, which goes beyond the 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 '[READ] List all Tier-0 gateways with HA mode and transit subnets', which names a specific verb, resource, and returned fields. It also clearly distinguishes itself from get_tier0_gateway by positioning list_tier0_gateways as the first step to resolve a tier0_id.

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 tells the agent when to use this tool: use it first to resolve a tier0_id, then use get_tier0_gateway for HA detail and the tier0_path needed by create_tier1_gateway, or get_bgp_neighbors for peering state. It also states a key constraint: Tier-0s are not created by this skill, only Tier-1s are.

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, openWorldHint, idempotentHint, and destructiveHint=false, and the description adds substantial behavioral detail: pagination via next_offset, the meaning of truncated, the warning 'Do not loop on truncated,' and the semantic rule that an empty tier0_path means the gateway is standalone. This is beyond what annotations 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 organized into three tight paragraphs: purpose, pagination contract, and usage context. Every sentence earns its place, especially the truncated/next_offset warning, which prevents a real pagination bug without adding bloat.

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?

There is no output schema, so the description appropriately explains the result envelope, truncated, next_offset, and stop condition—everything needed to consume the response correctly. It also covers prerequisite relationships with sibling tools and the standalone-gateway semantic, making the tool usable 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% and already documents limit, offset, and target with defaults and descriptions. The description adds operational semantics beyond the schema: '0 or negative is rejected,' the exact page-size range/default, and the pattern of passing next_offset back as offset until null. It doesn't mention target, but the schema fully covers that 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 '[READ] List all Tier-1 gateways with linked Tier-0 path and route advertisement,' naming the exact verb, resource, and scope. It also distinguishes itself from get_tier1_gateway by saying 'Then get_tier1_gateway for detail,' and from tier-0 listing tools by explicitly targeting Tier-1 gateways.

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 'Use this first to resolve a tier1_id' and lists the sibling tools that require it: create_nat_rule, create_static_route, list_nat_rules, and update_tier1_gateway. It also explains when to move to get_tier1_gateway for detail and notes the standalone-tier0_path caveat, giving an agent clear decision 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?

The description goes well beyond the readOnlyHint/idempotentHint annotations by disclosing pagination mechanics: limit validation, offset skipping, next_offset passing, and the subtle warning that truncated stays true on the last page of a walk. It also clarifies that the summary status does not explain why a node is degraded.

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 efficiently organized: a one-line READ summary, then pagination rules, then usage guidance. Each paragraph earns its place, and critical warnings like the truncated behavior are explicitly stated rather than implied.

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 no output schema, the description adequately covers return envelope handling, pagination, and the distinction from get_transport_node_status. An agent can correctly invoke and walk the results without additional inference.

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, but the description adds meaningful semantics: limit values 1-1000 with rejection of 0/negative, offset meaning 'rows to skip', and the response carrying next_offset to feed back. Only the target parameter is left to the schema, which already documents it sufficiently.

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 clear verb and resource: 'List all transport nodes (ESXi hosts and Edge nodes) with type and status.' It defines exactly what the tool returns and later distinguishes it from get_transport_node_status, which provides deeper per-node details.

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 'Use this first to resolve a node_id, then get_transport_node_status for that node's tunnels, controller connectivity and pNICs.' This tells an agent when to choose this tool over the sibling status tool and what not to expect from 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 mark this as read-only, idempotent, and non-destructive, so the description focuses on valuable behavioral details: pagination semantics, how to use next_offset, when to stop, and the warning not to loop on truncated. It also discloses response row fields and the VLAN-versus-overlay dependency, which goes well beyond annotation coverage.

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 core purpose, then organized into pagination behavior, integration with create_segment, and expected result fields. Every sentence adds distinct value with no filler or repetition of schema defaults.

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 explaining the result envelope and key row fields. It also covers pagination mechanics, required path construction, VLAN vs overlay parameter requirements, and error rejection behavior, making the tool self-sufficient for an agent to call 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?

Although the schema already documents all three parameters with good descriptions, the tool description adds meaningful operational semantics: 0 or negative limit is rejected, next_offset should be passed back as offset, stop when it is null, and truncated must not be used as a loop condition. This materially improves correct parameter usage beyond what the JSON schema alone 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 clearly states 'List all NSX transport zones' with a specific resource and scope, and immediately disambiguates what transport zones are in the NSX context. It is distinct from sibling tools like list_transport_nodes or list_segments because the resource and domain are 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 guidance: 'Use this first when building a segment' and explains how create_segment depends on the transport_zone_path returned here. It does not explicitly name alternatives to avoid, but it provides a clear usage context and practical downstream integration that an agent can act on.

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 partial-update semantics ('Only the fields you pass change'), the significant side effect of subnet changes (gateway re-address and potential traffic drop), and the return/error contract. This gives the agent the behavioral awareness needed to use the tool safely. The traffic-drop warning is a side-effect disclosure, not a contradiction of destructiveHint=false.

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: action and method first, then usage guidance, then risk warning, then return format. Every sentence carries essential information with no filler or repetition of schema contents.

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 4-parameter mutation tool with no output schema, the description is complete enough for an agent to select and invoke it correctly. It covers preconditions, alternative behavior, side effects, and the return/error shape, leaving no critical operational gap.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful parameter-level context by explaining partial-update behavior and warning specifically about the subnet parameter's network impact. It doesn't add detail for target or display_name, but those are already well described in the schema.

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

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

The description clearly states the action ('Update an existing network segment'), the resource, and the method ('partial update via PATCH'). It explicitly distinguishes itself from create_segment and delete_segment, so an agent can tell exactly what this tool does relative to its 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 concrete guidance: call get_segment first, prefer this over create_segment for existing segments, and check port_count before changing the subnet. It also explains why create_segment is the wrong choice (PUT overwrites everything). This is explicit when-to-use and when-not-to-use context.

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 reveals important behavior: only passed fields change, route_advertisement is replaced as a whole list, re-applying identical values is harmless, and the return value is the updated gateway dict or an error dict. This adds meaningful context about partial-update semantics and 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 well-structured with the operation tag front-loaded, followed by key behavioral rules, a comparison with create, and return behavior. Every sentence carries useful information without 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 5-parameter tool with no output schema, the description covers partial-update semantics, the tricky route_advertisement parameter, sibling differentiation, idempotency nuance, and return format. No critical gaps remain for an agent to call 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 coverage is 100% and each parameter already has a helpful description. The tool description adds critical semantic value beyond the schema by explaining that route_advertisement is sent as a whole list and that include every type you want kept, which is essential for correct invocation.

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 ('partially update'), a clear resource ('existing Tier-1 gateway'), and the HTTP method (PATCH). It clearly distinguishes itself from create_tier1_gateway by noting that create is a PUT that overwrites everything.

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 guidance: use get_tier1_gateway first, prefer this over create_tier1_gateway for existing gateways, and handle route_advertisement as a whole list. This clearly tells an agent when to use this tool and when not to.

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