civ_parse

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

With no annotations provided, the description carries the full burden, and it does well: it discloses that it splits bytes into frames, disambiguates the tool's own echoed command from the rig's reply, and decodes BCD frequencies, modes, OK/NG and PTT state. It omits error behavior for malformed frames, but the core operational traits are disclosed.

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

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

Two tight paragraphs, zero filler. The purpose line is front-loaded with verb, resource and input source, and the second paragraph lists behaviors in a compact bullet-like flow. Every sentence 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 output schema exists, so return format is covered externally, and the description handles the core decode behaviors and input origin. The gap is the undocumented controller parameter and the absence of any note on malformed input handling — noticeable but not crippling for a decode tool with a defined output schema.

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 covers hex_bytes implicitly ('from hex') but never explains the controller parameter (default 'E0') — its meaning, when to override it, or how it relates to the echoed-command disambiguation the description mentions. Half the parameter surface is left undocumented.

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

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

States a specific verb (Decode) plus a concrete resource (Icom CI-V frames) and names the input source (hex as returned by read_available). It differentiates from sibling parsers (cat_parse, rotator_parse) by being explicitly CI-V protocol scoped, and from civ_build by being the decode/inverse operation.

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

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

The phrase 'as returned by read_available' gives the agent a clear pipeline signal: feed this tool the output of read_available. This routes usage without opening the schema. It doesn't explicitly name when-not-to-use it or mention civ_build as the encode alternative, 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.