Phone Timeline

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

With no annotations, the description carries the burden and does add real behavioral detail: ordering (oldest first), line format, the '-- <piece>' change marker, and time-window scoping. However, it never states that the call is read-only, how `limit` truncates, or what happens when both `limit` and `minutes` constrain the result, which matters for a tool whose output is a bounded log.

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 useful scoping facts are front-loaded, but the middle is one long run-on clause listing every event kind with parenthetical asides ('(and what the phone heard)', '(opened, on which device; Listen and Stop; hidden and back; ...)'). It is dense and hard to scan rather than wasteful, but it could be structured into a short list.

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?

An output schema exists, so return formatting needn't be explained, and the description still covers ordering, windowing, filtering values, and the piece-change marker. Only the `limit` parameter and the read-only nature of the operation are left uncovered for a 3-parameter tool.

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 0% and `kinds` is an untyped array, so the description's enumeration of valid values (page, tap, mood, voice, voice_text, answer, exam, button) is essential and cannot be learned from the schema. `minutes` is also explained in prose; `limit` is left unexplained, keeping this short of a 5.

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 the resource (a chronological timeline of phone-session events) and its exact shape: oldest first, one line per event, with time, bar, and action. It is clearly the retrospective log rather than a live-status tool like phone_status or phone_now, though the opening phrase 'A take of the phone session' is a vague substitute for an explicit verb.

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?

'Use it to lay what they said over what they did' implies the use case (correlating speech with actions) but gives no when-not conditions and names no alternative sibling such as phone_listen or tell_heard. Usage must be inferred from the described content.

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