Google Shopping Insights

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

Annotations already cover read-only, open-world, non-idempotent, non-destructive, so credit goes to what the description adds: the tool launches a run of the 'epctex/google-shopping-scraper' Actor via Apify's mcp.apify.com gateway, requires the caller's own APIFY_TOKEN, and bills the caller's Apify account. It also explains that the response carries run and dataset IDs for paging the full dataset. It does not quantify cost or latency beyond the schema's 'resource consumption' notes.

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?

Well front-loaded with labeled 'When to use', 'Returns', and 'Behavior' sections and a docs link, so an agent can scan it quickly. The 'Unlock valuable insights from Google Shopping with our Data Extractor' sentence largely restates the title and could be cut.

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 an 8-parameter, no-output-schema scraping tool the description covers the essentials: what it returns (one row per result plus paging IDs), that it is a hosted Actor run requiring auth, and that it is read-only. Nothing critical is missing, though the absence of an output schema means field-level expectations rely on the summary sentence.

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%, so every parameter (queries, startUrls, countryCode, maxItems, maxItemsPerQuery, and the three include* toggles) is already documented, including precedence rules and enum semantics. The description adds nothing param-specific — it describes output fields rather than how to drive queries, URL vs. query precedence, or country selection. 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 concrete verb and resource: extracts Google Shopping results containing reviews, descriptions, prices, merchant details, and affiliation links, and the 'When to use' line narrows it to product/price/merchant/review queries across stores. The resource itself (Google Shopping) differentiates it from the Amazon/eBay/Walmart/AliExpress/Shopify/Etsy siblings without needing to name them. The opening 'Unlock valuable insights' is marketing filler, but the substance behind it is specific.

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 explicit 'When to use' clause gives a clear trigger condition (need Google Shopping results for a query across stores). It stops short of exclusions or naming an alternative sibling scraper for non-Google sources, so the agent still has to infer routing from the resource name.

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