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

Annotations already indicate read-only, non-destructive, idempotent, and closed-world behavior. The description adds valuable context beyond this: pagination details (use search_after for next page, results may overlap between pages requiring deduplication by product_id), response truncation (truncated_from field for image search), and input validation (empty keywords rejected). 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 front-loaded with core functionality (search for import) and efficiently covers key points like pagination, integration, and limitations in clear sentences. It could be slightly more concise by avoiding minor repetition (e.g., 'import_url' mentioned multiple times), but overall it's well-structured with zero waste.

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 (8 parameters, no output schema) and rich annotations, the description is complete: it explains the purpose, usage flow, pagination, deduplication, truncation, and input validation. It effectively compensates for the lack of output schema by describing response fields like import_url, search_after, and truncated_from.

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 fully documents all 8 parameters. The description adds minimal parameter-specific semantics beyond the schema, such as noting keyword and image_url are mutually exclusive (implied in schema) and that image_url takes priority. It doesn't provide additional syntax or format details, 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 searches the DSers product pool (AliExpress supplier catalog) for products to import, specifying it can search by keyword or image URL. It distinguishes from siblings by mentioning direct integration with dsers_product_import via the import_url field, unlike other tools like dsers_my_products or dsers_store_discover.

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?

Explicit guidance is provided: use this tool to find products for import, then use dsers_product_import with the import_url, followed by dsers_import_list and dsers_store_push. It distinguishes from alternatives by noting results are for direct import via dsers_product_import, and it specifies when not to use it (empty/whitespace-only keywords are rejected).

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, destructiveHint=false, idempotentHint=true, and openWorldHint=false. The description adds valuable behavioral context beyond annotations: explains the staging area nature, minimum 20 items per page API behavior with client-side truncation, and how to interpret specific fields (no_markup=true, low_stock_warning). 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?

Well-structured with front-loaded information about what the tool returns, followed by field explanations, usage guidance, and behavioral notes. Every sentence adds value with zero wasted words. The description efficiently covers multiple aspects in a compact format.

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 (list browsing with specific field interpretations), the description provides complete context: detailed return field explanations, behavioral notes about API pagination, clear guidance on when to use versus siblings, and next-step actions. No output schema exists, but the description thoroughly documents what's returned.

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 fully documents both parameters (page and page_size). The description adds some context about the minimum 20 items per page behavior when page_size < 20, but doesn't provide additional parameter semantics beyond what's in the schema. Baseline 3 is appropriate when schema does the heavy lifting.

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 ('browse') and resource ('DSers import list') with specific scope ('with enriched variant data'). It distinguishes from siblings by explicitly mentioning dsers_my_products for products already on store and dsers_find_product for searching new products.

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?

Explicit guidance is provided on when to use this tool ('staging area before push') versus alternatives: use dsers_my_products for products already on store, dsers_find_product for searching new products. Clear context about what this tool provides versus other options.

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 tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context by outlining the status lifecycle and return fields (job_id, status, target_store, push_status, warnings). This goes beyond the annotations and helps the agent anticipate what the tool will report and how to interpret it.

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 action and resource. Includes the status lifecycle and return fields without any filler. Every word earns its place, making it easy to scan and understand quickly.

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 read-only status tool, this description covers the purpose, lifecycle, and return payload. Since there is no output schema, the return field list is essential and provided. It omits error handling for invalid job IDs, but that is a minor gap given the tool's simplicity and the annotations covering idempotency.

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 the sole parameter, so the baseline is 3. The description adds extra context by specifying that job_id comes from dsers_product_import or dsers_store_push, helping the agent know where to find a valid job ID. This is useful guidance beyond the raw schema definition.

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?

Description uses a specific verb ('Check') and resource ('status of an import or push job'), clearly distinguishing it from sibling tools that perform imports, pushes, and product management. It immediately tells the agent what this tool does and why it is separate from the others.

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 implicitly defines when to use this tool: after initiating an import or push, you check its status. It also describes the lifecycle of statuses, giving context on what to expect. It does not explicitly state exclusions or alternatives, but sibling tools are all different operations, so there is no ambiguity about when this tool applies.

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 valuable behavioral context beyond what annotations provide: it discloses the API's minimum page size constraint ('DSers API returns a minimum of 20 items per page'), explains client-side truncation behavior ('If page_size < 20, results are truncated client-side'), and details the return format with specific field descriptions. While annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, the description enriches understanding of operational behavior without contradiction.

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 efficiently structured with zero wasted sentences: it opens with the core purpose, specifies required parameters, details the return format, provides sibling differentiation, and concludes with important behavioral notes. Every sentence adds essential information, making it both comprehensive and concise.

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 (list operation with pagination), rich annotations (readOnlyHint, destructiveHint, idempotentHint), and full schema coverage, the description provides excellent contextual completeness. It covers purpose, prerequisites, return format, sibling differentiation, and critical behavioral constraints (minimum page size, truncation). While there's no output schema, the description adequately compensates by detailing the return structure.

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?

