Server Quality Checklist

Tool Scores

• gx3_network_mapD
  1.7/5.0
  Behavior1/5

  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 does not state whether the tool reads, analyzes, or modifies data, what it returns, or any side effects. The description only names a generic 'relationship map' concept, lacking essential transparency.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness2/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is extremely brief (a single phrase), but it is under-specified rather than concise. It omits the core verb, usage context, and behavioral details, failing to communicate essential information an agent needs. Thus it does not earn credit for conciseness.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness1/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the likely complexity of aggregating multiple network types, the description is highly inadequate. There is no output schema and no explanation of return values, parameter relationships, or tool behavior. An agent cannot reasonably infer when or how to invoke this tool based on the description alone.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The input schema provides clear descriptions for both parameters (root, prefix) with 100% coverage, so the baseline is 3. However, the tool description adds no extra meaning about how these parameters influence the map generation or output, so it stays at the baseline without improvement.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose2/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description is a noun phrase ('Aggregated IP, CC-Link, SCON, and safety relationship map') with no explicit verb indicating what the tool does. It names the content domain but not the action (generate, list, analyze). It does not distinguish from sibling mapping tools like gx3_device_map or gx3_alarm_map beyond the network-specific scope.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines1/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  No usage context is provided. There is no indication of when to use this tool versus the other mapping or analysis siblings, no prerequisites, and no exclusions. The description offers no guidance for tool selection.

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

• gx3_alarm_mapC
  2.9/5.0
  Behavior2/5

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

  With no annotations, the description must disclose behavioral traits, but it only mentions the xref DB dependency. It does not state whether the operation is read-only, what happens if the xref DB is missing, or how results are returned, leaving important behavioral aspects undisclosed.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is extremely concise, consisting of two short sentences with no filler. It front-loads the core content (alarm/fault inventory and its attributes) and then quickly states the dependency, making every word earn its place.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness2/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The tool has three parameters, no annotations, and no output schema, yet the description only covers inventory content and the xref DB dependency. It omits usage context, mode behavior, and output expectations, leaving significant gaps for an agent trying to invoke the tool correctly.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The description adds meaning by specifying that the xref DB is required, which supplements the root parameter's 'Extracted project folder' schema description. It does not explain the mode parameter's list/show behavior or elaborate on the device parameter beyond the schema, but the schema already covers most parameters.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly identifies the tool as an alarm/fault inventory and lists specific attributes (trigger, hold type, timer setpoint, reset condition), which helps distinguish it from sibling mapping tools. However, it lacks an explicit action verb such as 'list' or 'show', so it is clear but not fully precise about the operation.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines2/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description gives a prerequisite ('Requires the xref DB') but does not explain when to use this tool over alternatives like gx3_device_map or gx3_network_map. No use-case scenarios, exclusions, or alternative references are provided.

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

• gx3_dead_logicC
  2.9/5.0
  Behavior3/5

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

  With no annotations, the description carries the transparency burden. It does provide useful behavioral context by stating the xref DB requirement and listing the exact detection categories. However, it does not disclose whether the tool is read-only, what output format to expect, or whether it has side effects, leaving meaningful gaps.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a single, efficient sentence that lists detection categories without wasted words. It is appropriately sized and front-loaded, though the missing main verb makes it slightly cryptic and prevents a perfect score.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness2/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Despite having only one parameter, the description is incomplete for an agent to invoke the tool confidently. There is no output schema, yet the description does not explain what the tool returns or how to interpret results. It also fails to distinguish this tool from siblings like gx3_lint, leaving the overall context incomplete.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The schema already describes root as 'Extracted project folder' with 100% coverage. The description adds that the tool requires the xref DB, implying the root folder must contain it, which provides meaningful context beyond the schema. This clarification justifies a score above baseline.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose3/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description enumerates specific dead logic categories (constant-off contacts, always-on NC contacts, etc.) but lacks an explicit verb like 'detects' or 'finds.' The tool name implies dead logic analysis, but the description does not clearly state the action, making it only moderately clear and not well differentiated from sibling tools.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines2/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  No guidance is given on when to use this tool versus alternatives like gx3_lint or gx3_interlock_check. The only usage-related note is 'Requires the xref DB,' which is a prerequisite, not a usage condition. There are no exclusions or alternative recommendations.

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

