sevennow_popular

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

With no annotations, the description carries the full burden of behavioral disclosure, and it succeeds. It explains that both axes matter, that vertical determines the catalogue, that store_id narrows to a regional index (with concrete examples like NY_NE and SE), and that the response echoes back both vertical and regional index. It also explicitly discloses the restaurant vertical's surprising behavior of ignoring store_id entirely. This is thorough and prevents surprises.

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?

Each sentence earns its place: the core purpose in the first two sentences, then the vertical axis, the store_id axis, the restaurant exception, and finally the response echo. The description is front-loaded with the most important information and is free of filler or redundant statements. It is dense but appropriately sized for the complexity it explains.

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?

Given that there is no output schema, the description covers the return content well by stating the trending terms are returned and that the response also echoes both the vertical and the regional index. It does not specify the exact structure of the returned terms (e.g., array shape, count, whether the list is sorted), but for a read-only trending-terms tool, this is likely sufficient for an agent to invoke and interpret the result.

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 already describes both parameters with full coverage, so the baseline is 3. The description adds meaningful semantic value by explaining the practical meaning of vertical values ('convenience', 'restaurant', 'global'), the relationship between store_id and region, and the restaurant exception. The examples (New York → NY_NE, Florida → SE) help an agent understand the outcome well beyond the schema's formal definitions.

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: 'Get 7NOW trending search terms.' It immediately clarifies the exact product (7NOW) and the data being returned (trending search terms shown in 7NOW's search box), leaving no ambiguity. This clearly distinguishes the tool from sibling 7NOW endpoints like sevennow_search or sevennow_suggest, which focus on queries and suggestions rather than trending terms.

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 extensive practical guidance on how to use the two axes (vertical and store_id), including the meaning of each vertical value and what happens when store_id is omitted. It also flags the restaurant vertical's exception to store_id. However, it does not explicitly name alternatives or say 'when not to use this tool,' instead leaving the alternative selection to inference from the purpose.

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