How often a condition occurred in 90 days (paid)

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

No annotations are provided, so the description must carry the behavioral burden. It reveals that it counts rising edges (throttled rule fires) and hours held, and clarifies it is not a forecast. However, it omits details like credit consumption (though title says paid), exact output format (e.g., integer counts), or any side effects. The 'rising edges' context adds value, but completeness is limited.

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?

Two sentences, front-loaded with the core action, and efficient. Every sentence adds unique information: the first explains the counting mechanism and metrics/operators; the second clarifies scope ('Past frequency'). No fluff or redundancy.

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 complexity (6 params, no output schema), the description adequately explains the tool's purpose, granularity, and output (counts and hours held). It also flags the 'not a forecast' caveat. It does not spell out the exact response structure or payment preimage requirements, but those are partially covered by schema descriptions and the 'paid' title. Overall, it is sufficient for an agent to understand what it will get and how to configure the condition.

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?

The description adds value beyond the schema by explaining metric-specific window requirements ('needs window 1h|24h|7d' for price_change_pct) and confirming the operator set. It also clarifies that all metrics are hourly-resolution counts. Schema coverage is 50% (window, preimage, payment_hash have descriptions), so the description compensates for missing semantics on metric, op, and value by providing context.

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 action: 'Counts, at hourly resolution, how often a single condition became true in the trailing 90 days'. It specifies the resource (condition frequency) and scope (90-day trailing window), distinguishing it from sibling tools like btcmatic_radar which likely focuses on current conditions. The 'Past frequency, not a forecast' clarification removes ambiguity.

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 historical analysis ('Past frequency') and warns against using it for predictions, but it does not explicitly say when to choose this over alternatives like btcmatic_radar or btcmatic_context. There is no direct comparison or exclusionary guidance.

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