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

Beyond the readOnlyHint/idempotent hints, the description discloses the trust model: registration is self-reported, verification_status distinguishes Self-Reported from Verified/Audited, and nothing implies safety or performance. This is valuable behavioral context that no annotation or schema conveys.

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 purpose, then immediately distinguishes it from the sibling, then covers trust and output shape. Every sentence contributes distinct information: scope, filters, trust caveat, return format, example, and read-only status. No filler.

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?

The description provides a return shape, filter guidance, trust caveats, and a usage example, which is strong for a tool with no output schema. It omits any pagination or result-limit details, and the phrase 'Returns (json)' slightly conflicts with response_format's default of 'markdown', leaving minor ambiguity.

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 schema already documents all 5 parameters. The description adds a concrete usage example with chain and x402_only, and clarifies that x402_only filters to agents exposing an x402 payment endpoint, adding modest value 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 names a specific verb ('search'), a specific resource ('REGISTERED onchain agents in the Sato Agent Registry'), and distinguishes it from the resource directory. This clearly separates it from sibling tools like onchain_agent_search_resources at a glance.

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 explicitly contrasts the tool with the resource directory: the directory lists 'the things agents are built FROM,' while this tool searches registered agents themselves. It also enumerates the available filters, giving an agent clear signals on when to call this tool and what to pass.

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