plot_series

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

No annotations are provided, so the description carries the full burden. It usefully discloses the visual conventions (mode changes dashed, failsafes red) and that the return value is a PNG image, but it says nothing about permissions, cost, size limits, or error behavior for a tool whose output is a rendered image.

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?

One tightly written sentence with the action, resource, and return value front-loaded and no wasted words.

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?

Although there is no output schema, the description states the output is a PNG and describes its visual encoding, and parameters are fully covered by the schema. The only meaningful gap is the missing guidance on when this tool should be chosen over its plotting-like siblings.

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 100% and the schema documents log path forms, t_from/t_to units, and the 'topic.field' with '+' joining syntax in detail. The description adds nothing beyond that, so the baseline 3 applies.

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?

Specific verb ('Plot') plus resource ('logged fields against time') and an explicit output ('return the PNG'). It is clear what the tool does, but it does not distinguish itself from plotting-adjacent siblings such as flight_timeline, estimate_vs_truth, or velocity_tracking, which an agent could easily confuse with 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?

The description states what the tool does but gives no when-to-use guidance, prerequisites, or alternatives. With several sibling tools that plausibly produce plots or timelines, the absence of any routing hint ('use estimate_vs_truth for X, this for Y') leaves selection to inference at best.

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