ebay_update_calculated_shipping_rules

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

Annotations only cover readOnlyHint=false and idempotentHint=true. The description adds real value beyond them: it discloses the auth scope (sell.account), the required X-EBAY-C-MARKETPLACE-ID header mapping, and the 204 No Content success response with a verification path via the get tool. It stops short of stating whether omitted fields are preserved or overwritten, which matters for a mutation.

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

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

A single dense, front-loaded sentence-block that opens with the action and resource before descending into details. Every clause (IDs source, header mapping, return code, scope) carries information, though the run-on length slightly reduces scannability.

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 mutation tool with nested objects and no output schema, the description supplies the key missing pieces: auth scope, return semantics (204), and a confirmation path. It is nearly complete; the only gap is an explicit statement of update semantics (partial vs full replacement), which matters given the array/nested body.

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 top-level parameters and their nested fields in detail. The description adds context (combinedShippingRuleId originates from the get tool, marketplaceId is a header), but that is minor value over a fully-documented schema. Baseline 3 applies.

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

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

States a specific verb (Update) plus resource (existing calculated combined-shipping rules) and enumerates the mutable fields (discount percentages, weight offsets, amounts, handling rule, combinedDuration). It maps directly to the Account API v2 updateCalculatedShippingRules operation and is cleanly distinguishable from ebay_create_calculated_shipping_rules and ebay_get_combined_shipping_rules.

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 routes the agent to ebay_get_combined_shipping_rules for rule IDs and to confirm results, and states the update context. It doesn't spell out when NOT to use it (e.g. creating a new rule), but the 'update existing' phrasing implies the boundary against its create sibling.

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