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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states the read-only guarantee, that only handshake and minimal read frames are sent, that no data is written, and that recognition does not imply accessibility. It also details the deep verification behavior and default timing budgets, going well beyond what the schema or annotations could 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 dense and well-structured, with a clear flow from scanning to probing to verification, followed by the read-only guarantee and return semantics. Every sentence contributes useful information, though the length is considerable and could be streamlined for faster consumption.

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, the description is highly complete. It covers input semantics, defaults, operational steps, safety guarantees, output ordering, and inter-tool handoffs (e.g., 'next_step' for 'plc_read', 'unknown_services' for 'start_listener'). The presence of an output schema further reduces the need to document return values, making this definition sufficient for an agent to use the tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the 'deep' parameter's effect (verification read or skip), 'timeout_ms' as a per-protocol budget (timeout_ms/1000 seconds, default 0.8s), 'ports' with a default candidate list, and 'host' as the target. This adds meaningful semantic context and defaults beyond the raw schema types.

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 verb and resource: given a host, it scans ports and determines the protocol ('设备自动识别: 给定 host 自动扫端口并判定协议'). It also describes the output structure and downstream uses. However, it does not explicitly differentiate itself from the sibling tool 'probe_device', which appears semantically similar.

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 operational flow and default behaviors, but it does not specify when to use this tool versus alternatives like 'probe_device' or 'plc_read'. There is no explicit 'when to use' or 'when not to use' guidance, leaving the agent to infer the appropriate invocation 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?

With no annotations provided, the description carries the full burden and does an excellent job: it discloses deterministic rule-based behavior, no fabrication, automatic frame extraction from logs, network probing from host+port, sorted candidates, preservation of raw observations, and empty candidates when the knowledge base does not cover the case. This is substantial behavioral disclosure beyond the bare tool name.

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, uses a bullet list for evidence modes, and every sentence carries information. It is dense but not bloated, with no filler.

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

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

For a tool with no annotations and 0% schema coverage, it covers the essential input modes, output contract, and behavior meaningfully, and the presence of an output schema reduces the need to describe return fields. The main missing piece is the required protocol/unit semantics and an explicit pointer to list_protocols or a list of supported values.

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

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

The description adds useful semantics for frame_hex, log_snippet, host, and port, including parse/checksum, automatic frame extraction, and probing behavior. But the schema coverage is 0% and the required protocol parameter is left completely unexplained, as is unit; an agent would have to guess or look elsewhere for valid 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 clearly identifies the tool as one that maps observations to structured fault candidates and specifies the output report. The verb 'diagnose' plus resource ('故障候选结论') is concrete, but it does not explicitly differentiate from sibling tools such as parse_frame or probe_device, so it stops short of full 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?

It gives explicit input constraints: any combination of frame_hex, log_snippet, or host+port, with at least one required. However, it never states when to choose diagnose over the sibling parsing/probing/listening tools or names an alternative, so the agent must infer the intended entry point.

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

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

No annotations are provided, so the description carries the behavioral transparency burden. It discloses that the result is a set of frames with direction/peer/frame_hex and frames them as analysis input, implying a read-only fetch. However, it does not mention prerequisites such as whether the listener must already be running, nor does it state side effects or limitations.

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 sentence that front-loads the operation and includes the relevant payload fields and purpose. The phrasing is slightly awkward, but there is no wasted content.

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

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

For a simple two-parameter getter with an output schema, the description is minimally adequate: it states the resource and reason for use. Gaps remain around when to prefer get_proxy_frames, listener prerequisites, and parameter meaning, so it is not 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?

The schema has 0% description coverage and the tool description does not explain the port or limit parameters. Port is inferable from the tool name, and limit has a schema default, but the description adds no meaningful semantic detail beyond the raw schema.

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

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

The description clearly states that the tool retrieves frames received by a listener and lists the payload fields (direction/peer/frame_hex) plus the downstream consumers (parse_frame/diagnose). It is distinguishable from the sibling get_proxy_frames by the 'listener' scope, though it does not explicitly name the 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?

The description gives clear context: use this tool to obtain listener frames for later analysis by parse_frame/diagnose. It does not state when not to use it or explicitly contrast it with get_proxy_frames, but the intended use case is clear enough for basic 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?

