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 cover key behavioral traits (read-only, non-destructive, idempotent, closed-world), so the bar is lower. The description adds value by detailing the status lifecycle (preview_ready → push_requested → completed/failed) and return fields, which are not captured in annotations. It does not contradict annotations, as checking status aligns with read-only operations.

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 the core purpose, followed by essential details like status lifecycle and return values in a compact two-sentence format. Every sentence adds value without redundancy, making it highly efficient and well-structured.

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 (single parameter, no output schema) and rich annotations, the description is largely complete, covering purpose, usage context, and return details. However, it lacks explicit error handling or edge-case information, such as what happens with invalid job IDs, which slightly reduces completeness.

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 the job_id parameter fully documented in the schema. The description adds minimal semantics by linking job_id to specific tools (dsers_product_import or dsers_store_push), but does not provide additional details beyond what the schema offers, meeting the baseline for high coverage.

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 ('Check the current status') and resource ('import or push job'), distinguishing it from sibling tools like dsers_product_import or dsers_store_push which initiate jobs rather than track them. It precisely defines the tool's function without being tautological.

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 by referencing job IDs from dsers_product_import or dsers_store_push, providing clear context for when to use this tool. However, it does not explicitly state when not to use it or name alternatives, such as dsers_import_list for broader job listings, which prevents a perfect score.

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?

While annotations already indicate destructiveHint=true, the description adds substantial behavioral context beyond annotations: the irreversible nature ('IRREVERSIBLE — the product cannot be recovered'), the two-step confirmation flow, business consequences ('losing the supplier mapping'), and detailed agent protocol requirements. This significantly enhances understanding of the tool's 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 appropriately sized and front-loaded with critical information (irreversible nature, confirmation requirement). While comprehensive, every sentence adds value - no redundant information. The structure moves from core functionality to business context to agent protocol in a logical flow.

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 destructive tool with no output schema, the description provides complete context: clear purpose, usage guidelines, behavioral transparency (including irreversible consequences), parameter semantics, business implications, and detailed agent protocol. It addresses all aspects needed for safe and correct tool 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?

With 100% schema description coverage, the baseline is 3. The description adds meaningful context about the confirm parameter's purpose in the deletion flow ('If called without confirm=true, returns a confirmation prompt — show this to the user') and the import_item_id's business significance ('losing the supplier mapping'), providing semantic understanding beyond the schema's technical documentation.

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 'Permanently delete a product from the DSers import list' - a specific verb ('delete') and resource ('product from DSers import list'). It clearly distinguishes from siblings by specifying this only affects the import list, not store listings, and mentions alternatives like using Shopify/Wix admin directly for store 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?

The description provides explicit guidance on when to use this tool vs alternatives: 'Only removes the product from DSers import list (pre-push staging area). Products already pushed to Shopify/Wix stores are NOT affected — to remove a store listing, use the Shopify/Wix admin directly.' It also specifies prerequisites (user confirmation) and the multi-step protocol 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?

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?

The description adds valuable behavioral context beyond annotations: it explains the workflow position, mentions that it returns specific fields (job_id, status, visibility_mode), and the input schema description provides risk warnings about 'sell_immediately' mode. While annotations cover idempotency and non-destructive nature, the description adds practical workflow context that helps the agent understand when and why to use this tool.

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?

Extremely efficient three-sentence structure: first states purpose, second provides usage guidelines, third specifies return values. Every sentence earns its place with critical information, and it's front-loaded with the most important context (when to use it in the workflow).

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 tool with good annotations and full schema coverage, the description provides excellent workflow context and return value information. The only minor gap is that without an output schema, the description could provide more detail about the return format, but it does list the specific fields returned, which is helpful. It adequately covers the tool's role in the broader workflow.

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 schema already fully documents both parameters. The description doesn't add any parameter-specific information beyond what's in the schema descriptions. It mentions the parameters indirectly through the return values but doesn't provide additional semantic context about how they should be used.

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 ('Change the visibility mode'), target resource ('a prepared job'), and distinguishes it from siblings by explicitly mentioning when to call it ('between dsers_product_import and dsers_store_push'). It goes beyond the title's generic 'toggle' to specify the actual modes (draft vs published).

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 to use this tool ('Call this between dsers_product_import and dsers_store_push') and names the specific sibling tools it works with. It also implies when not to use it (outside that workflow) and provides clear sequencing guidance that helps distinguish it from other product-related 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 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=true, destructiveHint=false, and idempotentHint=true, covering safety and idempotency. The description adds valuable context beyond annotations: it explains that ae_expired doesn't block imports (clarifying a potential confusion) and plan_issue only appears for real subscription problems, which helps the agent interpret responses correctly. 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?

Front-loaded with the core purpose, followed by critical usage instructions and behavioral notes. Every sentence earns its place: the first states what it does, the second explains its foundational role, the third details return values, the fourth clarifies error conditions, and the fifth provides procedural 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?

Given the tool's complexity as a discovery endpoint with no output schema, the description is complete: it explains the purpose, usage sequence, return structure (stores with id, name, etc., and rules), and key behavioral nuances (ae_expired, plan_issue). With annotations covering safety, this provides all necessary context for an agent to use it effectively.

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 the single parameter 'target_store'. The description doesn't add any parameter-specific information beyond what's in the schema, but it implies the parameter's role by mentioning store IDs from the response. Baseline 3 is appropriate since the schema handles parameter documentation.

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' and the resources 'available stores and supported rules', specifying it's for the connected DSers account. It distinguishes from siblings by explaining this is the foundational discovery call that provides IDs and configuration needed by all subsequent operations, unlike product-specific or rule-specific 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?

Explicitly states 'Call this first' and provides clear when-to-use guidance: to get store IDs and configuration for subsequent operations. It distinguishes from alternatives by noting this is for discovery, not for imports, previews, etc., and explicitly says 'do NOT retry discover' after calling, preventing misuse.

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 what annotations provide. While annotations indicate destructiveHint=true and non-idempotent behavior, the description details specific safety checks (pricing validation, stock validation), warning thresholds (low margin <10%, low stock <5 units), response structure (blocked vs warnings arrays), and the consequences of different visibility modes (backend_only vs sell_immediately). This significantly enhances the agent's understanding of the tool's operational 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 efficiently structured with clear sections: safety checks, three operational modes, and response format. Every sentence adds value—no redundant information or fluff. It's front-loaded with critical safety information, followed by operational details, making it easy for an agent to parse.

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 lack of output schema, the description provides comprehensive context. It covers safety mechanisms, operational modes, parameter interactions, and detailed response format. The description successfully compensates for the missing output schema by explaining what success/failure responses contain.

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 would be 3, but the description adds meaningful context about parameter interactions and usage patterns. It explains how job_ids_json takes priority over job_id, clarifies the relationship between target_store and target_stores_json for different modes, and provides concrete examples of JSON structures. However, it doesn't fully explain all parameter combinations beyond what's implied in the three modes.

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 ('Push one or more prepared import drafts') and target resources ('to the connected Shopify or Wix store(s)'). It distinguishes this from sibling tools like dsers_product_import (which creates drafts) and dsers_product_update_rules (which modifies rules rather than pushing 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?

The description provides explicit guidance on when to use this tool versus alternatives: it specifies three distinct modes (single push, batch push, multi-store push) and when each applies based on parameter combinations. It also includes clear safety warnings about when to use force_push and when not to (e.g., 'ONLY after explaining the risk to the user').

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