With 100% schema description coverage, the input schema already fully documents all three parameters (store_id, page, page_size) with their types, constraints, and descriptions. The description adds minimal parameter-specific information beyond the schema, mainly reinforcing the store_id requirement and mentioning page_size behavior, but doesn't provide significant additional semantic context. This meets the baseline expectation when schema coverage is complete.

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 specific action ('Browse products already pushed to a store'), identifies the resource ('products'), and explicitly distinguishes it from sibling dsers_import_list ('To see products waiting to be pushed, use dsers_import_list'). This provides precise differentiation from alternatives.

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 explicit guidance on when to use this tool ('Browse products already pushed to a store') versus when to use an alternative ('To see products waiting to be pushed, use dsers_import_list'). It also specifies a prerequisite requirement ('Requires store_id (from dsers_store_discover)'), giving clear context for proper usage.

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 include destructiveHint=true, but the description adds substantial context: the operation is 'IRREVERSIBLE,' requires 'explicit confirmation,' only affects the pre-push staging area, and deletes the supplier mapping. It also discloses the confirmation-prompt behavior when confirm=true is absent. This greatly exceeds what the annotations alone convey and introduces no contradictions.

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 structured with clear sections (main purpose, confirm requirement, scope, business context, agent protocol). Every sentence contributes meaningful information, avoiding fluff. Despite its length, it is front-loaded with the core purpose and organized so an agent can quickly extract the essential safety and usage instructions.

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 that this is a destructive operation with no output schema, the description covers all necessary context: what is deleted, what is not affected, the supplier-mapping consequence, and the required user-consent workflow. It explains the return behavior (confirmation prompt) and provides enough detail for an agent to use the tool safely and 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?

Although the input schema provides descriptions for both parameters, the description enriches them significantly. It clarifies the confirm parameter's two-step flow: the first call without confirm=true returns a confirmation prompt, and a second call with confirm=true executes only after user approval. It also specifies how to obtain import_item_id from dsers_product_preview or searchImportList results, which is not 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?

The description opens with 'Permanently delete a product from the DSers import list,' which uses a specific verb ('delete') and resource ('product from the DSers import list'). It clearly distinguishes itself from sibling tools such as dsers_product_import, dsers_product_preview, and dsers_store_push, making the 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?

The description explicitly states when to use this tool and when not to. It says only products in the import list are affected, and for store listings it directs to 'use the Shopify/Wix admin directly.' It also provides a detailed agent protocol: show the user product title and supplier URL, warn that deletion is irreversible, and obtain explicit consent before setting confirm=true.

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 valuable behavioral context beyond annotations: it explains the risk implications of visibility_mode (backend_only vs sell_immediately), describes response formats for single vs batch imports, and clarifies idempotent behavior for re-imports with expired job IDs. While annotations cover basic safety (readOnlyHint=false, destructiveHint=false), the description provides practical implementation details that help the agent understand consequences.

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 well-structured and front-loaded with the core purpose, then efficiently covers key usage scenarios. While comprehensive, some sentences could be more concise (e.g., the batch response explanation is somewhat verbose). Overall, most content earns its place by addressing distinct aspects of tool behavior.

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 tool with 18 parameters and no output schema, the description provides substantial context about response formats, risk considerations, and sibling tool relationships. It compensates well for the lack of output schema by describing single vs batch response structures. The main gap is not explicitly covering all possible error conditions or rate 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?

