ac_structure

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

Annotations already declare readOnly/idempotent/safe, and the description adds substantial behavioral context: the rational-fit-then-asymptotic-fallback algorithm, finite-sweep accuracy caveats, merged corner behavior, non-guaranteed pole/zero counts, and the requirement for human review against the Bode plot. No contradiction with annotations exists.

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 dense but each sentence carries real information: purpose, algorithm, output semantics, critical flag implications, caveats, accurate-result alternative, and sibling pointers. Formatting with an IMPORTANT callout helps prioritize the human-review requirement without padding.

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 complex analysis tool with an output schema and rich annotations, the description covers algorithm behavior, result interpretation, known limitations, prerequisite conditions, and alternative tools. It is complete enough for an agent to know exactly when to call it, what to expect, and how to guard against misuse.

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 high (83%) and already documents signal, raw_file, job_id, run_index, and format. The description adds only contextual clues (e.g., plot_waveform on the same signal, pass raw_file OR job_id), but does not extend parameter-level meaning beyond the schema; baseline 3 is appropriate.

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 uses a specific verb phrase 'Read the pole/zero STRUCTURE of an .AC response' and enumerates concrete outputs (net order, corner frequencies, Q, out-of-phase zeros, transport delay). It clearly differentiates from sibling analysis tools by naming each sibling's scope.

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?

It explicitly states the intended reasoning use case, the required prerequisite ('.AC run'), an alternative for exact results ('.pz analysis'), and names sibling tools with their different focuses (bode_metrics, resonance, stability_metrics). It also tells the agent not to act on magnitude alone when non_minimum_phase is flagged.

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