flexsim_pf_run_tokens

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

With no annotations, the description carries the full burden and does substantial work: it discloses the reset+run side effect, sets run speed to 1000, applies stoptime(60)+applicationcommand('run'), and waits for getrunstate==0 under a deadline. It also flags a behavioral caveat ('tokens runtime no siempre cambian subnodes', arrivals_observed can be 0). It stops short of explicitly warning that the reset discards current simulation state.

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 purpose sentence is front-loaded, but the body is dense, bilingual, and repetitive (the 'no construye/inyecta' point recurs; the reset/run sequence is described twice). Implementation minutiae (node(...).value) crowd out signal. It is serviceable but not tight.

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 reset+run observation tool with no annotations, the description covers the mechanism, arguments, side effects, and result caveats adequately. An output schema already exists, so the explicit 'Returns JSON {...}' explanation is bonus rather than necessity, and the overall picture is complete enough to call 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 description coverage is 0%, so the description must compensate and largely does: 'flow' is defined as an existing ProcessFlow (clear error if missing), and 'arrivals' is clarified as a non-injected reference with default 5 and range 1-100. This adds real meaning the bare schema lacks, though it omits how/why the reference value matters.

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?

Opens with a specific verb+resource: 'Observe ProcessFlow state across a short reset+run.' It distinguishes itself from the builder siblings by stating 'no construye nada (no crea actividades ni inyecta tokens).' It is clear on what it does, though the mixed-language and implementation-heavy body dilutes the focus somewhat.

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 a key precondition ('window backend only') and names the read neighbors (flexsim_processflow_inventory, flexsim_run_to_time), implying when this fits. However it never states explicitly when to use this tool instead of flexsim_run_to_time or flexsim_processflow_inventory, nor when not to use it. Usage is implied rather than spelled out.

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