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

Although annotations indicate the tool is not read-only (readOnlyHint=false) and not destructive, the description adds important behavioral constraints such as conditional parameter requirements ('content_language and feed_label must be both set or both omitted') and the return value (DataSource with dataSourceId). This goes beyond what annotations alone convey, though it does not disclose error conditions or idempotency details.

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 four sentences long and dense with necessary information, front-loading the core purpose. Each sentence serves a purpose, from usage context to conditional rules. It is longer than minimal examples, but the complexity of the tool (7 parameters, conditional logic) justifies 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?

The description captures the tool's essential context: what it creates, why it's needed, key parameter constraints, and the return value. It does not explain behavior on invalid input or specific account defaults, but those are covered in the schema. Given the lack of an output schema, the description does enough to guide correct 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 provides 100% coverage with descriptions for all parameters. The description rephrases and summarizes some parameter relationships (e.g., 'countries applies to primary sources only') but does not introduce substantial new meaning beyond the schema. It provides a useful high-level recap but remains at the baseline for schema-heavy tools.

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 clearly states the tool's action: 'Creates an API (generic) data source' and explains its role as the target needed by other tools (insert_product_input, update_product_input, insert_promotion). It distinguishes itself from sibling tools like list_data_sources and get_data_source by focusing on creation.

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 explicitly provides when-not guidance: 'Only API sources can be created through the API (file, UI and autofeed sources are set up in Merchant Center)' and indicates when to use it as a prerequisite for other data input tools. This effectively steers the agent away from inappropriate uses.

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?

Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description adds crucial behavioral details: the operation is async (processed product disappears after minutes) and returns an empty object on success. This helps the agent set expectations and handle the response appropriately.

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 action, then adding necessary context about source specificity and async behavior. Every sentence earns its place with no redundancy or fluff.

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?

The tool is simple, with all parameters documented in the schema and the description providing the key behavioral caveats (async processing, empty return). The absence of an output schema is compensated by explicitly stating the return value. Annotations cover safety, making this complete for an agent.

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 documents all three parameters with 100% coverage, including formats and the data_source requirement. The description adds little beyond emphasizing data_source is required and explaining the multi-source nuance, which is helpful but not essential since the schema already marks it as required.

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 clearly states the verb 'Deletes' and the resource 'a product input from a specific data source'. It distinguishes from siblings like insert_product_input and update_product_input by emphasizing the targeted removal from a specific source, which is a unique scope.

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 clear context on when to use this tool: when deleting a specific product input from a specific data source, with the nuance that the same product can exist in multiple sources. It doesn't explicitly mention alternatives or when not to use, but the purpose is clear enough for selection.

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?

Discloses key behavioral traits: the fetch runs asynchronously, returns an empty object on success, and errors on API-type sources. While annotations indicate non-read-only, non-idempotent, non-destructive, the description adds valuable context about async execution and the return contract, though it doesn't mention permissions or rate limits.

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 succinct sentences: purpose, usage condition, and return/async behavior. Every sentence provides unique, necessary information with no redundancy or fluff. The core action is front-loaded, making it easy to scan.

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 the tool's moderate complexity (trigger action, async execution, error condition), the description covers all critical aspects: what it does, when it's valid, what it returns, and how it executes. No output schema exists, so the explicit 'empty object on success' is especially important. The sibling tools are many, but the description sufficiently differentiates this tool from them.

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% for both parameters, with detailed descriptions in the schema itself. The tool description does not add new parameter syntax or formats, but it does contextualize the data_source parameter by reinforcing the file-feed requirement, which the schema only implies in a separate sentence about product/promotion writes.

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 uses a specific verb 'Triggers' and a clear resource 'file-based feed', immediately distinguishing this from read-only tools like get_data_source. It also explicitly mentions 'outside its regular schedule', clarifying the unique purpose.

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 states when the tool is applicable ('file input and fetch settings (scheduled fetch or Google Sheets)') and when it is not ('calling it on an API-type source is an error'). This provides clear usage boundaries and echoes the data_source schema description to reinforce the 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 readOnly, idempotent, and non-destructive behavior. The description adds valuable context by enumerating the returned fields and noting the account resource format, which helps set expectations beyond the safety profile. No contradictions with 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?

