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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds substantial behavior beyond that: the 300-purchase per-call cap, the repeat-until-remaining-zero loop, the exact mutation scope ('only purchases with no payee are changed, and only their payee'), the side effect of creating a vendor when none matches, and the 'requires full access' auth requirement. This is unusually rich disclosure that does not contradict the non-destructive annotation.

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?

Front-loaded with the core action and dense with useful detail, but the vendor parenthetical is long and nested, making one sentence do a lot of work. Nearly every clause earns its place, so the slight density cost is minor.

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 tool with no output schema, the description covers prerequisites, batching/pagination, mutation scope, side effects, and permissions. It even references the 'remaining' field, so an agent has enough to call it correctly and to know when to re-invoke.

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 meaning: vendor_id must reference an existing vendor while vendor is matched case-insensitively and created on miss, texts are group texts from list_purchases_without_payee, and ids cover purchases outside a group. These distinctions are not fully spelled out in the schema alone.

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 with scope: 'Give a vendor as payee to purchases that have none.' It implicitly distinguishes itself from the sibling list_purchases_without_payee, which it names as the source of group texts, so an agent can tell the two apart 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?

Gives the precondition ('after the user agreed to the vendor for each group'), the sourcing workflow (texts come from list_purchases_without_payee), and the pagination rule ('when remaining is above zero, make the same call again'). It also tells the agent to reuse the same from/to as the listing, closing the loop on correct invocation.

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