Scaffold Behavioral Subcircuit

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

Annotations already disclose that this is a non-read-only, non-destructive, non-idempotent, closed-world write, so the safety profile is covered. The description adds the meaningful constraint that the written schematic contains a single behavioral source, but says nothing about whether output_path is overwritten, what happens on error, or why the operation is non-idempotent.

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?

A single front-loaded sentence with no wasted words, stating the core action immediately. It is efficient, though arguably too terse given the tool's complexity.

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 no output schema, 33% parameter coverage, and 3 parameters, the description is too thin. It omits the expression format, overwrite behavior, and any usage context, leaving the agent under-informed for correct invocation.

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 33%: only workspace_root is documented, while expression and output_path are bare. The description alludes to a behavioral source but never explains the expression syntax or the meaning/format of output_path, so it fails to compensate for the coverage gap.

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 description gives a clear verb (write) and resource (a schematic whose only active device is a behavioral source), which distinguishes it from the generic create_schematic/create_starter_schematic and the protocol scaffolds. However, it does not explain what a 'behavioral subcircuit' scaffold contains or how it differs from materialize_reference_circuit, so sibling differentiation is only partial.

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?

There is no explicit when-to-use or when-not-to-use guidance and no alternative tool is named. The 'only active device is a behavioral source' clause implies a scope but never tells the agent under what conditions this scaffold is preferable to create_schematic or add_component.

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