Plan Ecommerce Design

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

Beyond readOnlyHint=false and openWorldHint=true, it discloses versioning semantics (each call creates a new revision), optimistic-concurrency requirements, that missing information produces a needs_input response with questions, the return content (per-frame title, body, fact citations, subject and layout), and a governance constraint that the draft must be shown to the user and is not approval. These are material traits that no annotation or schema field conveys.

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 first sentence front-loads the core purpose and the rest is dense but every line carries distinct operational information (concurrency, evidence requirements, defaults, output shape, approval boundary) with no filler. It reads as telegraphic fragments rather than cleanly labelled sections, which slightly raises parsing cost for such a long 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?

For a tool with four required nested payloads, an enormous brief schema and an output schema, the description covers workflow, evidence rules, defaults, versioning and the not-approved caveat. The main gap, given 21 siblings, is that it never names the confirmation or export step (confirm_ecommerce_design, build_product_suite_prompts) an agent should take next.

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?

Top-level schema description coverage is 0%, so the description must carry the load, and it does: expected_revision semantics, brief completeness, edits as optional per-image changes, facts requiring a source, benchmarks versus reference_choice/request-or-skip, default counts (5 main, 10 detail screens, one SKU image per variant with its own real photos), and canvas size/ratio needing user confirmation. It does not explain design_id, endpoint/api_format/model selection, or the suite/replica mutual exclusion beyond a passing mention.

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 opening clause gives a specific verb+resource (save/free draft of main image, detail page and SKU design) plus an explicit scope boundary: '不出图' (produces no images). That separates it from generate_images and submit_image_tasks, though it never distinguishes itself from the closely named sibling plan_ecommerce_images, leaving a real ambiguity for an agent choosing between the two.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear operating rules: expected_revision=0 for a new draft, current revision + complete brief + optional per-image edits for modification, every call yields a new version requiring re-confirmation. It also states prerequisites (view actual product photos, fill visual_observations and sourced facts, supply benchmarks or record a user's reason for skipping) and the fallback behaviour (return needs_input and questions). What it lacks is explicit naming of alternatives such as confirm_ecommerce_design or plan_reference_replica.

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