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

Beyond annotations (idempotentHint, non-destructive), the description reveals the asynchronous nature: 'No change occurs until separate human approval' and 'Returns an AurasPay approval URL first'. It also instructs 'never invent a store or consent', setting an honesty constraint. The idempotency hint is operationalized by 'Reuse the identical requestId and details to retrieve the result'. This adds substantial behavioral context.

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 five short sentences, each delivering a distinct piece of information: purpose, honesty constraint, return behavior, approval requirement, and idempotency/retrieval. No filler or redundancy – every sentence earns its place and the critical 'Save...' verb is front-loaded.

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 async merchant-qualification tool with an output schema present, the description covers the essential workflow: what it saves, what it returns first, that no change happens until human approval, and how to retrieve the result later. It omits nothing an agent needs to call it correctly, and the output schema covers return structure.

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 description does not explain the individual parameters beyond naming 'requestId' and 'details'. It says 'Reuse the identical requestId and details to retrieve the result', which gives requestId a retrieval/reuse role, but it does not describe the contents of details (platform, storeUrl, country, marketingConsent) or their expected formats. With schema_description_coverage at 0%, the description fails to compensate for parameter meaning.

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 opens with 'Save actual merchant/store onboarding details', a specific verb and resource, and adds 'Records a lifecycle event' to clarify the action's nature. It distinguishes itself from siblings like auraspay_merchant_setup_status by focusing on saving details rather than retrieving status. It also warns 'never invent a store or consent', reinforcing its real-data purpose.

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 implies when to use it: when you have actual merchant/store details to save for onboarding. It provides critical workflow context – 'Returns an AurasPay approval URL first' and 'No change occurs until separate human approval' – which tells the agent not to expect immediate changes and to handle the approval flow. It does not explicitly name alternatives or exclusions, but the 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.