With no annotations, the description carries the full burden of behavioral disclosure. It identifies the operation as retrieval, but does not state whether an active proxy is required, whether frames are returned from a buffer, whether the call has side effects, or what happens when no frames exist. The direction definitions add domain context but not behavioral detail.

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 that front-loads the verb and object, then clarifies direction terminology in parentheses. Every word carries meaning; there is no redundant filler, and it remains scannable.

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 an output schema exists, the description is incomplete for effective invocation. It fails to explain the port parameter's role, the behavior of limit, or the relationship to the proxy lifecycle. In the absence of annotations, key context is missing, leaving an agent to guess how to correctly use the 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 for explaining port and limit. It does not: port is entirely undefined, and limit is not explained beyond its schema default. The only parameter-related addition is the meaning of direction labels, but those are output semantics, not input parameter 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 clear verb ('取' / get) and a specific resource ('代理录制的双向透传帧' / proxy-recorded bidirectional transparent frames). It additionally defines the meaning of the direction values (c2s and s2c), making the tool's function unambiguous and distinct from the sibling get_listener_frames by explicitly anchoring it to proxy recording.

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 is given about when to use this tool versus alternatives. There is no mention of prerequisites such as an active proxy, nor an explicit contrast with get_listener_frames or start_proxy. The usage context must be inferred entirely from the tool name and resource description.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It explains what the tool returns (port hints, address model, data types, brand clues) and that it is a read-only listing operation implied by '列出'. It does not explicitly state side-effect absence, but the listing nature makes that evident.

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 four short, purposeful sentences. It front-loads the main purpose, then summarizes return content, then gives actionable usage rules. There is no filler or repetition of schema 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 parameterless tool with an output schema, the description is complete. It states what data comes back, how the agent should use it, and when to delegate to detect_device, leaving no important gap 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?

The tool has zero parameters and the schema is empty with 100% coverage, so the baseline is 4. The description correctly focuses on the output and decision context rather than parameter details that do not 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: it lists the industrial protocols supported by this server and their capabilities. It further distinguishes itself from detect_device by stating that this tool answers 'which protocol should this device use' while detect_device handles protocol/port uncertainty.

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

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

The description gives explicit usage guidance: call this tool first when the protocol name is uncertain, and call detect_device when both protocol and port are uncertain. This directly routes the agent to the right sibling tool and states when not to rely on this tool.

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

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

With no annotations provided, the description carries the full disclosure burden and does so thoroughly: no device connection, malformed frames do not throw but return errors, and each field includes byte_offset and raw_hex evidence. It also discloses per-protocol direction heuristics, giving an agent an accurate model of how the tool behaves in edge cases.

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

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

The description is front-loaded with a one-sentence summary, then extends into necessary protocol-specific rules in a structured list. It is long, but each section serves a distinct purpose; a small amount of tightening could remove minor redundancy across the protocol examples.

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 that an output schema exists and the tool handles multiple protocols, the description covers the essential behavioral and parameter context well. The main gaps are the missing explicit list of accepted protocol identifiers and frame_hex formatting details (whitespace, '0x' prefixes, case), which an agent may need to construct valid input.

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 compensates by explaining direction values ('auto', 'req', 'resp'), frame_format values ('3e_binary' etc.), and per-protocol classification logic. It does not enumerate accepted protocol values or the exact hex string format for frame_hex, but the core meaning of each parameter is well conveyed.

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 '把一帧报文 hex 逐字段结构化解析', which names the exact action (parse), resource (a single frame hex), and result (field-by-field structured output). It also states '不需要连接设备', distinguishing it from device-connecting tools. This clearly separates it from siblings like parse_pcap and validate_frame.

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

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

It provides clear context: this is an offline parser for one frame, and it explains when to override direction ('auto' vs explicit 'req'/'resp') and when frame_format applies (only melsec). It does not explicitly name sibling alternatives or say when not to use this tool, but the conditions are sufficiently implied by the scope and protocol-specific guidance.

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

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

With no annotations, the description carries the full burden and delivers: it details the processing pipeline, return of full frame sequences plus partial truncated frames as diagnostic info, automatic protocol detection, and the optional scapy dependency. This is rich behavioral disclosure beyond the structured fields.

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 opens with the core action and pipeline, then methodically covers return values, default behavior, dependency, and performance. Each sentence adds information without 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 two-parameter tool with an output schema, the description covers the processing flow, return semantics, dependencies, and parameter defaults. The only minor omission is naming the sibling parse_frame for single-frame cases, but that's not required for invoking 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?

The schema has 0% description coverage, so the description must fill the gap. It explains the protocol parameter (default auto-detection by the protocol with the most complete frames) and characterizes the path as a Wireshark pcap export. While it doesn't explicitly map each parameter name, it provides necessary context for both.

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?

Describes a specific verb+resource: parsing a Wireshark-exported pcap. The pipeline of aggregating by TCP stream, slicing by protocol, and per-frame parse_auto clearly distinguishes it from single-frame siblings like parse_frame.

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 notes the batch scenario is far more efficient than per-frame frame_hex, giving a clear when-to-use. However, it does not name an alternative for single-frame cases (e.g., parse_frame) or state when not to use this tool, so it stops short of full guidance.

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

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

