calibrate

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true), the description explains key behavioral constraints: stock calibration is disallowed and why, the least_squares method reports a linearized std_error, differential_evolution is global and seeded, and no extrapolation is allowed. These details provide substantial context that the agent could not infer from annotations or schema alone.

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 three sentences, each earning its place: the first states the core purpose and inverse relation, the second covers calibration constraints and method differences, and the third addresses extrapolation and the optional dependency. It is front-loaded with the most critical information and contains no filler or repetition.

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 the complexity (13 parameters, nested objects, output schema), the description covers the main constraints and prerequisites well. The output schema handles return values. However, there is a slight ambiguity about whether calibration persists by modifying the model's current values or just returns fitted parameters; this is hinted by 'Fit constant model parameters' and the readOnlyHint, but not explicitly stated. This small gap prevents a 5.

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 coverage is 100%, so the baseline is 3. The description adds value by clarifying method-specific parameter semantics: it notes that differential_evolution requires bounds, which ties the method enum to the 'min' parameter's optionality, and it explains the stock rejection behavior beyond the parameter array's description. This strengthens the relationship between parameters and their intended use.

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 clear verb+resource: 'Fit constant model parameters to an observed time-series' and immediately distinguishes it from siblings with 'the inverse of simulate.' This makes the tool's purpose unambiguous and differentiates it from simulate, sensitivity_analysis, and other related tools.

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 explicit when/when-not guidance: stocks are rejected, observation times must be within the model window, and the two optimizer alternatives (least_squares vs. differential_evolution) are described with their trade-offs (local vs. global, needs bounds). It also mentions the required pysd dependency, adding a prerequisite context. 'Inverse of simulate' makes the alternative tool explicit.

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