Preview imported schematic normalization

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description still adds real value beyond that: determinism, a stable plan ID, a model hash, and the presence of validation gates/warnings/blockers all describe the output contract and behavior, which the structured fields do not.

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?

Two dense sentences, front-loaded with the core action and output artifacts, closing with the critical read-only guarantee. 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?

An output schema exists, so return-value explanation is not needed, and the behavioral contract (deterministic, read-only, plan ID, gates) is well covered. But for a 6-parameter tool with 17% schema coverage, the description leaves the parameter semantics entirely unaddressed, which is a meaningful completeness gap.

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 description coverage is only 17% (just projectId is documented), so the description must compensate for the other five parameters (componentLimit, normalizeNetNames, annotateReferences, componentOverrides, resolveMetadataExpressions) and it does not mention any of them. An agent gets no elaboration on what these toggles or overrides do.

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?

Names a specific verb+resource (read the live schematic, produce a normalization plan) and enumerates the concrete artifacts produced: stable plan ID, model hash, proposed operations, validation gates, warnings, blockers. This clearly distinguishes it from write/apply siblings and from the audit tool, since it is explicitly a read-only planning step.

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?

The read-only, never-writes framing implies this is the preview/plan step taken before an actual normalization write, and the 'plan ID' hints at a follow-up commit. However, no sibling alternative is named (e.g., audit_imported_design) and there is no explicit when/when-not guidance, so usage is only implied.

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