gx3_xref_where_used

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

With no annotations, the description carries the behavioral burden. It discloses an output convention—the first line carries the device comment and should be repeated alongside the device—and it warns that a prebuilt xref database is required. It does not mention side effects or failure modes, but for a read-oriented where-used lookup the disclosed context is meaningful and useful.

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 compact and front-loaded with the core purpose, followed by an output-handling note and a setup prerequisite. Each sentence adds distinct information, though the first sentence is slightly elliptical and could be more explicit.

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 two-parameter tool with no output schema, the description covers the main needed context: what the tool returns, how to handle the first-line device comment, and the xref database prerequisite. It does not fully describe the result structure beyond the first line, but enough is present for an agent to invoke and interpret 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?

Schema description coverage is 100%, with both 'root' and 'device' already described, so the baseline is 3. The description adds only a mention of '--root <root>' in the prerequisite command and does not deepen the meaning of either parameter beyond the schema.

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 states the tool surfaces writers and readers of a device, with POU name and real step, which clearly points to a where-used lookup. It lacks an explicit verb like 'list' or 'find,' and it does not contrast itself with siblings such as gx3_trace_device or gx3_data_flow, but the meaning is still reasonably specific.

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 clear operational context by requiring the xref DB and telling the agent to run 'gx3-cli xref build --root <root>' once per project first. It does not explicitly compare against sibling tools or state when not to use this tool, but the purpose and prerequisite make the intended usage fairly clear.

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