Get a shipping address link for your owner

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

With annotations giving readOnlyHint=false, destructiveHint=false and openWorldHint=false, the description still contributes real context: link lifetime (60 minutes), that the address is never visible to the agent, that the link is for the owner only, and that GLONGUS_API_KEY is required. The gap is re-issue behavior – it doesn't say whether calling again invalidates a previously issued link or whether links can coexist, which matters for a token-minting 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?

Four short sentences, no filler: purpose and lifetime first, trigger second, handling constraint third, recovery action last. Every sentence carries information an agent needs and nothing is repeated from the annotations.

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 zero-parameter tool with no output schema, the description supplies everything operationally necessary: what is returned, how long it lasts, the failure that triggers it, how to verify the need first, who may receive the link, the auth requirement, and how to recover afterwards.

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 tool takes zero parameters, so there is nothing for the description to disambiguate; baseline is 4. The description correctly implies everything is implicit in the caller's identity and the pending operation rather than in arguments.

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 first sentence states a specific verb and resource plus its scope: returns a 60-minute link where the owner enters a shipping address. It is clearly distinguishable from sibling link tool get_photo_upload_link and from the listing/transaction tools, since the delivered artifact (an owner-facing address form) is named explicitly.

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?

It gives an explicit trigger ('when a call fails with address_required') and points at the exact signal to check first ('the response's has_address says whether one is already on file'), which prevents a pointless call. It also states the post-condition for resuming ('Retry what needed it once they say it's done'), so the agent knows both when to call and what to do next.

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