alarm_rationalization_worksheet

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

The description opens with [READ][risk=low] and adds rich behavioral context beyond the readOnly/destructive annotations: it discloses live OPC-UA collection, CSV file writing when out_path is set, bounded inline rows with truncation noted, and that endpoint is used only when events are omitted. This exceeds what annotations alone convey and does not contradict them.

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 well-structured with a summary, Args, Returns, and Example, and it front-loads safety tags. It is somewhat lengthy but necessary given the lack of schema descriptions; there is minimal 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?

For a 6-parameter tool with no output schema, the description is complete: it explains input modes, output dict shape, CSV side-effect, truncation behavior, defaults, and provides an example. An agent has everything needed to invoke the tool correctly.

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 input schema has 0% property description coverage, so the description must carry the burden, and it does thoroughly. The Args section explains all six parameters with purpose, defaults, constraints (e.g., duration_s 1..300, default 60; window_s default 600; threshold default 10), and the expected structure of events. This is exemplary compensation for schema gaps.

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 produces an ISA-18.2 alarm-rationalization worksheet (CSV or inline rows), with specific columns and count-descending ordering. It distinguishes itself from sibling alarm tools by framing itself as the starting document for rationalization review and explaining both event-based and live-endpoint modes.

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 clear context: pass 'events' for pure analysis or provide an endpoint to collect live via the OPC-UA scan, and use 'out_path' to write CSV versus inline rows. However, it does not explicitly name sibling alternatives or state when not to use this tool, so it stops short of a 5.

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