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

With no annotations, the description carries the burden and does well: it discloses the default short-lived signed https link, the inline byte behavior and host fallback, the export-vs-native renderer tradeoff, the ui-builder-export capability requirement, and that unboxed nodes are reported rather than drawn at a guessed position. It omits side-effect/read-only framing and rate-limit context.

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?

Dense and front-loaded — the core output (PNG with overlays plus JSON) leads, then optionality, then renderer caveats. Sentences are long but each carries distinct information; no filler.

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 an output schema exists, the description needn't detail returns, yet it still specifies the JSON contents (revision, node ids/boxes, pin threads/positions) and the envelope caveat ('Not an McpResponseEnvelopeV1'). For an 8-param tool with one enum and nested viewport, this is complete enough to invoke 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?

Schema coverage is already 88%, so the 3 baseline is met by the schema; the description adds real meaning beyond it by explaining renderer semantics (export vs native, capability, box reporting), what each overlay in `include` draws, and the image-pixel coordinate basis of the returned JSON. This exceeds the baseline the schema alone would justify.

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+resource: render a design the way the editor shows it, as a PNG with overlays plus JSON metadata. It clearly distinguishes itself from siblings like ui_builder_render_native and ui_builder_export by naming the composite (image + JSON report) output and the overlay set.

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?

Gives strong in-tool context: the default export renderer reports no node boxes, native is needed when selection must be outlined and requires the ui-builder-export capability, and inline:true vs the default signed link. It does not explicitly route to sibling tools (e.g. when to prefer ui_builder_render_native or ui_builder_export instead), so it stops short of full alternative guidance.

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