audit_chain_artifact_claim

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

The description goes well beyond annotations: it discloses that the tool throws INVALID_INPUT when no identifying input is provided, that chain_facts is null when daemon calls fail, that proof_decode and forge_demo are conditionally null, and that it joins against a flagged false-claim registry. It also reveals the demo amount auto-selection logic, which is valuable behavioral context not in the schema. No contradiction with readOnlyHint/destructiveHint/idempotentHint is present.

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?

Although lengthy, the description is well-structured with clear sections (Composite, When to call, Input Requirements, Output, PREFER directives) and front-loads the core purpose. Each sentence carries operational value, and the critical at-least-one rule is not present in the schema, so the repetition in Input Requirements is justified rather than redundant.

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 has no output schema, the description provides a thorough output map: top-level fields, verdict semantics, null-condition behavior for chain_facts/proof_decode/forge_demo, and the slim forge_demo shape. It also covers error conditions, parallel execution, registry lookup, and documented citations, making the tool safely callable by an agent without prior context.

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 already 100%, but the description adds essential semantics: at least one of topoheight/block_hash/tx_hash/proof_string MUST be provided despite zero declared required params, and it adds format constraints (64 hex, full deroproof bech32 with HRP). For include_forge_demo it explains the default, the tx_hash precondition, and the intended rebuttal use case beyond the schema's description.

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+resource: 'audit a chain artifact... end-to-end' and clearly states the outputs (verdict, chain facts, proof decode, narrative, citations). It also differentiates itself from siblings by naming the exact composite operation and explicitly saying to prefer it over chaining dero_get_block_header_by_topo_height + dero_get_transaction + dero_decode_proof_string.

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?

Provides an explicit 'When to call' section with concrete user intents ('what's going on with DERO block X?', 'is this transaction the inflation-claim TX?', 'does this proof string come from a known false claim?'). It also states when NOT to chain manually, when to set include_forge_demo=true, and instructs the agent to cite related_docs verbatim.

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