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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description goes beyond by explicitly guaranteeing read-only behavior (only handshake and minimal read frames, no writes), reveals optional deep verification, and explains that identification does not guarantee access. This adds significant behavioral context beyond 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?

Description is detailed and front-loaded with purpose, but it is lengthy with multiple clauses. It covers essential details without excessive fluff, but could be more compact. Structure is logical: purpose, flow, assurances, return format.

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's complexity and output schema exists, the description covers main workflow, parameter semantics, and return behavior. It doesn't detail edge cases like host unreachable or all ports closed, but is adequate for an agent to invoke 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 explain parameters. It explains deep (default true, performs minimal read verification), ports (default list of candidate ports, null likely means use defaults), timeout_ms (per-probe budget, default 0.8s), and host (target device). This adds meaning beyond the schema for all parameters.

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 action: auto-scan ports and identify protocol for a given host. The description distinguishes it from siblings like probe_device by clarifying it is read-only and focused on identification, not probing. However, the exact protocol detection scope is implicit but clear 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?

Provides detailed workflow and default ports, and clarifies the tool is for identification, not full access verification. It mentions that if S7 PUT/GET is closed, read may fail, implying use for reconnaissance. Does not explicitly state when to use alternatives like probe_device or plc_read, but context is fairly clear.

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

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

Annotations already cover read-only, idempotent, open-world, non-destructive. The description goes beyond annotations by disclosing that it uses deterministic rules ('不编故事'), performs a live probe when host+port is used, automatically extracts hex frames from log_snippet, and returns empty candidates rather than forcing a conclusion when the knowledge base doesn't cover the case. These are important behavioral traits that an agent needs to know. No contradiction with 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?

The description is front-loaded with the core purpose, then structured as a bulleted list of evidence sources and output details. Every sentence earns its place, and the formatting makes the options and constraints easily scannable. It is not overly verbose despite including substantial behavior and return 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?

Given the tool's complexity (6 params, multiple evidence modes, output schema), the description is largely complete. It explains the output structure and the meaning of empty candidates. The main gaps are the lack of explanation for the required protocol parameter, no guidance on when to use this vs. sibling tools, and no mention of any network/access requirements for the host+port probing mode. These are notable but not fatal, so a 4 is appropriate.

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 the semantics of frame_hex, log_snippet, and host+port as evidence types, including how they are processed. However, it does not mention the required protocol parameter or the unit parameter at all, leaving an agent to guess what values are expected. Thus it adds meaning to half the parameters but fails to clarify critical required inputs.

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 clearly states the tool's purpose: to produce structured fault candidate conclusions from observations. It specifies the resource (observations) and the output (DiagnosticReport with candidates), and distinguishes its reasoning behavior (deterministic rules, no fabrication) from simpler parse/validate tools. However, it does not explicitly name sibling tools or state when this tool is preferred over them, so it lacks explicit sibling differentiation.

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 the use case: when you have at least one evidence source (frame_hex, log_snippet, host+port) and want a diagnostic conclusion, you can call this tool. It lists acceptable evidence combinations and the condition 'at least one'. But it does not name alternatives like validate_frame or parse_frame, nor does it specify when not to use this tool, so usage guidance is only implied, not 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?

The description significantly enriches the annotations by disclosing the ring-buffer hard cap of 1000 entries, automatic truncation when limit exceeds buffer size, and empty result when limit<=0. These are meaningful behavioral constraints beyond the readOnlyHint/idempotentHint annotations, with no 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?

Two dense sentences that front-load the purpose and then add the critical limiting behavior. There is no filler or repetition; every clause adds useful 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?

Given the output schema exists and annotations indicate a safe read-only, idempotent operation, the description covers purpose, usage context, and key behavioral edge cases. It lacks only minor context such as requiring an already-started listener, which is inferable from sibling tools like start_listener.

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 'limit' behavior well (latest N, truncation, <=0 means empty), but does not clarify what 'port' refers to beyond the implied listener context. This is partial compensation, not complete.

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?

Description uses a specific verb ('取/get') and resource ('监听收下的帧' / listener frames), and names the returned fields (direction/peer/frame_hex). It also states the downstream purpose (供 parse_frame/diagnose 分析), which helps an agent distinguish it from sibling tools like get_proxy_frames.

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

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

The description clearly implies when to use the tool: after capturing listener frames and before parse_frame/diagnose analysis. However, it does not explicitly mention alternatives like get_proxy_frames or state when not to use this tool, so it stops short of full exclusion guidance.

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

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

