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

With no annotations, the description carries the full burden of behavioral disclosure. It transparently explains that bars are ascending by bar_ts, that gaps are honest (absent bars, no filling), and that each item carries a slim game tag rather than the full game block. It also indicates the tool is a read operation (no side effects implied). It does not mention pagination or error behavior, but these are less critical for a read-only timeline. No contradiction with annotations (none provided).

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 dense sentence but well-structured: main purpose first, then schema difference, then intent, then ordering and gap behavior. Every clause carries meaning; no fluff. It could be split into two sentences for readability, but it earns its length.

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?

The tool has no output schema, so the description must convey the response shape and semantics. It references the sibling's schema and clarifies the divergence (slim game tag), explains ordering, gaps, and the transition history use case. It doesn't explicitly define the time range covered or how 'limit' interacts with 'since', but for a timeline tool this is largely self-evident. Given the complexity, it is reasonably complete.

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 50% (symbol and timeframe have descriptions). The description does not add new parameter-specific semantics; it merely mentions bar_ts ordering, which relates to the 'since' parameter but doesn't go beyond the schema's own description of 'ISO8601 lower bound on bar_ts'. It doesn't explain 'limit' beyond the schema defaults/constraints. This is adequate given partial schema coverage, but not exemplary.

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 per-bar state timeline for a symbol/timeframe, with a specific comparison to decker.get_market_state (slim game tag vs full block). It names the exact use case: reading status transitions across bars (forming → testing → resolved/failed). This distinguishes it from siblings, especially get_market_state.

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 when to use this tool: when you need the per-bar timeline with slim game tags to trace game progression, versus get_market_state which likely returns the full game block for a single state. It does not explicitly say 'use this instead of X when...', but the contrast with the sibling and the stated purpose provide clear context. Missing explicit exclusions, but adequate.

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