linear_fit

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

The description's 'Checkpoints first' adds a warning that aligns with the destructiveHint annotation, providing actionable pre-call guidance. However, it does not state what exactly is mutated or what a linear fit does to the view beyond 'match channel/sessions.' Since annotations already declare destructiveness, this partial addition earns a 3.

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?

A concise, two-clause sentence captures the core action and immediate safety warning. No extra words, front-loaded with the purpose. It is clear and efficient.

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 tool's complexity (3 params, destructive behavior, no output schema), the description is minimal but still lacks clarity on what exactly gets transformed and how 'match channel/sessions' translates into action. It does not clarify the process enough for an agent to anticipate consequences beyond the checkpoint hint.

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 only 33% (only 'checkpoint' has a description). The tool description fails to explain the id, reference_id, or checkpoint semantics in more detail; 'reference view' hints at reference_id but does not elaborate on the id field or checkpoint meaning. This leaves critical parameters underdocumented.

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 states a specific action ('LinearFit the view') and a target ('a reference view (match channel/sessions)'). It tells the agent what the tool does and its scope, but does not explicitly distinguish it from siblings like match_calibration. Still clear enough for an agent to infer the operation.

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?

There is no guidance on when to use this tool versus alternatives such as match_calibration or register. 'Checkpoints first' is a caution, but it does not explain when the tool is appropriate or when another tool should be chosen instead.

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