batch_results

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

The description adds substantial behavioral transparency beyond the annotations. It explains the default behavior (peak across waveform, conflates startup/roll-off with run-to-run variation), the effect of the `at` parameter on slicing, and the `raw` parameter's relationship to reductions versus raw samples. It correctly matches the annotations (readOnly=true, idempotent=true, destructive=false) without contradiction.

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 main description is two sentences: first states the purpose, second explains the two modes concisely. Every word serves a purpose. The parameter descriptions enrich the schema with valuable caveats without bloat.

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 read-only query tool with good parameter schema coverage and an output schema, the description is complete. It covers the main behavioral branches, exception cases (when NOT to use for raw samples), and integrates well with the rich schema. Could arguably include a precondition that the job_id exists, but this is implied by the schema.

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 input schema has rich per-parameter descriptions, so the description doesn't repeat them. The primary description adds high-level semantics about the two usage modes. The schema descriptions provide full context including an important caveat in the `at` parameter about AC sweep aliasing and in `raw` about reduced rows not being sample vectors.

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 states the tool queries a batch simulation job and differentiates two modes: without a signal it returns job status/progress, with a signal it returns aggregate statistics or per-run data. It explicitly names the sibling tools run_sweep and run_montecarlo (in the job_id parameter) as the source of job IDs, which differentiates it from other query tools.

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 clearly explains when to use it (for batch simulation jobs, sweep or Monte Carlo) and the signal param differentiates modes. The raw parameter description explicitly states when NOT to use it for raw samples (use export_waveform or get_waveform instead). It doesn't explicitly exclude other siblings but context makes the tool's place clear versus similar tools.

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