Prepare Ac

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

Annotations already declare readOnlyHint=false and idempotentHint=false, so the write/non-idempotent profile is known. The description adds nothing beyond that: it does not say what file is mutated, whether the directive is appended or replaces an existing one, or what happens on repeat calls. For a mutation tool the description contributes essentially no behavioral 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?

The single sentence is short and has no padding, but it is under-specified rather than concise. Brevity here comes from omitting necessary information, not from tight editing.

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?

With 6 parameters, 17% schema coverage, no output schema, and no annotations explaining the mutation, the description is far too thin. An agent cannot determine what values to supply for the sweep parameters or what the call will change in the schematic.

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 workspace_root), and the description compensates for none of it. The domain-critical parameters f_start, f_end, sweep, and points — the actual AC sweep configuration — are undocumented in both the schema and the description, leaving their formats and units entirely unknown.

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 verb ('Insert') and a resource ('.ac directive'), but 'Ac' is never expanded and the statement largely restates the tool name 'prepare_ac'. It makes no attempt to distinguish itself from the many sibling analysis preparers (prepare_dc_sweep, prepare_transient, prepare_noise), leaving an agent to infer the relationship from naming convention alone.

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 guidance on when to use this tool versus prepare_dc_sweep, prepare_transient, or the other prepare_* siblings, nor any stated prerequisite such as a prior create_schematic call. The agent must guess the context entirely from the tool name.

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