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

Annotations only supply destructiveHint=true; the description goes well beyond it by explaining sign semantics (positive adds, negative deducts), the server-side rejection of deductions that would drive the balance negative, the undo strategy, and field-level visibility to the customer. This is exactly the behavioral context an agent needs before issuing a destructive write.

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 WRITE marker and purpose, then ordered by operational concern: sign semantics, failure mode, undo, field visibility, alternative tool, scope, endpoint. No filler sentences.

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 four-parameter destructive mutation with no output schema, the description covers everything an agent needs: purpose, polarity rules, rejection behavior, reversal, field visibility, alternative routing, auth scope, and endpoint.

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 100% and the schema already documents sign semantics and the customer-visible vs merchant-only distinction. The description largely restates that; its only marginal addition is the negative-balance rejection behavior. Baseline 3 is appropriate when the schema carries the parameter burden.

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?

Opens with an explicit 'WRITE:' marker and a specific verb+resource ('add or deduct points from a customer's balance'), then scopes it as a manual adjustment with concrete examples. It also explicitly names the sibling it is not for ('To reward a customer for completing an action, prefer smile_create_activity'), so an agent can differentiate without opening schemas.

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 when (goodwill credit, correction), the when-not with a named alternative (smile_create_activity for action rewards), and the recovery path (undo by creating an opposite adjustment). The required scopes and underlying endpoint are also stated.

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