COT-Reports

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful behavior beyond that: results are short, include a link to the full guide, and are available at every level (no tier gating).

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?

One front-loaded sentence whose dash-list items each correspond to a real enum value, so nothing is padding; the trailing 'Available at every level' is slightly ambiguous about what 'level' means.

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 one-parameter, read-only lookup with no output schema, the description conveys return shape (short explanation plus guide link) and access scope; only output format details (e.g., markdown vs plain text) are left unstated.

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% and the single parameter is an enum, so the schema already does the heavy lifting; the description's inline list of concepts loosely maps to enum values but adds no format or fallback guidance.

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?

States a specific verb (explain) plus resource (a COT concept), and enumerates the covered concepts, which makes it clearly distinct from data-returning siblings like get_cot_index and get_latest_snapshot.

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 phrase 'a short explanation of a COT concept' plus the availability note gives clear context for when to reach for this tool rather than a data tool, but it never names an alternative explicitly or states when not to use it.

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

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

Goes well beyond the readOnly/idempotent/closed-world annotations by disclosing authentication-dependent gating: which lookback windows and which CFTC variants are available anonymously versus with a key. The disclosure is dense and somewhat ambiguous ('a free account, COT Premium and a Data API key: every window' reads as if all three tiers grant everything), which slightly undercuts its usefulness, and it says nothing about result shape.

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 metric definition is correctly front-loaded and earns its space, but the tier-availability sentence is a telegraphic colon-fragment stack that takes effort to parse. Information density is high, yet clarity is traded away for brevity.

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 no output schema, the description should indicate whether this returns a single latest index value or a historical series per report date; it does not. The tier gating is thoroughly covered, but the return contract for a derived-metric tool is left implicit.

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 already 100%, so the baseline is 3; the description adds genuine new meaning by tying the variant and lookback-window availability to account tier, which the schema does not state. It does not resolve the apparent tension between 'without an account: 26 and 52' and the schema's 'Default: 156 … 52 without an account'.

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?

States a specific computed resource (the COT index for large speculators and commercials) and even defines the metric's scale and meaning: '0–100: where the current net position sits between its lowest and highest of the lookback window.' It also scopes the data source ('from the Legacy report'), which separates it from siblings like get_latest_positions and scan_extremes.

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?

Gives clear context about what is reachable at each access tier (no account, free account, COT Premium/Data API key), which directly governs when a caller gets a useful result. It does not name alternative siblings (e.g. when to prefer get_latest_positions or scan_extremes), so it falls short of explicit when/when-not routing.

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

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

Beyond the annotations, which already declare read-only, idempotent, non-destructive behavior, the description adds substantial operational context: newest-first ordering, a 260-report cap, paging semantics, account-tier data availability, Premium close prices, and trial-subscription behavior.

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 core purpose is front-loaded and most of the dense access-tier material is substantive. The description is still a long multi-clause paragraph with some repetition, such as repeated 'without an account' phrasing, which slightly reduces clarity.

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?

There is no output schema, but the description identifies the returned content and explains paging, access tiers, report families, and variants for a relatively complex tool. This is enough context for an agent to select and invoke it correctly.

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 schema already explains the parameters well. The description still adds meaning by clarifying 'until' for paging back, the 260-report limit, report-family availability by access tier, and default variant behavior, though it adds little about 'from' beyond the schema.

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 states a specific verb and resource: 'Weekly COT history for one market, newest first.' It also identifies the returned content (open interest and net positions by trader group), making it distinguishable from siblings like get_latest_positions and get_weekly_summary.

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 clear context for when this tool is appropriate by emphasizing history and explaining that callers can page back with 'until.' However, it does not explicitly name alternative sibling tools or contrast their use cases, so it falls short of full when-not/alternatives guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond that: results are gated by credentials (anonymous/free = Legacy only; COT Premium and Data API keys unlock Disaggregated, TFF, Supplemental; Premium adds close price), and variant defaulting depends on the report family. It does not say what happens on an out-of-tier request (error vs silent fallback).

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?

