Live Mark Dislocations

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

Annotations already mark the tool read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds useful behavioral context by clarifying the data is historical (despite 'live' in the name), bounded to the last 30 days, and composed of timestamped mark/oracle/basis values. No caveats about pagination or freshness are given, but the annotations lower the burden.

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?

Two sentences with a front-loaded action, an illustrative use case, and a concise return-value summary. No word is wasted; the second sentence clarifies the output without padding.

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 annotations covering safety and schema covering all parameters, the description supplies the missing output-level information (timestamped fields, 30-day history). An agent can correctly select and call this tool with the provided information alone.

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?

The input schema already documents all three parameters at 100% coverage, including coin prefix syntax, hours bounds/default, and toon format. The description only implies the 30-day historical window and adds no parameter-specific guidance beyond the schema, so baseline 3 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 description opens with a specific verb and resource: 'Get historical mark/oracle dislocation data for a coin,' and immediately distinguishes the tool's focus from broader price/risk tools by naming the returned fields (mark price, oracle price, basis percentage). The example question about basis stress/oracle drift before liquidations reinforces a unique use case among the 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?

It gives a concrete trigger ('Use this to answer questions like...') that maps to dislocation analysis, which tells an agent when this tool is relevant. It does not explicitly name alternatives or give when-not-to-use conditions, so it stops short of full routing guidance.

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