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

With annotations already declaring readOnly=false, destructive=false, idempotent=false, the description goes well beyond them: build and type-check failures reject the write before committing, the previous source and revision remain intact, warnings do not block the build, and the return is the Asset ID. It also discloses the project-wide compile blast radius and the animation-API restrictions (atTime only; animate/animateIn/animateOut generators refused).

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 core operation, which is good, but the body is a dense wall that mixes several concerns (skill-loading order, import lists, animation API, shared modules, cross-component wiring). Most sentences carry real constraints, yet the skill-loading enumeration and import guidance are verbose and could be tightened or delegated to the skill docs themselves.

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?

No output schema exists, and the description covers the return value (Asset ID), the rejection behavior, revision retention, the shared-module alternative for name, and the cross-component compilation implications. For a mutation tool with 4 required params and a project-wide side effect, nothing essential is missing.

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 75%, so the description partly compensates: it clarifies that replacements are applied together 'in one compile', that an empty replace deletes a span, and that branchId writes a version without switching the editor. Some of this restates the schema descriptions, but the atomic-application framing and the Asset ID return add meaning beyond the field-level docs.

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 — 'Apply exact source replacements to an existing component in one compile' — and immediately contrasts with named siblings ('Use import_element for an unchanged library element and scaffold_component for a skeleton'). An agent can distinguish this from replace_component, scaffold_component, and import_element without opening any schema.

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 routing: alternatives are named for adjacent cases (import_element, scaffold_component, patch_film placement), and the preconditions are spelled out (which builtin skills to load before the first component write, first fontFamily, first DataSrc prop, first flex layout). It also states when to use branchId vs. the current version.

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