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

The description is exceptionally transparent about behavior beyond the readOnlyHint annotation. It states 'Nothing is written', 'READ-ONLY', and 'this call changes nothing and can be repeated safely'. It also adds security-relevant context: listing titles are untrusted citizen text, the returned data is untrusted citizen-authored, and the CallToolResult _meta carries a server-owned provenance boundary. This gives the agent a clear trust model and side-effect 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 dense and front-loaded, starting with the purpose and then detailing each kind's usage. Every sentence earns its place by adding either purpose, usage, parameter mapping, or trust/safety context. It loses a point for the structural inaccuracy of claiming 'three signed sentences' when the schema supports four kinds, which slightly undermines precision.

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 14-parameter tool with no schema descriptions and no output schema, this description covers a great deal: purpose, per-kind usage, read-only behavior, and trust boundaries. The significant gap is the unexplained payout_wallet enum value, which an agent could encounter in the schema and be unable to resolve. It also does not describe the return value structure beyond noting it is untrusted and carries a provenance boundary.

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 coverage, the description compensates strongly by mapping nearly every parameter to specific kinds: handle, row, address, expiry for payout; handle, title, amount_atomic, expiry, optional verifier_price_atomic, max_verifiers for listing; binding_id, tx_hash, log_index, source_address, relationship for funder_statement. However, it omits the payout_wallet kind entirely from the schema enum and provides no semantics for it. It also leaves some parameter meanings implicit (e.g., row, expiry format), so it is strong but 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?

The description states a specific purpose: building the exact byte strings for the signed sentences of the payout rail so the caller signs what the registry rebuilds. It enumerates the three supported kinds with their byte variants and fields, clearly distinguishing this tool from the long sibling list, none of which overlap in function. The only blemish is the phrase 'three signed sentences' while the schema enum has four kinds (missing payout_wallet), but the core purpose is still unambiguous.

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 for each kind: payee signs payout, funder wallet signs listing for proof of funds, and paying wallet signs funder_statement after transfer. It also explains why to use it ('so you sign exactly what the registry rebuilds'). It does not provide when-not-to-use scenarios or compare with alternative sibling tools, 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.