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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety. The description adds further context: it is public research data, involves no account access, order placement, or fund transfers, and explicitly states 'Not investment advice'. It also discloses conditional behavior (daily_ranking only when rank index configured) and that include_orderbook_summary is ignored. This goes beyond the annotation set but doesn't fully exhaust every behavioral nuance given the rich annotations.

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 a compact single paragraph that front-loads the core purpose before listing outputs and caveats. Every sentence adds distinct information: primary resource, window behavior, return fields, depth disclaimers, discovery path, deprecations, and legal disclaimers. It is efficient but slightly dense, reading more like a specification than a prose explanation, which slightly reduces readability.

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 an output schema exists, the description appropriately skips return-type details. It covers all non-schema context: the window options, default behavior for include_markets, the null depth_summary and the proper alternative, the conditional daily_ranking, the discovery route for event_ref, the deprecated parameter, and the read-only/public nature. Nothing essential for calling this tool 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 description coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema: it clarifies the event_ref format (split on first colon), specifies the window allowed values, states the default for include_markets, and notes that include_orderbook_summary is deprecated/ignored. This extra explanation enhances parameter understanding without redundancy.

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 explicitly states the tool reads a single event signal from a specific table (dws_external_event_signal_hf) keyed by event_ref in the format venue:venue_event_id. It lists the primary output fields and explicitly contrasts with get_market_orderbook for depth and search_events for discovery, distinguishing it from all sibling 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?

Clear guidance is provided: when to discover event_ref via search_events and when to use get_market_orderbook for live depth instead of this tool (since depth_summary is always null). It also notes that include_orderbook_summary is ignored, steering agents away from a parameter that won't affect behavior.

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