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

With no annotations provided, the description carries the full behavioral disclosure burden and does well: it states the tool reads the project, writes a CSV, requires the xref DB, and flags alarms with no reset condition. It does not detail CSV location or overwrite behavior, but the key operational facts are present.

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?

Every sentence earns its place: the inventory scope, the answered question, the CSV side effect, the no-reset-condition warning, and the xref DB prerequisite. It is front-loaded with the core purpose and contains no filler.

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 tool with no output schema, the description gives enough context about output (a CSV) and prerequisites. It does not explain how mode=list versus mode=show changes behavior, but the schema compensates with the enum, default, and device requirement.

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 description adds no parameter-level explanation; it does not mention mode, root, or device. The schema already describes root and device and gives mode an enum and default, so the agent can invoke the tool correctly, but the description misses the chance to clarify when mode=show is appropriate.

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 names the resource (alarm and fault devices), the specific analysis (triggers, latch state, timer setpoints, reset conditions), and the user-facing question it answers. It also differentiates itself from ladder-reading tools like gx3_ladder_print by explicitly saying it avoids reading the ladder by hand.

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 clearly states when to use this tool: when the user needs to know what raises an alarm and how it is cleared, without inspecting the ladder manually. It does not explicitly name alternatives or state when not to use it, so it falls just short of full exclusion guidance.

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

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

With no annotations provided, the description carries the full behavioral burden and does well: it discloses that the analysis is conservative, that no guessed edges are emitted, that unresolved operations become unresolved records, and that device comments are included when available. This adds substantive behavioral context beyond the schema.

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 tightly packed sentences with no filler. The main purpose is front-loaded, followed by edge attributes, then behavior for unknown operations and device comments. Every sentence earns its place.

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 no output schema and no annotations, the description does a solid job of conveying the result shape: edges with specific fields, unresolved records, and device comments. It is slightly incomplete because it does not describe how the returned data is packaged or how the format parameter affects it, but the core behavior is well covered.

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 75%, so the schema already explains root, device, and opcode. The description introduces important domain concepts like argument indexes, widths, ranges, and confidence, but it does not specifically explain how the parameters affect the output beyond what the schema states.

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 starts with a specific, action-oriented verb ('Build') and names a well-defined resource ('argument-level source-to-destination value-flow edges'). It goes on to specify the kinds of instructions covered and the fields produced, making it clearly distinct from siblings like gx3_trace_device or gx3_xref_where_used.

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 implies this tool is for conservative value-flow analysis and mentions behavior for unknown operations, so an agent can infer a use case. However, it never explicitly states when to choose this tool over alternatives such as gx3_trace_device or gx3_xref_where_used, nor does it name any exclusions.

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

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

No annotations are provided, so the description carries the full burden. It explicitly discloses that the tool reads the project and writes a CSV under the output directory, which is a non-obvious side effect. It also reveals the network-device exclusion and the xref DB prerequisite, making behavioral traits and assumptions transparent.

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 front-loaded with a vivid purpose statement followed by concrete examples. Each subsequent sentence earns its place: return grouping, side effects, exclusions, and prerequisites. There is no redundant or filler content.

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 absence of annotations and output schema, the description is remarkably complete. It covers purpose, output format, side effects (CSV write), exclusions (network devices), and prerequisites (xref DB), enabling an agent to select and invoke the tool safely.

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%: the only parameter 'root' is already documented as 'Extracted project folder.' The description mentions 'the project' but does not add new meaning about how 'root' is used beyond what the schema provides. This matches the baseline for full schema coverage.

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 uses a specific verb ('Find') and resource ('logic that can never do anything'), then enumerates four concrete detection categories: contacts that can never close, NC contacts on always-ON relays, written-but-never-read coils/words, and SET latches with no matching RST. This distinguishes it from siblings like gx3_lint, gx3_data_flow, and gx3_xref_where_used without needing to open their schemas.

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 provides clear context by stating a prerequisite ('Requires the xref DB') and an exclusion rule ('Devices refreshed from a network are excluded, since a remote station may be the real reader'). However, it does not explicitly name alternative tools or state 'use this when...', so it lacks explicit routing versus siblings.

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

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

