getOpenInterest

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

Annotations already mark the tool as readOnlyHint=true and openWorldHint=true, so the safety profile is established. The description adds valuable behavioral context beyond those annotations: no authentication required, possible latency during extreme volatility, cursor-based pagination, and supported product types. There is no contradiction between the annotations and the description.

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 well organized with a lead summary, bulleted use cases, a do-not-use section, and notes, and it front-loads the core purpose. However, it repeats 'Supports cursor-based pagination' in both the main description and the notes, and the getTickers alternative appears multiple times, including in the Agent hint. Some redundancy keeps it from being fully concise.

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?

For a 7-parameter endpoint with no output schema, the description covers the essential operational context: purpose, use cases, alternatives, intervals, supported products, pagination, auth requirements, and latency behavior. It is somewhat thin on startTime/endTime and limit semantics, but an agent has enough context to select and invoke the tool correctly for historical open interest data.

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 0%, so the description must compensate. It names the three required parameters (category, symbol, intervalTime), lists the interval enum values, and explains cursor pagination semantics. However, it leaves startTime/endTime units, limit behavior, and the mapping between category values and supported products unexplained, so the parameter guidance is incomplete.

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: 'Query historical open interest data for derivative contracts.' It clearly states what the tool returns (total outstanding position size) and explicitly distinguishes itself from getTickers by framing itself as historical rather than real-time. This makes its purpose unambiguous even among a very large sibling list.

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 explicitly lists when to use the endpoint (tracking sentiment, analyzing trends relative to price, retrieving time series) and provides a direct do-not-use instruction: for current open interest, use getTickers instead. The Agent hint reinforces required parameters and pagination behavior, leaving little ambiguity about when this tool is appropriate.

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