simulate_ladder

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

With readOnlyHint/destructiveHint already covering the safety profile, the description adds substantial behavioral context: missing X inputs reset false every scan, missing initial devices default false, T/C contacts are fixed initial states, timers/counters are not executed, and networks evaluate in display order. These are exactly the non-obvious execution semantics an agent needs and none are in the annotations.

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 most important distinction ('Boolean IR scan model, not PLC emulation') is front-loaded, and each following sentence adds a distinct execution rule. Slightly terse and fragmented, but nothing is wasted.

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 values need not be explained, and the description covers the unusual evaluation quirks for a simulator. The remaining gap is that it never connects the ladder parameter to what the simulation actually produces, leaving a modest amount to inference.

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 carry parameter meaning. It indirectly explains two of the three parameters ('Missing X inputs reset false each scan' maps to inputs; 'Missing initial devices default false' maps to initial) and network ordering for ladder, but it never describes the expected shape of inputs/initial maps or which device keys they accept.

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 frames the tool as a 'Boolean IR scan model, not PLC emulation', which conveys the computation model but never plainly states the verb+resource (e.g. 'simulates execution of a ladder program'). The contrast with PLC emulation is helpful positioning, but it does not differentiate this tool from actual siblings like validate_ladder or inspect_ldr.

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?

There is no guidance on when to use this versus validate_ladder, inspect_ldr, or the other siblings. The description only explains internal semantics of the model, never a usage condition, prerequisite, or exclusion.

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