ebay_update_combined_payments

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

Annotations already flag it as a write (readOnlyHint=false) and idempotent. The description adds real value beyond that: the 204 No Content success shape, the required sell.account scope, and the header-based marketplace transmission. It does not detail reversibility or error modes, so not a 5.

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?

Single dense but front-loaded passage: purpose first, then the value enum, header note, return behavior, and scope requirement. Every element is functional with little waste, though the parenthetical API reference is slightly redundant 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 mutation with no output schema, the description covers the return semantics (204), a confirmation path, and the auth scope, which is what an agent needs. The only minor gap is enumerating failure/edge behavior, keeping it just below fully 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 coverage is 100%, so the schema already documents both parameters including the enum. The description restates the combinedDuration enum and the header convention but adds no syntax or constraints beyond what the schema provides. Baseline 3 is correct.

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 ("Change") and resource (the duration window in which unpaid orders can be combined into one invoice), and disambiguates from the sibling ebay_get_combined_shipping_rules by naming the mapping tool explicitly. An agent can tell this is a config mutation distinct from the read tool without opening either 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 clear usage context: this sets the combined-payment window, and success should be confirmed via ebay_get_combined_shipping_rules. Also names the required scope (sell.account). It stops short of stating when not to use it or listing alternative config tools, so it is clear context without full exclusions.

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