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

With annotations declaring destructiveHint=true, the description adds critical scope: only purchases with no payee are changed, and only their payee. It additionally discloses the vendor-creation side effect (created when no vendor by that name exists), the per-call 300-purchase limit with retry semantics, and the full-access requirement.

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?

Dense but every sentence carries information — scope, matching rules, batching, and auth. It is a single long paragraph rather than front-loaded bullets, which slightly hurts scanability, but there is no 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 destructive mutation with no output schema, the description covers scope, side effects, batching/retry, and auth. It does not state what the response contains (e.g., which purchases changed or the remaining count it references), a minor gap given the retry instruction depends on 'remaining'.

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 baseline is 3, but the description adds real semantics: vendor_id must be an existing vendor, vendor is matched case-insensitively and created if absent, texts are group texts from the listing, and from/to must match the listing. Minor gap: it doesn't clarify the maxItems 60 constraint against the 300-purchase limit.

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 and resource — assign a vendor as payee to purchases that lack one — and explicitly distinguishes from siblings by naming list_purchases_without_payee as the source of group texts. An agent can tell this apart from update_purchase or create_vendor without opening a 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?

Explicit about when to use: after the user agreed to the vendor for each group, using group texts from list_purchases_without_payee, with the same from/to as the listing. It also gives operational guidance — 300-purchase cap and repeat the call while remaining is above zero — leaving little to inference.

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