• gx3_semantic_diffB
  3.2/5.0
  Behavior2/5

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

  With no annotations provided, the description carries the full burden of disclosing behavioral traits. It does mention the granularity (rung-level) and the matching key (GUID), but it omits whether the operation is read-only, how output is formatted, or any required permissions or context. This leaves significant gaps.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a single, well-structured sentence that front-loads the key information. There is no unnecessary padding; every word contributes to understanding the tool's purpose.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness2/5

  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 and no annotations, the description does not explain the return value or how to interpret the diff results. It also lacks context about prerequisites or operational details, making it incomplete for a two-parameter tool.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Both parameters are fully described in the schema ('New project folder or .gx3' and 'Old project folder or .gx3'), so schema coverage is 100%. The description adds no additional meaning about the parameters, so a baseline score of 3 is appropriate.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool does a 'Rung-level diff between two projects' and specifies the matching mechanism 'by stable block GUID.' It uses a specific verb (diff) and resource (projects), and it distinguishes itself from the sibling tools, none of which are diff tools.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines2/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description provides no guidance on when to use this tool compared to alternatives. There is no mention of prerequisites, exclusions, or explicit 'use this when...' language. The purpose implies usage, but the description fails to give contextual direction.

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

• gx3_device_mapB
  3.3/5.0
  Behavior3/5

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

  With no annotations, the description carries the full transparency burden. It discloses the prerequisite and data source, implying a read-only query, but does not explicitly state side effects, error conditions, or whether anything is modified. The prerequisite adds useful behavioral context.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  One sentence with no filler, front-loaded with the output types. The prerequisite is efficiently included at the end. Every word earns its place.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a report tool with no output schema, the description conveys the core purpose and prerequisite but omits return format, structure of 'usage ranges/density/free gaps', and behavior around edge cases. Adequate but leaves important questions unanswered.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The schema covers all 3 parameters with descriptions, so the baseline is 3. The description's mention of 'device-type' and 'free gaps' loosely connects to 'types' and 'min_free' but adds no syntax or format details beyond what the schema provides.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description identifies concrete outputs ('usage ranges, density, free gaps') and the data source ('SQLite index'), making the tool's function clear and distinguishing it from sibling tools. It lacks an explicit verb, but the intent is unambiguous.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines2/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Provides a prerequisite ('build index-lite first') but no guidance on when to use this tool over alternatives like gx3_network_map or gx3_trace_device. No exclusion criteria or alternative references are offered.

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

• gx3_xref_where_usedA
  3.6/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the burden. It discloses the xref DB prerequisite and implies a read-only lookup, but it does not describe the output shape, failure behavior if the DB is missing, or any other side effects beyond the query nature.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is two sentences, front-loaded with the core purpose and followed by the essential setup command. Every sentence adds value with no redundancy or filler.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a two-parameter lookup with no output schema, the description gives enough to select and invoke: the return type, the input requirement, and the prerequisite setup. The phrase 'POU name and real step' is somewhat ambiguous but is likely domain-specific, and the schema covers the parameters, making this adequate for the tool's complexity.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The input schema already covers both parameters (`root` and `device`) fully at 100% coverage. The description adds no parameter-level detail beyond what the schema provides, so the baseline score of 3 applies.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description identifies the tool's output as 'Writers and readers of a device', indicating this is a where-used query. It is clear about the resource (device) and the kind of result (writers and readers), though the verb is implicit and it does not explicitly distinguish itself from siblings like gx3_trace_device.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  It provides a concrete prerequisite ('run gx3-cli xref build --root <root> once per project first'), which is important usage context. However, it does not explicitly state when to prefer this tool over alternatives or mention any exclusions.

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