Beyond the read-only/idempotent annotations, the description discloses meaningful behavior: the ring buffer hard cap of 1000, automatic truncation of limit, and empty result for limit<=0. These are concrete runtime behaviors that annotations do not convey.

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

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

The description is compact and every sentence carries useful information: the data source, direction meaning, and limit/buffer semantics. No filler or repetition of schema types.

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 description covers limit and buffer semantics wellwing and an output schema exists, so return structure is likely handled elsewhere. But the required port parameter is undocumented, and there is no statement about ordering or behavior when no frames have been recorded. These are modest gaps for an otherwise simple read 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?

With 0% schema description coverage, the description must compensate, and it does for limit: latest N frames, truncation at buffer cap, non-positive returns empty. However, the required port parameter is left entirely unexplained in both schema and description, which is a notable 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 states a specific action and resource: fetch proxy-recorded bidirectional passthrough frames, with direction conventions c2s and s2c. It is clearly distinguishable from sibling get_listener_frames by the explicit 'proxy-recorded' scope, though it does not name that alternative 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?

The tool's context is implied: it is for reading frames captured by the proxy, after proxy operation. However, it gives no explicit guidance on when to prefer this over get_listener_frames or other sibling tools, and no when-not-to-use 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safe read-only behavior is covered. The description adds useful behavioral context: it returns capability details per protocol and is meant to let the agent infer the correct protocol without asking the user. No contradiction with 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?

Three short sentences: purpose, output content, and usage guidance. Every sentence earns its place and the key call-decision rule is front-loaded near the end without excess wording.

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 zero parameters, comprehensive annotations, and an output schema present, the description fully covers why and when to call the tool as well as what it returns. Nothing needed for correct invocation is missing.

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 has zero parameters and the schema is complete, so the description has no parameter burden. Baseline 4 applies; the description instead enriches understanding of the output, which is appropriate for a no-argument discovery tool.

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

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

The description states a specific action and resource: '列出本 server 支持的工业协议及其能力' (list the protocols supported by this server and their capabilities). It further specifies what is returned per protocol (port hints, address model, data types, brand clues), making the tool's purpose concrete and distinct from siblings like detect_device.

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

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

The description gives explicit routing guidance: call this tool when the protocol name is uncertain, and call detect_device when the protocol/port is uncertain. This directly tells the agent when to use this tool versus an 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it states that malformed frames are parsed best-effort and errors are reported as diagnostic evidence, that direction auto-detection follows protocol-specific heuristics, and that explicit direction overrides auto-detection. It does not describe output structure in detail, but an output schema exists, so that burden is reduced. Minor gap: no mention of rate limits or large-frame handling, but not essential for a read-only parser.

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

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

The description is dense but well-structured: a one-sentence summary, then a paragraph on error behavior, then a bulleted list of protocol-specific direction rules. Every sentence earns its place, and the most important scoping info (no device connection, structured parsing) is front-loaded. It is longer than the typical description, but the length is justified by the protocol-specific rules that are essential for correct invocation. Slight deduction for density that may require careful reading.

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's complexity (4 protocols, direction auto-detection, malformed-frame handling) and the presence of an output schema, the description is complete. It covers what the tool does, when to use it, how parameters behave, and what happens on malformed input. The output schema handles return-value documentation. An agent has everything needed to select and invoke this tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It does: it explains the direction parameter's 'auto' default and explicit 'req'/'resp' values, and it explains frame_format's allowed values ('3e_binary'/'3e_ascii'/'4e_binary'/'4e_ascii') and that it only applies to melsec. It does not explain protocol or frame_hex in detail, but those are self-evident from the tool name and description. The description adds meaning beyond the bare schema, though it could have explicitly listed protocol values.

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

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

