analyze_waveform

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

With no annotations, the description carries the full behavioral burden and does so thoroughly: raw samples are never returned, analyses defaults to all, stats and fft contents are specified, and frequency accuracy is bounded by frequency_resolution_hz. These are precise behavioral constraints an agent can rely on.

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, with the core purpose in the first sentence and every subsequent sentence carrying operational detail. There is no repetition of schema fields or padded language.

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 tool with no annotations and no output schema, this description conveys the return contents and main parameter semantics well enough for typical use. It falls slightly short of complete because max_points is unexplained and the exact JSON shape of the returned summary is not described.

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 description adds strong meaning for analyses, including the allowed subset, the default, and the exact contents of each result type. However, schema description coverage is 0%, and channel and max_points receive no descriptive treatment; max_points in particular is left to inference.

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 opens with a specific verb and object: Analyze a waveform on the host and return only the summary. It immediately separates itself from capture_waveform by stating that raw samples are never returned, so an agent can tell the two tools apart without inspecting schemas.

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 gives an explicit when-not and alternative: when the raw data itself is needed, use capture_waveform instead. It also explains the default behavior of the analyses argument, so the agent knows omitting it yields all available analyses. This is direct routing guidance.

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