get_flow_metrics

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

With no annotations, the description fully carries the burden. It transparently discloses critical behavioral traits: data source constraints (bitbank UTC day boundary, limited coverage for current day), processing details (sorted transaction list, dedup key using timestampMs:price:amount:side without transaction_id), and warnings about limited coverage. This exceeds typical descriptions.

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 relatively long with three paragraphs. While it is well-structured (overview, constraints, processing details), it could be more concise. Some technical details (e.g., exact dedup key) may be overly specific for initial understanding, adding verbosity.

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 8 parameters, no output schema, and complex data source constraints, the description is remarkably complete. It covers parameter interactions, data limitations, processing internals, and potential edge cases (e.g., merge dedup). The tool is adequately documented for correct invocation.

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 description coverage is 63%, and the description adds significant meaning beyond the schema. It explains hours (supports multiple days), limit (ignored when hours set), view enum (summary, compact, buckets, full), bucketMs and bucketsN usage, and default values. It compensates well for the missing schema descriptions.

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 clearly states it performs flow analysis (flow, CVD, buy-sell pressure) using transaction data to detect CVD, aggressor ratio, and spikes. It is specific to flow metrics, distinguishing it from other analytical tools like candle patterns or volume profile, though not all siblings are explicitly differentiated.

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?

The description recommends using 'hours' for time range or 'limit' for count, providing clear guidance on parameter choice. It also explains data source constraints and merge behavior, giving context for when the tool is appropriate. However, it does not explicitly state when not to use this tool versus siblings.

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