• gx3_trace_deviceA
  3.9/5.0
  Behavior4/5

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

  With no annotations provided, the description carries full responsibility for behavioral disclosure. It adds valuable context beyond the schema by explaining that MC master-control zone conditions are folded into enable logic and that the output warns on multi-OUT-coil devices and rows below conditional jumps. This informs the caller of special-case handling, though it does not address read-only nature or 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.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is two sentences, front-loaded with the core purpose and then adding consequential behavioral details. Every sentence contributes unique information: the first defines the main action, the second discloses edge-case handling and output warnings. There is no fluff or repetition.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a tool with six parameters and no output schema, the description gives strong behavioral context but does not explain what the trace result looks like or how it is structured. It mentions warnings but not the main output format. Given the tool's complexity and the absence of an output schema, more information about the return value would improve completeness, though the purpose and behavior are largely covered.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  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 (device, root, ja, compact, strict_logic). The description itself does not elaborate on individual parameters, but the overall context about tracing from ladder topology helps interpret the required device and root inputs. It adds no specific parameter semantics beyond what the schema provides, aligning with the baseline of 3.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description opens with a specific verb ("Trace") and resource ("a device's ON/OFF/hold conditions") from a defined source ("exact ladder topology"), clearly distinguishing this tool from sibling tools like interlock_check or xref_where_used. It also adds distinctive details about folding MC master-control zone conditions and warning on multi-OUT-coil devices, making its purpose unambiguous and non-tautological.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description implies usage context for device-level tracing in ladder logic but provides no explicit when-to-use or when-not-to-use guidance, nor names alternatives. It does not mention how this differs from interlock_check or xref_where_used beyond the inherent purpose, so usage is only implicit.

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

• gx3_interlock_checkA
  4/5.0
  Behavior4/5

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

  With no annotations, the description must disclose behavior. It does so by explaining that a 'mutually-exclusive' verdict is sound while 'simultaneous-possible' is not a reachability proof, which is crucial for interpreting results. This adds meaningful behavioral context beyond the tool's existence, though it omits details like side effects or 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.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Two sentences, no wasted words, and the purpose is front-loaded. The caveat about verdict soundness is essential and succinctly included.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The tool has no output schema and no annotations, so the description must carry the burden of explaining result semantics. It does that well by clarifying the soundness of verdicts and the existence of witness assignments. However, it does not describe the expected input format or what the witness looks like, leaving a slight gap for an agent.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The schema provides complete descriptions for all 5 parameters (100% coverage), so the description's contribution to parameter understanding is minimal. It mentions 'coils' aligning with device_a/device_b, but the schema already handles parameter semantics. Baseline 3 is appropriate.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's purpose: a static satisfiability check on two coils' ON/enable conditions. The specific verb 'check' with a precise resource ('coils' conditions) and the interlock verification context distinguish it from all sibling tools, which perform different analyses.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description implies the tool is used to verify whether two coils can be ON simultaneously, but it does not explicitly say when to prefer it over sibling tools or mention any exclusions. No alternatives are named, leaving the agent to infer usage context.

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

• gx3_lintA
  4/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the burden of behavioral disclosure. It explicitly states 'Writes one CSV per check to the working directory,' which is a crucial side-effect and goes beyond just the tool's name. It also lists the types of checks. However, it doesn't mention whether source files are modified or if specific permissions are needed, leaving some minor gaps.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is two concise sentences that front-load the purpose and then disclose the output mechanism. It avoids fluff and every detail serves a purpose, making it highly efficient for an AI agent to parse.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The description covers the tool's primary function (static lint checks) and its output side-effect (CSVs per check). Given that the schema fully documents parameters and there is no output schema, the description provides sufficient context to understand the tool's behavior. A minor shortcoming is not explaining how results are presented beyond the CSV files, but that is not critical.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The input schema fully describes both parameters — 'root' as 'Extracted project folder' and 'checks' as 'Comma-separated check names, or "all" (default)'. Since schema description coverage is 100%, a baseline score of 3 is appropriate. The description adds no additional parameter-level meaning.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool performs 'Static lint' and enumerates specific check categories (duplicate coils, multi-writers, alarm quality, etc.), making its purpose unambiguous. It also notes the output behavior (writes CSVs), which distinguishes it from sibling tools like gx3_list_commands or gx3_trace_device.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description implies usage for static analysis but does not explicitly state when to use this tool over alternatives or mention any exclusions. There is no comparison to sibling tools like gx3_dead_logic or gx3_interlock_check, so usage guidance is only implicit.

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

