cot_data

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

With no annotations, the description must carry the behavioral disclosure burden. It discloses that data is weekly and limited to the listed currencies, which are useful constraints. However, it does not mention error behavior for unsupported currencies, date handling, authentication, or rate limits. The read-only nature is implied by 'Get' but not stated explicitly.

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 single, concise sentence that immediately states the action and the resource, followed by a list of supported currencies. Every word earns its place; there is no fluff or redundancy, and the most important information is front-loaded.

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?

While the description lists supported currencies, it does not explain the date parameters, which are optional but likely important for filtering historical data. The output schema exists but does not cover input semantics. An agent would lack the information needed to correctly construct calls with start_date and end_date, making the definition incomplete for proper 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 0%, so the description must compensate. It partially explains the 'currency' parameter by listing valid values, but it does not describe the purpose or format of 'start_date' and 'end_date'. These optional parameters remain ambiguous, and the description provides no guidance on how to use them, leaving a significant gap for an agent.

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 identifies the action ('Get') and the resource ('CFTC Commitment of Traders (COT) weekly positioning data for a currency's FX futures contract'), and explicitly lists the supported currencies (AUD, CAD, CHF, EUR, GBP, JPY, NZD, USD). This makes it distinct from sibling data tools like forex or commodities, which serve different data domains.

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 implies usage (when you need COT positioning data, use this tool) but provides no explicit guidance on when to choose it over alternatives like forex or indicator_query, nor does it mention any exclusions or prerequisites. The supported currency list is a form of context but does not address tool selection among siblings.

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