flexsim_add_conveyor_leg

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

With no annotations, the description carries the full burden and does so well: it discloses that o.size is written but the visual geometry stays ~10 m because Conveyor.length is readonly, that objectconnect alone leaves belt.in at 0, that the transfer chain uses contextdragconnection plus selective port deletion, and how verification walks the outObjects chain via EntryTransfer/ExitTransfer. These are genuine side effects and limitations an agent could not infer. It is docked a point for being noisy and self-repeating rather than a clean behavioral contract.

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 text is long, mixes English and Spanish mid-sentence, and repeats the same ~10 m visual-length caveat three separate times. The critical constraint is buried rather than front-loaded, and parenthetical verification notes ('verificado con screenshots 2026-09-27') add bulk without helping an agent call the tool.

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 mutation tool with no annotations, the definition covers what is created, the flow-wiring behavior, the auto-layout rule, and the known limitation. An output schema exists, so return values need not be explained. What is missing is permission/authorization context and a clear statement of prerequisites for the referenced from_object/to_object nodes.

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 it largely does: name, length, x, y, z, from_object and to_object are each given meaning, defaults, and the auto-layout derivation (midpoint position, length = dist-1, min 2). It adds real semantics beyond the bare JSON types. It stops short of a 5 because the prose is tangled and the ~10 m caveat is repeated instead of stated once.

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 opening line states a specific verb+resource: 'Add one Conveyor::StraightConveyor leg (window backend only)'. It also clarifies that with from_object/to_object it additionally builds a transfer chain, which is a second responsibility made explicit. It does not, however, differentiate itself from likely-overlapping siblings like flexsim_create_objects or flexsim_connect_objects.

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 useful conditional guidance (auto-layout applies only when x/y/length are None and from_object+to_object are supplied) and flags 'window backend only'. But it never states when to reach for this tool versus flexsim_create_objects or flexsim_connect_objects, so the routing decision is left to inference.

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