batch_purchase

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

With no annotations, the description fully discloses behavior: it picks the cheapest active listing, validates via Seaport.getOrderStatus, encodes fulfillAvailableAdvancedOrders, and sends NFTs directly to the wallet. It also covers partial failures ('skips it and refunds excess ETH') and response details (lists which succeeded/dropped). This is rich transparency for a mutation 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?

The description is front-loaded with the core action and every sentence adds value—covering validation, execution, failure semantics, cost trade-offs, and marketplace scope. No redundant filler or repetition of schema fields.

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?

Despite no output schema, the description explains what the response contains ('lists which labels succeeded and which were dropped'), behavior on stale orders, and the NW-only limitation. For a complex batch purchase tool, it covers the key operational and edge-case context an agent needs.

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 already describes both parameters with 100% coverage, but the description adds operational meaning: 'For each name, picks the cheapest active NW listing' clarifies how the names array is processed, and 'receives all purchased names' clarifies the wallet's role. This goes slightly beyond schema documentation.

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 a specific verb+resource+scope: 'Buy up to 20 NameWhisper-listed ENS names in a single Seaport transaction.' This clearly distinguishes batch_purchase from sibling purchase_name (single name) and sweep (a different batch strategy). The purpose is explicit and unambiguous.

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?

Provides explicit when-to-use guidance: 'Cheaper per name than individual buys (gas is amortized). For a single name, use purchase_name.' It also gives a clear exclusion: 'NW-only: this tool ignores listings posted exclusively to Grails / OpenSea.' These conditions help the agent decide between this and alternatives.

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