plc_program_xref

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

Annotations already declare readOnlyHint=true and destructiveHint=false; the description reinforces this with '[READ][risk=low]' and adds substantial extra context: the access classification is heuristic (op/regex, not data-flow analysis), specific classification rules for SCL/AWL/L5X are given, hits are truncated at 200, and the file must exist and be ≤5 MB. This goes well beyond the annotations and fully discloses limitations such as the verbatim source quoting and L5X line-as-rung behavior.

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 dense but well-organized: it opens with a one-line summary, then details search scope, access classification, arguments, return structure, and an example. Every sentence provides necessary information—no filler or redundant repetition of schema fields. The layout makes it easy to scan and quickly extract key constraints and behavioral nuances.

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 the tool has 2 params, no output schema, and moderate algorithmic complexity, the description is remarkably complete. It explains what the tool returns (dict with source_file, format, symbol, hit_count, hits, hits_truncated, by_access), lists the classification rules, specifies file size and word-boundary matching, and even includes a usage example. This is more than sufficient for an agent to select and invoke the tool correctly without additional documentation.

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 provides only 'path' and 'symbol' with no descriptions (0% schema coverage). The description compensates fully: 'path' is defined as an exported program file with accepted extensions, existence requirement, and size limit; 'symbol' is described as a symbol/tag/absolute address with word-bounded match semantics. This adds essential meaning that the schema completely lacks.

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 opens with 'Cross-reference one symbol in an exported PLC program,' which uses a specific verb ('cross-reference') and resource ('symbol in exported PLC program'). It further distinguishes itself from siblings by detailing exactly what it finds (read/write/call/declare sites) and providing concrete symbol examples. This is unmistakably distinct from tools like plc_program_outline or plc_program_section.

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 clearly implies when to use the tool: whenever an agent needs to trace all references to a given symbol or address in an exported PLC file. It does not explicitly mention alternatives or exclusions, but the specificity of the purpose ('finds every... site') and the file format constraints make the intended context very clear. No explicit when-not guidance is provided, so slightly below a 5.

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