The description is two focused sentences: the first states the action and result fields, the second gives practical use cases. Every word earns its place, with no filler or 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?

Given the low complexity (one optional parameter, no output schema) and complete annotations, the description adequately conveys what the tool returns and when to use it. It is sufficient for an agent to select and invoke this 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 single parameter 'account' is fully documented in the schema with a clear description and default behavior. Since schema coverage is 100%, the description does not need to add parameter syntax, and it offers no additional parameter-level meaning.

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 uses a specific verb 'Returns' and identifies the resource as 'a single Merchant Center account', listing key fields. It distinguishes itself from the sibling 'list_accounts' tool by emphasizing 'single' account retrieval.

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 explicitly states the tool is 'Useful to verify the configured account or inspect a sub-account', providing clear contexts for use. However, it does not explicitly name alternatives or state when not to use it, so it misses the full 'when/alternatives' bar.

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 read-only nature is covered. The description adds value by specifying exactly what is returned and the constraint around re-fetching, which goes beyond annotation coverage.

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 concise, information-dense sentences. The first front-loads the core purpose and return fields, while the second delivers actionable guidance. No wasted words.

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 read-only retrieval tool with two well-documented parameters and no output schema, the description sufficiently covers the return value, usage context, and the key caveat about fetch settings. It is complete for its complexity.

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% for both parameters, with the data_source parameter already describing both ID and full name forms. The description reaffirms the ID/name format but does not add additional meaning beyond the schema, so baseline 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 clearly states the tool returns one data source by numeric ID or full resource name, listing the fields returned (type, input, feed configuration, fetch settings). This distinguishes it from sibling tools like fetch_data_source, which performs a different operation.

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 to check the 'input' field before calling fetch_data_source, and clarifies that only file-based feeds with fetch settings can be re-fetched. This provides direct guidance on when to use this tool vs the fetch tool.

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?

The description adds meaningful context beyond the annotations: it explains the significance of the 'claimed' field, noting it's a prerequisite for serving offers, and clarifies that no claiming/unclaiming tool exists. This complements the readOnlyHint and idempotentHint annotations without contradicting them, though it doesn't detail response format or error behavior.

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 two sentences long, front-loads the primary purpose, and every clause adds value. It avoids redundancy and clearly communicates the tool's role, the meaning of its output, and a relevant workaround. No unnecessary fluff.

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 the simple nature of the tool (one optional parameter, no output schema), the description is sufficiently complete. It provides enough context for an agent to decide when to use it and what to do with the result. A minor gap is the lack of explicit return type, but the description names 'uri and claimed' which suffices.

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 fully documents the single optional 'account' parameter, including the default behavior (omit to use GOOGLE_MERCHANTS_ACCOUNT_ID) and format. The description does not add additional parameter-level detail beyond what the schema already provides, so a baseline score 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 clearly states the tool's function: 'Returns the store homepage of an account: uri and claimed'. It identifies the specific resource (store homepage) and the two data points returned. This unambiguously distinguishes it from sibling tools like get_account or get_shipping_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?

The description provides implicit usage context by explaining that an unclaimed homepage is a common cause of account-level problems, suggesting when to call this tool for diagnostics. It also gives an explicit alternative for the related mutation (raw_request) and notes that claiming/unclaiming is not exposed as a tool, guiding the agent away from unsupported operations.

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 safety (readOnlyHint, idempotentHint, non-destructive). The description adds behavioral context beyond annotations: the tool returns itemLevelIssues, supports multiple ID formats (including base64url and legacy local prefix), and may return 404 for recent products due to async processing. This is valuable context without contradicting 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?

The description is two focused sentences. The first sentence states the core function and key use case; the second covers identification and a timing caveat. No filler, key information front-loaded.

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 read tool with rich annotations and full schema coverage, the description is complete enough. It explains the main output focus (itemLevelIssues), how to specify the product, and a caveat about 404s. It does not enumerate all possible return fields, but no output schema exists and the description highlights the most relevant details for the tool's purpose.

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?

