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?

Beyond the annotations, the description discloses the write semantics explicitly with '[WRITE]', explains PUT overwrite behavior, describes the return value ('created pool dict, else {"error", "hint"}'), and states the validation constraint between parameters. This adds meaningful behavioral context that annotations alone do not provide.

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

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

The description is front-loaded with the operation type and purpose, then gives concise workflow instructions. Every sentence adds value: prerequisite, constraint, behavior, return value, verification step, and inverse operation. No filler or redundancy.

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

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

For a 7-parameter tool with no output schema and limited annotations, the description is remarkably complete. It covers prerequisites, operational behavior, validation rules, return shape, post-verification step, and inverse relationship. An agent has enough context to use and verify 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 coverage is 100%, so the schema already documents every parameter with examples. The description adds important cross-parameter semantics: start_ip and end_ip must both fall inside cidr, and the same pool_id overwrites. This justifies a score above the baseline 3, though not a 5 since most parameter meaning already lives 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 action ('Create an IP address pool'), a specific resource ('IP address pool'), and its scope ('with one static subnet and allocation range'). It also differentiates from related tools by naming list_ip_pools, get_ip_pool_usage, and delete_ip_pool, making the tool's role in the workflow clear.

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

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

The description gives explicit usage guidance: run list_ip_pools first to avoid overlaps, ensure start_ip and end_ip fall inside cidr, be aware that same pool_id overwrites (PUT), verify with get_ip_pool_usage, and use delete_ip_pool as the inverse. This is strong practical routing and sequencing 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 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 mark the tool as destructive and not read-only, but the description adds crucial behavior: deletion is irreversible, consumers can no longer allocate, NSX rejects deletion if allocations are active, and the return value is a string rather than a dict. 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 compact and front-loaded with the core action, then adds necessary warnings and return-type details. Every sentence serves a purpose, and 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?

For a destructive tool, the description fully covers the essential context: irreversibility, failure conditions, required precheck, user confirmation, and return format. The annotations and schema cover the rest, so 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?

The input schema already provides 100% parameter coverage, including pool_id and target descriptions. The description adds a small amount of extra meaning by linking pool_id to get_ip_pool_usage, but the schema does the primary documentation work.

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 an IP address pool.' It is immediately distinguishable from sibling tools like create_ip_pool, list_ip_pools, and get_ip_pool_usage through its focus on deletion.

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 preconditions: run get_ip_pool_usage on the same pool_id first to confirm the pool is unused, and confirm with the user before deleting. This tells the agent exactly when and under what conditions to invoke the tool.

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

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

The description discloses irreversible consequences, immediate traffic translation stoppage, and potential DNAT/SNAT connectivity breakage, which is rich behavioral context beyond the destructiveHint and idempotentHint annotations. It also clarifies the return format ('confirmation string, or an Error string — not a dict'), a useful trait not present in any 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 compact and front-loaded with the action marker '[WRITE]' and the primary verb. Each sentence earns its place: scope, irreversibility, prerequisite steps, user confirmation, and return type. There is no redundant wording or restatement of the schema.

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

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

For a destructive mutation tool, the description covers what is deleted, why it is dangerous, how to verify before deleting, what to do before calling, and what the response looks like. The output schema is indicated as present, and the description itself communicates the return behavior, so 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 description coverage is 100%, so the baseline is 3. The schema already explains rule_id and tier1_id, and the description reinforces the relationship between them by advising to run list_nat_rules on the same tier1_id. The optional target parameter is not elaborated, but the schema documents its default. Thus the description adds only marginal 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 states a specific verb and resource: 'Permanently delete a NAT rule from a Tier-1 gateway's USER NAT section.' This clearly distinguishes the tool from siblings like create_nat_rule and list_nat_rules, and the qualifier 'USER NAT section' adds precision beyond the name alone.

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

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

