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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows it's a safe read operation. The description adds valuable context: the directory is human-verified, monitored daily, and has a 'stale' flag after 180 days without human confirmation, and the response reports stale counts. This goes beyond the annotations and provides useful behavioral insight.

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 a single, well-structured paragraph that front-loads the core purpose, then adds key details about verification and staleness, and ends with filter options. Every sentence adds value; no fluff or repetition.

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?

Given the tool's moderate complexity (4 optional parameters, no output schema), the description is quite complete. It explains the data source, verification process, staleness semantics, and filter options. It doesn't describe the return format, but since there's no output schema, that's a minor gap. The annotations cover safety, so the description focuses on domain-specific behavior, which is appropriate.

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 75% (3 of 4 parameters have descriptions). The description adds meaning by explaining the 'stale' flag and that the response reports stale matches, which relates to the query parameter. It also clarifies the directory's verification process, which adds context to the query semantics. The category enum is self-explanatory. Slight deduction for not explicitly describing the 'limit' parameter's default behavior, but the schema already covers that.

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 the tool searches a human-verified directory of Bitcoin-accepting merchants, specifying the resource (directory), the action (search), and the scope (native Bitcoin, on-chain + Lightning, real goods). It distinguishes itself from sibling tools, which are all data-fetching tools for prices, gauges, glossary terms, etc., by focusing on merchant search.

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 implies usage context: it's for finding merchants that accept Bitcoin, with filtering by query, category, or country. It doesn't explicitly state when not to use it or name alternatives, but the sibling tools are clearly different (price, gauge, treasury data), so the context is clear. A slight deduction for not explicitly stating exclusions or alternatives.

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