Although the schema provides 100% parameter descriptions, the tool description adds crucial semantic meaning by explaining the two alternative identification methods ('product' vs. content_language+feed_label+offer_id) and the format details. This goes beyond what the schema fields individually state.

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 clearly states the tool returns 'one processed product including productStatus.itemLevelIssues' and explicitly identifies it as 'the place to see why a product is disapproved.' This specific verb+resource+scope distinguishes it from list_products and other sibling tools.

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 clear usage context: use this to inspect item-level disapproval reasons. It also explains how to identify the product via two alternative formats and warns that a recently inserted product may 404 until processing completes. It does not explicitly mention alternatives like list_products, but the purpose is clear enough to guide selection.

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 safe read-only nature is known. The description adds value by disclosing that the response includes approval status and item-level issues, which is behavioral detail beyond 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?

A single concise sentence that leads with the action and resource, then adds the key purpose and return details. Every word earns its place; no fluff or repetition.

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?

There is no output schema, so the description carries the burden of explaining what is returned. It mentions promotionStatus and itemLevelIssues, which covers the most important return aspects for the stated use case. It does not describe the full response structure, but given the tool's simplicity and annotations, it is sufficient.

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% with clear descriptions for both parameters (account and promotion). The description does not add extra parameter syntax or format details; it only references the promotion ID implicitly. Baseline 3 is appropriate because the schema fully documents parameters.

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 uses a specific verb ('Returns') and clearly identifies the resource ('one promotion'). It also names key return fields (promotionStatus, per-destination approval, itemLevelIssues), distinguishing it from list_promotions and insert_promotion.

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 explicitly states the intended use case: 'the place to check whether a freshly inserted promotion was approved.' This gives clear context for when to call it, though it does not explicitly mention when not to use it or name alternative tools like list_promotions.

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 and destructiveHint; the description goes beyond by explaining the API's only write is a full replace, why that's dangerous, and what fields are returned (services, warehouses, etag). This is substantial additional behavioral 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?

Two sentences: the first front-loads the return payload, the second provides a critical safety caveat. No wasted words.

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 read-only getter with one optional parameter, the description fully specifies return contents, notes safety, and warns about the dangerous write path. It covers all needed context without an output schema.

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 sole parameter 'account' is fully described in the schema (100% coverage), including role and default behavior. The description itself adds no extra parameter semantics beyond the schema, 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?

The description clearly states the tool returns account-level shipping settings, listing specific components (services[], warehouses[], etag). It distinguishes itself from sibling get_ tools by specifying the resource.

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 provides when-to-use and when-not-to-use: read-only by design, warns against the dangerous full-replace write, and suggests raw_request for writes. This gives strong guidance on when to invoke this tool versus alternatives.

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?

Goes well beyond annotations: it discloses full replacement (aligned with destructiveHint=true), the MOVES behavior when the data source differs, async processing lag, and that data-quality issues appear later in productStatus.itemLevelIssues instead of API errors. No contradiction with 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?

Every sentence carries distinct value: core upsert behavior, data-source constraint, MOVES edge case, return shape, async behavior, and price format. The most important semantics are front-loaded 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?

For a complex 8-parameter write tool with no output schema, the description is remarkably complete: it explains return values, async behavior, error behavior, destructive replacement, and the trickiest parameter format. The remaining parameter details are already in the 100%-covered schema.

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?

Even though the schema already covers parameters at 100%, the description adds critical semantics: the exact price object shape with amountMicros/currencyCode, the 1 unit = 1,000,000 micros conversion, and the meaning of data_source (API-type only). This materially helps an agent construct correct input.

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 action (Uploads/upserts a product) and resource (API data source), and clearly explains the replace semantics on the contentLanguage~feedLabel~offerId triple. It does not explicitly differentiate from the update_product_input sibling, though the 'fully replaced' wording implies the distinction.

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?

