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

Annotations declare non-read-only, non-idempotent, non-destructive, so the safety profile is already structured. The description adds real context beyond that: the human signs in their own wallet, the result (eSIM QR or top-up confirmation) appears on the page, no key is held, and the call is free — useful for a mutation tool whose side effect is an external payment.

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 purpose and the when-to-use condition, then detailed behavior. Slightly padded by promotional phrasing ('Free.', the referral upsell) but every sentence still carries selection or behavior 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 an 8-parameter tool with no output schema, the description covers the user-facing flow, delivery outcome, and payment responsibility well. The one gap is that it never says what the API call itself returns (presumably the link URL), which matters since there is no output schema.

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 all eight parameters are already documented, giving a baseline of 3. The description adds little parameter-level detail beyond what the schema says — its `ref` explanation ('earn a share of margin on each delivered order') largely restates the schema's 'earn referral share'.

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: create a checkout link that a human pays from their own Algorand wallet. It immediately distinguishes itself from the agent-paid sibling `buy` by saying 'use this when you have no wallet' and 'you never hold a key', so an agent can route without opening either 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 a clear selection condition ('when you have no wallet, or when the person should approve and pay themselves') and differentiates top-up vs eSIM delivery semantics ('a top-up link can be paid by anyone', 'an eSIM link delivers to whoever pays'). It never names the alternative tool (`buy`) explicitly, so the routing is strong but not fully spelled out.

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