Build Reference Replica Prompts

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

Beyond the annotations (destructiveHint=false, openWorldHint=true) the description discloses meaningful behavior: prompts are Pydantic-validated then persisted, no image is generated, and insufficient information yields no executable prompt rather than a silent partial result. It also describes the return payload (design, shared style_digest, per-image task.prompt, actual three-model config, input_images roles, SHA) and states that export and execution share the same ReplicaDrawingPrompt→ImageTask validator/compiler. It does not say whether an existing design is overwritten or how expected_revision conflicts are handled.

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?

It is front-loaded with the purpose and non-goal, and the paragraph breaks roughly follow purpose → prerequisites → scope rules → return/next steps. But the prose is extremely dense, packing several independent constraints into single run-on clauses (e.g. the style/frames sentence), which costs readability for an agent parsing it. Little is pure filler, but the density makes it slower than it needs to be.

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 write tool with a very deep schema, the description covers the critical things: shared-style-only rule, kind consistency per scope, fact/SKU evidence requirements, validation-before-save, and the exact downstream confirmation path. Output schema existence lowers the burden of explaining returns, though it explains them anyway. Remaining gap is concurrency/idempotency (expected_revision) and how this builder relates to build_product_suite_prompts.

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%, and 'brief' is a deep nested object, so the description must carry the load — and it does: it explains that reference_replica.style is the single shared style (colors/lighting/typography/hierarchy), that frames carry only per-image content and composition and must not override scene/style, and that SKU frames need their own real images, real attributes, and legal fact_ids. These are the rules that actually govern the nested structure. It does not explain design_id, expected_revision, or the endpoint/api_format/model switches.

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 clauses give a specific verb and resource ('构造新版竞品复刻提示词'), the two scopes (single image / same-category series, or main+detail+SKU suite), the validation-and-save behavior, and an explicit non-goal ('不出图'). It also distinguishes itself from the legacy plan_reference_replica/export_reference_replica. What it never does is differentiate itself from the closest live siblings (build_product_suite_prompts, export_validated_reference_replica), so an agent must still infer which builder to call for a suite.

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?

Concrete prerequisites are stated: read nanobanana://templates/reference-replica, reference-analysis, or reference_replica_brief first. Scope-specific rules are given (scope=series requires brief.kind to match every frame.kind; product_suite requires brief.kind=main with all three kinds complete), plus the downstream sequence export → confirm_ecommerce_design → authorized submit_ecommerce_design, and the exclusion '新版本须重新确认，不能用普通edits或替换task.prompt'. Missing only an explicit rule for when a caller should pick build_product_suite_prompts or plan_reference_replica instead.

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