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

Beyond the annotations it discloses retry-on-failure semantics, disable-after-10-consecutive-failures, one-POST-per-token-per-subscription delivery, URL replacement when the same wallet is resubmitted, and the HMAC signing scheme (X-TRNCH-Signature, t=<seconds>,v1=<HMAC-SHA256 of t.body>). The replacement behavior is consistent with idempotentHint=false because each subscribe mints a new subscription with a new one-time secret, so no annotation contradiction arises.

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 core purpose and required inputs come first, and every clause carries load (quota, retry, signing, replacement). It is a dense semicolon-heavy block rather than a violation of brevity, though splitting delivery rules from limits would improve scanability.

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 mutating, open-world subscription tool with no output schema, the description covers auth, quota and 409 error condition, retry and disable lifecycle, payload contents (token, status/category/rugged/dumped verdict, canSell, trnch_sell), and the one-time secret plus signature construction. Almost nothing an agent needs to call this correctly and handle the result 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 already 100%, yet the description still adds meaning: it clarifies that any address format is accepted for wallet, and that webhookUrl must be https on a public domain at port 443 with IPs, localhost, and private/internal names actively refused — a validation rule the schema only gestures at. The 300-character limit and pattern are left to the schema, which is appropriate.

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 opening sentence names a specific outcome (a signed webhook POST) triggered by a specific event (a held token being newly flagged by Trnch), which is a clear verb+resource pairing. Combined with the title, an agent can tell this apart from trnch_alerts_list and trnch_alerts_unsubscribe 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?

It establishes the monitoring use case (ongoing, checked every 5 minutes, initial backfill of already-held flagged tokens) which implicitly contrasts with one-off reads like trnch_check, and it spells out prerequisites (API key via Authorization: Bearer) and quota behavior (3 per key, 5 per wallet, 20 per host, 409). It stops short of explicitly naming a sibling tool to use instead for one-time lookups, so the routing is inferred rather than stated.

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