lars_runtime

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

The description explicitly discloses side effects and destructive behaviors: list auto-cleans stale workspaces, start auto-creates workspaces, remove deletes workspace configs, gc deletes unreferenced workspaces (with a dry_run option to preview), set_station_target modifies .lss files, and target_pc switches compile targets. Even though no annotations are provided, the description carries the full burden and does so thoroughly, including the lazy cleanup behavior and the fact that changes alter station configuration.

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 description is long but information-dense, with a clear structure: an overall purpose sentence, a key architectural note (one workspace per station), and a colon-separated action list. Each sentence earns its place, though the repetition of action names in the initial summary and the action enum description is slightly redundant. It's not overly verbose for the complexity of the tool, but a more compact phrasing could improve clarity.

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?

The description covers the tool's role within the broader ecosystem (e.g., interaction with build_project and deploy_all after set_station_target, the port separation between PLC and HMI). It also explains the purpose of the less obvious actions like target_pc and restore. There is no output schema, so return values are not specified, but the description is sufficient for an agent to understand when and why to call this tool and what side effects to expect.

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?

The schema already provides descriptions for all seven parameters (100% coverage), so the baseline is 3. The tool description adds extra meaning beyond the schema: it explains the action parameter's semantics in detail (e.g., the auto-clean behavior of list, the auto-create behavior of start, and the lazy criteria for gc). This enrichment of parameter meaning, especially for action with its eight enum values, justifies a 4.

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 clearly states the tool's purpose: managing local LARS simulation instances, with a specific note about one workspace per station (PLC + HMI) running on separate ports. The list of actions (list, setup, start, stop, remove, gc, etc.) immediately distinguishes this from sibling tools like control_plc or hmi_runtime, which focus on other aspects of the runtime environment.

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?

The description provides usage context for each action (e.g., 'start' auto-creates the workspace if unconfigured, 'gc' runs lazy garbage collection with specific retention rules). It also explains a cross-tool interaction: after set_station_target, build_project/control_plc/plc_values/deploy_all operate on the LARS instance. While it doesn't explicitly contrast with every sibling, the action semantics and the note about when to use this tool relative to others are clear enough for an agent to decide when to invoke it.

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