With 100% schema description coverage, the input schema already documents all 18 parameters thoroughly. The description adds minimal parameter semantics beyond the schema - it mentions the source_url vs source_urls_json distinction and hints at rules_json structure, but doesn't provide significant additional parameter understanding that isn't already in the schema descriptions.

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 specific action ('Import product(s) from supplier URL(s) into the DSers import list and return a preview'), identifies the resources involved (products from AliExpress, Alibaba, Accio.com), and distinguishes it from siblings by explicitly mentioning when to use dsers_product_update_rules instead for rule updates.

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 explicit guidance on when to use this tool vs alternatives: it specifies to use dsers_product_update_rules for updating rules on existing imports, dsers_product_preview for individual details, and clarifies behavior for expired/lost job IDs. It also distinguishes between single and batch usage contexts.

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, destructiveHint=false, and idempotentHint=true, so the agent knows this is a safe, repeatable read operation. The description adds valuable behavioral context beyond annotations: the default modes, field truncation behavior, hard cap of 200 variants, and that active_rules is always present (even if empty). 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 appropriately sized and front-loaded with core functionality. Every sentence adds value: explaining modes, key fields, options behavior, and usage tips. It could be slightly more structured with bullet points for clarity, but there's minimal wasted text.

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 (6 parameters, no output schema) and rich annotations, the description provides comprehensive context. It explains return data structure, behavioral defaults, and practical usage scenarios. The main gap is lack of explicit output format details, but the description compensates with field explanations and usage guidance.

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 all parameters thoroughly. The description adds some semantic context (e.g., explaining that sell_price is 'store listing price, $' and compare_at_price is 'strikethrough, $'), but most parameter details are already in the schema. Baseline 3 is appropriate when schema does the heavy lifting.

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: 'Reload preview for an import job' with specific details about two modes (compact and full) and what data they return. It distinguishes this from siblings like dsers_job_status (which likely shows status only) and dsers_product_import (which initiates imports).

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 explicit guidance on when to use different modes: 'Use variant_detail='full' when agent needs compare_at or cost columns' and 'Set include_images=true... useful for visual SKU matching across suppliers.' It also distinguishes this from other tools by focusing on previewing import job data rather than finding, importing, or managing products.

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 indicate non-read-only, non-destructive, non-idempotent, open-world hints. The description adds substantial behavioral context beyond annotations: explains incremental merging rules, clearing mechanisms, option_edits replacement behavior, response format (compact preview), failure states (persist_failed blocks subsequent push), and retry/re-import recovery options. 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 appropriately front-loaded with core purpose, followed by detailed behavioral rules. Every sentence adds value: merging rules, clearing methods, option_edits actions, response format, and error handling. Slightly dense but well-structured for a complex tool.

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 mutation tool with no output schema, the description provides comprehensive behavioral details (merging, clearing, failure states) and parameter semantics. It covers key aspects like incremental updates and error recovery, though doesn't explicitly document all 13 parameters' usage scenarios or sibling tool relationships.

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?

With 100% schema description coverage, the baseline is 3. The description adds meaningful semantic context: clarifies rules_json structure (keys, merging behavior, clearing rules), explains option_edits actions with examples, and distinguishes between rules_json and flat parameters. However, it doesn't fully detail all 13 parameters' interactions beyond 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?

The description clearly states the verb ('Update') and resource ('pricing, content, images, or variant rules on an already-imported product'), distinguishing it from siblings like dsers_product_import (import new) or dsers_product_delete (remove). It specifies this is for incremental rule updates rather than full replacements.

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 context ('on an already-imported product') and mentions retry scenarios, but doesn't explicitly state when to use this versus alternatives like dsers_product_import for new products or dsers_rules_validate for validation. It provides operational guidance but lacks comparative sibling differentiation.

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. The description adds workflow timing and return fields but does not disclose additional behavioral traits (e.g., confirmation needed for sell_immediately), which appears only in the schema parameter description. This is adequate but not rich 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?

Three short sentences deliver purpose, workflow placement, and return fields without redundancy. Front-loaded with the core function and no 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 combination of full schema coverage, annotations (idempotent, non-destructive), and a description that states purpose, timing, and return fields fully contextualizes the tool. The lack of an output schema is compensated by the explicit return fields listed.

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 detailed parameter descriptions including risk warnings for visibility_mode. The description itself does not add parameter-specific semantics beyond what the schema already provides, 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 changes the visibility mode of a prepared job, using a specific verb ('Change') and resource ('visibility mode'). It further explains the effect (switch between draft and published) and distinguishes itself from siblings by positioning it between dsers_product_import and dsers_store_push.

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 call this tool between dsers_product_import and dsers_store_push, providing clear workflow context. However, it does not mention alternatives or exclusions, though the placement is sufficient for this specific toggle.

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, destructiveHint=false, and idempotentHint=true, covering safety and idempotency. The description adds valuable behavioral context beyond annotations: it specifies validation outcomes (warnings for extreme pricing values, errors for blocking issues), security validation (HTML description fields against script injection), and normalization behavior ('normalize a rules object'). No contradictions with annotations 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 efficiently structured with two sentences: the first states the core purpose and usage context, and the second details specific validation behaviors. Every sentence adds essential information without redundancy, and it's front-loaded with the primary function.

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 (validation with normalization and multiple rule types), annotations cover safety aspects well, but there's no output schema. The description compensates by detailing return components (effective_rules_snapshot, warnings, errors) and specific validation logic. However, it could be more complete by explicitly mentioning idempotency or providing examples of error formats.

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%, providing detailed documentation for both parameters. The description adds minimal parameter semantics beyond the schema: it implies the 'rules' parameter is validated against provider capabilities and mentions specific validation thresholds (e.g., multiplier >100x). However, it doesn't significantly enhance understanding of parameter usage beyond what the schema already covers.

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 with specific verbs ('check and normalize', 'verify') and resources ('rules object', 'pricing, content, and image rules'). It distinguishes from siblings like dsers_product_import by focusing on validation rather than execution, and from dsers_product_update_rules by emphasizing pre-import checking.

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 ('before importing') and why ('to verify... are valid and see exactly which ones will be applied'). It names a specific alternative (dsers_product_import) for post-validation actions and indicates blocking issues must be fixed before calling that sibling.

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 substantial behavioral context beyond annotations: it explains the default safe mode ('preview'), the two discovery paths (STRICT vs DISCOVER), the workflow sequence, the auto_confidence threshold implications ('DSers does NOT validate supplier payload correctness; data errors only surface at order fulfillment time'), and OAuth scope requirements. While annotations cover basic hints, the description provides rich operational 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 information-dense but well-structured with clear sections (DEFAULTS, discovery paths, WORKFLOW, Returns, requirements). Every sentence adds value, though the length pushes it toward comprehensive rather than concise. The front-loaded safety warning about mode='preview' is particularly effective.

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 (7 parameters, destructive operation, multiple modes) and the presence of both annotations and output schema, the description provides excellent completeness. It covers the operational workflow, safety considerations, mode differences, practical usage scenarios, and OAuth requirements. The output schema handles return values, so the description appropriately focuses on behavioral context.

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?

