run_analysis

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

With no annotations, the description carries the full burden and does reasonably well: it discloses the save-to-file prerequisite, that running locks the model (a stateful side effect), and that large models run long and may return a pending status. It does not say whether the lock is released, what permissions are needed, or whether the operation is destructive.

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?

Short and front-loaded: the action comes first, then prerequisite, then locking behavior, then the async caveat. Each sentence adds information, though the fragmented line breaks make it slightly less scannable than a single tight paragraph.

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 described. Combined with the prerequisite, lock disclosure, and pending/job_wait guidance, the definition is nearly complete for a stateful long-running analysis tool; only the lone parameter remains unexplained.

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?

There is one parameter (wait_seconds) at 0% schema description coverage, and the description never mentions it. The passing reference to waiting via job_wait does not explain what wait_seconds controls or its default of 50, so the single parameter is effectively undocumented.

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+resource ('Run the analysis of the open model'), and the reference to the 'open model' links it to the open_model sibling. However, 'the analysis' is left undefined — an agent cannot tell what kind of analysis is executed or what it operates on beyond the currently open model.

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?

Gives a concrete prerequisite ('The model must already have been saved to a file') and an explicit follow-up path when the call is asynchronous ('if this returns pending, keep waiting with job_wait'), naming the sibling tool. It lacks a when-not-to-use clause, but the conditional routing is genuinely actionable.

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