create_capsule

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

With no annotations, the description carries the full burden. It discloses that the tool persists session details (model info, job status, output files, version), but it does not explain side effects such as whether an existing capsule with the same capsule_id is overwritten, errors, timeouts, or any impact on the current session. This is adequate for a simple snapshot tool but lacks edge-behavior detail.

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 short, front-loaded with the main action, and every sentence adds value. The Args section provides meaningful parameter semantics without redundancy, and there is no filler or repetition of the schema's type/title information.

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?

The description covers the tool's purpose, main parameters, and saved data, and an output schema exists so return values are documented elsewhere. However, it lacks timeout guidance, duplicate-capsule behavior, and explicit alternatives. These are meaningful gaps for a tool with no annotations and a missing parameter description.

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%, so the description must compensate. It gives useful meaning for capsule_id ('Unique identifier' with an example) and notes ('Optional description'), but completely omits the timeout parameter. Since one of the three parameters is undocumented in both the schema and the description, the parameter semantics are incomplete.

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 verb and resource: 'Capture current Abaqus session state into an experiment capsule.' It also lists exactly what is saved (model info, job status, output file inventory, Abaqus version), and the 'capture' verb clearly differentiates this tool from sibling capsule tools like list_capsules, load_capsule, and delete_capsule.

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 implies when to use the tool by saying the capsule is 'for reproducibility and later comparison,' which hints at using it before compare_capsules. However, it does not explicitly state when not to use it or mention alternatives such as load_capsule or list_capsules. Usage context is present but left to inference.

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