load_project

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

No annotations are present, so the description carries the full burden. It discloses that this tool is limited to PLCopen XML only (implied by open_project finding 'Extended and native sources') and that it is kept for parity with a legacy connector. It doesn't mention mutation, but 'Parse and return summary' implies a read-only operation; the limitation and parity context add value beyond a simple one-liner.

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 efficient: a one-sentence purpose, a rationale for parity, and a clear parameter explanation. It front-loads the primary action and avoids fluff. Every sentence earns its place without redundancy.

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?

Given there is an output schema (true), return values are presumably covered there, so the description need not repeat them. It covers the tool's function, limitation, and parameter semantics. A minor gap is that it doesn't describe what a 'project summary' includes, but that is likely in the output schema, keeping completeness acceptable.

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%, but the description compensates fully by explicitly documenting the parameter in the 'Args:' section: 'plcopen_xml_path: Path to a PLCopen XML file exported from MotionWorks IEC.' This adds specific meaning (file path, export source) far beyond the bare schema type 'string'.

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 specific verb ('Parse'), resource (PLCopen XML export), and output ('project summary'). Clearly differentiates from sibling 'open_project' by noting it is 'Kept for parity with the studio5000 connector' and that open_project is preferred, so an agent can distinguish them.

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?

Explicitly names the alternative (open_project) and gives the condition for preference: 'open_project is preferred because it also finds the Extended and native sources.' This tells the agent when to avoid this tool and why, leaving no ambiguity about usage.

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