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

Beyond the read-only annotations, it states the OAuth/safe-scope context, confirms it writes nothing, lists returned server facts, and discloses that no buyer PII/free text is included. It also surfaces an important failure mode: claim verification is offline with 409.

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, using short clauses to pack in scope, return facts, routing, and constraints without filler. Every sentence contributes actionable information.

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 lists what the tool returns: status timeline, frozen terms, current listing anchors, evidence refs, and any existing dispute. It also covers the key alternative paths and failure behavior, making it complete for this one-parameter read-only 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?

With 100% schema description coverage, the schema already explains that order_id is a buyer order and points to webaz_buyer_orders. The description reinforces ownership and safe scope but does not add syntax, format, or examples beyond the structured field.

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 a specific verb and resource: 'Assemble an after-sales CASE DRAFT for one of YOUR orders.' It also clarifies the tool's role as fact organization only, explicitly distinguishing it from dispute filing and buyer actions handled elsewhere.

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 routing: delivery problems go to a delivery dispute with 48h/120h timing, disputes are filed by the human at webaz.xyz, and cancel/return uses webaz_buyer_action_request. It also warns that claim verification is offline (409), which prevents misrouting the human.

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