Export an event window for PlotJuggler

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

With annotations already marking this as non-read-only, non-destructive, and idempotent, the description adds useful behavioral details beyond them: it returns paths, plotted curves, and an opening command, automatically selects up to eight numeric curves unless signals are specified, and does not launch the viewer. These disclosures help an agent set expectations around side effects and output.

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 compact and front-loaded: the core output behavior and purpose come first, followed by selection guidance, parameter hints, and a launch caveat. Every sentence contributes information, and there is no redundant restating of the title or schema.

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?

The description covers the main workflow, output, and key behavioral constraints, and an output schema exists to define return values. Still, with 7 parameters and no schema-level parameter descriptions, the omission of path, name, and especially the free-form args object leaves the definition incomplete for an agent that needs to construct a fully correct invocation.

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. It adds real meaning for start_seconds/end_seconds ('inclusive source timestamps in seconds'), signals ('unless signals are specified'), and topics ('Inspect topic schemas'). However, path, name, and args remain undocumented in both the schema and the description, which leaves meaningful gaps for a 7-parameter tool.

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 names a specific verb and resource: writing a selected time window as flattened scalar CSV plus a PlotJuggler XML layout, with return values also stated. It also distinguishes itself by saying 'Choose this for scalar plotting in PlotJuggler, not native bag preservation', which sets it apart from sibling export tools like export_for_rerun and export_for_lichtblick.

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 explicitly states when to use this tool ('Choose this for scalar plotting in PlotJuggler') and what it is not for ('not native bag preservation'). It also adds practical context such as inspecting topic schemas and using inclusive source timestamps in seconds, but it does not name a specific alternative tool for bag preservation.

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