Front-loaded with the highest-value sentence (what you get back for one market), and every subsequent sentence carries access-tier information that affects invocation. The middle sentences are convoluted ('Without an account and with a free account', 'Both CFTC variants ... with COT Premium and Data API keys') and could be tightened into a small tier table without losing content.

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 no output schema, the description carries the return-value burden and does so by naming the metrics returned. Access tiers, report families and variant defaults are all covered, which is what an agent needs for a 3-parameter read tool. The only gap is failure behavior when a requested family is not entitled.

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 coverage is 100% with examples and defaults for all three parameters, so the baseline is 3. The description adds real meaning on top: it ties the report-family enum and the variant enum to entitlement and per-report defaults, telling the agent which enum values will actually be honored under a given key.

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 opening clause gives a specific verb+resource+scope: the latest COT report for exactly one market, with the returned fields enumerated (long, short, net positions per trader group, WoW change, % of open interest). 'Latest' implicitly separates it from get_history and the single-market scope separates it from get_latest_snapshot, but neither sibling is named, so the differentiation is inferred rather than stated.

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?

Usage is implied by 'for one market' and 'latest', but the description never says when to pick this over get_latest_snapshot, get_history or get_weekly_summary. The account-tier sentences explain what data each access level unlocks, which helps an agent predict results, but that is availability information rather than when-to-use-the-tool guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: a fixed page size of 100 markets with offset paging, and access-tier behavior where Premium/Data API keys unlock both CFTC variants while anonymous and free users get only each report's default variant. It doesn't clarify what happens if a restricted user requests a non-default variant, but the disclosure goes well beyond the 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?

Front-loaded with the core identity ('the latest Legacy COT report of every market') followed by page size, contents, filtering, and access tiers. The trailing account-tier clause is dense and slightly run-on, but every element carries information an agent would otherwise lack.

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 no output schema, the description does the right work by naming the returned measures and the 100-market page size, and it covers auth tiers, which are essential for predicting failures. The main remaining hole is sibling disambiguation between this tool and get_latest_positions, which an agent needs in order to choose correctly.

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 coverage is 100%, so all three parameters are fully documented in the schema, which sets the baseline at 3. The description reinforces meaning — offset as the next-page mechanism, category as a filter, variant as tier-gated — but adds no syntax or edge-case detail (e.g. whether category is exact-match or prefix) beyond what the schema already supplies.

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?

States a specific resource and scope: the latest Legacy COT report across every market, enumerating the returned fields (net positions of large speculators and commercials, week-on-week change, open interest). It is clear on its own, but it never distinguishes itself from the very similar sibling get_latest_positions, leaving an agent to guess which 'latest' endpoint to pick.

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?

Gives operational guidance — use offset to page through 100 markets per answer, filter by category — and notes availability at every account level. It does not say when to prefer this over get_latest_positions, get_history, or scan_extremes, so the usage decision against alternatives is left implicit.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description earns credit for adding domain behavior instead: the CFTC publishes Fridays at 3:30 pm Eastern for the prior Tuesday, and holidays shift the schedule. That is exactly the kind of rule an agent cannot derive from structured fields. It does not describe the shape of the returned timestamps or timezone formatting, which keeps it from a 5.

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?

One dense sentence, front-loaded with what the agent gets, followed by the scheduling rule that explains the timing values. The nested parenthetical is slightly awkward to parse but carries real information and no filler.

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 zero-parameter, read-only metadata tool with no output schema, the description supplies the returned facts and the publishing rule that governs them. Nothing an agent needs in order to call it and interpret the result 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?

The tool takes no parameters, so the baseline is 4. The description correctly implies no input is needed and notes availability at every level, which is consistent with the empty schema.

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 names the concrete outputs: which COT report is latest, its publication timestamp, and the next due date. That is a specific resource-plus-facts statement that separates it from data-retrieval siblings like get_latest_positions or get_history. It stops short of explicitly naming those siblings as alternatives.

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?

Usage is only implied: the agent can infer this is the timing/metadata tool to call before or alongside the position-fetching tools. There is no explicit when-to-use statement, no exclusion of alternatives, and no mention of prerequisites or ordering relative to siblings. 'Available at every level' is a weak hint that no scoping is required.

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

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

Annotations already establish read-only, idempotent, closed-world behavior, and the description goes beyond them by disclosing the data source (latest Legacy report), the market coverage (35 markets across six asset classes), what is measured (speculator/commercial net positions plus change), and the authentication tiers that gate variant selection. It does not describe result ordering, units, or how a 'weekly' period is bounded.

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?

