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

Annotations already declare readOnlyHint, openWorldHint=false, idempotentHint, and destructiveHint=false, so safety is well covered. The description adds useful behavioral context beyond annotations: it explicitly says computations are pure and offline, nothing is fetched or stored, and gives out_len bounds (1-64). It does not, however, describe error behavior or operation-specific failure modes, so it falls short of a 5.

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

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

The description is front-loaded with the operation list, which is the highest-value information, and each op entry is compact. The only slightly tangential part is the closing pointer to swapchan_playbook workflows, which adds context but is less directly about invoking this tool. Overall it is appropriately sized for a seven-operation dev utility.

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 nine parameters, one required op, no output schema, and 0% schema description coverage, the definition does a reasonable job outlining the seven operations and their rough inputs/outputs. However, it is incomplete for correct invocation: it does not specify which optional fields belong to which op in a table-like way, does not describe expected formats, and does not clarify output shapes precisely enough for an agent to use the tool without trial and error.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It maps several parameters to operations (address for ss58_decode, account+prefix for ss58_encode, SCALE hex for decode_account_info, text for twox128, out_len/personal for blake2b), which is useful. But it leaves ambiguities: hex and data both appear in the blake2b entry, the applicable parameters for each op are not exhaustively stated, and format details such as SS58 address syntax or expected hex lengths are absent.

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

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

The description names a specific umbrella resource (Substrate helper operations) and enumerates each operation with concrete input→output mappings, e.g. ss58_decode (address → account public key hex + network prefix) and storage_key (account address → System.Account storage key hex). It also distinguishes the tool from siblings by stating it is 'Pure, offline computation (blocktools); nothing is fetched or stored,' which clearly contrasts with the swap/wallet tools in the sibling list.

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

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

Usage is implied by the operation list and the note that it can be combined with swapchan_playbook, but there is no explicit guidance on when to choose this tool versus address_tool, solana_address, or other address/hash utilities. It also does not state when not to use it or what prerequisites are required. The playbook pointer adds context but does not route the agent between alternatives.

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