Provides clear when-to-use context: only API-type data sources, with an explicit exclusion (file feeds cannot be written) and an alternative way to create the required source (create_data_source). It stops short of fully routing the agent between insert/replace and the update_product_input sibling, so it is strong but not exhaustive.

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 mark readOnlyHint=false, but the description adds valuable context: the data source body quirk, required fields, and async approval with promotionStatus returned. This goes beyond annotations by explaining the write behavior and return value. It doesn't cover potential side effects of updates or error cases, but the disclosed behavior is substantial.

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 four sentences, front-loaded with the core action and then key caveats. Each sentence adds non-redundant information, though it's slightly long for a simple tool. The logical flow from action to quirk to requirements to return/async works well.

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 the nested promotion object and no output schema, the description covers requirements, optional attributes, return type, and async workflow. It also points to get_promotion for later status checks, making the tool's place in a workflow clear. No major gaps are apparent.

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 already covers all three parameters, but the description adds extra meaning: it clarifies the data source travels in the body despite being a parameter, lists required fields within the promotion object, and decodes optional attributes like couponValueType and promotionEffectiveTimePeriod. It also adds ISO/CLDR format details not in the schema, significantly enriching parameter understanding.

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 'Creates or updates a promotion,' clearly stating the action and resource. It distinguishes from sibling tools like insert_product_input and get_promotion by specifying it handles promotions and noting an upsert behavior, making its purpose unambiguous.

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 says 'Unlike product writes, the data source travels in the request BODY,' providing a specific usage note that differentiates this from product-oriented tools. It also directs checking get_promotion later for async approval, offering a follow-up path. However, it doesn't explicitly state when not to use this tool, so it misses a complete exclusion list.

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, openWorld, and non-destructive hints. The description adds useful behavioral context: it lists accessible accounts, returns a specific structure, includes pagination via nextPageToken, and gives a filter syntax example. This goes beyond the annotations without contradicting 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, each earning its place: purpose, return structure, and usage guidance. Front-loaded with the primary verb and resource. No fluff or 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?

Despite having no output schema, the description compensates by listing the exact return fields and nextPageToken. It covers authentication scope, pagination, filter syntax, and the typical first-step use case. Slightly less complete than a perfect list tool description because it omits error scenarios or default page size, but the schema already provides limits.

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 descriptions cover 100% of the three parameters (filter, page_size, page_token) with examples and constraints. The description repeats the filter example but adds no new semantic detail beyond the schema. With full schema coverage, the baseline is 3, and no additional value is provided.

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?

Clear verb 'Lists' with specific resource 'Merchant Center accounts'. The description names the returned fields and nextPageToken, and explicitly distinguishes this tool from siblings by stating it is the first step to discover the account ID other tools need.

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?

Provides explicit when-to-use guidance: 'Use it first to discover the account ID the other tools need'. Also mentions an alternative (setting GOOGLE_MERCHANTS_ACCOUNT_ID once). However, it doesn't explicitly mention when not to use it or name alternative sibling tools, 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 already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds transparency about the return structure: each data source has specific fields, exactly one type object, and fileInput for file feeds. This is valuable context beyond the annotations, helping the agent know what to expect in the response even though there is no output schema. It does not contradict 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?

The description is three sentences and information-dense. The first sentence defines the action, the second lists the output fields, and the third explains a primary use case. Every sentence adds value, though the second sentence is a bit long. It is structured and front-loaded with the main purpose.

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 the tool is a simple listing operation with no output schema and strong parameter documentation, the description covers the essential context: it explains the return data structure and gives a concrete usage scenario. It does not explicitly mention pagination behavior, but the schema's page_token description already covers that. The description is sufficient for an agent to select and invoke the 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?

Schema description coverage is 100%, with each parameter (account, page_size, page_token) fully described inline. The description does not add any additional meaning about parameters beyond what the schema already provides. It focuses on the return data and usage, which is useful but not parameter-specific. Baseline 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 explicitly states the tool 'Lists the data sources of an account' – a specific verb and resource. It also describes the key fields of each data source (name, dataSourceId, displayName, input, type object, fileInput), which clearly distinguishes it from sibling tools like get_data_source and list_promotions. The purpose is unambiguous and complete.

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 gives a clear use case: 'Use it to find the API-type data source that insert_product_input / insert_promotion require as data_source.' This directly tells when to use the tool. However, it does not explicitly mention when not to use it or provide an alternative reference (e.g., get_data_source for a single data source), 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral detail: 'Daily counters reset at 12:00 UTC — midday, not midnight.' This clarifies a potentially confusing aspect beyond what annotations provide. No contradiction with 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?

