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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds real context beyond them: the mandatory CoinGecko attribution string and source_terms, the observational/'not financial advice' framing, and the one-question-one-answer bounded-query constraint. It stops short of rate-limit or freshness details.

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?

Purpose is front-loaded, then filters, then the inline return shape, then constraints. The return-shape enumeration is long, but it is justified because there is no output schema. Minor redundancy exists between the 'disclaimer' field listing and the standalone 'information, not financial advice' sentence.

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 carries the return contract itself and does so thoroughly: top-level fields, per-signal fields (id, type, value, signal_strength, direction, why, sources, as_of), attribution terms, and the data_contract envelope. Nothing an agent needs to invoke or interpret the call 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% with per-parameter descriptions and an enum for direction, so the baseline is 3. The description goes further by showing a concrete combined filter example ({min_strength: 70, direction: tailwind}) and clarifying that an empty object yields the full ranked list, which is behavior the schema alone does not convey.

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 noun phrase 'Ranked cross-signal feed of CoinBucha's leading, non-price Bitcoin indicators' clearly identifies the resource and its aggregate, ranked nature, which implicitly sets it apart from the single-signal siblings (get_hiring_signal, get_network_signal). It never names a sibling explicitly, so the differentiation is inferred rather than stated.

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 gives an explicit when-not-use with an alternative: bulk, history, backfills and scheduled pulls should go to the CSVs/datapackage.json instead of this server. It also explains the default empty call ('{} for the full ranked list') and shows a filter example. The gap is that it never routes the agent among in-server alternatives like get_signal_history.

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