Load data

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

With no annotations, the description carries the full burden; it does usefully disclose that kind=\"script\" loads and runs a script (an executable side effect) and that other kinds do not. It says nothing about whether loaded data overwrites existing workspace variables, error behavior on missing files, or unit handling for NK files beyond the schema field.

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 bullets, front-loaded with the core action and no repeated filler. The SimWorks-specific notational aside (load('file_path'), .msf) is slightly opaque but earns its place by clarifying the script mode.

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 output schema covers return values, so the description need only explain invocation, which it mostly does by naming the primary discriminator (kind) and its two modes plus the project alternative. Given the output schema and 71% parameter coverage, nothing essential for a correct call is missing.

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 71%, so the schema already documents many parameters; the description only adds meaning for kind (script vs data) and file_path (prefer absolute paths). The remaining 16 parameters, including x/x0/y0/z0, swapb, reverse_index, and file_units, receive no explanation of when they are relevant.

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 verb and resource set: load a script file, data files, or NK/raw arrays into the workspace. It explicitly distinguishes the script case from project files and routes project opening to a named sibling, so an agent can separate this from project_action and file_io without opening the schema.

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?

Gives an explicit when-not ("To open a project (.sim/.mpps), use project_action(action=\"open\")") and clarifies that only kind=\"script\" executes a script while other kinds merely import data. It does not help choose among the 12 non-script kinds, so guidance is clear but incomplete.

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