tickerbot_list_signal_events

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

With no annotations provided, the description carries the burden of explaining behavior. It does this well by detailing the difference between state windows (null ended_at while active, prices at both ends) and event point fires (started_at=ended_at), and clarifies the meaning of from/to. It does not cover merge_gap_seconds or pagination behavior beyond what the schema already describes, but the core behavior is well disclosed.

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 paragraph, front-loaded with the core purpose, and each sentence adds value. It is slightly longer than necessary but packs domain-specific details (state vs event, example query) without 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 there is no output schema, the description does a good job explaining the row structure (started_at, ended_at, prices). It also covers the main use cases and exclusions. It does not explicitly list every return field, but the essential shape is conveyed. The tool is complex enough that a bit more detail on paging or merge behavior could be useful, but the description is largely sufficient.

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 the baseline is 3. The description adds context around from/to with the example but does not provide additional semantics beyond what the schema already states for each parameter. It reinforces the 'built-in booleans only' constraint for signal, but this is also implied in the description's first sentence.

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 it lists 'Occurrence SPANS of a boolean signal for one ticker, newest-first,' which is a specific verb+resource+scope. It distinguishes itself from siblings by explicitly contrasting state vs event flags and referencing tickerbot_get_series for non-boolean signals.

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?

Provides explicit when-to-use guidance: 'Built-in booleans only — numerics and custom signals have no precomputed spans (use tickerbot_get_series).' Also gives a concrete example for date filtering ('Golden crosses in June' is from=2026-06-01&to=2026-06-30), making usage clear.

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