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

The annotations declare readOnlyHint=true, destructiveHint=false and idempotentHint=true, yet the description describes adding, changing and deleting rows in the seller's own table. Even if the write is confined to a local table, that is still a state mutation that contradicts the read-only claim, and the description does nothing to reconcile the two. The contradiction is serious because an agent relying on the annotation could invoke this expecting a harmless read.

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 tight sentences with zero filler: what it edits, which fields matter, then the create/update/delete switch, then the blast-radius note. The most decision-relevant content (rule_id/delete behavior) is front-loaded rather than buried.

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?

The output schema exists so return values need not be described, and the 'nothing is sent to a marketplace' clause usefully bounds the effect. However, for a 13-parameter mutation with 15% schema coverage and inverted annotations, the description leaves an agent without permission requirements, merge-vs-replace semantics on update, or any hint that the annotation profile is wrong.

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 only 15% (account and category_id are the only documented properties), so the description has to carry 13 parameters. It does clarify rule_id (update selector) and delete (removal flag) and names pct_base, fixed_fee_per_order, valid_from/valid_to and source, but it gives no semantics for fixed_fee_base, fixed_fee_note, category_name, or whether unspecified fields are cleared on an update.

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 uses specific verbs (add, change, delete) against a specific resource (commission rule of an account) and enumerates the editable fields, so an agent knows exactly what this does. It also implicitly separates itself from marketplace-facing tools by stating nothing is sent to a marketplace, though it never names commission_rules_list or commission_import as the read/sync counterparts.

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 create/update/delete routing is spelled out explicitly: omitting rule_id creates, passing rule_id changes, and delete=true removes. What is missing is guidance on when to use this versus commission_rules_list (to inspect first) or commission_import (to bulk-load rules), so alternatives are only partially covered.

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