Feed issues (Avada)

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

Annotations already cover the safety profile (readOnly, non-destructive, openWorld), and the description adds real context on top: preview-API status, the AVADA_API_KEY requirement, one-page-at-a-time pagination, and a documented failure mode where the tool can answer "unavailable." The guidance against inventing or zero-filling numbers usefully warns that results may be incomplete, though it does not say what a page contains.

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 short sentences, scope first and operational caveats second, with no filler. The parenthetical problem list is dense but earns its place by defining what counts as an issue.

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 paginated read with no output schema, the description covers scope, auth, paging, and failure behavior reasonably well. It remains incomplete on the severity filter and on what fields a returned issue record carries, which matters because nothing in the schema fills those gaps.

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 0%, so the description must carry parameter meaning and it largely does not. "One page at a time" gestures at after/limit but never explains the cursor or the 1-50 range, and the severity enum (error vs warning) is not mentioned at all, leaving the most consequential filter undocumented.

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?

"Products the last feed snapshot found problems with" states a concrete resource (feed products with issues) and enumerates the problem classes (missing image, GTIN, price, rejected by OpenAI), which separates it from query_feed_products or list_feed_uploads. It stops short of explicitly naming a sibling, so an agent must infer the boundary itself.

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 wording implies the use case (diagnosing products the last snapshot flagged), but there is no explicit when-to-use instruction and no reference to alternatives such as query_feed_products for healthy catalog browsing. The only directive given concerns error handling, not tool selection.

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