The description is two sentences with no filler. The first sentence front-loads the core purpose and output shape, while the second adds the critical reset-time detail and the diagnostic use case. Every phrase contributes value, and it is appropriately sized for the tool's complexity.

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?

There is no output schema, but the description compensates by explicitly listing the output fields (quotaGroups[] with name, quotaUsage, quotaLimit, quotaMinuteLimit, methodDetails[]). It also covers the daily reset behavior and the primary use case (429 errors, headroom). For a read-only diagnostic tool, this is complete and well-rounded.

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 parameters (account, page_size, page_token) are fully documented in the schema. The description does not add parameter-specific guidance beyond the schema, but it does describe the output structure (quotaGroups, methodDetails) which indirectly relates to how parameters affect results. Baseline 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 begins with 'Shows the account's Merchant API usage vs limits per method group', clearly identifying the verb (shows), resource (Merchant API quota usage), and scope (per method group). It distinguishes from sibling tools like list_products or list_promotions by focusing on quota diagnostics and explicitly mentions the quota sub-API.

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 clear context by stating 'Use it to diagnose HTTP 429 RESOURCE_EXHAUSTED errors and to see how much headroom is left.' This gives a specific use case, but it does not explicitly mention when not to use it or name alternative tools, so it stops 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 already cover read-only, open-world, idempotent, and non-destructive nature. The description adds significant context about account type restrictions and filter constraints, which are not in annotations. It doesn't detail pagination behavior or edge cases, but the schema covers page_size and page_token.

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 main purpose. Each sentence provides essential information: what it returns, key restrictions, and an alternative. No wasted words or 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?

Without an output schema, the description explains return values (stats and itemLevelIssues). It covers account-type restrictions and filter limitations. It doesn't detail response structure or pagination flow, but schema covers pagination parameters. Adequate for a read-only listing tool.

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 parameters are already well-documented. The description reinforces the filter constraint with an example but adds no meaningful semantics beyond the schema. The baseline is appropriate at 3.

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 clearly states the tool lists aggregate product statuses per reporting context and country, with specific stats and itemLevelIssues. It distinguishes itself from get_product for single product issues, and the verb 'lists' with resource 'aggregate product statuses' 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?

Explicitly states it works only for sub-accounts and standalone accounts, not advanced accounts, and limits the filter to reporting_context and country. It also directs users to get_product for single product issues, providing clear when-to-use and alternatives.

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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses the open-world behavior (no server-side filter), async visibility of new products, and important format quirks (NO channel segment, base64EncodedName for hostile characters). No contradiction with 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?

The description is dense but every sentence provides value: purpose, key fields, filtering guidance, and async caveat. It is well-structured and not redundant.

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?

Despite lacking an output schema, the description covers the essential return fields, resource ID structure, important caveats, and alternative tools. It gives a complete picture for an AI agent to select and use the 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 schema already documents all three parameters with 100% coverage, so the description doesn't need to explain them. It adds some contextual value about resource naming and URL-hostile handling, but this is about output fields rather than parameter usage. 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?

The description clearly states the tool 'Lists the processed products of an account' with a specific verb and resource, and distinguishes it from sibling tools like list_promotions and list_accounts.

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 explicitly states when to use this tool vs alternatives: 'The list has no server-side filter — filter via search_reports on product_view.' Also mentions async processing for recently inserted products, providing timing guidance.

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 indicate read-only, idempotent, non-destructive behavior. The description adds behavioral context by explicitly mentioning nextPageToken for pagination and the detailed return composition, which goes beyond the annotations. No contradictions exist.

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 a single sentence that conveys the purpose, return structure, and pagination succinctly. It is information-dense but not overly verbose; each element serves a purpose, though the long field list makes it slightly heavy.

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 no output schema, the description fully covers the return values including field names and nested statuses, plus pagination via nextPageToken. The parameters are well-documented in the schema, and the tool's moderate complexity is adequately addressed. No significant gaps remain.

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 has 100% coverage for all three parameters, each with clear descriptions. The tool description does not add additional parameter semantics beyond what the schema provides, so the baseline score 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 clearly states the tool lists promotions for an account, with a specific action verb 'Lists' and a defined resource. It details the return fields including nested structures like promotionStatus with destination statuses and itemLevelIssues, distinguishing it from sibling tools like get_promotion (single promotion) or list_products (different resource).

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 implies usage as a list operation for promotions but does not explicitly state when to use it versus alternatives such as get_promotion or insert_promotion. There is no mention of exclusions or specific scenarios, so guidance is only implicit.

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=truelok and idempotentHint=true, so safety is covered. The description adds crucial behavioral details: it is a wrapper over a canned query, it requires Market Insights opt-in, and price amounts are in micros and may be strings. It also explains the business meaning of results, which goes beyond 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?

