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?

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?

Beyond the annotations, the description discloses important behavioral traits: it explains the difference between single and batch responses, the deduplication behavior on re-import ('DSers finds the existing draft (no duplicate)'), and the deprecation of job_id. It also clearly indicates that imports create entries (not read-only) while warning about update operations. No contradictions with 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 lengthy but well-structured and information-dense. It front-loads the core purpose and then details response modes and alternative tools without redundancy. The use of all-caps section headers (e.g., 'SINGLE RESPONSE', 'BATCH RESPONSE') improves scannability, though slightly verbose for a tool 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?

Given the tool's complexity (16 parameters, single/batch modes, no output schema), the description is remarkably complete. It explains what the return previews look like in both single and batch modes, how to handle lost job IDs, and the distinction between this tool and its siblings. No output schema exists, so the description fully compensates by detailing response 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?

The input schema already provides 100% description coverage for all 16 parameters, so the baseline is 3. The description adds value by clarifying parameter relationships and usage patterns, such as 'Provide source_url (single) or source_urls_json (batch)' and 'Optionally apply rules at import time via rules_json or flat params.' However, the marginal gain is limited since the schema already explains each parameter in detail.

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 clear, specific action: 'Import product(s) from supplier URL(s) into the DSers import list and return a preview.' It also names the exact supported platforms (AliExpress, Alibaba, Accio.com), distinguishing this tool from siblings like dsers_product_preview and dsers_product_update_rules by explicitly pointing to them for alternative use cases.

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: 'To UPDATE rules on an existing import, use dsers_product_update_rules instead' and 'Use dsers_product_preview for individual details.' It also advises on batch vs single usage and how to handle expired/lost job IDs, giving clear context and exclusions.

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. The description adds substantial behavioral context: default truncation of options to 10, always-present active_rules and price_summary, column differences between modes, and hard cap of 200. 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 well-organized, covering modes, field meanings, defaults, and usage tips. It is slightly long but every sentence adds value, and information is front-loaded with the core 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?

Despite lacking an output schema, the description thoroughly specifies the return structure (price_summary fields, options structure, active_rules) and behavior differences between modes. It fully compensates for the missing output schema and covers the tool's 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%, so baseline is 3. The description adds meaning beyond schema by explaining key field semantics (e.g., sell_price is store listing price, cost is supplier price), clarifying variant_limit defaults, and advising when to use show_all_options. This extra context elevates the score.

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: 'Reload preview for an import job.' It specifies the resource (import job) and action (reload preview), and distinguishes between compact and full modes, making the purpose unambiguous and distinct from sibling tools that handle imports, updates, or status checks.

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 variant_detail mode ('Use variant_detail='full' when agent needs compare_at or cost columns') and explains default behaviors for variant_limit. However, it does not explicitly compare to sibling tools like dsers_job_status, so overall tool selection context 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?

The description goes well beyond annotations by disclosing merge semantics (replace-by-family vs field-merge), the use of null to remove entire families, the full replacement of option_edits, and the destructive delete of variants for remove_value. This provides critical side-effect visibility beyond the generic destructiveHint=false.

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 efficiently structured: purpose, merge rules, clearing/removal, option_edits actions, and response format. Each sentence contributes unique information, making it 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?

The description covers operational behavior, edge cases for clearing/removing, all option_edits actions, and the response shape. Combined with the rich schema, it is comprehensive for a tool with 13 parameters, no output schema, and complex merge logic.

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?

Despite 100% schema coverage, the description adds substantive semantics for rules_json: explaining merge behavior, clearing fields with empty string/null, removing families via null, and the DELETE consequence of remove_value. These details are not fully captured in the schema description, raising the value beyond the baseline.

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

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

The description opens with a clear, specific action: 'Update pricing, content, images, or variant rules on an already-imported product.' It identifies the resource (rules on an imported product) and disambiguates from sibling tools like import or preview by focusing on 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 strong context for when to use ('already-imported product') and detailed how-to guidance (merge behavior, clearing, removal of families). However, it does not explicitly name alternative tools or state when not to use it, leaving the distinction to the reader.

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?

The annotations (readOnlyHint=true, destructiveHint=false) already cover safety, but the description adds valuable behavioral context: it returns an effective_rules_snapshot, warnings for adjustments, and blocking errors. 'Normalize' could imply mutation, but the readOnlyHint clears that up, so no 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 three sentences, front-loaded with the primary action, then usage context, then return values. Each sentence earns its place with clear labeling of outputs (effective_rules_snapshot, warnings, errors) 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?

Given only 2 parameters and no output schema, the description fully covers the tool's purpose, timing, and return structure. It even explains what errors mean in the context of a dependent tool (dsers_product_import), making it complete for an agent to understand when and how to use it.

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 per the baseline rules, a score of 3 is appropriate even without additional param detail. The description reiterates the types of rules (pricing, content, images) but adds nothing beyond the schema's existing parameter 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 uses specific verbs 'check and normalize' and clearly identifies the resource ('rules object against the provider's capabilities'). It distinguishes itself from siblings by explicitly stating this is a pre-import validation step, with unique return values like effective_rules_snapshot, warnings, and errors.

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 clearly states when to use it ('before importing') and ties it to the follow-up tool (dsers_product_import). It does not explicitly mention when not to use it or list alternative tools, but the intended context is unambiguous.

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.