With 100% schema description coverage, the baseline is 3. The description adds meaningful context about parameter interactions: it explains how 'new_supplier_url' determines the mode (STRICT when provided, DISCOVER when omitted), clarifies that 'max_candidates' is DISCOVER-mode only, and provides practical guidance about 'auto_confidence' thresholds. However, it doesn't add syntax or format details beyond what the schema already documents.

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 verb ('Replace') and resource ('supplier on a store product') with specific scope ('SKU-level variant matching'). It clearly distinguishes this tool from siblings by focusing on supplier replacement rather than product discovery, import, deletion, or rule management.

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 explicit guidance on when to use each mode: 'preview' for safe read-only analysis and 'apply' for actual writes. It also distinguishes between STRICT mode (when you have a specific supplier URL) and DISCOVER mode (when the current supplier is broken/out-of-stock and you need auto-discovery). The workflow section gives clear step-by-step instructions.

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. The description adds valuable behavioral context beyond annotations: it explains the meaning of ae_expired and plan_issue flags, clarifies that ae_expired does not block imports, and advises not to retry the tool. These are non-obvious behaviors that an agent needs to know, fully satisfying transparency.

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 somewhat long but every sentence serves a purpose: stating the main function, giving usage timing, describing return values, clarifying error flags, and setting expectations for the next step. It is well-structured and front-loaded, though it could be trimmed slightly without losing 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?

Given the tool's low complexity (one optional parameter, no output schema), the description thoroughly covers what an agent needs: what is returned, how to interpret flags, when to call it, and what to do afterward. It is complete for the tool's context and annotations.

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% for the single optional parameter, so the baseline of 3 applies. The parameter description already explains filtering, omission behavior, and how to use the values in later calls. The tool description adds no additional parameter semantics beyond what the schema provides, but it does not need to.

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 ('Retrieve'), resource ('available stores and supported rules'), and scope ('for the connected DSers account'). It also distinguishes the tool by positioning it as the mandatory first call whose response is needed by all subsequent operations, setting it apart from 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 explicitly instructs when to use the tool ('Call this first'), how to proceed after ('proceed to the next step'), and what not to do ('do NOT retry discover'). It also provides context on handling response flags (ae_expired vs. plan_issue), giving clear when-to-use guidance without naming 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 annotations (destructiveHint=true), the description discloses extensive behavioral details: automatic pre-push validation, blocking vs. warning thresholds, hard stop vs. soft alert semantics, and the requirement to explain risks before using force_push. This is exactly the kind of behavioral context that annotations do not provide.

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 long but well-structured with clear sections (SAFETY, modes, SAFETY RESPONSE). It is front-loaded with the core purpose. Every section provides necessary detail, though there is slight repetition of the warning/block distinction between the SAFETY section and the response description.

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 fully enumerates success response fields (job_id, status, target_store, etc.) and error/warning structures ('blocked', 'warnings'). It also references related tools (dsers_product_import, dsers_store_discover) and conveys preconditions, making it self-contained for a complex batch/multi-store 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?

All 7 parameters have descriptions in the input schema (100% coverage), so the bar is at baseline 3. The description adds value by explaining inter-parameter relationships (e.g., job_ids_json takes priority, target_stores_json for multi-store) and mode-specific usage, though some of this is already present in the schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb + resource: 'Push one or more prepared import drafts to the connected Shopify or Wix store(s).' It clearly distinguishes this from siblings like dsers_product_import (import drafts) or dsers_product_preview (preview).

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 describes three usage modes (single, batch, multi-store), parameter priority order (job_ids_json takes priority over job_id), when target_store is required, and the condition for force_push (only after user confirmation of risk). This is clear when-to-use guidance with exclusions.

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