Plecs Submit

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

With no annotations, the description carries the burden and delivers the key traits: the call is blocking but is backgrounded, it yields a task id, the work is uncancellable, and timeouts should be set via SolverOpts.Timeout. It omits concurrency limits, what happens on timeout, and permissions, but the critical lifecycle behavior is disclosed.

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?

Three short sentences, front-loaded with the core behavior, then constraints and a usage example. No filler, though the SolverOpts.Timeout remark sits at the end where it reads almost as an afterthought.

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-value explanation is unnecessary, and the method enumeration fills the biggest schema gap. But for an async submission tool, the description never tells the agent how to poll or retrieve results (plecs_task/plecs_task_result), which is essential context for using it correctly.

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% and zero enums, so the description must compensate: it does enumerate the five valid method values and specifies the two-element array form for runScript. It says nothing about the `timeout` parameter's semantics or the params shape for the other methods, so compensation is partial.

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 concrete action and outcome: 'Start a long blocking call in the background and return a task id.' It also enumerates the allowed method values, which tells the agent what work can be dispatched. It doesn't distinguish itself from method-specific siblings like plecs_simulate or plecs_analyze, leaving the agent to infer when the generic dispatcher is preferred.

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 gives the allowed method list and a concrete call shape for runScript, plus a note to bound runs with SolverOpts.Timeout because there's no cancel API. However, it never says when to choose this over plecs_simulate/plecs_analyze/plecs_run_script, nor does it mention the follow-up (plecs_task/plecs_task_result) needed to collect the result.

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