The description is dense but well-structured: it opens with the core function, then details the benchmark, the interpretation, the prerequisite, the price format, and the optional parameter. Every sentence adds value; nothing is redundant. It's appropriately sized given the complexity.

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?

The tool is a read-only report query with no output schema. The description explains the business meaning, the data format quirk (micros, strings), the prerequisite, and the optional filtering. Combined with full schema coverage and read-only annotations, the agent has all necessary information 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 each parameter already has a description. The tool description adds context about the country parameter (narrows to one report country) and mentions the price format (micros, strings) which relates to the output but not directly to parameters. Overall, the description doesn't add much beyond what the schema provides.

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 clearly states the tool's purpose: a convenience wrapper over a canned MCQL query that compares product prices against a market benchmark, and explains the outcome (priced above benchmark loses clicks). It distinguishes it from related tools like price_insights by specifying the exact view and report_country_code.

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 explicitly mentions the prerequisite (opted into Market Insights) and the consequence of not meeting it (empty rows). It also notes the optional country filter narrows results, giving clear context for use. No alternative tools are named, but the specificity about the view and the opt-in requirement provide strong usage guidance.

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?

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds useful context about how the wrapper works (canned MCQL query) and warns about empty rows without opt-in, which the annotations do not cover. However, it doesn't disclose other behavioral traits such as no pagination details beyond the standard schema, or potential rate limits, but given the strong annotation coverage, the added context justifies a 3.

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 a single focused paragraph that front-loads the core purpose (wrapper over canned query and what it returns) then adds the key caveat and a data format note. Every sentence earns its place, though it could be slightly more scannable with bullet points.

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 read-only wrapper with 3 fully-described parameters and 100% schema coverage, the description does well. It explains the return structure (predicted_*_change_fraction, effectiveness bucket) and the opt-in requirement. However, it omits details on how the effectiveness bucket is computed or what to do if the opt-in is missing (it only says rows are empty), and there's no output schema to lean on. The absence of those details is a minor gap.

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 descriptions cover all 3 parameters (account, page_size, page_token) with 100% coverage, including the default behavior for account and the requirements for page_token. The description doesn't add additional parameter-level details beyond what's in the schema, so a baseline 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 clearly states it is a convenience wrapper over a canned MCQL query on a specific view, and lists exactly what it returns: suggested_price, predicted change fractions, and an effectiveness bucket. This distinguishes it from the sibling search_reports and price_competitiveness by specifying the data source and the canned nature. It is specific and action-oriented.

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 explicitly mentions a prerequisite (Market Insights opt-in) that must be met for non-empty rows, and it implies this is the tool to get suggested pricing data from the product view. It doesn't explicitly name alternatives that should be used instead, but the canned nature and specific view suggest that search_reports or raw_request could be alternatives for more custom queries, though this is not stated.

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?

The description warns that the tool 'Can create, modify and delete data', which aligns with the destructiveHint and readOnlyHint annotations. It adds context by framing the tool as an 'escape hatch' and reminding the agent to prefer dedicated tools, but it does not disclose additional behavioral nuances such as rate limits or error handling. Given the annotations already cover the safety profile, the extra caution is useful but not extensive.

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 dense but every sentence contributes: purpose, example paths, prefix list, query/body semantics, and a safety warning. It is front-loaded with the core 'escape hatch' concept and never wastes words, making it both informative and scannable.

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 generic raw API tool with no output schema, this description is complete. It covers the path format, required prefix, query parameter usage, body handling, HTTP method options, and the critical warning about mutation. It gives the agent enough context to safely invoke the tool for arbitrary endpoints.

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?

