read

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

With no annotations provided, the description carries the full burden. The verb 'Read' and the phrase 'the agent inspects' clearly signal this is a non-destructive inspection operation, which covers the core behavioral safety trait. However, it does not describe what happens with the read output or whether any state changes occur per zoom level, though for a read tool the most important behavior is embodied in the verb itself.

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, front-loaded sentence with zero filler. It packs the verb, resource, and parameter relationship in the main clause, with a parenthetical that immediately communicates the use case. Every word adds value; there is no room for trimming.

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?

This is a low-complexity tool with one optional parameter, but the description still leaves key gaps. It does not state what output is returned (and there is no output schema), nor what each zoom level actually offers. An agent would need extra context to know exactly what happens when it calls this tool. The description, while simple, is not fully complete without those details.

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?

The only parameter 'zoom' has an enum but no schema descriptions, so the description must compensate. The description correctly ties the parameter to the notion of viewing the timeline at a zoom level, which adds meaning beyond the mere enum. However, it does not explain what each enum value (summary, outline, detail) semantically maps to, so the agent still lacks full parameter-level guidance.

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 identifies a specific verb ('Read') and resource ('the timeline') with a scope qualifier ('at a zoom level'). The parenthetical 'the agent inspects its work' adds contextual purpose, distinguishing this from editing or creation siblings like add_clip or trim. It is not a perfect 5 because it does not explicitly name a sibling alternative, but the read-only verb is enough for agents to reliably distinguish it.

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?

No explicit guidance is given about when to or when not to use the tool. The phrase 'the agent inspects its work' implies a checking or review use case, but there is no mention of alternatives like qc, vlm_review, or render, nor any exclusion criteria. This leaves the agent to infer when this tool is the right one compared to dozens of other timeline-related operations.

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