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

The description adds essential behavior beyond the annotations: cost is $0.01 per call, payment is USDC on Solana via x402, MCP callers should first trigger a PaymentRequired challenge and retry with payment metadata, and results are returned in deterministic id order. This is exactly the operational context an agent needs for a paid data query.

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 dense but front-loaded: purpose and filters come first, followed by return behavior, payment details, and HTTP equivalent. Every sentence carries relevant information, though it could be slightly tighter.

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 paid query tool with four optional parameters and no output schema, the description covers filtering, return ordering, cost, and the x402 payment handshake. It does not detail the fields in the returned full service records, but that is not essential for correct invocation.

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 description coverage is 100%, so all four parameters are already documented in structured data. The description restates the filter meanings, including that maxPriceUsd matches services with at least one paid endpoint at or under the bound, but does not add materially beyond the schema.

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 a specific verb and resource: a ranked shortlist over the Agent Data Core store of service records with category, price, verification, and limit filters. It is easy to distinguish from most siblings by resource and operation, though it does not explicitly name an alternative tool it should not be confused with.

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?

Usage is implied by the description: call this to get a filtered, ranked shortlist of services. The payment flow is explained, but there is no explicit when-to-use vs when-not-to-use guidance or named alternative such as a full snapshot or verification-report tool.

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