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

Annotations already mark the tool read-only and idempotent, and the description adds productive behavioral detail: the directory is daily-rebuilt, entries are scored from public evidence, deprecated resources are never returned, and pagination is via limit/offset. There is no contradiction with annotations, though the unconditional 'Returns (json)' statement sits awkwardly against the response_format parameter's markdown default.

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 long but tightly organized: USE WHEN, evidence-based rationale, filter inventory, return shape, then examples. The trigger sentence is front-loaded, and the examples compress a large amount of parameter semantics into a very small space.

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 an 18-parameter, no-output-schema read tool, this is nearly complete: it covers when to use it, the full taxonomy of filters, sorting, pagination, return fields, and read-only behavior. The notable gap is that the documented JSON return shape is not tied to response_format, whose schema default is markdown, so an agent could invoke it without setting response_format and receive a different format than the description implies.

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; the description adds real value by explaining that query terms are AND-matched, identifying category/is_agent/is_skill/is_harness as legacy flags, and giving three natural-language-to-parameter examples. It skips response_format, but that parameter is already fully documented in 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 and resource: it searches a daily-rebuilt directory of onchain agents, frameworks, skills, and tooling, and it lists concrete question triggers such as which tools support a chain or standard. It is clearly about resource discovery, but it never explicitly contrasts itself with the sibling onchain_agent_search_agents, and its scope even includes agents, so some sibling differentiation is left implicit.

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 'USE WHEN' clause gives explicit invocation context: building an onchain agent, checking chain/standard support, or checking whether a project exists and is maintained. It explains why the directory beats web search for these questions, but it does not state when to prefer the sibling search_agents or other alternatives, so the when-not guidance is incomplete.

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