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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without description help. The description adds useful domain context (these are adjustments recorded after label usage, and records carry old vs actual package data), but says nothing about pagination, result volume, or the total/limit behavior of a list endpoint.

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 short sentence with no padding, and the core concept is front-loaded. It is a sentence fragment rather than a complete statement, which slightly weakens orientation but wastes no words.

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?

With 8 optional parameters, no output schema, and a list endpoint's pagination semantics, this description is far too thin to stand alone. The trailing phrase 'with old and actual package' is ambiguous — likely describing returned fields — and does not tell the agent what a response contains or how to page through results.

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?

The description mentions no parameters whatsoever — not the carrier filter (USPS/UPS), status, date range, or search. With schema coverage at 63%, three parameters (sort, limit, offset) are undocumented in both schema and description, and the description does nothing to compensate for the gap.

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 sentence defines the domain entity well — post-label charges or credits from the carrier — but it is a noun phrase with no verb, so the action (list/retrieve) comes only from the tool name. It also never distinguishes this from the sibling dispute_adjustment, which operates on the same records, or from list_transactions/list_refunds which could also contain charges and credits.

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?

There is no when-to-use guidance at all: no statement of when to call this versus dispute_adjustment, no prerequisite that a label must exist, no mention of the default sort/pagination behavior. The agent must infer usage purely from the name.

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