DecaData Odyssey Lite

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

Beyond the readOnly/non-destructive annotations, it discloses cost ('free'), dataset scope (~380 US consumer-goods makers), the meaning of tier (1 largest, 3 smallest, weekly only), and the exact fields returned (ISIN, ticker, name, tier, first/last day of data). That tier caveat matters behaviorally: tier 3 has coarser weekly coverage, which an agent would otherwise miss.

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 compact sentences, front-loaded with the data domain and scale, then the negative guidance, then the return fields. No filler or restatement of the title.

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 3-param read tool with no output schema, the description covers purpose, scope, cost, tier semantics and the return fields — everything needed to call it correctly. Remaining details (limit bounds, empty-query default) are already handled by the schema's defaults and the query description.

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?

With only 33% schema description coverage, the description compensates well: 'by name or ticker' clarifies query semantics, and the tier gloss ('1 largest, 3 smallest, weekly only') gives the bare enum real meaning. The limit parameter is left entirely to the schema (default 25, max 400), so coverage is good but not complete.

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+resource: looking up companies for which DecaData has point-of-sale data, with concrete scope (~380 US consumer-goods makers, examples PepsiCo/Kraft Heinz) and lookup keys (name or ticker). It also explicitly excludes what the tool is not (products, prices, deals), making it unmistakable against siblings like quote_sales or get_yoy_growth.

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 when-to-use framing ('For company sales research, not shopping') plus explicit exclusions for products, prices and deals. It doesn't name sibling tools as alternatives, so routing relies on the reader inferring that this is the discovery step before get_sample/quote_sales, but the exclusions do most of the disambiguation work.

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 only cover safety/read semantics, yet the description adds substantial non-obvious behavior: this is a paid x402/USDC-on-Base resource with a time-decaying price ladder ($250 early, $25 last week, $0.01 post-publication). That price-by-lead-time behavior is essential and not derivable from annotations or schema. It stops short of stating whether each call re-charges (relevant given idempotentHint=false) or how payment is authorized.

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, front-loaded with what is delivered, then pricing, then the disambiguation. Dense but nearly every clause carries information; the parenthetical payment-rail detail is the only mildly incidental item.

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 describe the returned artifact; it hints at 'our own index for BLS's six food-at-home groups' but never says the response shape, units, or whether the nowcast value and group indices both come back. Coverage of prerequisites and timing is good, but return-value completeness is partial for a paid data product.

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 month parameter already documents the YYYY-MM format and next-release default. The description adds the useful nuance that lead time to BLS's release drives price, which affects month choice, but supplies no month-format or validity detail beyond the schema. Baseline 3 applies.

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+resource ('nowcast of BLS's CPI food-at-home inflation, year on year') with scope (US high-low grocery chains, six food-at-home groups) and timing (before BLS publishes). The closing line 'For inflation questions, not company sales' explicitly separates it from the company-oriented siblings like find_companies and quote_sales.

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 a clear negative boundary ('not company sales') and an implicit positive condition (inflation questions). It does not name a specific sibling alternative such as get_yoy_growth, so an agent must infer the routing itself, but the domain split is unambiguous.

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 readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that — that the call is free, fixed to Q1 2019, and available at daily or weekly granularity — but says nothing about rate limits, result size, or response format.

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?

A single dense sentence with the scope and the value proposition front-loaded and no filler. Slightly clipped to the point of being a fragment, which costs a little clarity, but nothing is wasted.

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, no-output-schema tool this covers the data scope and cost, which is most of what an agent needs. However, it offers no way to know how daily versus weekly output is selected when no such parameter exists, leaving an actionable ambiguity unresolved.

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 'company' parameter is fully documented in the schema (ticker:, ISIN, isin: forms). The description adds nothing about the parameter, so the baseline 3 applies.

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 resource and its scope concretely: Q1 2019 sales, units and panel stores for one company. It is clear this returns a preview dataset rather than an analysis, which separates it from get_yoy_growth and quote_sales, though it never uses an explicit verb like 'retrieve' and doesn't name those siblings directly.

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?

'Free, to see what the data looks like' implies the intended use case (data preview before committing to a paid/larger query), but there is no explicit when-to-use/when-not guidance or reference to the sibling tools that would serve the follow-up need. Usage is inferable but not stated.

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 read-only, non-destructive behavior, and the description adds substantial context: it is a paid $0.01 x402/USDC-on-Base endpoint, uses the latest reported quarter only, compares same weekdays year earlier, and is same-store/like-for-like. These details go 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?

The core metric is front-loaded, but the description is a single long, dense sentence with many nested clauses. The information is relevant, but the structure makes it harder to parse than necessary.

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 metric tool with no output schema, the description provides extensive context about timing, comparison method, cost, and data scope. It is largely complete for invocation, though it does not fully clarify the return structure implied by 'vs_market_*'.

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 'company' parameter is fully documented in the schema with ticker and ISIN formats. The description does not add parameter-specific meaning beyond what the schema already provides, so the baseline score of 3 applies.

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 metric being returned: year-on-year growth in point-of-sale sales and units for a company's latest reported quarter. It is specific about the computation and scope, but it does not explicitly distinguish this tool from sibling tools such as quote_sales.

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?

There is no explicit guidance on when to use this tool versus alternatives like quote_sales or get_sample. The phrase 'vs_market_*, read it first' is a vague prerequisite reference, not a clear usage rule or exclusion.

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=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real value by disclosing that the quote is free and that it returns an x402 purchase URL, but says nothing about rate limits, authentication for the buy step, or price currency/units.

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?

A single compact sentence with no filler, and the core output (exact price) is front-loaded. The phrasing 'price of a window of daily or weekly sales and units' is slightly convoluted but still parses cleanly.

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 correctly compensates by naming the return values (price plus HTTP buy URL), which is the key missing piece. It still leaves gaps around price units/currency, behavior when the requested window is unavailable, and the relationship to the sibling lookup tools.

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 75%, so company, from, and to are largely documented in the schema itself. The description confirms the daily/weekly dimension (mapping to freq) and the notion of a date 'window', but adds no format, default, or syntax detail beyond what the schema already provides.

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 concrete verb+resource: pricing a window of daily or weekly sales/units, and returning both the price and a purchase URL. This is clearly distinguishable from find_companies, get_sample, and get_yoy_growth, though it never explicitly names what those siblings do differently.

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 parenthetical '(free)' and the mention of a buy URL imply this is the pre-purchase quoting step, which is useful implied guidance. However, there is no explicit statement of when to use this versus get_sample or get_yoy_growth, and no stated prerequisites (e.g., company must be resolvable via find_companies).

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