Plecs Analyze Data

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

readOnlyHint=true already covers the safety profile, and the description adds real behavioral detail beyond it: list inputs are summarised entry-by-entry, and THD processing happens only when `fundamental` is supplied. It stops short of saying what the metric set contains, how null `signal`/`fundamental` are resolved, or how large sweeps are handled.

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?

Two short paragraphs, front-loaded with the purpose and followed by the input-shape caveat. Dense with no filler, though the clipped 'metrics, and optional FFT/THD' phrasing reads slightly elliptical.

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 values need not be described. However, with 4 undocumented parameters and a nontrivial input polymorphism (single result vs. sweep list), the description leaves an agent guessing about `signal`/`harmonics` behavior before it can call the tool confidently.

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% across 4 parameters, so the description must carry the load. It explains `fundamental` (enables THD) and implies `result_path` (the saved JSON), but `signal` (which signal index) and `harmonics` (default 10) are never mentioned, leaving two parameters with no semantic anchor anywhere.

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?

States a concrete verb and resource: post-processes a saved JSON result into metrics plus optional FFT/THD analysis at a given fundamental. This is clearly distinct from siblings like plecs_analyze or plecs_statistics in the sense that it operates on a saved file, though the description never names those siblings to make the distinction explicit.

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?

Usage is implied rather than stated: it accepts a single result object or 'the list written for a parameter sweep', which tells the agent this runs after a simulation has saved output. There is no explicit when-to-use/when-not, no prerequisites, and no pointer to a sibling when the raw result is not yet on disk.

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