Parse Frame

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.