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

Adds behaviour the annotations cannot convey: despite readOnlyHint=false, calling it changes no product data and instead returns a preview plus a confirmation link, and only the merchant on that page can commit it. That is exactly the kind of non-obvious, failure-inducing detail an agent needs, and the money-in-cents note is a further unit caveat.

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, front-loaded with the purpose, then the two facts most likely to cause a mistake. Nothing is redundant with the title or schema, and the deferred-write warning is prioritised over the minor unit note.

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 12-parameter tool with a nested mapping object and no output schema, the critical unknowns are covered: full schema descriptions for every field, plus an explanation of the effect (preview only) and the return (preview plus confirmation link). What is missing is minor: relationship to imports_inspect/imports_run is only implied.

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%, including the nested mapping values and enums, so the per-parameter burden is already carried by the schema and the baseline is a 3. The description adds one genuine cross-parameter note (money is integer minor units, cents), which is useful but narrow.

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

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

States a specific verb and resource (create/set up a product import), which cleanly separates it from imports_run, imports_update, imports_inspect and imports_delete by implying it creates the import configuration rather than executing or reading one. It does not name any sibling explicitly, so an agent must infer the boundary, but the purpose is 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?

Usage is implied by the deferred-confirmation workflow: you call this to register an import, then a merchant approves it. However, it never says when to choose this over imports_update (changing an existing import) or imports_run (executing one now), nor what prerequisites exist, so the agent is left to infer the boundary.

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