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

Annotations only indicate readOnlyHint=false and destructiveHint=false, which are minimal. The description goes far beyond this by detailing side effects (purchase initiation), possible immediate resolution with 'waived' status, the return of a checkoutUrl, the agent's inability to pay on behalf, the need to poll for payment status, and a required auth token. This is rich behavioral context that no annotation provides.

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 concise and well-structured, with four sentences that each carry essential information. It front-loads the core action, then explains conditional behavior, the payment flow, and follow-up steps. No filler or redundant content.

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?

Given that there is no output schema, the description handles return behavior well by explicitly mentioning the 'waived' status, checkoutUrl, and saleId. It also covers the required authentication token and the process flow (handing URL, polling). Combined with clear parameter schema, the description is sufficiently complete for an agent to select and invoke the tool correctly.

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 input schema already provides 100% coverage, including example values for productId ('use 8 for the Stay Application fee') and a clear explanation of applicationId. The description adds no direct parameter-specific detail beyond what the schema states. It does add broader context (like the waived scenario) but that doesn't alter parameter meaning. Baseline of 3 is appropriate.

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 clearly states the tool's purpose: 'Start a purchase of a Nomad Stays product on the caller's own behalf.' It uses a specific verb and resource, and distinguishes itself from sibling tools like getPurchaseStatus by framing it as the initiation step. It also clarifies the 'caller's own behalf' nuance, making it unmistakable what the tool does.

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 provides explicit workflow guidance: it explains when the tool resolves immediately (waived status) versus when it returns a checkoutUrl, and instructs that the URL must be handed to the member (not paid by the agent). It also directs the agent to poll getPurchaseStatus afterward, effectively naming the follow-up tool. This is clear, actionable guidance for when and how to use the tool.

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