sevennow_catalog

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

With no annotations, the description carries the full disclosure burden and handles it well: it reveals live data, store-scoped scope, real per-item pricing/promotions/calories/UPC/image, active/out-of-stock inventory counts, uniform pagination, and limit cap/default. The inert lat/lon behavior is also explicitly disclosed. Only minor operational details like rate limits are absent, which are not essential for this read-style catalog tool.

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 front-loaded with the core purpose and well-ordered: return contents, store_id source, scope caveat, pagination. It is slightly redundant in emphasizing store-scoped behavior twice, but every sentence contributes useful guidance and there is 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?

Given no output schema and no annotations, the description compensates by specifying return contents (categories, paginated items with pricing/promotions/calories/UPC/image, inventory counts) and all relevant parameter behaviors. An agent can determine the required input, ignore inert parameters, and understand pagination without further research. It is complete enough for correct selection and 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 input schema already documents all five parameters at 100% coverage, so the baseline is 3. The prose adds little beyond the schema: store_id sourcing, inert lat/lon, uniform pagination, and limit cap/default are all already present in the property descriptions. No meaningful new parameter semantics are introduced.

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+resource ('Get one 7NOW store's live product catalog') and enumerates exactly what is returned. The repeated store-scoped language distinguishes it from national price lists and from sibling tools like sevennow_stores, sevennow_categories, and sevennow_product. There is no ambiguity about the tool's function.

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 a concrete prerequisite: store_id comes from GET /7now/stores. It also warns that lat/lon are inert and that the catalog is genuinely store-scoped rather than a national price list, preventing misuse. It does not explicitly name alternative sibling tools or state when not to use it, so exclusions are implicit rather than enumerated.

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