The description provides explicit sequential guidance: run list_nat_rules on the same tier1_id first, confirm the rule_id, review its action and networks, and confirm with the user before deleting. This goes beyond vague context to actionable when-to-use instructions that reduce the risk of accidental deletions.

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 richly discloses behavior beyond the destructiveHint annotation: it is irreversible, disconnects all attached VMs, requires a pre-check via get_segment, and returns a confirmation string or an error string rather than a dict. This fully prepares the agent for side effects and failure modes.

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 operation and warning, then provides concise, high-value procedural steps. Every sentence earns its place, and the length is justified given the destructive nature of the operation.

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 an output schema, the description explicitly clarifies the return format (confirmation string or error string), which is useful. It covers prerequisites, irreversibility, user confirmation, and failure behavior, making it complete for a destructive 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 coverage is 100%, so the baseline is 3. The description adds meaningful semantic guidance for segment_id by instructing the agent to run get_segment first and check port_count, which goes beyond the schema's simple 'Segment ID to delete' 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 states a specific verb and resource: 'Delete a network segment.' It clearly differentiates from siblings like delete_tier1_gateway and get_segment by naming the target resource and the warning about attached VMs.

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

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

The description gives clear usage context: run get_segment first, check port_count, and confirm with the user before deleting. It explains the precondition (NSX refuses deletion when ports are attached) but does not explicitly compare against alternative tools for different deletion scenarios.

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

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

Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description adds meaningful behavioral context: the operation is irreversible, traffic immediately falls back or gets dropped, one must confirm with the user, and the return value is a confirmation string or an 'Error: ...' string rather than a dict. This materially improves agent calibration.

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

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

The description is compact and front-loaded with the operation type, followed by necessary warnings, preconditions, and return behavior. Every sentence contributes: irreversibility, traffic impact, prerequisite list, user confirmation, type constraint, and response format. No filler.

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

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

For a destructive 4-parameter tool with annotations and full schema coverage, the description is complete. It covers prerequisites, destructive side effects, parameter consistency, user confirmation, and return shape. An agent has everything needed to safely invoke this tool and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by tying route_id to list_static_routes output, clarifying that tier1_id must be the owning gateway according to gateway_type, and emphasizing that gateway_type must match where the route lives. This goes beyond the raw schema descriptions.

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

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

The description opens with a specific verb and resource — 'Permanently delete a static route from a Tier-0 or Tier-1 gateway' — which precisely identifies the operation and distinguishes it from sibling tools like delete_tier1_gateway, delete_nat_rule, and create_static_route. No ambiguity about what is acted on.

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 tool tells the agent to first run list_static_routes on the same tier1_id to confirm the route_id, destination, and next hops, and instructs user confirmation before deleting. It also requires gateway_type to match where the route lives. It does not explicitly name alternatives or when-not-to-use scenarios, but for a destructive route deletion the workflow guidance is clear enough.

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

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

Annotations already mark destructiveHint=true, and the description substantially expands on this by detailing exact side effects: removes attached segments and NAT rules, irreversibly deletes, removes the default locale-service first, explains the Policy API constraint, and clarifies error/return behavior. 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 front-loaded with the most critical warning, then expands into prerequisites, API behavior, and return type. Every sentence contributes meaningful 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 destructive, non-idempotent write operation, the description covers side effects, irreversibility, required pre-checks, confirmation need, API-specific locale-service handling, and return format. The output schema is also present, so nothing needed to invoke the tool correctly is missing.

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

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

Schema description coverage is 100%, with tier1_id described as 'Gateway ID to delete, as returned by list_tier1_gateways' and target explained as an override. The description adds no new parameter-level details beyond reinforcing that the same tier1_id should be used for pre-checks, so the baseline 3 is appropriate.

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

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

The description begins with '[WRITE] Delete a Tier-1 gateway', clearly identifying the verb and resource. It distinguishes this from sibling create/update tools by emphasizing removal and irreversible side effects.

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 pre-use guidance: run get_tier1_gateway and list_nat_rules on the same tier1_id first, and confirm with the user before deleting. It does not explicitly contrast with alternatives like delete_nat_rule or update_tier1_gateway, but the destructive context makes the appropriate usage clear.

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

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

Annotations already declare readOnlyHint, 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.