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

With no annotations supplied, the description carries the full burden and does so: it discloses the write effect (one service due date per customer, dated by the shop's lead days), the downstream email job and that it fires once, skip behavior for unemailable or off-list customers with counting, the owner-only permission gate, and the two configuration prerequisites. This is exactly the kind of side-effect and eligibility detail an agent needs before invoking a mutation.

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 action, then mechanism, then eligibility, then prerequisites, then the channel exclusion — every clause carries distinct information. Short fragments ('Owner only.', 'No texts.') deliver constraints efficiently with 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?

An output schema exists, so return values (including the skip counts) need no explanation here, and the description covers permissions, prerequisites, and side effects thoroughly. The remaining shortfall is the undocumented 'months' parameter, which leaves the agent guessing about due-date timing relative to the stated lead-days behavior.

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 0%, so the description must compensate and only partly does: 'title' is implied by '(title, due in the shop's lead days)' and customer_ids is implied by the winBack list, but the 'months' parameter (1-120) is never mentioned and appears to conflict with the stated 'due in the shop's lead days' default. shop_id is only inferable from context, leaving a real gap on two of four parameters.

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 ('Send the win-back note to customers from customers.winBack') and then discloses the actual mechanism ('adds one service due date each ... so the service_due_reminders job emails them'). It explicitly ties itself to the sibling customers_winBack as the source list, 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 clear preconditions ('Owner only', service due emails must be on, shop mailing address required) and a channel exclusion ('No texts'), plus the implicit prerequisite that the audience comes from customers.winBack. It does not name explicit alternatives (e.g. phone_sendText or customers_audience) for reaching customers another way, so it stops just short of full when/when-not routing.

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