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

The description goes well beyond the annotations (readOnlyHint, destructiveHint false) by disclosing that the operation is free, involves no fee or gas, moves no credits, requires no Regen address (derived from signature), reads tradable balance, never prices the credit, enforces one offer per wallet per packet, and replaces previous offers. It also specifies the 5-minute expiry and the signing method, adding rich behavioral context without contradicting the annotations.

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 long but densely informative; it is front-loaded with the main purpose and then systematically covers constraints, state conditions, and next steps. Every sentence contributes necessary information, so the length is justified rather than verbose. It could be slightly tightened, but overall structure and priority are excellent.

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 (6 params, output schema exists), the description is remarkably complete. It covers prerequisites, constraints, state-dependent behavior, the signing flow, and the follow-up tool. It even mentions the returned MESSAGE_TO_SIGN and BODY_JSON, which complements the output schema. Nothing an agent needs to invoke it correctly is missing.

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 100%, so parameters are already described. The description adds meaning by explaining amount units and decimal-place limits, giving a batchDenom example, clarifying backerWallet must be an address only (never a key), and referencing workId from find_work. It also notes that the board derives the account from the signature, adding context for backerWallet. This is more than a baseline, though not exhaustive per-parameter detail.

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 verb ('offer to pay') and a concrete resource ('this packet in verified stewardship hour (VSH) ecocredits from a named batch on Regen Ledger (chain regen-1)'). It clearly positions itself as step 1 of 2 and distinguishes from siblings like submit_credit_offer and prepare_credit_settlement, so an agent can tell exactly what it does and what it is not.

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 timing ('Before the work'), explains when a backer's offer is refused (claimed, settled, expired, already funded), and notes that the packet's own creator or beneficiary may offer at any state. It also directs the agent to call prepare_credit_settlement after approval and submit_credit_offer within 5 minutes, providing clear routing to alternatives.

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