vcc_scan_signal

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

With no annotations provided, the description carries full burden for behavioral disclosure. It transparently describes return values (Tcl list), the search logic, handling of annotated values, and default time ranges. It does not explicitly state it is read-only, but the scanning nature implies no side effects.

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 well-structured with a concise summary followed by detailed parameter explanations. Every sentence adds value, and there is no redundancy or unnecessary verbosity.

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?

Despite having 5 parameters and no output schema provided, the description covers all aspects: purpose, parameter behaviors, return format, and special cases. It is complete and leaves no obvious gaps for the agent to infer.

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%, so the description fully compensates by explaining each parameter: signal format, find_value optionality, from_time/to_time default behaviors, and radix options. It adds meaning beyond the schema, such as the default radix and the behavior when to_time is omitted.

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 scans a signal across a time range and optionally searches for a value. It provides a specific verb and resource, distinguishing it from siblings like vcc_examine (which examines a single signal) and vcc_force (which forces a value).

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 explains default behaviors (e.g., from_time defaults to 0 when find_value is given) and signal format requirements. However, it does not explicitly state when to use this tool versus alternatives like vcc_examine or vcc_get_time, leaving usage context implied rather than explicit.

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