memory_timeline

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

With no annotations provided, the description carries the full behavioral burden. It discloses useful traits beyond structured data: '~200 tokens/result' (output size/cost), the window behavior, and its 'Layer 2' pipeline position. However, it never states whether the operation is read-only or has side effects, and it offers no failure behavior or rate-limit context; the repetitive phrasing also dilutes the signal.

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 section layout (triggers, sequencing hint, parameters) is well organized and front-loaded with 'Layer 2.' But the same idea is stated three times: 'Get chronological context,' 'Returns narrative flow around observations,' and 'Provides timeline context for how observations relate to each other,' and the trigger bullets partially repeat this as well. It could lose ~30% of its words without losing information.

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?

For a simple tool (2 flat params, 1 required, no output schema, no annotations), the description covers the essentials: purpose, when to invoke it, both parameter semantics, and a result-size hint. The main gaps are the absence of an explicit read-only/no-side-effects declaration and a precise return shape — but the tool's low complexity makes this close to 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 0%, so the description must compensate — and it does. It explains ids as 'List of observation IDs from search_memory' (tying the parameter to its upstream source) and window as 'Time window for context around each observation (default: "5m")' (semantics plus default value). Both parameters gain real meaning beyond the bare schema titles 'Ids' and 'Window.'

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 states a specific verb+resource: 'Get chronological context for memory IDs' and clarifies the return as 'narrative flow around observations' and 'timeline context.' It distinguishes itself by positioning as 'Layer 2' to be used after search_memory, which separates it from siblings like topic_context, search_memory, and get_observations. An agent can readily tell what this tool does and how it differs from nearby alternatives.

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 'AUTOMATIC TRIGGERS' section gives concrete when-to-use conditions: having observation IDs from search_memory, needing event sequence, or needing temporal relationships. It also gives the procedural hint 'Use AFTER search_memory to understand sequence.' It lacks explicit when-not-to-use guidance or named alternatives (e.g., when to prefer topic_context), so it falls just short of a 5.

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