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

Annotations are minimal (only a title), so the description carries the full burden. It fully discloses critical behaviors: requires one-time owner approval via email, re-quotes weekly, books only if at/below ceiling, over-ceiling weeks book nothing and notify, and 'nothing ever books without the owner's one-time email approval'. It also notes auth is required. This is exceptionally transparent for a complex automation tool.

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 a single focused paragraph that front-loads the purpose and includes a critical caveat in caps. Every sentence contributes meaningful information about the approval workflow and ceiling behavior. It is slightly long but avoids fluff and earns its length.

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?

Given the tool's complexity (recurring automation with owner approval and ceiling logic), the description covers the essential behavior well: proposal-only nature, weekly re-quoting, automatic booking under ceiling, and over-ceiling notifications. It does not mention return values or failure modes, but no output schema exists, and the description still provides a robust mental model for a multi-step automation.

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 input schema has 100% description coverage for all parameters, including nested objects with references to other tools (e.g., 'same shape as the book tool'). The description itself adds little parameter-specific detail beyond summarizing the flow. With such high schema coverage, a baseline of 3 is appropriate; the schema does the heavy lifting.

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 clearly states the tool's purpose: 'Set up a RECURRING weekly shipment (standing order)' with a specific verb and resource. It distinguishes itself from sibling booking tools by explicitly noting 'THIS TOOL ONLY PROPOSES — nothing books now', which separates it from immediate-booking tools like book and batch_book.

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?

The description explains the workflow and when the automation acts: after owner approval, re-quotes weekly, and books automatically under the ceiling. It implicitly contrasts with one-time booking tools by stating nothing books now. However, it does not explicitly mention alternatives like manage_automation for editing/deleting existing automations, but the usage context is clear enough.

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