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

Annotations declare this is a non-destructive write, and the description is consistent with that. It adds a meaningful behavioral detail — the mail goes to the order's own address rather than an arbitrary recipient — but says nothing about re-send behavior, rate limits, or that an outbound e-mail cannot be recalled.

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?

One dense, front-loaded sentence that leads with the action and recipient, then the prerequisites. The nested parenthetical is slightly heavy but every clause carries information.

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 and only minimal annotations, the description covers the action, recipient, and required inputs, but omits failure modes and any warning that sending a page link to a customer is an irreversible outbound side effect.

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 0%, so the description must carry the load: it names both parameters, confirms they are required, and clarifies that 'email' is specifically the order's own e-mail address while 'reference' identifies the order. It stops short of stating the expected format of the reference.

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 concrete verb and object: it mails the order's status-page link to the order's own e-mail address, and enumerates what the page enables (approve proof, send file, pay, write to team). That distinguishes it from siblings like message_team and order_status, though it never names them.

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?

Usage is only implied through the parenthetical list of actions the recipient can take, and the description notes the prerequisites (reference and e-mail address). It gives no explicit when-to-use guidance or when to prefer order_status or message_team instead.

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