Security radar snapshot (paid)

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

With no annotations, the description carries behavioral disclosure. It explicitly states it costs one call, returns a 402 offer as data if unpaid, and clarifies that it only provides counts/labels, not verdicts. This adds meaningful behavioral context beyond what any schema would imply, though it does not explicitly state whether it is read-only.

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 concise and well-structured: one sentence summarizing the data content, one sentence covering payment and failure behavior. No filler or redundancy, and the most important aspects (data type, payment requirement) are front-loaded.

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 there is no output schema, the description adequately covers what the tool returns (incidents, chatter counts, precision ledger) and the payment condition. It also implies how to satisfy payment (via preimage/payment_hash in schema). While not exhaustive, it is complete enough for an agent to understand the tool's purpose and invocation, especially with the 100% parameter documentation.

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 parameters are already documented. The tool description does not add additional meaning about parameters or their usage beyond what the schema provides. The baseline of 3 is appropriate because the schema carries the full burden and the description adds no extra value.

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 provides a security radar snapshot: open/corroborated incidents, chatter counts with source counts, and a precision ledger. It distinguishes itself from siblings by focusing on security radar data and explicitly notes it returns counts/labels, not verdicts, which differentiates it from other btcmatic tools like discovery or context.

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 by stating what data it returns and that it's a paid snapshot, but it does not explicitly mention when to use it instead of sibling tools. It provides clear context on the tool's function, but lacks direct exclusions or alternative recommendations.

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