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

Rich disclosure of cost ('FREE, no gas'), signer model (worker wallet personal_sign or passkey, house never holds a key), payer standing requirement (active credit offer on the packet), and the 5-minute signature TTL. However, it states this call 'writes the same settlement record' and that 'your work record, the place's standing and the board's settled count all move' — a state mutation attributed to this invoke — while annotations declare readOnlyHint=true and idempotentHint=true. The write actually belongs to submit_credit_settlement, so the description misleads about when state changes.

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 action and the inputs are front-loaded, which is good, but the body wanders into motivation ('what lets work pay for work') and repeats the cost/signer information twice ('FREE, no gas' mid-paragraph and again as 'Cost and signer: free, no gas'). Roughly a quarter of the text could be cut without losing instructions.

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 an output schema exists, return values need not be detailed, and the description still flags MESSAGE_TO_SIGN/BODY_JSON and the signing step. It covers prerequisites, cost, signer, refusal cases and the next call; the main gap is that the two-step commit semantics are described inconsistently, leaving the agent unsure whether the settlement is final at prepare time or at submit time.

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 the baseline is 3, but the description adds real constraint beyond the schema: the txHash must be a transfer that reached the regen1 account controlled by the signing key, and the amount credited must be tradable rather than retired. That materially narrows which values are valid, though it doesn't spell out the relationship between workerWallet and worker identity beyond 'YOUR signing key controls'.

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?

Names a specific verb and resource ('record that you were paid in a VSH ecocredit'), the exact inputs required (batch denom + regen-1 tx hash), and positions itself as step 1 of 2 with submit_credit_settlement as the follow-up. An agent can distinguish it from submit_credit_settlement and from the dollar-payout path without opening any schema.

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?

Clear entry condition ('after your proof is approved and someone sent you VSH ecocredits'), an explicit exclusion ('a transfer that only retires is refused here'), and the required follow-up call plus 5-minute window. It does not name the sibling alternatives (prepare_direct_settlement / prepare_token_settlement) outright, so the routing decision between settlement types is only implied.

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