No annotations are provided, so the description carries the full burden for behavioral disclosure. It clearly states that the tool is read-only, returns a table, writes nothing, and requires the index-lite DB to be built first. This is strong disclosure, though it could mention whether empty results are possible or how the output table is structured.

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 focused sentences with no filler. The main purpose is front-loaded, use cases follow, and the prerequisite command is placed last where it is relevant. Every sentence earns its place.

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 read-only reporting tool with three optional parameters and no output schema, the description covers purpose, usage, read-only behavior, return shape ('a table'), and prerequisite setup. It could more fully explain the default behavior when `types` is omitted, but the core context an agent needs is present.

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%, so the baseline is 3. The description adds some context around 'device types' and 'gaps' but does not add meaningful details about the `root`, `types`, or `min_free` parameters beyond what the schema already provides.

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 names a specific action ('Report'), a specific resource ('per device type ... numbers in use ... free gaps'), and concrete use cases. This clearly differentiates it from sibling tools like gx3_trace_device or gx3_interlock_check without needing to compare schemas.

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 gives explicit context: use it before adding devices or for project layout inspection. It also warns about the index-lite DB prerequisite with a concrete command. It does not mention alternatives or explicitly say when not to use it, so it gets a 4 rather than a 5.

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

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

With no annotations, the description carries the behavioral burden. It adds significant value by explaining that 'mutually-exclusive' is sound and 'simultaneous-possible' returns a witness but not a reachability proof. This clarifies the nature of the result and its limits beyond the schema.

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?

