suggest_intervention_form

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

With no annotations, the description carries the full disclosure burden. It reveals that the tool writes to output_path, auto-selects the most extreme residual when date is empty, and that form='auto' is a heuristic. It also notes the token-saving behavior of include_histogram, making the side effects and trade-offs visible.

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 opening summary is clear, and the parameter explanations are valuable. However, the description is somewhat long due to the redundant duplication of parameter names from the schema, though this is mitigated by the semantic additions. It is well-structured with sections.

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 tool with 12 parameters, no output schema, and no annotations, the description adequately explains inputs, outputs, and usage. It mentions the return value (updated parameter table and diagnosis) and the iteration workflow. Minor gaps remain, such as whether the original .inp is modified or only a new file is written, but the overall context is sufficient.

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 schema has 0% description coverage, but the description includes a full parameter list explaining each argument, including accepted formats for date ('MM/YYYY' or 'QN/YYYY' or 'YYYY'), the meaning of 'form', and the purpose of guion_* fields. This fully compensates for the schema's lack of descriptions.

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's function: 'Adds a pulse, step or ramp intervention at the given date, saves to output_path, re-estimates and returns the updated parameter table and diagnosis.' It uses a specific verb with the .inp resource and distinguishes it from sibling tools by noting it is used iteratively, one intervention at a time.

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 instructs to 'Use this iteratively — one intervention at a time,' which provides clear usage context. It also gives timing guidance for include_histogram ('set True for final round'), but it does not compare against sibling tools like intervention_analysis or test_interventions, so no exclusions are stated.

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