run_lsprepost

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

With no annotations, the description carries the full burden and does well: it discloses the env-var gate, the worker-thread execution, a hard timeout capped at 900 s that kills the entire process tree, and that created files are reported. It does not state what happens to partial output when a timeout fires or how failures surface, leaving a meaningful gap for a process-spawning tool.

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?

Front-loads the most consequential fact (the DISABLED gate) and then covers mode and timeout behavior compactly. The trailing 'Args:' line slightly restates parameter names but does add non-obvious semantics such as the character cap and allowed-folder constraint.

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 4-param process-execution tool with an output schema present, the description covers gating, execution model, timeout/kill behavior, headless modes, and that output files are listed. Remaining gaps — error/failure reporting and whether files persist after a kill — are minor given 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 coverage is 0%, so the description must supply all parameter meaning, and it largely does: commands is cfile text capped at 20000 chars, working_dir must be an allowed folder, headless toggles 'runc=' vs 'c= -nographics', and timeout_s is bounded by the 900 s hard cap. The timeout_s default (300) and the exact per-call vs overall nature of the timeout are only implied.

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 an LS-PrePost command file (post-processing automation)' — plus the target directory. The resource is clearly distinct from sibling script/job runners like run_mechanical_script and submit_lsdyna_job, so an agent can route 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?

Gives concrete preconditions: disabled unless LSDYNA_MCP_ENABLE_LSPREPOST=1, and working_dir must be an allowed folder. It also scopes headless=True to non-graphical commands only. It does not explicitly contrast with sibling automation tools (e.g. run_mechanical_script), so routing between them is left partly to inference.

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