Two sentences, tightly written, with the core question and the critical soundness caveat front-loaded. Every phrase adds meaning and there is no filler.

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 no output schema, the description provides useful return semantics by mentioning verdicts and witness assignments. It covers the most important caveat (not a reachability proof), which is essential for correct interpretation. Minor gaps include not describing possible error conditions, but overall it is sufficiently complete for this tool's complexity.

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 100%, so the baseline is 3. The description does not add much parameter-specific detail, though it loosely maps device_a/device_b as coils. The schema already covers root, max_vars, and max_depth adequately.

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 a specific action (static satisfiability check) and precise resource (two coils' ON/enable conditions). It clearly distinguishes this from sibling tools like trace, data flow, or lint by focusing on whether two conditions can be true simultaneously.

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 makes the intended use clear: determine if two coils' ON/enable conditions can co-occur. It also signals a key limitation—'simultaneous-possible' is not a reachability proof—which helps the agent avoid over-trusting the result, though it does not explicitly name alternative tools for reachability analysis.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that output can be large, that 'output' writes to a file, that list_sections exits after listing, and that the result should be quoted verbatim rather than restructured. This is strong coverage, though it does not detail all edge-case behaviors such as exact return format.

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, front-loaded with the core purpose, and each sentence earns its place: purpose, output handling, and filtering workflow. There is no filler or 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 no annotations and no output schema, the description covers the essential context: what the tool renders, how to present the result, how to manage large outputs, and how to narrow the result via list_sections and filters. An agent has enough information to invoke the tool correctly in the intended workflow.

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%, so the baseline is 3. The description adds value beyond the schema by explaining why 'output' matters (large output), how list_sections relates to filtering, and which filters are appropriate for narrowing the rendered circuit. This enriches the schema definitions without repeating them.

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 a specific verb and resource: "Render a program in GX Works3 print-text layout." It also clarifies the intended use case—showing a user how a circuit is wired—which distinguishes it from sibling analysis and check tools like gx3_lint or gx3_interlock_check.

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 gives explicit guidance on when to use the tool: when explaining circuit wiring, and how to present the output (verbatim in a code block, not JSON). It also provides a concrete workflow for filtering output using list_sections, section, pos_range, and device, making usage conditions clear.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It states the tool reads the project, writes one CSV per check plus a JSON summary, and that findings are advisory rather than definitive. This is excellent transparency about side effects and interpretation.

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 front-loaded with the core purpose, followed by a compact list of covered checks, then behavioral and prerequisite notes. Every sentence carries load-bearing information with no filler.

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 tool without an output schema, the description adequately covers return behavior ('per-check summary with finding counts by severity'), file side effects, advisory semantics, and prerequisites. An agent has enough context to call it correctly and interpret results.

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 100%, so the baseline is 3. The description adds value by listing the specific check categories an agent can expect, which helps interpret the 'checks' parameter even though the schema already documents comma-separated names or 'all'. The 'root' parameter meaning is already clear from 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 opens with a specific verb and resource: 'Run static review checks over the whole project' and names the exact kinds of checks. This clearly distinguishes lint from sibling tools like gx3_trace_device or gx3_data_flow, which serve different inspection purposes.

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 conveys when to use this tool: when a whole-project static review with per-check severity summaries is needed. It also gives the prerequisite that index and xref DBs are needed for the full check set. It does not explicitly name alternatives or when-not-to-use conditions, but the scope is clear enough.

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

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

No annotations are provided, so the description carries the full behavioral disclosure burden. It clearly states the tool is read-only, touches no project, and returns a one-line summary per command. This adequately discloses side effects and output shape for a simple listing tool, though it does not describe pagination or formatting details.

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?

Two sentences with no wasted words. The core purpose and output are front-loaded in the first sentence, and the second sentence adds essential usage guidance. Every sentence earns its place.

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 zero-parameter discovery command with no output schema, the description is complete: it states what the tool lists, how the list is formatted, that it is safe/read-only, and when to use it relative to gx3_run_command. An agent has everything needed to select and invoke it 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 tool takes zero parameters and schema coverage is 100% by definition. With no parameters to document, the description does not need to add parameter-level semantics; the baseline of 4 is appropriate.

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 a specific verb ('List') and resource ('every project-read-only GX3 CLI command'), and clearly states the output format ('with a one-line summary of each'). It is immediately distinguishable from all sibling tools, especially gx3_run_command, because it is a meta-command that enumerates available CLI commands rather than performing a domain action.

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 gives explicit usage guidance: call this before gx3_run_command when no typed tool fits, to discover what is actually available rather than guessing a command name. This names the alternative tool and the condition that selects this tool, leaving no ambiguity about when to invoke it.

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

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

No annotations are present, so the description carries the full burden of behavioral disclosure. It explicitly states that the tool reads project and comm detail CSVs, writes its own CSVs under the output directory, and does not communicate with any device. This fully covers the main side-effect and safety-relevant behaviors.

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 three sentences with no filler: purpose, usage cue, and behavioral constraints are each given their own sentence. Key information is front-loaded, and every sentence earns its place.

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 tool with no annotations and no output schema, the description is quite complete: it explains the purpose, the triggering scenario, the data sources, the write side effect, and the lack of device communication. It does not enumerate output CSV filenames or the exact return shape, but 'aggregated into one view' plus CSV output is enough to invoke it 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 parameters already described meaningfully, so the baseline is 3. The description only contextualizes the parameters by mentioning project and comm detail CSVs; it does not add new format, optionality, or behavioral detail 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 uses a specific verb and resource: it maps how the PLC is wired to everything outside it, covering IP addresses, CC-Link/SCON stations, and safety relationships. It clearly distinguishes from the sibling tools by emphasizing external/network wiring and device ownership rather than command lists, ladders, or diffs.

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 a clear selection cue: 'Use it to find which unit or remote station owns a device before assuming the program drives it.' It does not name sibling alternatives or explicitly state when not to use it, but the context is strong enough for an agent to choose it appropriately.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It discloses that the tool is read-only, restricts to MCP-allowed commands, rejects mutating operations, and confines local artifacts to GX3_MCP_OUTPUT_DIR. It does not describe error behavior or exact execution semantics, but the key safety-relevant traits are clearly stated.

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 sentences, front-loaded with the core purpose, followed by constraints and routing guidance. Every sentence adds necessary information with no wasted words.

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 generic command-running escape hatch without annotations or an output schema, the description covers the essential constraints: allowed scope, rejected operations, artifact confinement, and sibling tool preference. It could be more complete with an example or note on command availability via gx3_list_commands, but the core guidance is sufficient for an agent to select and invoke it safely.

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 50%: command and root have descriptions, while args and timeout_seconds do not. The description adds useful context by noting commands must be MCP-allowed and project-read-only, and that args are explicit, but it does not explain how to format args or how timeout behaves. It partially compensates for the schema gaps but leaves room for ambiguity.

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 ('run') and resource ('GX3 CLI command'), and frames itself as an 'escape hatch' for cases where typed tools don't fit. It clearly distinguishes itself from the sibling typed tools by naming them as preferable when they do fit.

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 says to prefer typed tools when one fits, and defines the boundary of what is allowed: MCP-allowed, project-read-only commands only. It also states what is rejected (project-mutating commands and local demo generation), giving clear selection guidance.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It states that both projects are only read, that neither project is modified, and that a detail CSV is written. This is strong transparency, though the destination/location of the CSV is not specified, leaving a minor gap.

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: the core comparison behavior is in the first sentence, the matching mechanism in the second, the intended use in the third, and side effects in the final sentence. Every sentence adds distinct value without repetition.

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 tool with two string parameters and no output schema, the description covers the main behaviors: what it compares, how rungs are matched, what it returns, and that it writes a CSV without modifying inputs. The only notable omission is where the CSV is written and the exact return format, but this remains adequate for invocation.

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 'old' and 'new' described as 'project folder or .gx3'. The tool description does not add extra parameter-level semantics beyond that, but the baseline of 3 is appropriate because the schema already documents the parameters adequately.

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 a specific verb ('Compare') and resource ('two versions of a project rung by rung'), and clearly states the output ('what was added, removed or changed'). It also distinguishes itself from positional diffing by mentioning stable block GUID matching, which helps separate it from simpler diff-like tools.

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 gives clear usage context: 'Use it to review what a revision actually did.' It does not explicitly name alternatives or exclusion conditions, but the intended scenario is clear enough for an agent to select this tool over siblings like gx3_explain_snapshot or gx3_list_commands.

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

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

With no annotations, the description carries the full burden and succeeds: it discloses that MC master-control zone conditions are folded into enable logic, that multi-OUT-coil devices and jump-skipped rows produce warnings, and that output includes device comments. These are non-obvious behavioral details beyond what the schema or name reveal.

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 dense sentences, front-loaded with purpose and followed by edge-case behavior and output guidance. Every sentence earns its place; there is no filler or repetition of schema content.

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 complex tool with no output schema, the description covers the main behavioral results, warnings, and the expected output-pairing instruction. It could go slightly further by explaining how max_depth constrains the trace, but the high schema coverage and strong behavioral detail make it largely complete.

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 83%, so the schema already documents most parameters. The description adds no parameter-specific meaning beyond noting the output carries comments; max_depth remains undocumented in both schema and description. This meets the baseline but does not exceed it.

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 a specific verb and resource: 'Trace a device's ON/OFF/hold conditions from exact ladder topology.' It also distinguishes itself from siblings by telling the agent to use gx3_ladder_print for showing the rung, making the division of labor clear.

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 gives clear context for when to use the tool—when tracing a device's conditions from ladder topology—and explicitly routes rung display to gx3_ladder_print rather than describing the rung in prose. It does not enumerate exclusions versus other siblings like gx3_xref_where_used or gx3_interlock_check, but the context is still clear.

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

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.