demand_reportFREE, no payment. The aggregate of what agents have told us they are looking for, most-requested first, with the categories nothing available yet serves. Useful if you are deciding what to build or sell into the agent economy.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Window in days, default 30, max 90. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does state that the data is an 'aggregate of what agents have told us' and that it is ordered 'most-requested first,' and includes 'categories nothing available yet serves.' These reveal the nature and ordering of the data. However, it does not mention output format, data freshness, pagination, or any side effects (likely none). For a simple report tool, this is adequate but not deeply transparent.
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 concise and well-structured. The first clause highlights the cost ('FREE, no payment') which is immediately useful. The second clause states content and ordering. The third provides the use case. Each sentence earns its place without redundancy or fluff, and the most critical differentiator (free, aggregate demand) 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?
For a simple tool with one optional parameter and no output schema, the description covers the essential aspects: what the tool returns (aggregate demand, ordered, with unmet categories), the use case, and the free aspect. The schema covers the 'days' parameter. It does not describe the exact response structure, but that is not required given the simplicity, and the description gives a good mental model. Minor gaps like output format don't significantly hinder correct 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?
The schema covers the only parameter 'days' with full description (window in days, default 30, max 90), achieving 100% schema coverage. The tool description does not add parameter-specific details beyond that, but per the rubric, when schema coverage is high, the baseline is 3. The description's mention of 'aggregate' aligns with the window concept but does not elaborate further.
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 states the tool's purpose: it returns an aggregate of what agents are asking for, ranked by frequency, including categories with no available supply. This is a specific verb-resource combination (report on demand) that distinguishes it from siblings like find_product and price_basket, which are about product search and pricing.
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 provides a clear use case: 'Useful if you are deciding what to build or sell into the agent economy.' This tells the agent when the tool is appropriate. It also emphasizes the free nature ('FREE, no payment'), which is a practical consideration. However, it does not explicitly contrast with sibling tools or state when not to use it, so it stops short of full usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
find_product, demand_report, and request_data are clearly distinct, but price_basket and cheapest_basket both operate on a whole shopping list. Their descriptions define different output styles (itemized per-store baskets vs. optimized buying decision), so an agent can usually choose correctly, though some overlap remains.
All names are lowercase snake_case and descriptive, but find_product, price_basket, and request_data follow a verb_noun form while cheapest_basket and demand_report are noun phrases. This is a minor inconsistency rather than a chaotic naming scheme.
The four listed tools are well-scoped for grocery price/basket queries plus data demand. However, the header declares five tools while only four are described, so the exact intended surface is slightly uncertain.
Core grocery use cases are covered: single-item lookup, one-trip basket pricing, multi-store optimization, and data demand. A minor gap is the lack of dedicated tooling for broader store or product meta-information beyond the price and stock fields already returned.