With no annotations provided, the description carries the full burden and does a good job: it discloses protocol-dependent address/count semantics, the special datatype=None behavior returning an interpretations field, and the byteorder effect on float32 register pairs. It does not mention timeout/error behavior or explicitly state read-only safety, but the read verb plus return behavior covers most of the risk profile.

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 organized into scannable bullets with the main purpose front-loaded. Each bullet adds necessary information (protocol semantics, datatype behavior, byteorder, options) and the final pointer to list_protocols prevents duplication.

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 multi-protocol tool with 10 parameters and no annotations, the description covers the hard parts: protocol-specific addressing, datatype interpretation, byteorder, and where to find adapter-defined options. The existing output schema covers return shape, so its absence in prose is fine. Remaining gaps are the unexplained unit parameter and no statement about timeout/failure behavior, making it strong but not 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%, so the description must compensate. It adds substantial meaning for address, count, datatype, byteorder, and options, including concrete examples like S7 count=4 + uint16 yielding 2 values. However, unit is left unexplained despite being protocol-sensitive (e.g., Modbus slave ID), which is a noticeable gap for a 10-parameter tool with zero 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 opening line states a specific action and object: '从 PLC 读取数据区并按数据类型解释' (read data area from PLC and interpret by data type). This clearly separates it from siblings like parse_pcap, list_protocols, and proxy operations, even without naming alternatives.

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

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

The description provides clear context for when to call the tool (to read live PLC data) and instructs the agent to consult list_protocols for read_options, which is useful workflow guidance. It does not explicitly state when not to use plc_read versus probing or parsing tools, so it stops short of a 5.

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

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

With no annotations provided, the description carries the behavioral disclosure burden and does it well. It defines 'reachable', enumerates all failure_class values with their meanings and remediation hints, and explains that exception responses still count as online. It does not mention side effects or timeout details, but a probe tool's behavior is largely 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?

The description is well-structured and front-loaded: primary purpose first, then reachable definition, then failure classes with troubleshooting hints, then a typical usage scenario. Every sentence earns its place and there is no filler.

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

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

The tool has an output schema, so the return-value details do not need to be explained. The description covers the core scenario, failure taxonomy, and next-step suggestions, which is reasonably complete for a diagnostic probe. It could add more explicit parameter guidance or sibling-tool differentiation, but nothing essential is missing for calling 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 compensate for the undocumented parameters. It indirectly adds meaning to protocol and unit by referencing 'protocol config' and 'unit/register config' in the failure-class guidance, and host/port are self-evident. However, it does not document valid protocol values, unit semantics, or parameter formatting, leaving a clear 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 clearly states the tool's function: test whether a PLC can be connected to and communicated with, and provide layered attribution on failure. It is specific about the resource (PLC connectivity/communication) and the failure-class output, but it does not explicitly distinguish itself from sibling tools such as plc_read or 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 a concrete when-to-use hint: when a device reports 'cannot read data', call this tool first to locate the failing layer before deciding the next step. It does not explicitly name alternative tools or state when not to use it, so it stops short of full routing 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?

No annotations are provided, so the description carries the full behavioral burden. It discloses the three mode behaviors, that respond_normal is not a general-purpose simulator and returns constant-zero data, that inject_errors rotates deterministic faults, the protocol-specific fault options, that port=0 means OS-assigned with the actual port returned, and the recommended cleanup/restore step.

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 efficient: the core purpose is front-loaded, followed by mode semantics, fault details, workflow, and lifecycle guidance. Every sentence adds needed operational information, with 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 stateful listener with no annotations and 0% schema coverage, the description covers the core behavior, mode-specific caveats, fault options, port behavior, downstream tool usage, and cleanup. It omits explicit semantics for host and idle_timeout_sec, but an output schema exists and the included operational workflow is sufficiently complete for a capable agent.

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 for the key parameters: mode is fully explained with three enumerated behaviors, faults are explained per protocol, and port=0 semantics are clarified. However, host and idle_timeout_sec are only inferable from their names and defaults, not explicitly described.

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 scenario: start a fake-server ('phishing') listener when the device under test can only act as a client. It also distinguishes the listener from a generic simulator and orients it within the broader frame-analysis workflow, so an agent can tell it apart from start_proxy, probe_device, 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?

It clearly gives the condition for use ('when the device can only be a client'), describes the downstream pipeline (get_listener_frames → parse_frame/diagnose), and recommends stopping the listener and restoring the device config. It does not explicitly name a direct alternative for the opposite topology, but the usage context is specific enough to guide 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?

