query_waveform

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

With no annotations present, the description carries the full behavioral burden and does so thoroughly. It discloses output semantics (timescale, integer ticks, merged same-timestamp updates, initial_values vs events), condition behavior (equals/unknown/all_equals check initial values, change only checks later changes), truncation flag meanings, and that simulation_verdict is always not_evaluated.

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 front-loaded with purpose and key constraints, then return semantics, then parameter details. Although it is long, every sentence carries necessary operational information that cannot be inferred from the schema, so it earns its place without redundancy.

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 6-parameter tool with no schema descriptions and no annotations, the description is exceptionally complete. It covers input semantics, return values, edge cases, truncation behavior, and query limitations, leaving no critical gap for an agent selecting and invoking the tool.

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%, but the description's Args section fully compensates by explaining all six parameters: file_path, signals, start_time, end_time, max_events, and condition. It adds critical constraints like max 32 paths, exact hierarchical paths, inclusive end_time, the 1..1000 max_events range, and structured condition examples with supported/unsupported operations.

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 action: '离线发现 VCD 信号或查询有界波形变化', identifying both the resource (VCD signals/waveform changes) and the operation (offline discovery or query). It also states the return type is JSON and emphasizes the offline/no-Vivado-session nature, which clearly distinguishes it from interactive waveform tools like set_wave_zoom.

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 strong when-to-use and when-not-to-use guidance: it is for offline .vcd analysis only, with a 32 MiB limit, and explicitly excludes FST/WDB and non-queryable event/real/string values. It does not name an alternative tool to use instead, so it stops just short of the explicit-alternative bar, but the scope is unambiguous.

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