Report a sent swap

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

Goes well beyond the annotations: it discloses the auth requirement (Bearer key from trnch_register), that the return is an acknowledgement only, and that the tool does not send, cancel or change the transaction. It also clarifies that crediting happens only once the receipt is checked on chain, implying asynchronous settlement. The idempotency statement largely restates idempotentHint=true, a small duplication.

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?

Front-loaded with the usage condition, then side effects, idempotency and auth in a compact single paragraph. Dense but every clause carries actionable information; only the idempotency clause partly duplicates the annotations.

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 one-parameter report tool with no output schema, everything needed is present: prerequisite, auth, side-effect scope, idempotency, and failure mode. No return-value detail is required since only an acknowledgement is returned.

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?

The single parameter is fully described in the schema, but the description adds real meaning: the hash must come from a swap sent by this wallet via trnch_buy or trnch_sell, and any other hash credits nothing. That constraint is absent from the schema's pattern-only definition.

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?

States a specific verb and resource ('report its hash' for a sent swap) and ties it directly to the transactions produced by trnch_buy and trnch_sell, which no other sibling does. An agent can immediately distinguish it from the trading tools.

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?

Explicitly frames it as 'Optional, after sending a tx from trnch_buy or trnch_sell', naming the prerequisite tools and the exact moment of use. It also states the negative cases (hash that is not a swap of this wallet credits nothing; repeat calls change nothing), so when-not-to-use is covered too.

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