FeedShine: Shopify Google Shopping Feed

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description adds the response shape (tab grouping, per-attribute rules, latest run), which is useful context but largely duplicates what the output schema already provides.

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 sentences, front-loaded with the core purpose before the content enumeration. The long tab list is dense but genuinely descriptive of the response, so it earns its space without padding.

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?

With an output schema present, return values need not be re-explained, and annotations cover the safety profile, so the description is nearly sufficient. The only shortfall is the absence of any routing guidance toward list_feeds or update_feed_settings.

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?

There is a single parameter with 100% schema description coverage ('Feed id from list_feeds'), so the schema carries parameter semantics entirely. The description adds no format, sourcing, or edge-case detail about feedId, making the baseline 3 correct.

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 specific verb and resource ('Get one feed's full configuration') and enumerates the payload contents (saved settings, per-attribute rules, file URL, latest run). The singular 'one feed's' implicitly distinguishes it from the sibling list_feeds and from the mutation sibling update_feed_settings.

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?

Usage is only implied: the schema note 'Feed id from list_feeds' hints that list_feeds is the discovery step, but the description never states when to call this versus list_feeds or update_feed_settings, nor any prerequisites. No exclusions are given.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds useful context beyond that: 'No arguments,' the exact shape of the returned vocabulary, and the worked-example coverage. It stops short of noting caching or size characteristics, so it lands just under full marks.

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?

Front-loaded with the purpose and a single dense paragraph with no filler sentences. The mid-sentence enumeration partially duplicates the output schema, but each item helps an agent decide whether this reference is worth fetching.

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 no-argument reference tool with an output schema present, the description conveys everything needed: what to expect back, when to read it, and how it connects to the mapping-writing flow. Nothing an agent needs before calling is missing.

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?

Zero parameters, which is the baseline-4 case. The description's 'No arguments' is a redundant confirmation of what the empty schema already shows, adding no new semantics.

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 specific resource — the rule vocabulary for feed attribute mappings — and enumerates its exact contents (attributes, product fields, operators, value sources, limits, example). An agent can distinguish this reference tool from the sibling mutation tools like update_feed_settings without opening any schema.

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?

Explicitly instructs 'Read this before proposing any mappings.attributes change,' naming the prerequisite condition. It also explains the relationship to update_feed_settings (one call fixes a field for the whole catalog), so the agent knows when this lookup precedes that write.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds genuinely useful behavior: the overview mode returns per-section summaries and current affected counts, and the detailed mode returns rules, checklist, examples, and target attributes. It stops short of describing any pagination or limits, but for a static reference tool that is minor.

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?

Three sentences, front-loaded with the two-mode behavior, then the payload contents, then the actionable instruction. 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 a zero-required single-enum parameter, an existing output schema, and full annotation coverage, the description supplies everything an agent needs: mode selection, payload expectations, and the pre-change reading requirement.

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 100% and the enum is fully documented, so the baseline is 3. The description goes beyond the schema by explaining the semantic consequence of omitting the parameter versus passing one, which tells the agent how the mode switches. The enumerated section ids largely duplicate the enum, adding little extra.

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 specific verb and resource ('the app's feed optimization playbook') and clearly delineates the two operating modes. It is readily distinguishable from siblings like get_feed or optimize_next.

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?

Explicitly tells the agent what omitting the section does ('so you can pick where to start') and gives a hard directive: 'Read the relevant guide BEFORE proposing changes to any feed attribute it covers.' This is a clear when-to-use rule with a sequencing constraint.

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

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

Annotations already declare a safe, idempotent, non-destructive read. The description adds genuine context beyond them: the data comes from an imported copy created at merchant sync time, and the tool 'fails with instructions' when Search Console isn't connected. It doesn't cover freshness/staleness or pagination, but the failure path is valuable disclosure.

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?

Three tight sentences, front-loaded with the data source, then the two branches, then the failure case. Every sentence earns its place with no redundancy.

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?

With an output schema present, return values needn't be explained, and the description covers both modes, the data origin, and the failure condition. Nothing operationally relevant to invoking this 3-parameter tool is missing.

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 100%, so the baseline is 3, but the description meaningfully interprets productId's presence vs absence (product-level ranking queries vs store-wide mismatch opportunities) and clarifies the ordering (highest impressions first). It does not explain the feedId title-override behavior, keeping it below 5.

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 specific verb and resource ('Lifetime Google Search Console query data for product pages') and clearly delineates its two operating modes. An agent can distinguish it from siblings like optimize_next or list_products without opening the schema.

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?

Gives explicit conditions for each mode: supply productId to get the queries a product ranks for, or omit it for store-wide title/query mismatch opportunities. It also states what happens on failure (Search Console not connected/synced). It stops short of naming sibling alternatives or exclusions, so not a full 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description still adds real value by disclosing the market name/locale distinction so feeds for different languages can be told apart before writing text to them.

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?

Three sentences, zero filler, and front-loaded with the resource scope before the routing guidance and the locale caveat. Every sentence carries information an agent needs.

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?

An output schema exists and annotations cover safety, so return values and permissions need no explanation here. The description supplies the scope, the entry-point role, and the locale nuance, which is everything an agent needs to call a zero-parameter list tool correctly.

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 tool takes zero parameters, so per the rubric the baseline is 4. No parameter meaning is needed and the description correctly spends no words on inputs.

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 specific verb+resource ('List every product group and its feeds') and enumerates the returned fields (type, format, enabled state, market binding, latest generation run). This clearly distinguishes it from get_feed (single feed) and the other list_* siblings.

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?

'Start here to find feed ids' gives explicit entry-point guidance and implies the relationship to get_feed/run_feed which consume those ids. There is no explicit when-not or named alternative, so it falls short of a 5.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description adds traits the annotations cannot express: data freshness ('as of the app's last nightly sync') and aggregation granularity ('one row per issue code', account-level issues included). The staleness caveat materially changes how an agent should qualify its answer.

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?

Three tight sentences, front-loaded with the scoping constraint and the first-call instruction. The middle sentence enumerates return fields (severity, counts, sample products, destinations) that the output schema already carries, which is mildly redundant, but it supports the routing decision.

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?

An output schema exists so return values need no explanation, and the description still supplies the sync-freshness caveat, the account-level coverage, and a complete follow-up workflow. Nothing an agent needs to call and act on this tool is missing.

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 tool takes zero parameters, so there is nothing to disambiguate and the baseline is 4. The description correctly implies whole-account scope rather than suggesting unimplemented filters.

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 specific verb and resource ('Google Merchant Center issues for this store') plus exact output granularity ('one row per issue code with severity, affected product counts, sample products and destinations'). It also scopes coverage explicitly (account-level issues, file feeds and native channel), which distinguishes it from list_products, list_feeds, and get_feed.

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?

Gives an explicit entry condition ('Call this FIRST when the merchant asks why products are disapproved or wants to fix issues') and names the downstream alternatives with sequencing: preview_product to inspect, set_product_override or update_feed_settings to fix. An agent knows both when to pick this tool and what to do next.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered; the description adds value beyond that by disclosing pagination and the exact return shape (include/exclude state, merged vs. separate storeOverrides/feedOverrides, stock, tags, variant SKU/barcode/price/weight, API-feed Google status). It does not cover default page size behavior or limits, but with annotations present this is solid context.

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?

Front-loads the core action ('List products a feed covers, paginated') and every clause thereafter enumerates a distinct returned field or the filter options, so little is wasted. The single run-on sentence plus trailing fragment is dense but not padded.

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?

With an output schema present the return format needn't be explained, yet the description still describes it, and annotations plus full parameter documentation leave no operational gaps. The only shortfall is the absence of sibling-routing guidance for a large sibling set.

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 100%, so all five parameters are already documented in the schema. The description only restates the filter enum values (all | excluded | customized) and adds no format or semantic detail beyond that, so the 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 specific verb (List) and resource (products a feed covers) and enumerates exactly which fields are returned, so an agent can distinguish it from siblings like list_section_products or list_product_issues. The scope is unambiguous without opening the schema.

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?

Usage is implied via 'products a feed covers' and the filter enum, but there is no explicit when-to-use guidance or routing against alternatives such as list_section_products or get_feed. The filter hint duplicates what the schema already states rather than adding selection logic.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive). The description adds real behavioral context beyond them: no per-product enrichment and therefore cheap whole-field scanning, page cap of 50, worst-issue-first ordering on the issues section, and cursor-based pagination. It stops short of describing the reason field's format or failure modes, so not a 5.

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?

Front-loaded with what the tool returns, then when to use it, then section-specific behavior and pagination. Four sentences, each carrying distinct information; no restatement of the title or schema.

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?

An output schema exists, so return shapes need not be re-explained. Given the 4-param, enum-driven tool, the description covers purpose, selection criteria, workflow, sibling alternatives, ordering, and pagination — everything an agent needs to call it correctly.

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 100%, so baseline is 3. The description still adds meaning: 'up to 50' reinforces the limit cap, 'Paginate with nextCursor' ties cursor to the response field, and it explains that section='issues' yields Google's named sample rows ordered worst-first — section-dependent behavior the enum alone does not convey.

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 specific verb+resource (list a page of products flagged by one optimization section) and scopes it precisely: up to 50, with the machine reason, no enrichment. It explicitly distinguishes itself from siblings list_product_issues (counts/docs per code) and optimize_next (one-by-one fixing), so an agent can route without opening schemas.

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?

Gives an explicit when-to-use ('BEFORE optimize_next on any catalog big enough that fixing products one by one is not realistic'), a three-step workflow (read a page, find the shared cause, fix once with update_feed_settings), and names the sibling that covers the alternative need (list_product_issues). Nothing is left to inference.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), and the description adds behavior annotations cannot express: the cursor-chaining loop, the done:true termination signal, and the fact that top search queries are null when Search Console isn't synced. That null-handling caveat and the loop mechanics are exactly the kind of context that prevents an agent from stalling or misreading an empty field.

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?

It is dense and somewhat long, but every sentence carries load: loop scope first, payload contents next, workflow, termination, then the large-catalog alternative. Front-loading the tool's identity before the workflow detail keeps it easy to scan despite the length.

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?

An output schema exists, so return values need not be explained, yet the description still characterizes the payload well enough to be actionable. Combined with the workflow, termination signal, and large-catalog escape hatch, nothing an agent needs to drive this loop correctly is missing.

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 the schema already documents cursor provenance, the feedId default, and the full section enum. The description reinforces cursor chaining ('call this again with the returned cursor') and the section walk but adds no syntax or format detail beyond the schema, so the baseline of 3 is appropriate.

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 states a specific verb and resource ('Returns the next product needing work in a section') and explicitly frames the tool as the one-product-at-a-time loop, which immediately distinguishes it from the batch-oriented siblings. It names the exact payload the call returns, so an agent knows precisely what this tool yields versus what list_section_products yields.

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 explicit when-to-use conditions ('for small catalogs and for the exceptions left after a field-wide fix') and an explicit when-not with the named alternative ('On a large catalog, prefer list_section_products plus one update_feed_settings change over hundreds of overrides'). It also lays out the full surrounding workflow with the sibling tools to call between iterations.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavior beyond that: this executes the actual production mapping pipeline (not a mock) and the output includes overrides and market prices, which is meaningful context an agent could not infer from the annotations.

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 tight sentences with zero filler; the high-value scope and return-content information is front-loaded before the usage hint.

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?

An output schema exists, so return values needn't be enumerated, and the description still characterizes the payload (exact Google items, overrides, market prices). The only minor gap is variant pagination behavior, which the schema already covers via the page parameter.

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% – feedId, productId, and page are all documented in the schema, including pagination size and defaults. The description adds no additional parameter meaning, so 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+resource: it runs the real feed mapping pipeline for one product and returns the exact items Google would receive. The emphasis on 'ONE product' implicitly separates it from the feed-wide run_feed sibling, but it never names an alternative, leaving the differentiation to inference.

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?

Gives a clear situational trigger: 'Use after edits to verify the output.' That tells the agent when to reach for it, but there is no explicit when-not guidance and no named alternative (e.g., use run_feed for a full-feed validation).

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, so 'idempotent' partly restates structured data. The description nonetheless adds genuinely new behavioral context: it is cheap enough that no user confirmation is required, and it duplicates work that other tools trigger implicitly. It does not mention the 'feed must be enabled' precondition, though the schema covers that.

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 tight sentences with no filler; the action is front-loaded and the caveat about automatic runs follows immediately so the agent reads it before invoking. No restructuring would improve it.

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 single-parameter, idempotent trigger tool with an output schema and full annotation coverage, the description supplies everything missing from structured data: cost, lack of confirmation, and its redundancy relative to sibling mutations. Nothing an agent needs to invoke it correctly is absent.

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?

Only one parameter (feedId) with 100% schema description coverage, including its source (list_feeds) and a precondition (must be enabled). The description adds nothing beyond the schema, which is the expected baseline when the schema does the work.

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 specific verb and resource ('Queue a full regeneration of one feed') plus timing ('now'), which cleanly separates it from read-oriented siblings like get_feed and list_feeds. It also distinguishes itself from update_feed_settings and the override tools by framing itself as the manual trigger for the same run.

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?

Explicitly tells the agent when NOT to call it ('unnecessary after update_feed_settings or override changes, which queue a run automatically') and names the sibling tools responsible for that overlap. This is exactly the routing information an agent needs to avoid redundant runs.

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

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

Adds substantial context beyond the annotations: the sent map REPLACES the entire override map (send every attribute you want kept), empty string sends nothing, omitting an existing attribute reverts it to mapped value, and a feed-level override wins over the store-wide one per attribute. It also discloses the preview-by-default safety behavior, which is not expressible via the destructiveHint/idempotentHint annotations alone.

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?

Scoping is front-loaded and every sentence carries operational weight, with the confirm workflow placed last as the closing action. It is dense but slightly long; the destructive replacement warning is repeated in spirit across two clauses.

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?

With an output schema present, the description need not detail return values, yet it still tells the agent what the preview contains ('removes' and 'current'). Combined with the replacement, precedence, and confirm semantics, an agent has everything needed to call this correctly.

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 the baseline is 3, but the description adds genuinely new semantics: empty-string behavior, the per-attribute feed-vs-store precedence rule, and the fact that omitted attributes revert rather than persist. These are not spelled out in the schema.

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 specific verb and resource ('Set one product's attribute overrides and/or include state') and immediately scopes it by feed ('for every feed (omit feedId) or for one feed'). The singular 'one product' framing cleanly distinguishes it from the plural sibling set_product_overrides and set_products_included.

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?

Gives explicit operational workflow: previews by default, show the merchant the proposal, then re-call with confirm:true. It does not, however, name sibling alternatives (e.g. bulk set_product_overrides) or state when to prefer this tool over them, so routing relies on inference from 'one product'.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, but the description goes much further: replacement semantics for the override map, the requirement to resend every attribute that should stay, the removes list in the preview, unknown ids skipped and reported without failing, and a preview-by-default workflow that applies nothing without confirm. It also discloses the batch regeneration side effect. Nothing here contradicts the annotations.

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?

Dense but front-loaded: the batch scope, the title-pass use case, and feedId guidance come before the mechanics. Every sentence carries information, though the paragraph is longer than strictly necessary and could be split for scanability.

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?

An output schema exists so return internals need not be described here. The description still covers the mutation contract, preview/confirm flow, batch limits, and non-fatal error handling, which is everything an agent needs to call this destructive, batch-scoped write safely.

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 100%, so the baseline is 3, but the description adds real meaning: feedId omission writes the feed every feed inherits, confirm gates preview vs apply, and an omitted included preserves current state. This clarifies intent beyond the schema text, though the per-attribute specifics remain in the schema.

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 specific verb, resource, batch scope (up to 200), and the key qualifier 'DIFFERENT' overrides, which separates it from the singular sibling set_product_override. An agent can identify it without opening the schema.

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?

Explicitly says this is 'the tool for a real title pass', explains why a feed mapping cannot substitute (each product needs a different string), and gives a clear rule for feedId: omit by default, name a feed only when that feed needs its own values. This is when-to-use, when-not, and alternative routing in one place.

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

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

Annotations declare destructive/idempotent/openWorld, but the description adds the traits that actually matter to an agent: preview-by-default (applies NOTHING without confirm), the 1000-id ceiling, and that a store-wide exclusion persists in every feed until lifted store-wide. That is richer behavioral context than the annotations supply and does not contradict them.

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?

Three sentences, zero padding, front-loaded with the core action and limits before the preview-vs-apply workflow. Every clause carries operational meaning.

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?

With an output schema present, the description need not explain return values, and it covers the remaining gaps an agent needs: batching limit, feed scoping, preview safety, and store-wide exclusion persistence. Nothing required to call this destructive tool safely is missing.

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 100%, so the baseline is 3; the description earns above that by explaining the consequence of omitting feedId (applies to every feed) and the persistence semantics of an exclusion set without a feedId. The confirm preview/apply mechanic is largely restated from the schema, so it is not a full 5.

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 specific verb pair (include/exclude) on a specific resource (products), plus scope (bulk, max 1000 ids, one feed or all feeds). An agent can place this against set_product_override/set_product_overrides without opening any schema.

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?

Gives explicit operational guidance: omit feedId for store-wide, provide it for a single feed, and call once without confirm to preview then again with confirm to apply. It does not name the sibling override tools or state when to prefer one over this, so it stops short of full alternative routing.

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

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

Adds substantial behavior beyond the annotations: preview-by-default with nothing applied, merge-per-attribute semantics so one field can be fixed per call, precedence over the store's shared rule, conflict protection via the revision token, and the fact that changes only reach Google on the next generation run. The destructiveHint=true annotation is reconciled by the preview gate, not contradicted.

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?

Front-loaded with purpose and ordered sensibly from payload shape to merge semantics to the preview/confirm gate. It is on the long side, and the preview behavior is restated in both the description and the confirm parameter's schema text, which is mild redundancy for a safety-critical point.

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 nested-object mutation tool with an output schema present, the description covers everything an agent needs: payload shape, merge/drop semantics, scoping and precedence, the two-phase confirm flow, the revision guard, and downstream propagation timing. No return-format explanation is needed.

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 already 100%, so the schema itself documents confirm and revision. The description still adds meaning the schema does not carry: that a null attribute value drops the mapping and reverts it to the smart default, and that mappings are feed-scoped and outrank shared rules. That is real added value above the 3 baseline.

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?

Opens with a specific verb and resource ('Update a feed's attribute settings') and immediately characterizes the payload shape ('PARTIAL settings object mirroring the tab shape from get_feed'). It is clearly distinguishable from siblings like get_feed, list_feeds, and the set_product_override family.

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?

Gives an explicit ordered workflow (preview first, show merchant, then call again with confirm: true) plus two named prerequisites: call get_mapping_schema before writing a mapping, and fetch the tab shape from get_feed. It also states the exact condition for dropping a mapping (pass null).

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