The description opens with a specific verb and resource: '把一帧报文 hex 逐字段结构化解析' (parse a frame's hex into structured fields per field), and immediately distinguishes itself from device interaction by noting '不需要连接设备' (no device connection needed). It clearly differentiates from siblings like validate_frame (which validates) and parse_pcap (which parses captures), and the protocol-specific direction rules further clarify its scope.

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

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

The description provides explicit when-to-use guidance: it handles normal request/response frames and abnormal response frames, and it explicitly states that malformed frames do not throw but are parsed best-effort with errors reported. It also gives detailed protocol-specific direction auto-detection rules for modbus, fins, melsec, and s7, and notes that frame_format only applies to melsec. This is far beyond minimal usage 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial behavior beyond them: the optional scapy dependency with install command, the 64KB token-budget truncation rule, the 'truncated:' sentinel flow format with total/shown counts, partial-frame handling, and protocol auto-detection when the parameter is omitted. No contradiction with 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?

The core pipeline is front-loaded, then the description flows logically through output structure, parameter default, dependency, and truncation behavior. Every sentence carries distinct information; the length is justified by the tool's genuine complexity around truncation, sentinel flows, and dependencies.

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?

Covers the essential operational context: dependency requirements, truncation budget, sentinel flow shape, auto-detection default, and efficiency characteristics. Since an output schema exists, return-value structure is already handled elsewhere. Minor gaps: no explicit error conditions for invalid paths or malformed pcaps, and the path parameter format is not stated.

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 protocol's semantics well — auto-detect by the protocol with the most complete frames when omitted, and use it as a filter to retrieve remaining frames — but path is only implied by the phrase 'Wireshark 导出 pcap' rather than explicitly documented as the pcap file path to read.

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 — parse Wireshark-exported pcap — and details a distinct three-stage pipeline: aggregate by TCP flow, split by protocol, then parse_auto per frame. The batch/flow-aggregation scope clearly differentiates it from single-frame siblings like parse_frame, and the explicit efficiency comparison against per-frame frame_hex reinforces that 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?

Provides clear context: suited for Wireshark-exported pcap files and large batch scenarios where it is 'much more efficient' than parsing frame by frame, plus a concrete follow-up strategy ('use protocol= to filter or split the pcap to re-parse') when frames are missing. It does not explicitly name alternative sibling tools or state when not to use it, but the implied usage scope is largely sufficient.

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 description adds behavioral details beyond the annotations: it explains the return structure ({node, children, total, shown, truncated}), the output budget (max 200 children, ~30KB), truncation behavior, default starting node, and the need to call again with a child node_id for deeper levels. It also notes the protocol limitation. No contradiction with the readOnlyHint.

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, dense paragraph that front-loads the core function and return format. It is efficient, but slightly long; however, every sentence adds value, covering purpose, usage, and behavioral constraints.

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 description covers the essential aspects: return structure, truncation behavior, default node, usage context, protocol limitation, and output budget. The output schema likely defines the return format, so the description focuses on behavior. It could detail more parameters, but overall it is complete enough for the tool's scope.

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 explains the 'node' parameter (default ns=0;i=85) and 'limit' (output budget of 200), and implies 'protocol' by restricting to OPC UA. However, it does not describe host, port, unit, or timeout_ms, leaving these to be inferred from context.

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 clearly states the tool's purpose: browse the address space by expanding one level of child nodes from a given node, framed as a 'list directory' for diagnostics. It differentiates from siblings like plc_read (reading values) and list_protocols (listing protocols) by specifying when to use it and what it returns.

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 explicitly says to use this before plc_read to understand the address space structure, and notes that it only supports OPC UA, directing users of other protocols to use list_protocols' read_options instead. This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already mark readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, and the description adds protocol-specific behavior such as S7 count being byte-based, OPC UA returning native values, and datatype None returning multiple interpretations. This meaningfully supplements the annotation safety profile without contradicting it.

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

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

The description is dense but well-organized, with protocol-specific semantics in a scannable bullet-like layout. Every sentence carries useful operational information, and the most critical parameter behavior is front-loaded before lower-level detail. No word is wasted.

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's complexity—10 parameters, 6 protocols, protocol-dependent semantics—and the absence of schema descriptions, the description is remarkably complete for tool selection and correct invocation. It covers protocol semantics, datatype behavior, byteorder effects, and options, while an output schema exists to cover return-value structure. Nothing essential for calling this tool correctly is missing.

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 full responsibility for parameters. It provides detailed semantics for address/count across six protocols, explains datatype choices including the None fallback, clarifies byteorder's effect on float32 pairs, and points to list_protocols for options. This thoroughly compensates for the lack of schema-level 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?

State a specific verb and resource: read data areas from a PLC and interpret values by datatype. The protocol-specific address/count semantics make its scope concrete and distinguish it from sibling tools like plc_browse or probe_device. The title and name align cleanly with the described behavior.

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

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

The description gives clear operational guidance for when this tool is appropriate across different PLC protocols, and explicitly instructs agents to consult list_protocols for adapter-specific read_options. It does not explicitly name alternatives for non-read tasks, but the protocol coverage makes invocation conditions unambiguous.

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 and idempotentHint=true already covering safety, the description adds valuable behavioral semantics: reachable is defined as TCP established and includes exception responses, and each failure_class value is tied to a likely cause. This goes well beyond the annotations and gives the agent a mental model of expected outcomes.

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

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

The description is front-loaded with the core purpose, then organized as a compact taxonomy of failure_class values, and ends with a typical-use directive. Each line earns its place, and the structured list makes the behavior easy to scan.

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 output schema exists and annotations cover side effects, the description is nearly complete for invoking the tool. It still leaves protocol/host/port/unit semantics to inference and doesn't mention the relationship to detect_device, so slightly more context would make it 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 compensate. It implicitly explains port (via connection_refused), protocol (via connected_but_no_reply), and unit (via exception_response), but it never formally defines the parameters or their allowed values/relationships. This is adequate for a PLC-expert agent but leaves gaps for less obvious parameters like protocol 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?

The description states a specific purpose: test whether a PLC connection and communication are possible, with failure_class attribution on failure. It is clear about the resource and behavior, but it does not explicitly contrast with the similar-sounding sibling detect_device, so sibling differentiation is only implicit.

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

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

The description gives a clear trigger: when the device 'cannot read data', call this tool first for layer-by-layer diagnosis. It does not spell out when not to use it or name alternative tools such as detect_device or diagnose, so it falls short of the strongest 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?

The description is highly transparent about side effects beyond what annotations declare. It discloses that this is a stateful operation (consistent with readOnlyHint=false), that respond_normal minimally responds with constant-zero data, that inject_errors applies deterministic faults, and — critically — that starting this listener may alter the device under test and requires restoration to original config afterward. This cleanup warning goes well beyond the annotations and gives the agent an accurate mental model of consequences.

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

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

The description is dense but well-organized: purpose first, then mode semantics, then fault injection rules, then the companion-tool workflow, then cleanup guidance. Every sentence carries meaningful operational information — no filler. It is on the longer side, but for a 6-parameter multi-mode tool with zero schema descriptions, that length is justified.

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

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

For a complex tool (6 params, 0% schema coverage, multi-mode, protocol-specific fault lists), the description is nearly complete. It covers the purpose, all modes, fault options, port behavior, the companion tool chain, and the required cleanup. The only omissions are host and idle_timeout_sec semantics, which the agent would have to infer or guess. Given the output schema exists (not shown), the return contract is at least partially specified elsewhere.

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?

With 0% schema description coverage, the description carries the full burden, and it largely succeeds. It fully documents mode (all three values with behavior), faults (protocol-specific options: modbus exception/bad_length/truncate, fins/melsec end_code/bad_length, universal garbage), and port=0 system-assignment semantics. Protocol is implied via the fault options. However, host and idle_timeout_sec are left entirely unexplained — a real gap given no schema descriptions 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 opens with a specific verb and resource — starting a fake server (listener) to fish out frame behavior from a device that can only act as a client. It names the exact trigger condition (待测设备只能当 client) and the mechanism (立假 server), which clearly distinguishes it from sibling tools like start_proxy and get_listener_frames. The purpose is unambiguous and actionable.

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

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

The description gives explicit when-to-use context (device is client-only) and lays out a complete workflow: start the listener, collect frames via get_listener_frames, feed them to parse_frame/diagnose, then stop_listener and restore device config. It also sets expectations by noting respond_normal is not a general-purpose simulator. It does not explicitly contrast with start_proxy as an alternative, which is a minor gap given that sibling exists.

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 indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the description doesn't need to restate those. It adds valuable behavioral context: the proxy is a diagnostic facility that only forwards and records frames, never rewrites them; listen_port=0 means the system assigns a port; and protocol support is limited to modbus/fins/melsec. This goes beyond the annotations and helps the agent understand side effects and constraints.

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

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

The description is compact and front-loaded: the first sentence states the core function, the second gives the use case and workflow, and the third covers constraints and special values. Every sentence earns its place, and the structure makes it easy for an agent to quickly understand what the tool does and when to use it.

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's complexity (6 params, no schema descriptions, output schema present), the description covers the essential context: purpose, use case, protocol limitations, and the diagnostic-only guarantee. It doesn't explain idle_timeout_sec or the output schema, but the output schema exists and the parameter names are reasonably self-explanatory. The description is complete enough for an agent to select and invoke the tool correctly in most cases.

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 the meaning of protocol (supported values: modbus/fins/melsec), listen_port=0 (system-assigned), and the overall role of target_host/target_port (the real PLC address). It doesn't explain idle_timeout_sec or listen_host, but the parameter names are fairly self-explanatory and the description covers the most critical semantics.

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 ('起透明代理'), the resource (上位机 → 代理 → 真实 PLC), and the core behavior (透传同时按协议分帧录制双向帧). It clearly distinguishes this from sibling tools like start_listener and get_proxy_frames by explaining the transparent proxy role and recording function.

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 explicitly tells when to use this tool: during on-site debugging, point the upper computer at this proxy instead of the real PLC, and you can capture all interaction frames without Wireshark. It also names the workflow: use get_proxy_frames to retrieve frames, then feed them to parse_frame/diagnose. It even states a limitation (S7 TPKT framing not supported), which helps the agent decide when not to use it.

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

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

Annotations already indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description adds that the operation returns receive/transmit frame statistics, which is useful, but it does not disclose behavior when no listener exists on the port or whether buffered frames are cleared.

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 one compact sentence that leads with the action and immediately states the return value. There is no filler or redundancy.

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

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

For a tool with a single required integer parameter and an output schema, the description covers the core action and return behavior. Minor gaps remain around prerequisites and failure cases, but overall the context is sufficient for straightforward use.

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 for the port parameter. It only repeats the notion of a 'specified port' without adding range, format, default, or semantic details beyond the property name 'port'.

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 ('停掉' / stop) and a concrete resource ('指定端口的监听' / the listener on a specified port), and it adds an observable outcome (receive/transmit frame statistics). This separates it clearly from sibling tools like start_listener and get_listener_frames.

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 wording implies the tool is meant to stop a listener that was previously started for a port, but it never explicitly states when to use it or when to prefer a sibling like stop_proxy. No alternative guidance is provided.

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 signal that this is a mutating, non-idempotent, non-destructive action. The description adds the return behavior (recording stats with c2s/s2c frame counts) beyond the annotations, but it does not disclose side effects such as whether in-flight traffic is dropped, whether recording is preserved, or what happens if the port has no active proxy.

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 compact sentence with no filler. The action and return value are front-loaded, and the format is appropriate for a simple one-parameter 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?

Given the tool's low complexity, the description plus annotations and output-schema presence largely cover what an agent needs to invoke it: supply a port and expect recording statistics. The main gap is usage guidance, but that is already accounted for in the usage_guidelines dimension.

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?

With 0% schema description coverage, the description carries the burden for the port parameter. The phrase '指定端口的代理' does clarify that the port identifies which proxy to stop, which is the key semantic relationship. However, it does not explain what the port represents precisely, valid ranges, or error conditions for invalid ports.

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 action: '停掉指定端口的代理' (stop the proxy on the specified port), naming both the verb and the resource. It also states what the tool returns, which further disambiguates it from siblings like start_proxy and stop_listener.

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 about when to use this tool instead of related siblings such as stop_listener or start_proxy. It also does not mention prerequisites, such as whether the proxy must already be running, or any conditions under which this tool should not be used.

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 readOnly, idempotent, and non-destructive. The description adds behavioral detail: it supports exactly three protocols, runs a checklist per protocol, and clarifies the direction parameter. It also notes a Modbus TCP nuance (no CRC, unlike RTU). This goes beyond the annotations without contradicting them.

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 compact paragraph that front-loads the core purpose, then organizes protocol-specific checks in a list-like format. It is efficient, though slightly dense with technical terms. No wasted words, but could be more scannable with bullet points.

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's complexity (multiple protocols and many validation items) and zero schema coverage, the description is reasonably complete for its core function. However, it omits details on frame_hex formatting and frame_format options, and does not describe the output structure (though an output schema exists). The protocol-specific check lists are thorough, but the parameter gaps lower completeness.

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 all parameters. It clarifies 'direction' (req or resp) and implicitly defines 'protocol' by listing supported protocols, but it does not explain 'frame_hex' format (e.g., with/without separators) nor 'frame_format' beyond the default '3e_binary'. This is a significant gap given zero schema help.

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 clearly states the tool validates a frame against a specification checklist, producing pass/fail per item. It names the specific protocol checks (Modbus TCP, FINS/TCP, MELSEC 3E) and explicitly notes it requires no device connection, distinguishing it from sibling tools like parse_frame (which would decode) and probe_device (which requires a device).

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 usage context by stating 'no need to connect device' and by listing the protocols it handles, but it does not explicitly say when to use this tool versus parse_frame or get_proxy_frames. It gives context (offline validation) but lacks explicit exclusions or alternative routing.

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