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

Annotations already declare readOnlyHint=false and destructiveHint=true; the description earns credit for going beyond that by naming failure modes (DesignAttachedError for items with a design already attached, UploadMappingSubmittedError for submitted mappings) and side effects (Compass reuses a design or creates an upload-only target that must not be used with design_chat). However, it does not explain why the call is flagged destructive, nor whether anything existing can be overwritten – a notable gap given destructiveHint=true.

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 purpose before branching into conditions and errors, which is the right order. The closing paragraph about markdown hyperlinks and the "Open upload page" card is prescriptive but operationally relevant to how the returned url gets surfaced; the wording is dense but almost every sentence carries a constraint.

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 of this complexity the description covers invocation, parameter selection, failure modes, downstream effects on design_chat/design_generate_candidates, and how to present the returned url. An output schema exists, so explaining return values further is unnecessary.

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 0%, so the description carries the full burden and mostly does: design_id means an existing design, order_id means an order created in this session, item_id applies when an order has several items, and their precedence is spelled out. Only session_id, the required parameter, is left undefined.

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?

"Return a browser page for uploading the user's own logo or photo" gives a specific verb and resource, and the conditional framing ("this client cannot receive its bytes") tells the agent what situation the tool exists for. It falls short of full sibling differentiation: the several other upload-related siblings (design_request_image_upload, order_get_artwork_upload_page, design_confirm_image_upload) are never named as alternatives, so the agent must infer the boundary.

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 invocation conditions ("Call when the user wants to add an image and this client cannot receive its bytes"), explicit prohibitions ("never ask for a local file path or claim images cannot be accepted"), and an explicit ordering constraint relative to design_generate_candidates. It further states precedence among design_id, order_id, and item_id, which is exactly the decision the agent needs to make.

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