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

Goes well past the readOnlyHint/openWorldHint annotations: discloses the 25-per-page unit, the 50-page ceiling, sort order, the source (dealstream.com public pages scraped via residential proxy), a real data limitation (financial details beyond asking price live on the listing page, not in the response), and a full cost model — $0.002 USDC per successful call via x402 on Base/Solana/Arc, with failures not charged.

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 what is returned, then constraints, then provenance and pricing — no filler. The long field list makes the first sentence dense, but each clause carries information an agent needs, and the payment caveat is properly separated.

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?

With an output schema present, return shapes need no explanation, and the description still covers provenance, pagination limits, sort order, geography, data gaps and the paid-call mechanics. Nothing material an agent needs to invoke this correctly is missing.

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 the baseline is 3, but the description adds semantics the schema lacks: page size is 25 results, ordering is newest-first, and state scopes to exactly one state with the default spanning all states. That extra detail legitimately lifts it above baseline.

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 — DealStream business-for-sale listings — and enumerates exactly which fields come back (title, asking price in USD, industry, city/state, id, link). That is unambiguous, but it never distinguishes itself from the sibling ecommerce_dealstream tool, so an agent cannot tell from this text alone which DealStream endpoint to pick.

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?

Geography (whole US or a single state), page bounds (1-50) and ordering (newest first) imply the intended use case. There is no explicit when-to-use / when-not-to-use statement and no named alternative for the obvious question of how this differs from ecommerce_dealstream.

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