• gx3_list_commandsA
  4/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the burden. It mentions 'project-read-only' suggesting safe commands, but does not describe output format, pagination, or side effects. The listing itself is inherently harmless, but more behavioral detail would improve transparency.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  A single, concise sentence that front-loads the purpose. Every word earns its place, and there is no fluff or redundant information.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple list tool with no parameters and no output schema, the description is nearly complete. It states what is listed and the scope ('project-read-only', 'through this server'). It lacks detail on the return format, but given the simplicity, this is acceptable.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  There are zero parameters, so the baseline is 4. The description correctly implies no input is needed, and the empty schema confirms this. Nothing more to add.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's function: listing GX3 CLI commands available through the server. The verb 'List' and resource 'project-read-only GX3 CLI commands' are specific and distinguish it from sibling tools like gx3_run_command which executes commands.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description implies use for discovery of available commands but provides no explicit guidance on when to use it versus alternatives, nor any exclusions. Context is present but no direct comparison with siblings.

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

• gx3_ladder_printA
  4.4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden. It discloses that output can be large and that the 'output' parameter writes to a file (implying side effects). It also explains filtering behavior. However, it does not state the return format or whether the tool is read-only, but for a rendering tool this is acceptable.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is three concise sentences. The first sentence states the core purpose. The second addresses output size and file writing. The third gives a practical filtering workflow. Every sentence earns its place; no fluff or redundancy.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Despite having 7 parameters, no output schema, and no annotations, the description provides a coherent mental model: render a program, handle large output via file, and filter using discovered sections. It is not exhaustive about return values or exact parameter syntax, but the schema covers those. The description is sufficiently complete for an agent to decide when and how to invoke the tool.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  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 by explaining how the parameters interrelate: using 'list_sections' to discover section titles, then using 'section', 'pos_range', or 'device' to filter. It also clarifies that 'output' handles large outputs by writing to a file. This enriches the schema-only meanings.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  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: 'Render a program in GX Works3 print-text layout.' This clearly states what the tool does and differentiates it from sibling tools like gx3_trace_device or gx3_lint, which focus on analysis rather than rendering.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description gives clear usage context: it warns that output can be large and suggests using 'output' to write to a file. It also provides a concrete workflow for filtering by using 'list_sections' to discover section titles and then applying filters like 'section', 'pos_range', or 'device'. It does not explicitly mention when not to use this tool versus alternatives, but the workflow is sufficient.

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

• gx3_run_commandA
  4.4/5.0
  Behavior4/5

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

  With no annotations, the description discloses read-only scope and rejects mutating/demo commands, which is essential safety context. However, it doesn't describe return format, timeout behavior, or error handling, leaving some behavioral gaps.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Two concise sentences, front-loaded with the tool's purpose and constraints, no fluff.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The escape hatch is generally well-specified given its generic nature: it defines what commands are allowed and points to typed tools for common cases. Yet without an output schema, it could benefit from a line on result formatting or how to discover allowable command names, but that is available via sibling tools.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema covers command and root descriptions, but args and timeout lack schema descriptions. Description adds 'explicit arguments' hint but doesn't clarify array format or timeout semantics, providing minimal added value over schema.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  Clearly states it runs any MCP-allowed, project-read-only GX3 CLI command, distinguishing itself from typed siblings as an escape hatch. The phrase 'when one fits' reinforces its role as a fallback for commands not covered by other tools.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Explicitly instructs to prefer typed tools when one fits, and identifies rejected command categories (project-mutating, local demo generation), providing clear when-to-use and when-not-to-use guidance.

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