Start a parameter study

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

Annotations only say it is a non-read-only, non-destructive, closed-world call; the description adds the genuinely behavioral facts: runs execute one after another in the background, it returns a study id immediately, and 'nothing is written to project files'. It also discloses non-obvious return diagnostics (keys_not_found, workspace_not_found, workspace_overruled) beyond what any annotation carries.

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 core purpose, return behavior, and follow-up tool are front-loaded in the first two sentences, and every sentence carries information. The trailing Driver.Acc.ayMax paragraph is heavily nested in parentheses and reads as an aside, costing some clarity.

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?

An output schema exists, so return values need not be re-explained, and the description still covers async behavior, side effects, and the sibling tools to use next. Only the absence of explicit when-not-to-use guidance and any concurrency/limit notes (beyond maxItems=50) keeps it from being fully complete.

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 baseline is 3, but the description adds real semantics: an example keys payload with a concrete value, the 0.5-step sweep idiom, and the guidance that a workspace shadowing a key should be handled with scope=<model>. That is meaning the schema does not supply.

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?

States a specific verb and resource: run one test run multiple times with different parameter values in the background, returning a study id. It is clearly differentiated from cm_start_sim (single run) and points at cm_study_wait/cm_study_status for the follow-up, so an agent can pick it without opening the schema.

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 establishes the workflow explicitly: start here, then 'wait with cm_study_wait', and it gives conditional advice for the Driver.Acc.ayMax sweep case. It stops just short of stating when not to use a study versus a single run, so it is clear context but not full exclusion guidance.

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