Quote network product

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

Annotations only declare safety flags (readOnly=false, openWorld=true, idempotent=false, destructive=false). The description goes far beyond: it declares the fixed prepare_after_payment=true behavior, the auth scopes (networking:read / networking:manage) that defaults do not grant, backend-enforced ownership/feature/2FA locks, the required feature flags (networking:order, spend caps), and a full operational contract for polling (in_progress, reason_code, reason_kind waiting vs failure) plus idempotency-key reuse on transport uncertainty. None of this is available from structured fields.

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?

It is front-loaded correctly (what the tool does comes first), but the single dense paragraph carries some redundancy — 'Only use currently supported catalog tiers' is restated later as 'Choose a supported live catalog tier and its documented request kind' — and the error/polling contract is compressed into run-on sentences. For a tool of this complexity the length is defensible, but it is not tight.

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 no-output-schema, 4-required-param tool, the description covers authorization, feature gating, idempotency, approval workflow, and failure semantics thoroughly. The main gap is that it never states what the quote response actually contains beyond gross_amount in EUR (e.g. whether an operation/resource handle is returned and its key fields), leaving the polling instruction ('poll the returned operation/resource') without a described return shape.

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 only 50%: network_id and idempotencyKey are documented in the schema, while kind and tier are not. The description compensates substantially by mapping catalog products to request kinds (load_balancer -> private_lb for tier nlb, proxy_lb for alb_proxy_3/alb_proxy_5; vpn_gateway directly) and constraining tiers to 'currently supported catalog tiers'. It doesn't fully enumerate the tier pattern or spell out the exact kind/tier pairing for every case, which keeps it short of a 5.

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

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

States a specific verb+resource+scope: 'Create the network product's exact paid quote for COMMON CHECKOUT', and immediately bounds it ('No charge or stock preparation occurs here'). It explicitly distinguishes itself from the sibling order_network_product, and by implication from quote_network_product_renewal, so an agent can route correctly without opening a 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?

Gives explicit when-to-use and when-to-hand-off: 'Create with order_network_product after disclosure and approval', plus prerequisites ('Read current capabilities and owned resource state first; obtain approval for the exact change'). It also states the constraint on inputs ('Only use currently supported catalog tiers'), which functions as usage guidance.

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