There are no annotations, so the description carries the behavioral burden. It discloses key behaviors: transparent pass-through, bidirectional frame recording, no frame rewriting, diagnostic-only purpose, and OS-assigned port when listen_port=0. It could add lifecycle details such as needing stop_proxy, but the current level of transparency is strong.

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 concise and front-loaded with the core purpose, then adds usage context, protocol constraints, and a behavioral guarantee. The text is slightly dense with wrapping, but every sentence contributes useful information without padding.

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 tool's role, supported protocols, port allocation behavior, and the intended diagnostic workflow. It does not explain all parameters or explicitly mention proxy shutdown, but the output schema and the sibling stop_proxy help fill the remaining context. Overall it is sufficiently complete 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%, so the description must compensate for undocumented parameters. It explains protocol values and listen_port=0 behavior, but does not explain target_host, target_port, listen_host, or idle_timeout_sec, leaving significant param semantics to inference.

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 function: start a transparent proxy between a host and a real PLC, forwarding frames and recording bidirectional traffic by protocol framing. It distinguishes itself from siblings by emphasizing the diagnostic role and referencing get_proxy_frames, parse_frame, and diagnose for the workflow.

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

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

The description gives explicit usage context: during on-site commissioning, point the host at this proxy instead of the PLC to capture all frames and analyze them later. It also states protocol support limits (modbus/fins/melsec, no S7 TPKT framing), though it does not explicitly contrast with alternatives like start_listener or stop_proxy.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It states the core state-changing behavior (stopping listener) and the return value (frame statistics), which is valuable. However, it does not disclose side effects, idempotency, or behavior when the port is not currently being listened on.

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 that states the action and the return result with no wasted words. Every element earns its place.

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

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

Given the tool's simple single-parameter schema and the presence of an output schema, the description is mostly complete for selecting and invoking it. It could be more complete by adding guidance about stopping behavior and side effects, but the essential calling contract is present.

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

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

The schema only provides 'port' as an integer with 0% description coverage. The description adds minimal meaning by indicating the port is the one whose listener should be stopped, but it does not specify ranges, formats, or edge conditions. For a single simple parameter this is adequate but not rich.

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 specific action: stopping listener on a specified port and returning receive/transmit frame statistics. This distinguishes it from sibling tools such as 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 description implies the tool is used when the agent needs to stop listening on a given port, but it does not explicitly state when to use this tool versus alternatives like get_listener_frames or stop_proxy. Usage context is inferable but not directly articulated.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action and that recording statistics are returned, but does not mention side effects, idempotency, whether recorded frames are preserved, or any prerequisites. For a state-changing operation this is a notable gap.

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

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

A single, front-loaded sentence that states the action and return value without any filler. Every word earns its place.

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

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

The tool is simple with one parameter, and an output schema exists so return values need not be fully detailed in the description. The core purpose and outcome are covered. Missing details like error behavior or prerequisites are minor for this level of complexity.

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

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

Schema coverage is 0% and the schema provides no description for 'port'. The description's '指定端口' clarifies that the port identifies which proxy to stop, which partially compensates, but it does not explain what the integer should represent (e.g., local listening port) or any constraints.

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) with a clear resource '指定端口的代理' (proxy on the specified port), and even specifies the return value. This distinguishes it from siblings like start_proxy and stop_listener without requiring further inspection.

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 purpose implies when to use it (stop a proxy on a specific port), but there is no explicit guidance about when not to use it or alternatives such as stop_listener. The inference is straightforward, yet no exclusions or conditions are 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?

With no annotations provided, the description carries the behavioral disclosure burden and does so reasonably well: it discloses offline operation, item-by-item pass/fail behavior, and protocol-specific validation logic including the nuance that Modbus TCP has no CRC (unlike RTU). It does not cover error handling or invalid-input behavior, but the output schema covers the return shape.

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

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

The description is front-loaded with a one-sentence summary, followed by clean per-protocol bullet lists, and ends with a direction note. Every sentence adds protocol-specific value; there is no redundancy or fluff.

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 handles return values, so that is not a gap. However, for a 4-parameter tool with no annotations and no schema descriptions, accepted protocol strings, frame_hex formatting, and frame_format values should be specified; they are mostly implied. The rich protocol checklists make it usable, but the missing parameter details keep it 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%, so the description must compensate. It only explains direction explicitly ('direction 取 req 或 resp') and hints at protocol values via the protocol sections. frame_hex format and frame_format semantics are not described, leaving an agent without enough information about how to supply those 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?

The description clearly states the action: run a spec validation checklist on one frame with itemized pass/fail results, and explicitly notes it requires no device connection. The protocol-specific checklists (Modbus TCP, FINS/TCP, MELSEC 3E) make the validation purpose concrete. It does not explicitly distinguish from the sibling parse_frame tool, so it stops short of a top score.

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

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

The description gives clear usage context: use it offline to validate a frame against protocol rules, and it enumerates the supported protocols with their specific check items. It also explains the direction parameter accepts req or resp. It does not explicitly name alternatives or state when not to use it, so exclusion guidance is missing.

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