statewave_get_timeline

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

No annotations provided, so description carries full burden. Declares read-only, returns unmodified chronological log, capped by limit, and describes return structure. Does not discuss pagination or error handling, but adequately covers core behavior for a read operation.

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?

Single paragraph of five sentences, front-loaded with purpose, then details. No wasted words. Clearly structured with contrasting sibling and enumeration of parameters.

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 no output schema, description explains return array with fields and behavior when empty. Covers key aspects for agent decision (read-only, filters, limit). Missing error conditions or existence checks, but adequate for typical usage.

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 coverage is 100%, so baseline is 3. Description adds value by contextualizing parameters (e.g., 'bound the window with since/until', 'filter to specific event kinds'), providing format examples for kinds and subject, and explaining limit cap. Reinforces schema descriptions with usage 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?

Clearly states the verb 'retrieve', the resource 'subject's raw episodes', and ordering 'chronological order'. Distinguishes from sibling statewave_search_memories by contrasting raw vs compiled, and lists specific use cases (audit trails, change-logs, debugging, replaying history).

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?

Explicitly states when to use (audit trails, debugging, etc.) and contrasts with statewave_search_memories (ranked, compiled). Mentions optional filters but doesn't explicitly say when not to use. Provides enough context for an agent to choose based on need for raw vs compiled data.

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