save_identification_report

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose the key side-effect of writing a file to disk and adds useful nuances such as the differencing orders and the fact that the model spec is ignored. However, it does not mention whether the output file will be overwritten, what happens on error, or whether any prerequisites (e.g., data must be loaded) exist. This is a moderate gap given the lack of annotation support.

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, opening with a clear, front-loaded purpose statement followed by a brief content summary and then a formatted parameter list. It avoids unnecessary prose and each line adds information. The parameter list slightly duplicates schema information but earns its place by adding explanatory context, so no redundancy is wasted.

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?

Given that an output schema exists, the description need not explain return values, and the omission is fine. It covers the report contents, all parameters with semantics, and key behavioral notes like the differencing orders and model-spec handling. It lacks explicit prereq conditions or file-handling behavior, but for a save-report tool this is acceptable. It is more complete than many tool descriptions, though not exhaustive.

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's Parameters section adds substantial meaning beyond the input schema. It explains each parameter's role (e.g., 'inp_path: path to the .inp file', 'd: regular differencing order') and provides specific value interpretations ('lam: 0.0=log, 1.0=identity'). Since the schema only lists names, types, and defaults with no descriptions, the parameter semantics are fully compensated by the description.

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 that the tool 'Generate and save a full HTML identification report to disk.' It specifies the exact resource (HTML identification report) and the action (generate and save), distinguishing it from sibling tools that focus on analysis or estimation rather than producing a report file. Additional details about the report's contents (ACF/PACF listing and top-5 ARMA order suggestions) reinforce its purpose.

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 provides clear context by specifying the report type and the parameters, including the note that 'series is used, model spec ignored.' While it does not explicitly name alternatives or state when not to use it, the purpose is distinct enough that an agent can infer when to invoke this tool—when a saved HTML identification report is needed. It stops short of giving explicit 'use this instead of X' guidance, so it does not earn a 5.

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