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

With no annotations, the description carries full behavioral burden. It discloses the always-HTTP-200 behavior, locked_count/payment_required mechanics, pricing (10🍒 or $0.10), and the return-field list. It even clarifies that absolute order sizes are never returned—useful preemptive context.

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 dense and front-loaded with purpose, then organized by mode. Every clause earns its place given the payment behavior, but it is long enough that a slightly tighter structure could improve scannability.

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?

With no output schema, the description fully enumerates returned fields (counts, mirroring_paused, rules_hash, latest timestamp, locked_count, payment_required, per-signal fields). It covers prerequisites, mode-dependent behavior, and the alternative single-signal route, making the tool safe to invoke.

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?

Although the schema covers both parameters, the description adds meaning beyond the schema: it explains what 'live' does semantically, its paid/free implications, and reinforces vault_id as required. This goes well beyond the terse schema text.

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 clear verb+resource: 'Read a Forge vault's signals' and explicitly references the mirroring doc. It differentiates this list-read from the single-signal route by naming the alternative endpoint, so an agent knows exactly what this tool is for.

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 explicitly explains when to use live vs. omitted/false ('With live true: signals younger than 24h — a paid read; With live omitted or false: signals older than 24h, free') and points to the alternative route for reading exactly one signal. It also states the vault_id prerequisite.

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