Beyond the schema's 100% description coverage, the tool description adds semantic depth: it explains the path prefix requirement, gives concrete query parameter examples (dataSource for productInputs writes, updateMask for PATCH), and clarifies that body is sent as JSON. This significantly enriches understanding of how to construct parameters.

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 clearly identifies this as an 'Escape hatch' for calling any Merchant API v1 path directly, specifically for endpoints without a dedicated tool. It names the exact resource (Merchant API v1) and distinguishes itself from siblings by noting it should be used only when no dedicated tool exists.

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 explicitly states when to use this tool ('for endpoints without a dedicated tool') and when not to ('use the dedicated tools when one exists'). It also gives concrete examples of paths and explains the required sub-API prefix, providing actionable guidance that contrasts with the sibling tools.

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 mark the operation as read-only and idempotent, and the description adds valuable behavioral details beyond that: field naming differences, the no-SELECT* rule, required date ranges, opt-in requirements, and the fact that each result row has exactly one populated view object. No contradictions with 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?

The description is dense but well organized: it opens with the core function, lists relevant tables, provides query rules, and closes with the product-filtering use case. The list of view names is long but necessary, and every sentence contributes useful information; only slightly less scannable due to the packed table list.

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 query tool with no output schema, the description covers the critical context: supported tables, query rules, example syntax, prerequisites, result-row behavior, and the key sibling alternative. Pagination is already documented in the parameter schema, so nothing essential is missing for an agent to call this 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?

Schema coverage is 100%, so the schema already documents all four parameters. The description goes beyond the schema by clarifying query-level semantics such as snake_case versus camelCase, valid table names, the no-SELECT* restriction, and the date-range requirement for performance views, adding meaningful guidance for the query parameter especially.

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 ('Runs a Merchant Center Query Language (MCQL) query via reports:search') and enumerates the exact supported tables. It also differentiates this tool from sibling list_products by noting it is the way to filter products, making its purpose unmistakable.

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 concrete usage conditions: performance views require a date range, price_* views require the Market Insights opt-in, and product filtering should use this tool because list_products has no filter. This gives the agent explicit when-to-use and when-not-to-use guidance relative to alternatives.

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 only state readOnlyHint=false (mutation), openWorldHint=true, idempotentHint=false, destructiveHint=false. The description adds substantial behavioral detail: update_mask semantics (comma-separated paths, omission applies all populated fields), the local rejection of masked paths without values (and pointing to raw_request for intentional erasure), the async refresh of the processed product, and the requirement that data_source match the source. These go beyond the annotations without contradicting 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?

The description is a single dense paragraph but logically front-loaded: purpose → key constraint → mask behavior → return → alternative. Every sentence carries necessary information, though it could be marginally tightened without loss. It avoids redundancy with the schema, so it earns a 4.

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 the tool's complexity (mask semantics, async processing, alternatives for creation/clearing), the description covers all essential call-time aspects: how to specify fields, mask handling, data_source requirement, return value (updated ProductInput), and the async refresh. No output schema exists, but the return type is stated. Nothing an agent needs to invoke it 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 coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining how update_mask interacts with request fields (must carry a value for each masked path, erasure behavior), clarifies that data_source must be the source holding the input, and gives a concrete example for product_attributes. This elevates it above a bare schema repeat, earning a 4.

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 ('Sparse-updates') and resource ('existing product input'), and immediately differentiates from siblings by calling it 'the cheap way to change price or availability without re-sending the whole product.' It explicitly names insert_product_input as the alternative for creation or wholesale replacement, so an agent can distinguish without opening other 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?

It gives explicit when-to-use ('cheap way to change price or availability'), a key prerequisite ('data_source must be the source holding the input'), and alternatives ('use insert_product_input' for create/replace, 'use raw_request' to intentionally clear attributes). No ambiguity remains about selection among siblings.

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