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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=true, so the safety profile is covered. The description adds useful context by naming the UDP discovery protocol and stating that credentials are required. It does not explain reversibility, side effects, or what the confirm_token parameter is for, leaving meaningful 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.

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

The description is very concise and front-loads the action and target. The trailing fragment 'Control-class.' is terse but cryptic, slightly weakening an otherwise efficient structure.

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?

The tool is a destructive mutation with 7 parameters and zero schema descriptions, yet the description omits parameter-level meaning, confirmation flow, and side effects. It does mention protocol and credential requirements, but this is not enough for the agent to invoke the tool confidently.

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 0% for 7 parameters, so the description must compensate but largely does not. 'Needs the target's Windows/TC-BSD credentials' loosely hints at plc_username and plc_password, but plc_ip, hostname, route_name, local_net_id, and confirm_token are not explained at all.

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 ('Create') and resource ('PLC-side route back to this PC'), which distinguishes it from sibling route-listing tools such as ads_routes. However, it does not explicitly name any alternative tool or clarify when this creation tool should be preferred over discovery or listing 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?

It mentions a prerequisite ('needs the target's Windows/TC-BSD credentials') and the protocol involved, which gives some usage context. But it gives no explicit when-to-use guidance, no when-not-to-use conditions, and no alternatives among the many sibling tools.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the field inventory, which is useful, but says nothing about connection/auth requirements or whether it is safe to poll repeatedly. Adequate with annotations, but not rich.

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?

A single dense sentence with the resource definition front-loaded and the field list appended parenthetically. It earns its place, though the internal TwinCAT type name is borderline clutter for an agent.

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?

With no parameters and an output schema present, the description needn't explain return formatting, and it does supply the semantic meaning of the payload fields. The only real gap is the lack of connection/precondition context for a PLC-targeted read.

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, so the baseline is 4. The empty schema leaves nothing to disambiguate, and the description correctly adds no parameter guidance that would be redundant.

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?

Names the specific resource (PLC application info, anchored to TwinCAT_SystemInfoVarList._AppInfo) and enumerates the fields it covers, so an agent knows exactly what it returns. It does not differentiate itself from adjacent siblings such as ads_status or ads_task_stats, which overlap on task count and state, so it falls short of a 5.

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?

There is no when-to-use guidance, no stated prerequisites (e.g. an active ADS connection via ads_connect), and no named alternative among the many ads_* siblings. The agent must infer invocation context entirely.

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?

Annotations already flag readOnlyHint=false and destructiveHint=true; the description is consistent ('Write-class') and adds substance the annotations cannot: the TcRpcEnable prerequisite and the ordering/type constraints for arguments. It still does not describe failure modes on the PLC side or whether a partial write can occur.

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?

Terse and front-loaded: the purpose comes first, then the prerequisite, then the argument contract. The telegraphic fragments ('Write-class.', parenthetical type note) are dense but each carries information; no filler sentences.

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?

An output schema exists, so return values need not be explained, and the description covers the essential calling contract plus the RPC-enable prerequisite. Missing pieces are secondary: how to address the FB instance, error behavior, and side effects of a destructive write-class call.

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 0%, so the description carries the burden. It does well on two of the five parameters (exact shapes for inputs as {type,value} and outputs as type-name strings, with VAR_INPUT/VAR_OUTPUT ordering and a base-type warning), but says nothing about instance, method, or return_type, which are the required/optional identifiers.

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 and resource: invoking an FB method on a running PLC over ADS RPC, which is distinct from the symbol-level ads_read/ads_write siblings. It does not explicitly name a sibling it competes with, so an agent must infer that this is the only method-invocation tool.

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?

Gives a real precondition (the method must carry {attribute 'TcRpcEnable'}) and labels the operation 'Write-class', which steers the agent toward mutating-use context. It stops short of stating when to prefer this over ads_write/ads_write_many or what to do if the attribute is absent.

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?

Annotations already declare destructiveHint=true and non-idempotent, but the description adds genuinely new context beyond them: re-targeting is 'control-class' because it changes which machine every later write hits. That side-effect disclosure is real value. It omits that re-targeting likely requires the confirm_token the schema exposes.

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 compact sentences, front-loaded with the action and followed by the highest-value caveat. No filler; a slight tightening of the parenthetical would be the only improvement.

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?

An output schema exists so return values need no explanation, but for a destructive, non-idempotent control operation the description should say whether a confirmation/confirm_token is required and what happens on failure. That gap is meaningful for a 4-parameter mutation tool.

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 0%, so the description must carry the parameter burden. It ably explains ams_net_id formats ('5.12.34.56.1.1', 'local', None) and the 851 port meaning, but leaves ip_address and confirm_token completely unexplained.

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?

(Re)connect to a target' states the verb and resource clearly and could not be confused with read-oriented siblings like ads_read or ads_status. It does not, however, differentiate itself from ads_discover or ads_add_route_to_plc, which also concern target/routing topology.

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 implies when to call it (reconnect, optionally re-target) and gives useful defaults ('None = keep current'), but never states when NOT to use it or names an alternative tool for changing targets. Usage is inferable rather than explicit.

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?

Annotations already establish readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuine behavioral context beyond that: the operation is a UDP broadcast on port 48899 scoped to the local network, meaning it cannot reach remote subnets and may block for the timeout window. It does not mention behavior on zero results or timeout exhaustion, which keeps it short of a 5.

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?

A single sentence, front-loaded with the action and the transport, followed by the returned fields and an intuitive analog. 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?

Low-complexity tool with only two optional parameters and an output schema, so return-value explanation is unnecessary. The remaining gap is the lack of any workflow framing (that discovery precedes connect/route-added operations) and timeout semantics, but for a discovery tool this is close to 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 0%, and the description compensates only partially: 'local network' loosely gestures at the broadcast address parameter, but neither the broadcast target handling (default 255.255.255.255) nor the timeout_s semantics or units are explained. For two undocumented parameters the description should carry this load, and it does not.

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 verb and resource (broadcast search for TwinCAT targets), states the transport (UDP 48899), and enumerates the payload fields returned (NetId, host name, TwinCAT version, IP). This clearly separates it from connection-oriented siblings like ads_connect/ads_ping and from the XAE-side xae_target tool, without the agent needing to open either schema.

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 XAE 'Broadcast Search' analogy implies this is the discovery step performed before connecting (e.g. ahead of ads_connect or ads_add_route_to_plc), but usage is only implied. There is no explicit statement of when to prefer this over e.g. ads_status or a direct-IP connection, nor any prerequisite/exclusion.

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 readOnlyHint=true already covering the safety profile for the PLC side, the description adds the meaningful behavioral detail that this operation also writes files to disk and returns counts, file paths, and a 50-leaf preview rather than the full data. It does not explain what out_dir defaults to, whether existing files are overwritten, or what max_leaves / max_total_mb do when hit.

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?

Front-loaded with the core action and scope, then constraints, then return shape and hand-off to sibling tooling. Dense but every sentence carries information; the parenthetical expansions are the only slightly heavy part.

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 bulk-dump tool that also writes files, the description covers scope, filtering, exclusions, and return shape well, and an output schema exists so return values need not be detailed. However, with 0% param coverage and no statement about write destination defaults or cap behavior, the agent cannot fully predict the side effects of the call.

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 0%, so the description must carry all five parameters. It explains pattern with syntax examples and include_system with its default behavior, but out_dir, max_leaves, and max_total_mb — two of which look like truncation/safety caps an agent should reason about — are entirely undocumented.

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 ('Read EVERY variable on the PLC'), the exact scope (top-level symbols fully expanded through the datatype table including structs, FB instances, arrays of structs), and the two artifacts produced (nested JSON tree plus flat CSV). This clearly separates it from siblings like ads_read, ads_read_many, and ads_list_symbols.

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?

Gives concrete scoping conditions ('pattern limits the roots (MAIN.*, GVL_*)', 'system/library symbols excluded unless include_system') and routes the agent to direct alternatives for detail ('use proj_read_file / rec-style tooling on the files'). It doesn't explicitly contrast against ads_read_many or state when a bulk dump is preferable to a targeted read, but the context is strong.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful return-content context (master state and slave count) and the default port, but it omits behavioral details such as connection prerequisites, error conditions, or what happens when no master is found.

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 a single, front-loaded sentence: purpose first, then parenthetical port details. Every fragment earns its place 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 read-only tool with an output schema, the description provides the necessary purpose, return fields, and parameter default. It is nearly complete, though it could mention that the ADS connection must already exist and clarify its relationship to general ADS status tools.

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 0%, so the description must carry the parameter meaning. It does this well by stating the default port (65535 for the first master) and pointing to the Device → ADS tab in XAE, which is meaningful guidance beyond the bare 'Master Port' schema title.

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 specific resource (EtherCAT master) and the exact information returned (state values INIT/PREOP/SAFEOP/OP and slave count). It is clear enough to distinguish from generic ADS tools, but it does not explicitly contrast with siblings like ads_status or ads_plc_state.

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?

No when-to-use guidance is provided. The description explains the default ADS port and where to find it in XAE, but it does not say when an agent should call this tool versus ads_status, ads_discover, or other diagnostic 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context about what the generated csharp output is for (Beckhoff.TwinCAT.Ads ReadAny/WriteAny), but says nothing about the out_path parameter, which implies filesystem write behavior not reflected in the annotations.

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?

Front-loads the core purpose in the first clause, then compresses format semantics into a dense but readable single passage. No filler sentences, though the run-on format list is slightly hard to parse.

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?

An output schema exists, so return values need not be described. However, for a 5-parameter tool with 0% schema coverage, leaving out_path and namespace undocumented leaves the definition short of what an agent needs 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 0%, so the description must carry the full parameter burden. It richly documents fmt (all four values), types, and prefix, but leaves out_path and namespace completely unexplained — two of five parameters remain undocumented in both schema and description.

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 and resource ('Generate code from the runtime') and immediately enumerates the four output formats, making it clearly distinguishable from siblings like ads_types, ads_list_symbols, and rec_export. An agent can tell what this produces without opening the schema.

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 explains what each fmt produces but never says when to choose this tool over alternatives such as ads_read, ads_types, or xae_plcopen_export, nor what preconditions (e.g. a live ADS connection) apply. Guidance is entirely format-selection, not usage selection.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuine behavioral context: this reads the raw process image as the task actually sees/wrote it, bypassing symbols. It does not mention port/size behavior or error conditions.

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?

A single dense sentence with the resource front-loaded and area/offset semantics attached efficiently via punctuation. No filler, though the em-dash clause packs several ideas together at the cost of some scannability.

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?

An output schema exists, so return values need not be described. However, for a 4-parameter tool with 0% schema coverage, the description leaves port and size unexplained and offers no guidance on selecting this tool over the many sibling read variants.

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 0%, so the description must carry the load. It usefully explains 'area' (I=%IB inputs, Q=%QB outputs) and 'offset' (byte offset), functioning as an implicit enum. It adds nothing for 'port' (default 851) or 'size', leaving half the parameters undocumented.

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 specific resource (raw process image of the PLC), the areas I/Q with their %IB/%QB mapping, and the byte-offset addressing. It distinguishes itself from symbol-based reads via 'independent of symbol names,' though it does not differentiate from the close sibling ads_read_raw.

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 parenthetical '(link checks)' hints at the intended use case but there is no explicit when-to-use/when-not guidance or named alternative versus ads_read, ads_read_raw, or ads_read_many. Usage is implied rather than stated.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that – leaves carry byte offsets, and with values=true the values come from a single whole-symbol read – but says nothing about limits, truncation from max_leaves, or ordering.

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 compact sentences, front-loaded with the core action and followed by a concrete example. The example and the with_values note both earn their place; only the trailing ellipsis-style formatting is slightly loose.

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?

An output schema exists, so return shape need not be described. Still, for a read-only enumeration tool with 0% schema coverage, the missing explanation of max_leaves and the absence of any when-to-use routing against sibling read tools leave the definition short of fully self-sufficient.

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 0%, so the description must carry parameter meaning. It partly does: it shows the accepted 'name' syntax and explains the effect of with_values=true. However, max_leaves (default 5000) is never mentioned, so one of three parameters is entirely undocumented.

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 ('Enumerate') and resource ('every scalar leaf under a symbol'), and gives concrete examples of the symbol syntax ('MAIN', 'MAIN.arrSteps' → arrSteps[1].nId) that pin down exactly what is returned. It is clear what the tool does, though it never explicitly distinguishes itself from leaf-reading siblings like ads_read or ads_symbol_info.

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?

Usage is implied rather than stated: the syntax examples and the byte-offset detail hint at when leaf enumeration is appropriate, but there is no explicit 'use this when you need X instead of ads_read/ads_symbol_info'. An agent must infer the alternative from the description alone.

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?

Annotations declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds that compact mode returns a token-reduced format (one fifth of the tokens), which is useful behavioral context beyond annotations. However, refresh parameter behavior and pagination are not described.

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?

Dense but well-structured, front-loading the purpose then covering parameters with concrete examples. Every sentence adds value. Slightly terse but not wasteful.

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?

With 7 parameters, 0% schema coverage, and no output schema, the description covers the key parameters well but omits limit, offset, and refresh semantics. An agent might not know default pagination behavior or what refresh does. Adequate but incomplete for a 7-param tool.

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 0%, so the description must compensate. It explains pattern (fnmatch with examples and bare-text wrapping), type_filter (substring match with examples), flag (accepted values), and compact (format and token savings). This meaningfully clarifies the most important parameters, though limit, offset, and refresh are left undocumented.

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+resource: 'Browse the runtime symbol table.' Clear what it does. It doesn't explicitly differentiate from siblings like ads_symbol_info or ads_discover, but the tool name and description are distinct enough.

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?

No when-to-use guidance or mention of alternatives. An agent must infer that this is for enumerating symbols vs ads_symbol_info which likely gets details for one symbol. No exclusions or routing.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that this measures round-trip time and relates to router/route/network health, but says nothing about blocking behavior, timeouts, how count affects duration, or rate limits.

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?

A single compact sentence with no padding, front-loaded on the tool's subject. Slightly awkward phrasing ('statistics to the target') costs it the top score.

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?

An output schema exists, so return values needn't be explained, and annotations cover safety. Still missing are parameter meaning (port/count) and any usage guidance, which are needed for correct invocation even on a simple two-parameter tool.

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 0% and the description never explains the two parameters. It implies repeated measurement (count) and a target port, but neither is stated or given format/semantics, so it fails to compensate for the empty schema descriptions.

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 (ADS target) and the measurement (round-trip time statistics), plus the diagnostic domain (router/route/network health). However, it uses no explicit verb and reads more like a description of the output than of an action, so it is only vaguely distinguishable from siblings like ads_status or ads_routes.

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 parenthetical hints at a diagnostic use case, but there is no explicit when-to-use, when-not-to-use, or named alternative among the many ads_* siblings. The agent is left to infer that this is a connectivity/latency probe.

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?

Annotations already declare destructiveHint=true and non-idempotent, but the description adds real beyond-annotation context: 'reset' is a cold reset that loses all non-persistent data, and 'Control-class: confirmation in guarded mode' signals the confirm_token requirement. This is meaningful disclosure of what gets destroyed and what authorization is needed.

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 compact sentences, front-loaded with the tool's function and immediately followed by the critical destructive-action caveat. The pipe-list action notation is efficient; there is essentially 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?

An output schema exists so return values need not be described, and the destructive semantics are covered. The gap is the confirm_token workflow: the agent is told confirmation exists in guarded mode but not how to obtain or use the token (e.g., via the sibling tc_request_confirmation), leaving invocation incomplete for write operations.

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 0%, so the description must carry parameter meaning; it does partially compensate by enumerating the accepted action values (run | stop | reset), which the schema omits. However confirm_token is only obliquely referenced via "confirmation in guarded mode" and its format/obtaining procedure is unexplained.

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+resource ("PLC runtime control via ADS") and enumerates the concrete actions run | stop | reset, so the agent knows exactly the domain of effect. It does not explicitly differentiate itself from adjacent siblings like ads_system_mode or xae_restart_twincat, leaving some disambiguation to be inferred from the name.

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 its use case (runtime state control) and adds the important prerequisite that confirmation is required in guarded mode, but it never states when to prefer this over ads_system_mode or tc_set_mode, nor any exclusions. Usage is implied rather than explicitly guided.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description goes beyond that by disclosing decoding behavior: structs/FBs become a nested datatype table, TIME/DATE get readable text, enums get names, and oversized trees are truncated to member names plus sizes.

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 with the core behavior front-loaded, followed by decode specifics and the truncation escape hatch. No filler, though the output-format detail is arguably more than needed given an output schema exists.

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?

Return-value rendering is well explained (and an output schema exists anyway), and safety is covered by annotations. However, with three of four parameters undocumented at 0% schema coverage, the definition is not complete enough for an agent to tune the call confidently.

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 0%, so the description carries the full burden, yet only max_chars is given meaning (the truncation threshold). max_members, expand_struct, and the name format are entirely undocumented in both schema and description.

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 and resource ('Read one symbol') with a distinguishing qualifier ('type-aware decoding'). The 'one symbol' phrasing implicitly separates it from ads_read_many, and 'type-aware' implies a difference from ads_read_raw, though neither sibling is named directly.

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?

Gives an explicit routing rule: when the decoded tree exceeds max_chars it is summarised, so use ads_leaves or ads_dump instead. This is clear conditional guidance, but it does not cover when to prefer ads_read over ads_read_raw or ads_read_many.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real context beyond that — a single batched round trip and per-name error results rather than an all-or-nothing failure — but says nothing about connection requirements or limits on batch size.

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, front-loaded with the action and mechanism, no filler. The return-shape notation '{name: value | {error}}' is terse to the point of being slightly cryptic, and it partly restates what the output schema already defines.

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?

An output schema exists, so return values need not be re-explained (the description does so anyway). What is missing for correct invocation is the symbol-name format and the connection precondition implied by sibling ads_connect; for a one-parameter batch read that leaves a visible gap.

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?

One parameter ('names') with 0% schema description coverage, so the description must compensate. It conveys that the array holds symbols and roughly what comes back, but never clarifies the expected symbol path format (e.g. 'MAIN.bVar'), which is the main thing an agent would get wrong.

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 and resource (read several symbols) plus the mechanism (one ADS sum-command), which distinguishes it from the singular ads_read without needing the schema. It does not, however, name the sibling it replaces the way a 5-level description would.

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 batching intent is implied by 'several symbols in one' command, so an agent can infer this is the multi-read variant of ads_read. But there is no explicit when-to-use statement, no mention of ads_read_raw or ads_io_read as alternatives, and no prerequisites (e.g. an active ads_connect) despite ads_connect being a sibling.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that reads are raw, address-based, usable on any port, and mentions hex/little-endian uint output, but it does not clarify that parenthetical or disclose connection requirements or error 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?

A single front-loaded sentence with no padding. The parenthetical is terse but cryptic, slightly reducing clarity rather than adding useful structure.

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?

Although output schema exists and annotations cover safety, the description is too thin for a five-parameter raw-read tool. It omits meaning for size and ams_net_id and gives no sibling comparison or usage context.

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 0%, so the description must explain parameters. It names index_group, index_offset, and port, but says nothing about required size or optional ams_net_id, leaving two of five parameters undocumented.

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 and resource: 'Raw ADS read' by index group/offset on any port. This implicitly distinguishes it from higher-level reads like ads_read, but it never names or explicitly contrasts with any sibling tool, so it falls short of a 5.

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?

Provides no when-to-use guidance, no alternatives, and no exclusions. An agent learns what the tool does, but not when to choose it over ads_read, ads_read_many, or ads_io_read.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description contributes the useful detail that results are parsed from a local config file rather than queried live from the PLC, which explains why results are static. It says nothing about staleness, refresh behavior, or result volume, so it adds moderate value only.

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?

A single short sentence with zero filler, and the most important qualifier ('local static') is front-loaded. It is arguably too terse — no verb and no leading description of intent — which keeps it just below top marks.

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 zero parameters, an existing output schema, and annotations covering the safety profile, the description is close to sufficient. It still leaves open how this relates to ads_add_route_to_plc and ads_discover (static file view vs. live routing table) and whether the file is re-parsed on each call.

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, so there is no parameter semantics to explain and the baseline is 4. The description correctly implies the tool needs no arguments by scoping itself to 'this PC'.

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 resource (local static ADS routes) and discloses its provenance (StaticRoutes.xml on this PC), which distinguishes it from the write-oriented sibling ads_add_route_to_plc. It lacks an explicit verb (list/get/read), but the noun phrase is unambiguous enough that an agent knows what it retrieves.

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?

There is no when-to-use guidance at all: no statement of when to call this versus ads_add_route_to_plc, ads_discover, or ads_status, and no preconditions (e.g., whether the ADS connection must be live or whether 'static' excludes dynamically discovered routes).

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: what the composite contains and how the single-port mode differs, including a mapping of well-known port numbers to their services.

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, front-loaded with the composite behavior, then the port override with concrete examples. No filler, and each clause adds usable information.

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?

With an output schema present, return-value documentation is unnecessary, and annotations cover the read-only nature. The description covers the composite/single-port duality and port semantics adequately, though it omits guidance on when to prefer this over the dedicated sibling status tools.

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 0% on the single port parameter, so the description must compensate, and it largely does: default null yields the composite, a supplied port yields only that port's ADS state, and example values (852 PLC2, 500 NC, 10000 system service, 65535 EtherCAT master 1) clarify intended input.

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+resource (composite ADS status) and enumerates the fields returned (connection, PLC runtime state, TwinCAT system mode, device name/version). It does not, however, differentiate itself from siblings like ads_plc_state or ads_system_mode despite naming overlapping data.

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?

Usage is implied: call with no port for the composite, call with port=N for a single-port ADS state. There is no explicit when-not guidance and no named alternative among the many status siblings (ads_plc_state, ads_system_mode, ads_ping), leaving routing to inference.

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?

readOnlyHint=true and destructiveHint=false already establish this as a safe read, so the description's burden is lower. It adds the field-level content (flags like READONLY, PERSISTENT), which is useful context, but says nothing about needing an active ADS connection or behavior on unknown symbols.

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?

One tight sentence with the resource and returned fields front-loaded; nothing is wasted. It reads as a fragment rather than a sentence, but that costs little.

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?

An output schema exists, so return values need no explanation, and the annotations cover the safety profile. What is missing is the connection prerequisite and the required format of the symbol identifier, both of which an agent needs to call this 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 coverage is 0% and the single 'name' parameter is undocumented. 'of one symbol' implies the argument identifies a single symbol rather than a pattern, which adds marginal meaning, but no symbol-path syntax (e.g. qualified path) is given.

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 resource (one symbol) and enumerates the exact metadata returned (type, size, index group/offset, flags, comment), which separates it from ads_list_symbols (listing) and ads_read (values). It lacks an explicit verb, but the noun-phrase form is unambiguous.

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?

No when-to-use guidance, no prerequisites, and no mention of the many alternatives in this large sibling set (ads_list_symbols, ads_leaves, ads_types, ads_read). The agent must infer that this is for a single symbol's metadata.

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?

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is covered. The description adds real value beyond that: it names the exact consequence (runtime restarts and I/O drops), which is essential operation context for a disruptive action.

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?

A single sentence that front-loads the core action, then immediately qualifies it with the destructive consequences. No filler, no 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?

An output schema exists so return values needn't be explained, and annotations cover the safety hints. But with 0% parameter coverage and an unexplained confirm_token tied to a destructive-mode switch, plus no routing guidance among many mode-related siblings, the definition is only minimally complete for such a high-risk operation.

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 0%, so the description must carry the parameter burden. It names the two 'action' values ('run' and 'config'), which is useful mapping, but it never explains the confirm_token parameter or the confirmation flow it implies, leaving a required interaction step undocumented.

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 ('Switch') and resource ('TwinCAT on the target') plus the two states it toggles between, so the agent knows exactly what the tool does. It does not, however, differentiate itself from close siblings like tc_set_mode or ads_plc_state, leaving ambiguity about which mode-switcher to pick.

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 warns of the side effect (runtime restart, I/O down) and declares itself 'Destructive-class,' which implies caution, but it never says when to use this versus the sibling alternatives such as tc_set_mode, ads_plc_state, or xae_restart_twincat, nor any prerequisite or ordering.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds useful context beyond that — the underlying SystemInfoVarList source and that timing is averaged over `samples` — but says nothing about how sampling blocks, cost of the read, or any permissions.

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?

A single dense sentence, front-loaded with the resource and source path, followed by the metric list. Every clause is informative, though the em-dash tail slightly overloads one sentence.

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?

An output schema exists so return values need no explanation, and read-only annotations cover safety. However, with 0% schema coverage the three parameters are not fully described, which is a real gap for an agent trying to tune sampling behavior.

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 0%, so the description carries the burden, yet it only mentions `samples` (execution time over `samples`) and hints at `task_index` via the [n] notation. `interval_ms` is never explained, leaving a third of the parameters undocumented in both places.

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 resource (PLC task timing) and enumerates exactly what it returns: cycle time, last/min/max/mean execution time, load %, and exceeded-counter delta. The parenthetical source path and the 'FB's cost on the real-time task' framing make the intent concrete, though it does not name or contrast a sibling profiling tool.

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?

Usage is implied rather than stated: measuring a function block's real-time cost suggests a profiling context, but there is no when-to-use, when-not, or alternative (e.g. wf_fb_profile, rec_stats) named. An agent must infer the scenario.

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?

Annotations already establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered by structured data. The description adds some behavioral value by enumerating the data returned (offsets, sizes, bounds, enum literals, attributes), but says nothing about scope limits, connection requirements, or behavior when a type/pattern matches nothing.

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?

A single dense sentence, front-loaded with the resource and then the two operating modes. Nothing is padded, though the parenthetical detail list pushes it toward a run-on.

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?

An output schema exists, so return-value explanation is not required, and the read-only annotations cover safety. Still, with three undocumented parameters (limit, pattern, type_name all at 0% schema coverage), the description should say more about parameter meaning and defaulting to be fully actionable.

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 0%, so the description carries the burden. It effectively disambiguates type_name (single type) from pattern (matching list), but leaves 'limit' entirely unexplained and gives no syntax for pattern (glob vs. regex) or expected type-name format, so it only partially compensates.

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 resource ('Runtime datatype table') and two distinct operations (describe one type vs. list types matching a pattern), plus what a description contains (members with offsets/sizes, array bounds, enum literals, attributes). It is clear enough to distinguish from symbol/read siblings, though it never names an alternative such as ads_symbol_info or ads_list_symbols.

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 two modes ('describe one type' vs 'list types matching a pattern') imply which parameter to use, giving implicit usage guidance. There is no explicit when-to-use/when-not-to-use statement and no routing to a sibling tool, so an agent must infer the selection.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds genuinely useful context beyond that: it will BLOCK until the condition is met or the timeout expires, and returns met/elapsed. However it omits operational details like polling behavior/interval and the risk of long blocking up to timeout_ms.

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 tight sentences with the primary action front-loaded and zero filler. It is efficiently sized, though for a tool with five undocumented parameters the brevity edges toward under-specification rather than clean conciseness.

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?

The three required params (name, op, value) are all covered, an output schema exists so return-value detail is not required, and annotations cover safety. The two optional params (timeout_ms default 10000, interval_ms default 50) are left undocumented, leaving a real gap against 0% schema coverage.

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 0%, so the description carries the full param burden and must compensate. It does meaningfully document the `op` argument by enumerating the six comparison operators the schema leaves as a bare string, and it clarifies name/value roles. But timeout_ms and interval_ms (their defaults and units) are never addressed.

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 (block/wait) and resource (symbol compared against a value via an operator) with the timeout escape condition. An agent can grasp the core action, but the description never distinguishes it from near-siblings like ads_watch or ads_read, so differentiation is left to inference.

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 explains the mechanism but gives no when-to-use guidance, no prerequisites, and no named alternative (ads_watch is the obvious competing polling tool). The agent must infer the usage scenario purely from the blocking semantics.

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?

Annotations already declare readOnlyHint and non-destructive, so the safety profile is covered; the description adds real behavioral content beyond them: the change_only filtering semantics and hard caps (60 s, ≥10 ms, 5000 rows). It does not say whether the call blocks for the full duration_ms, which is the main remaining unknown for a polling tool.

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 compact sentences, front-loaded with the sampling mechanism, then the filter flag, then the caps, then the use cases. Nothing is redundant and no sentence is 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?

An output schema exists, so return structure needn't be explained; the description complements it with caps and filter semantics. Blocking behavior and error/limit-exceeded handling are the only notable gaps for an agent deciding to call it.

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 0%, so the description must carry the load — and it does: change_only is defined, duration_ms and interval_ms get constraints, and names is implied by 'Sample symbols'. Units come from the schema's *_ms naming, and default values (2000 ms, 50 ms, change_only=true) are left to 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?

States a specific verb and mechanism: 'Sample symbols for duration_ms every interval_ms (polling trace)', which cleanly separates it from single-shot siblings like ads_read and ads_read_many. The two quoted timing questions ('does bDone pulse?', 'how long is the valve open?') further pin down its role, though no sibling is named explicitly.

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?

Gives clear context for when to reach for it — timing/pulse-width questions rather than point-in-time value reads. It stops short of stating when NOT to use it or naming alternatives such as ads_read or ads_wait_until for a single value or a one-shot wait.

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?

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds meaningful context: 'Returns before/after' and the gating rule ('readonly=never; guarded=write_allowlist; full=denylist only') tell the agent how writes are permitted in each mode. It stops short of warning about irreversibility or confirming a write actually took effect.

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 the core action, then the value formats, then the gating rule. No wasted words, though the accepted-literal list could be more tightly framed.

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?

An output schema exists, so return values needn't be spelled out, yet the description still notes 'Returns before/after'. For a destructive single-write tool with 0% param coverage, it covers value formats and permission gating adequately but leaves the name parameter and cross-tool routing unaddressed.

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 0%, so the description must carry the load. It does explain the value parameter's accepted forms (scalars, lists, literals like 'T#1s500ms', 'D#2026-10-15', '16#FF'), which is genuinely additive, but the required 'name' parameter (the symbol identifier) is never explained.

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 and resource ('Write a symbol on the running PLC') with the target context ('running'). It is clearly a single-symbol write, which implicitly separates it from ads_write_many and ads_write_raw, but it never names those siblings so the agent must infer the distinction.

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?

There is no explicit when-to-use/when-not guidance and no routing to alternatives such as ads_write_many for multiple symbols or ads_read to check current values. The 'Gated' clause describes permission modes rather than selection context, so usage must be inferred.

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?

Annotations already declare destructiveHint=true and readOnlyHint=false. The description goes beyond them by disclosing that each write is individually gated, audited, and that the batch aborts at the first refusal — meaningful behavioral context for a destructive batch operation.

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 dense sentences with the batching, format, and failure policy all front-loaded. 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?

With an output schema present, return values needn't be explained, and the description adequately covers format, gating, auditing, and abort semantics for a batch writer. Only the relationship to sibling write tools remains unstated.

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 schema documents a single free-form object at 0% coverage. The description compensates partially by specifying the '{name: value}' shape, but adds no detail on value typing, size limits, or ordering guarantees beyond 'sequentially'.

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+resource ('Write several symbols') and the format ('{name: value}'), which naturally distinguishes it from the singular ads_write and the raw variants. It doesn't explicitly name the sibling it supersedes, but 'several' clearly scopes it.

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 batch write usage and notes fail-fast behavior, but never states when to prefer this over ads_write, ads_write_raw, or ads_read_many, nor any prerequisites. Usage must be inferred from the name.

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?

Annotations already flag destructive=true and readOnly=false, but the description adds non-obvious behavior: every symbol whose memory overlaps the written range is validated against write allow/deny lists, and the raw target is named as 'raw:<port>/<igrp hex>/<ioffs hex>'. That safety-check disclosure is genuinely useful context beyond the annotations, though auth requirements and post-write state are not covered.

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 compact sentences with the core action and port restriction front-loaded and no filler. The trailing 'raw:<port>/<igrp hex>/<ioffs hex>' fragment is a bit dense and could be clearer, but overall it is efficient.

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?

An output schema exists so return values need not be explained, and the destructive/allow-deny context is present. Still, for a raw memory-write tool with 0% schema coverage, the description omits the hex_data format, the ams_net_id parameter's purpose, and what happens when an overlapping symbol is denied, leaving real gaps for correct 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 0% across 5 parameters, so the description must carry the load. It does clarify what index_group/index_offset mean (encoded as igrp/ioffs hex in the target string) and bounds the port parameter to 851-859, but it says nothing about hex_data's expected format or the role of ams_net_id, leaving the two most easily misused parameters undocumented.

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+resource: a raw ADS write addressed by index group/offset, with the scope restricted to PLC runtime ports 851-859. It implicitly separates itself from the symbol-based ads_write/ads_write_many by emphasizing 'raw' and index-group addressing, but never names a sibling, so it falls short of a 5.

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?

'PLC runtime ports (851-859) only' is a real domain constraint that tells the agent when the tool applies. However, there is no explicit guidance on when to pick ads_write_raw over ads_write, ads_write_many, or ads_read_raw, so usage is only implied rather than directed.

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?

Annotations declare the safety profile (write, idempotent, non-destructive), and the description usefully adds the side effects the agent could not otherwise know: recordings are closed and factor values are restored. It does not confirm the idempotent behavior or describe auth requirements, so it falls short of a 5.

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?

A single front-loaded sentence with the verb first and the two side effects appended; no filler or redundant restatement of the name.

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?

With an output schema present, return values need no explanation, and the annotations plus the side-effect sentence cover safety and effect. However, the complete absence of parameter documentation leaves a real gap for a mutation tool that takes an argument.

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 0% for both parameters, so the description carries the full burden, yet it mentions neither 'name' nor 'reason'. The agent gets no help on what to pass, and the 'reason' default of 'requested' is never explained.

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 ('Stop a running experiment') plus the effect, which cleanly separates it from exp_run, exp_status, and exp_list in the sibling set. An agent can identify the action without opening the schema.

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 phrase 'after the current step' gives an implied condition of use, but no alternative tool is named and there is no explicit when-to-use or when-not-to-use guidance relative to exp_run or exp_status. Usage must be inferred.

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?

Annotations already establish this as a safe read (readOnlyHint=true, destructiveHint=false). The description adds genuine behavioral context by disclosing what is computed (metric deltas, CI separation), but says nothing about what happens when the two experiments do not share levels or how results are scoped.

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?

One sentence, front-loaded with the core operation and no filler. The parenthetical is slightly dense but still earns its place by clarifying the comparison's purpose.

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?

An output schema exists, so return values need not be explained here. However, with 0% parameter coverage the definition leaves the two required inputs and the 'same levels' precondition undefined, which is a real gap for an agent trying to invoke it.

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 0% and the two parameters are opaque single letters ('a', 'b'). The description lets the agent infer they are experiments, but adds no format, identifier convention, or ordering semantics, so the agent must guess what to pass.

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 operation (side-by-side comparison of two experiments) and the concrete output (metric deltas and whether 95% CIs separate). It is reasonably distinguishable from exp_evaluate/exp_report by describing the two-experiment, error-bar framing, though it never names a sibling.

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?

Usage is implied by 'Two experiments with the same levels' and the parenthetical 'before/after question', which hints at when it applies, but there is no explicit guidance on when to prefer this over exp_evaluate, exp_runs, or the analogous rec_compare/snap_compare.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real value beyond that by disclosing that results are deterministic from runs.jsonl and that any user can rerun it, which tells an agent the output is stable and reproducible.

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 tight sentences with no filler, and the behavioral constraint (determinism, rerunnability) is front-loaded. The only weakness is that the opening sentence leads with outputs instead of the action.

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?

An output schema exists, so return values need not be re-explained. However, the unexplained 'name' parameter and the total absence of usage routing leave gaps for a tool sitting in a dense family of exp_* siblings.

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 single required parameter 'name' has 0% schema description coverage and is never mentioned in the description. An agent cannot tell whether 'name' is the experiment name, a file, or something else, so the description fails to compensate for the gap.

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 details what the tool returns (metrics per level, CIs, verdicts) rather than stating the action, leaving the verb to be inferred from the name 'exp_evaluate'. It does not distinguish this from siblings like exp_report or exp_compare, which likely also surface experiment results. The purpose lands as vague rather than a clear verb+resource statement.

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?

There is no guidance on when to call this versus exp_report, exp_compare, or exp_runs, nor any prerequisites (e.g., whether an experiment must have been run first). The only contextual hint is 'rerunnable by anyone', which touches idempotence but not selection.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered by structured data. The description adds only the content returned (spec/status/run summary); it says nothing about error behavior or whether the experiment must exist, which is acceptable given annotations but not generous.

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?

A single front-loaded noun phrase with zero filler; appropriately sized for a trivial getter, though the fragmentary style borders on under-specification rather than true economy.

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?

With an output schema present, return values need not be described, and the read-only annotations cover the safety profile. Still missing is any disambiguation from exp_list/exp_status/exp_runs and any hint about the 'name' parameter, leaving the definition minimally viable.

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 0% — the single 'name' parameter has no description. The tool description never clarifies whether 'name' is an experiment name, an ID, or a path, so it fails to compensate for the documentation gap.

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 phrase names the resource (one experiment) and enumerates the returned content (spec, status, run summary), and 'one experiment' is enough to distinguish it from exp_list. However it lacks an explicit verb and makes no reference to overlapping siblings such as exp_status or exp_runs.

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?

There is no statement of when to use this tool versus exp_list, exp_status, or exp_runs, even though those siblings clearly overlap. The agent must infer selection criteria on its own.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds only that it reads from disk and what metadata is attached, but since an output schema exists, these details are redundant and it says nothing about pagination, ordering, or authentication needs.

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 single noun-phrase fragment is very short and contains no fluff, but it lacks a subject and verb, making it less clear than a well-formed sentence. It is not front-loaded with an action verb.

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 is a simple read-only list with no parameters and a full output schema, the description still falls short by not stating the list action or any usage context. An agent could misread it as returning a single experiment rather than a collection.

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, so there are no parameter semantics for the description to clarify. Baseline of 4 applies.

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 (experiments on disk) and the data included (run counts, state, report existence), but it is a noun phrase that never states the list action. An agent must infer 'list' from the tool name rather than the description, and no sibling differentiation is provided.

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?

No guidance on when to use this tool versus alternatives. It does not mention when to call exp_list versus exp_get, exp_runs, or other experiment-related siblings, nor any prerequisites.

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?

Annotations already declare the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description goes beyond them by disclosing the two files written, that 'interpretation= saves a new one' with an author attribution scheme, and that firmware_check triggers proj_vs_runtime as a side effect. The audit-log content also signals that writes are tracked. Missing only details like overwrite behavior for existing reports.

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 verb and target paths are front-loaded, which is good, but the body is a long run-on list that conflates artifact sections with parameter behavior. Every clause carries information, yet the density could be structured more readably.

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?

An output schema exists, so return values need no explanation, and the description covers the substantive behavior an agent needs: what files are produced, that the interpretation is stored separately and labelled as not computed, and the firmware_check side effect. The unexplained fmt parameter and the lack of explicit alternative-tool routing are the remaining gaps.

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 0%, so the description must compensate. It explains interpretation (saves a new one; author=agent|operator|<name>), author, and firmware_check, but never mentions what fmt='both' controls and only implies that name is the experiment directory. Two of five parameters remain unexplained, so it adds real but incomplete value.

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+resource: 'Write <experiments_dir>/<name>/report.md and report.html', so the agent knows it produces report artifacts for a named experiment. It enumerates the artifact contents (identity, criteria table, metrics, charts, run table, spec, audit log, interpretation), which further distinguishes it from siblings like exp_evaluate or exp_compare that analyze rather than render. It stops short of explicitly naming a sibling contrast, so a 4 rather than 5.

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?

Usage is implied rather than stated: after a run, this is the tool that emits the report. The description does give conditional behavior ('firmware_check=true runs proj_vs_runtime first'), which hints at when the extra check matters, but there is no explicit guidance on when to prefer exp_report over exp_evaluate, exp_compare, or exp_get.

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?

Annotations only declare destructive=true and readOnly=false; the description adds substantial behavioral context beyond that: factor values are read first and restored on abort (read back and checked), every write is re-checked against a server guard, pinned to the starting machine, and audited with symbol/value, and a refusal/target change/timed-out write aborts the experiment. It also discloses the control-class confirmation flow (elicitation/confirm_token) and the single-experiment concurrency limit. This is exactly the extra context annotations cannot carry.

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?

Information-dense but structured poorly: the opening sentence is a long arrow-delimited pipeline that is hard to parse and not obviously the highest-value content for selection. The behavioral safety details are valuable but buried mid-paragraph. Every sentence does carry meaning, so it is not padded, just densely and unfront-loadedly written.

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?

An output schema exists, so return-value explanation is not needed. For a complex, destructive background runner the description covers the pipeline, safety/audit behavior, abort conditions, dry_run semantics, and confirmation flow. The main gap is undocumented parameters (resume, max_runs, name), which slightly under-serves correct 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 0% across 5 parameters, so the description must carry the burden. It explains dry_run well (resolves symbols, coerces enum names to ints, prints plan without writing) and clarifies confirm_token's role in guarded mode. But name, resume, and max_runs get no explanation at all, leaving three of five parameters undocumented.

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 clear verb+resource ('Run an experiment in the background') and then specifies the exact execution pipeline (preconditions → factor values → snapshot → stimulus → ... → runs.jsonl). This distinguishes it from siblings like exp_validate, exp_status, exp_runs and exp_abort, which clearly handle other phases. The core purpose is unambiguous, though the pipeline detail crowds the framing.

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?

Usage is implied through the described dry_run resolution/planning mode and the note that 'Only one experiment may run at a time,' plus the guarded-vs-full mode confirmation behavior. However, it never explicitly states when to prefer this over exp_validate or exp_save, nor routes the agent to exp_abort/exp_status for follow-up. Adequate but not directive.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context beyond that: no pagination behavior for last_n, no defaulting semantics, no scoping or ordering. It contributes essentially nothing beyond the annotations.

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?

Terse to the point of under-specification: a single sentence fragment with no verb. It is short but not because every element earned its place – it omits the core action while listing fields that the existing output schema already covers.

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?

An output schema exists, so return values need not be re-explained, yet the description spends its only line enumerating them. For a required-name query tool with weak usage and parameter coverage, the description is inadequate on the dimensions that matter.

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 0% and the description does not mention either parameter. The 'name' (required) identifier and 'last_n' (default 100) window are entirely unexplained in prose; the listed tokens are output fields, not parameters, so they provide no compensating meaning.

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 'Run records: level, status, measures, recording ids, duration, error' essentially restates the tool name and enumerates fields rather than stating what the tool does. There is no verb or action ('list', 'retrieve runs for an experiment'), and no differentiation from siblings like exp_list or exp_get. It reads as a tautological field list.

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?

No when-to-use guidance, no prerequisites, and no alternatives named despite many exp_* siblings (exp_list, exp_get, exp_run, exp_status). An agent must guess whether this lists, reads, or aggregates runs.

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?

Annotations establish the safety profile (not read-only, idempotent, not destructive), and the description adds real value beyond them: recorded runs for that name are preserved and resume continues from where they stopped. This behavior about existing data is not derivable from the annotations or 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 tight sentences with no padding, and the core action plus destination path are front-loaded. The resume clause is the only slightly tangential addition, but it is useful behavioral context rather than waste.

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?

An output schema exists so return values need not be described, and the key persistence/resume behavior is covered. However, the unexplained `replace` parameter and the absence of any usage routing leave gaps for a spec-writing tool.

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 0%, so the description carries the parameter burden. It clarifies that spec may be YAML or JSON, but says nothing about the `replace` boolean (default true) — whether it replaces the spec, the runs, or the directory, leaving a mutation-relevant flag undefined.

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 gives a specific verb (Save) and resource (experiment spec in YAML or JSON) plus the exact destination path <experiments_dir>/<name>/spec.yaml. It is clearly distinguishable from read/run siblings, though it does not name an alternative tool explicitly.

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?

Usage is implied by the save/resume framing but there is no explicit when-to-use vs alternatives guidance (e.g. vs exp_template, exp_validate, or exp_run). The resume note hints at context but the agent must infer the selection conditions.

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?

The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. Beyond that, the description discloses the live-versus-persisted behavior depending on session age, which is non-obvious context an agent could not get from the schema or annotations.

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, no waste, and the primary behaviour (live state of a running experiment) is front-loaded before the earlier-session caveat. Every clause carries information.

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 status tool with annotations covering safety and an output schema covering return shape, the description supplies the remaining essentials: what state is reported and how older experiments behave. Only the parameter's identity is left unaddressed.

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 0% and the only parameter is a bare 'name' string with no explanation in either schema or description. With a single parameter the ambiguity is limited, but the description contributes nothing about what name identifies (experiment vs run), so it fails to compensate for the coverage gap.

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 resource (experiment) and what is returned: the live state of a running experiment, enumerated as planned/done/failed, level, ETA, last error, recording ids. This clearly separates it from exp_list and exp_get in intent, though it never names a sibling to sharpen the boundary.

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 draws a useful internal distinction between a currently running experiment (live state) and one from an earlier session (persisted status), which is genuine usage guidance. However it never routes the agent to alternatives such as exp_get or exp_runs, so the choice among experiment tools is left to inference.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safe-read profile is covered structurally. The description adds content context by enumerating what the template contains (factors, levels, runs, preconditions, measures, metrics, criteria, writes_allowed), which is useful but does not disclose behavioral traits like whether the returned spec is meant to be edited in place or re-saved.

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?

One front-loaded sentence states the resource and then enumerates its contents; the enumeration is dense but each item earns its place by telling the agent what the template will include. Slightly run-on but not padded.

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?

An output schema exists, so return values need no explanation, and the tool is a simple one-parameter template provider. The description covers the template's content scope, leaving only the minor gap of not confirming how the template is consumed relative to siblings.

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 0%, so the description must carry the burden for the single 'kind' parameter. It partially compensates by naming 'kind: dosing_fill', but it only echoes the schema's default value and never explains what the parameter controls or what other kinds exist.

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 provides a complete example experiment spec for editing, which is a clear resource, but it uses a noun phrase ('A complete example experiment spec to edit') rather than an action verb, leaving the agent to infer that this returns/creates a template. It also does not distinguish itself from siblings like exp_get or exp_list, so the agent cannot tell from the description alone why it would pick the template over an actual experiment spec.

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?

There is no explicit when-to-use or when-not-to-use guidance, and no alternatives are named. The agent must infer that this is the starting point before building a real spec, but nothing in the text states that context.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds substantive context: it discloses that it inspects the server guard's view of each write and performs symbol resolution against the connected PLC, which tells the agent this check depends on a live PLC connection.

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?

A single dense sentence with the verb and resource front-loaded, followed by an enumerated list of checks. No filler, though the long comma-separated list is slightly heavy to parse.

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?

With an output schema present, return values need no explanation, and annotations cover the safety profile. The description adequately covers input forms and validation scope for an agent 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?

Despite 0% schema description coverage, the description compensates well by explaining that 'spec' can be YAML/JSON text, a dict, or a saved experiment by name, and by noting symbol resolution on the PLC (the resolve_symbols toggle). Only resolve_symbols' exact semantics remain implicit.

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 (Validate) and resource (spec), then enumerates exactly what is checked: structure, measures, metrics, criteria, write guards, symbol resolution, run count, duration. This clearly distinguishes it from siblings like exp_run and exp_evaluate.

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 verb 'validate' implies a pre-run check and the enumerated checks reinforce that context, but the description never explicitly says when to use this versus exp_run or exp_evaluate, nor does it name any alternative. Usage is implied rather than stated.

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?

Annotations already establish read-only, non-destructive behavior. The description adds useful behavioral context by disclosing that matching uses fnmatch on the symbol path. It does not mention limit or pagination behavior, but a 3 is appropriate with safety already covered.

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?

A single front-loaded sentence with no wasted words. It is appropriately terse for a lookup tool.

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?

An output schema exists and annotations cover safety, so return values need not be explained. However, for a three-parameter tool with 0% schema description coverage, the description is inadequate and provides no routing among many HMI/project siblings.

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 0% for all three parameters. The description hints that pattern uses fnmatch against the symbol path, but leaves kind and limit completely undocumented, so it only partially compensates for the schema gap.

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 resource (HMI files/controls) and relation (bind a PLC symbol), making the query identifiable. However, it does not distinguish itself from HMI siblings such as hmi_scan or hmi_vs_runtime.

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?

No explicit when-to-use guidance, prerequisites, or alternatives are provided. The interrogative phrasing implies you use it to find bindings, but there are no conditions or 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine context beyond that: the file scope it walks and the root resolution fallback (project.hmi_root, else project root). It says nothing about cost, scale, or whether an index artifact is persisted, which matters for a tool named 'scan/index'.

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 tight sentences, what-it-does first, default behavior second — nothing superfluous. The embedded glob notation (%s%PLC1.X%/s%) is telegraphic and slightly opaque, but it is compact rather than padded.

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?

With an output schema present, return values need not be described, and the one parameter is fully covered. The remaining gap is routing: nothing explains how this scan relates to hmi_bindings/hmi_vs_runtime, so an agent choosing among HMI tools is under-informed.

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 0% — the single 'root' parameter is only typed as string|null with default null. The description compensates well by explaining that root falls back to project.hmi_root and then to the project root, which the schema does not capture at all.

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+resource: 'Index HMI symbol bindings', and enumerates the exact file families it covers (TE2000 .view/.content/.usercontrol/.json and TcVIS). It does not, however, distinguish itself from close siblings like hmi_bindings or hmi_vs_runtime, so an agent must infer which one to pick.

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?

There is no explicit when-to-use or when-not-to-use guidance, and no routing to the obvious sibling tools (hmi_bindings, hmi_vs_runtime). The only usage-adjacent information is the root default fallback, which is parameter behavior rather than invocation 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: it discloses exactly what categories of mismatch are reported (broken bindings vs orphan declared variables) and that check_source extends the analysis to source declarations. It stops short of describing output shape, but an output schema exists.

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?

A single sentence, front-loaded with the key concept ('Broken HMI bindings'), with no filler. The parenthetical and comma-plus clause make it dense and slightly awkward to parse, but the compactness is appropriate and every clause carries information.

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?

An output schema exists, so return values need not be explained, and the safety profile is in annotations. What's missing is disambiguation from the many HMI/PLC-comparison siblings and any guidance on preconditions or scope, leaving the definition adequate but with clear gaps for a heavily populated sibling set.

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 0%, so the description must carry the burden for the single boolean parameter. The parenthetical '(and, with check_source, whether the source declares them)' gives a partial semantics hint for check_source, but it doesn't clarify the default-on behavior or the cost/tradeoff of enabling it. Partial compensation only.

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 diagnostic purpose: identifying HMI-bound symbols that don't exist on the running PLC plus declared variables with no HMI. It is concrete about what it reports. However, it does not distinguish itself from close siblings like hmi_bindings, hmi_scan, or proj_vs_runtime, leaving the agent to guess which to use.

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?

There is no when-to-use guidance and no alternative tool is named or excluded. The only usage hint is the parenthetical describing what check_source adds, which is a parameter note rather than usage context. An agent cannot tell from this description when to prefer this over hmi_bindings.

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?

Annotations already cover the read-only, non-destructive safety profile, so the description adds value by disclosing the sitemap download on first call (a few MB), the 7-day cache, and the TwinCAT 2 exclusion. These are genuine operational traits beyond the annotations.

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?

Compact and front-loaded: the core action leads, filters follow, and the caching note closes. It is dense but each clause carries information, with only minor run-on phrasing.

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?

With an output schema present, return values need no explanation. The description covers filtering, exclusions, and first-call cost/caching, leaving only the 'limit' parameter under-described.

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 0%, so the description must compensate. It documents 'pattern' as a glob on the slug with concrete examples and enumerates all valid 'category' values, covering two of three params well; 'limit' is left undocumented, so it does not fully close the gap.

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 and resource: 'List Infosys books (documentation sets) from the site's own sitemap,' and adds what is returned (page counts, indexed-locally status). It is clearly a discovery/listing tool, though it does not explicitly name how it differs from siblings like infosys_index or infosys_search.

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?

Usage is implied—this is the listing/enumeration entry point—and it discloses the exclusion ('TwinCAT 2 books are excluded') plus filter semantics. However, it never explicitly says when to use this versus infosys_index or infosys_search, leaving the routing to inference.

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?

Annotations already declare readOnlyHint=true/destructiveHint=false, so the safety profile is covered. The description adds useful context about what data the read yields (full ST declaration, page URL), but discloses nothing further about pagination, resolution failures, or lookup scope.

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, front-loaded with the returned payload and ending with the strongest routing cue. There is mild verbosity in the field enumeration, but no wasted framing.

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?

An output schema exists, so the description needn't explain return values (it does anyway, harmlessly). Safety is covered by annotations. The remaining gap is the undocumented parameters, which keeps this from being fully 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 0% and neither parameter is documented in the schema. The description only obliquely implies that 'symbol' is a library symbol; the optional 'library' parameter is entirely unexplained, so an agent must guess its meaning and format.

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 resource (a library symbol's declaration) and enumerates what it returns (kind, inputs/outputs, struct members, enum values, EXTENDS/IMPLEMENTS, ST text, URL). It's much clearer than a generic search tool, though it doesn't explicitly name which sibling (e.g. infosys_search_symbols) it should be preferred over.

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 thing to call before writing code against an FB you have not used before" gives an implied when-to-use. However, it names no alternatives and no exclusion conditions versus infosys_search_symbols, infosys_search, or infosys_get_page, which are the likely competing tools.

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?

Annotations already declare the read-only, non-destructive profile, so the burden is lower. The description adds real behavior: fetched live, cached, refresh=true bypasses the cache, and coverage extends beyond the index. It stops short of noting truncation 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?

Compact and front-loaded: output format first, then accepted ref forms, then caching/refresh. Every sentence carries information, though the packed parenthetical and inline ref examples make it slightly dense.

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?

An output schema exists, so return values need no explanation. The description covers the input formats, cache behavior, and coverage scope adequately for a fetch tool; the only gap is the undocumented max_chars truncation control.

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 0%, so the description must carry parameters. It thoroughly documents the many accepted forms of 'ref' (URL, book/pageid, bare id, symbol name) and explains refresh=true. However max_chars is never addressed, leaving one of three parameters undocumented in both schema and description.

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?

Clear verb+resource: returns a documentation page as Markdown, with a note that it works for any page 'indexed or not'. This implicitly distinguishes it from the infosys_search/index siblings, but it never names them, so differentiation requires inference.

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?

Usage is implied (fetch a specific doc page) and the 'works for any page... indexed or not' clause hints you can go direct rather than search. However there is no explicit when-to-use or when-not, and no sibling is named as the alternative.

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?

Adds substantial context beyond annotations: incremental fetching (only new/changed pages via sitemap lastmod), what is extracted (title/kind/library/declaration), and a concrete cost estimate (300 pages ≈ 30-60 s). One minor tension: it writes to a local cache while readOnlyHint=true, though cache population is idempotent and non-destructive so it does not rise to a true contradiction.

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, verb-first, no filler. The example glob, timing estimate, and prerequisite each earn their place and are ordered by usefulness.

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?

An output schema exists so return values need not be explained, and the prerequisite/enablement story is complete. The gap is the undocumented force/max_pages parameters, which an agent cannot disambiguate from the description.

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 0% and there are 3 params, so the description must compensate. It explains 'book' well (including glob syntax), but 'force' and 'max_pages' are left entirely undocumented in both schema and description, leaving two of three parameters ambiguous.

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+resource ('Index a book (or glob of books)') with a concrete example glob ('tcplclib_tc3_*') and names the target (the local cache). An agent immediately knows this builds a searchable index and can distinguish it from the infosys_* search siblings.

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 states the prerequisite: 'Needed before infosys_search_symbols/search_code can see a library' and the fallback behavior ('infosys_search falls back to the web'). This names the dependent siblings and the when-to-use condition precisely.

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 readOnlyHint and destructiveHint already covering safety, the description adds substantial non-obvious behavior: FTS5 bm25 ranking, [hits] excerpt format, DuckDuckGo fallback verified against the Infosys sitemap (TwinCAT 3 only), title/excerpt fetching, and a backend field indicating which path answered.

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 dense but front-loaded sentences with no wasted prose. The second sentence is long and packs several fallback details, but each detail is relevant.

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?

The output schema covers return values and annotations cover the safety profile. But with 0% parameter coverage and no sibling differentiation, key invocation details such as library filtering, web_fallback semantics, and limit behavior remain undocumented.

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 0%, and the description documents none of the four parameters. An agent must infer the meaning of query, limit, library, and web_fallback from bare schema titles and defaults.

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 and resource: 'Full-text search over the indexed Infosys pages.' It also describes the fallback path. However, it does not explicitly distinguish this from siblings like infosys_search_code or infosys_search_symbols.

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?

Mentions automatic fallback when the local index is empty, but gives no guidance on when to choose this tool over sibling search tools. It also does not explain when to use the web_fallback or library parameters.

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