Three sentences, front-loaded with the resource and coverage, with no filler. The middle sentence 'Available at every level' is vague enough that it does not clearly earn its place and interrupts the otherwise logical content-then-access flow.

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 one optional enum parameter, no nested objects, no output schema, and full annotation coverage, the description supplies what an agent needs: what data comes back, which report it derives from, market scope, and account-level constraints on the variant. The remaining gaps — return value shape, units, and which week is returned — are modest for a read-only summary tool.

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 coverage is 100% and the single enum parameter is fully documented with defaults, so the schema already carries the load. The description adds a genuinely useful entitlement constraint — paying keys get both CFTC variants while unauthenticated/free users are locked to each report's default variant — but it does not elaborate on how variant choice affects the returned numbers.

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 states a concrete verb and resource: it returns the weekly summary of net speculative/commercial positions for 35 named market groups from the latest Legacy report, and specifies that change data is included. That is far more specific than the title alone and implies a weekly-snapshot scope distinct from the point-in-time siblings get_latest_positions and get_latest_snapshot, though it never names those siblings explicitly.

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?

Usage is only implied: 'The weekly summary ... from the latest Legacy report' suggests this is the periodic overview rather than an ad-hoc query, and 'Available at every level' gestures at coverage of market hierarchy levels. There is no explicit statement of when to pick this over get_latest_positions, get_history, or get_cot_index, leaving the agent to infer the choice.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed world, so the safety profile is covered. The description adds genuinely new behavioral context: the dataset size (350+ markets) and the exact shape of each returned record, which annotations cannot convey and which matters since there is no output schema. It omits any note on result volume or pagination beyond the schema's limit field.

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 compact sentences with the resource and return fields front-loaded, followed by the filtering options. The trailing phrase 'Available at every level' is vague filler that costs a sentence slot without conveying a concrete constraint.

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 no output schema, the description usefully enumerates the fields returned per market, and it covers all three filter dimensions plus dataset scale. The one meaningful gap is pagination/result-volume behavior, which the schema only partially addresses via limit; the cryptic availability sentence does not fill it.

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 all four parameters are already documented, including the report enum and example categories. The description only restates the filter axes (search text, category, report family) without adding syntax, matching behavior, or defaults, and it never mentions the limit parameter. Baseline 3 is appropriate when the schema carries the parameter burden.

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 ('Lists the CFTC markets COT-Reports covers') and enumerates the returned fields (CFTC code, ticker, name, exchange, category, report families), which makes the tool's job unambiguous. It does not explicitly differentiate itself from the closest sibling, get_cot_index, so it stops short of a 5.

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 filtering options imply the lookup/discovery use case (finding a market's code or ticker before calling other tools), but that workflow is never stated. There is no explicit when-to-use or when-not-to-use guidance and no named alternative. 'Available at every level' is too cryptic to function as usage guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower and the description clears it. It adds genuinely non-obvious behavior: the data source (Legacy Futures Only), the weekly time window, the exact crowded-long/crowded-short threshold rules including hysteresis (entry at 80, exit below 75), and the COT Premium subscription requirement. Return shape and pagination are not described, but there is no output schema to compensate for.

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 core purpose is front-loaded in the first clause, and the long parenthetical is dense but every element (percentile blend, thresholds, report source) earns its place as operational detail. It is one sentence with a nested definition, which is slightly hard to parse but not padded.

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 a single optional enum parameter, rich annotations, and no output schema, the description supplies everything needed to decide whether to call it and what the filter does. The main residual gap is what the returned records look like (market names, scores, position values), which the agent must discover from the response.

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 coverage is 100% and the side enum is already documented with its default ('both'), so the schema does the heavy lifting. The description reinforces that 'long' and 'short' refer to crowded positioning rather than raw net positions, but adds no format or edge-case detail beyond that. 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 uses a clear verb-and-resource framing: markets where large speculators are crowded long or short this week, sourced from the Legacy Futures Only report. It goes further than the name by defining the Crowding score and its hysteresis thresholds, so an agent knows exactly what qualifies as an 'extreme'. It does not explicitly name a sibling it differs from (e.g. get_cot_index), which keeps it just short of a 5.

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?

Usage is implied by 'this week' and the screening concept, so an agent can infer this is a weekly crowding screen rather than a lookup. There is no explicit when-to-use/when-not statement and no pointer to get_cot_index or get_latest_positions for cases where the user wants raw index values instead of extremes. The 'COT Premium only' note functions as a prerequisite rather than routing guidance.

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