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

Beyond the readOnly/idempotent/non-destructive annotations, the description adds real behavioral context: histories remain readable after cancellation, empty series mean no samples yet and must not be fabricated, and force series only exist if force outputs were enabled in the saved request. It also states the negative side effects it does not cause (no compute start, no viewer creation).

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?

Well front-loaded: purpose first, then polling, empty-series semantics, force preconditions, and the sibling redirect. Most sentences earn their place, but the poll_after_seconds reference points at a nonexistent parameter and the closing 'Does not start compute or create a viewer' partly restates the readOnly annotation.

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?

For a one-parameter read tool with an output schema and full annotations, the description covers what an agent needs: ownership scoping, availability after cancellation, polling cadence, empty-result interpretation, and the force-outputs precondition. Return value structure is correctly left to the output schema.

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 0% for the single job_id parameter, so the description would need to carry it; it only indirectly implies ownership via 'an owned simulation'. It also references 'poll_after_seconds' as if it were an input even though the schema allows only job_id with additionalProperties false, which is a mild inconsistency rather than useful parameter semantics.

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 first sentence names a specific verb and resource ('Read live or retained residual and force histories') and scopes it to an owned simulation, including the post-cancellation case. Later sentences actively distinguish it from assess_convergence and from viewer/compute tools, so an agent can separate it from siblings without opening a 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?

'Poll at least poll_after_seconds apart' and 'use assess_convergence on finished results for a numerical assessment' give concrete usage rules and name the alternative for numerical work. It does not explicitly contrast with get_simulation_results or view_simulation_result, so the routing guidance is clear but not exhaustive.

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