fastmean_annotate_circuit

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

With readOnly=false and destructive=false already in the annotations, the description still adds real behavioral detail: sources are unchanged, root TD/FD settings are retained, SCM model dependencies are packaged privately, native child-instance parameter declarations are unsupported, and no calculation or GUI is launched. The sentinel rule '[] clears saved traces; None preserves them' is exactly the kind of destructive-behavior disclosure annotations cannot convey. It loses a point only because these facts are scattered mid-paragraph and the copy-destination behavior is left implicit.

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?

Purpose is front-loaded in the first sentence and every subsequent sentence carries information. Density is high and some phrasing is genuinely hard to parse ('mapping to an expression for convenience value fields'), and the td_signals/fd_signals explanation is split across two non-adjacent sentences including the sentinel rule.

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 the description rightly omits return-value detail and instead spends its space on mutation semantics and limitations. For a six-parameter tool with zero schema descriptions, it covers five of six parameters and the preservation/clearing rules. The remaining gap is what 'path' points at and where the resulting copy lands, which the agent must infer.

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 0%, so the description carries the full burden, and it largely meets it: it explains that parameters maps ASCII identifiers to finite numbers/SI literals, that bindings maps root component names either to expressions for convenience value fields or to native scalar fields (with a concrete example), that descriptions creates native TEXT objects, and that td_signals/fd_signals replace saved active expressions with example syntax like db(U(OUT)/U(IN)). The required 'path' parameter is never described at all, which is a notable hole for the one mandatory argument.

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 opening sentence gives a specific verb and resource: it adds numeric constants, text explanations and saved native formulas to a copy of a circuit. That is materially more informative than the tool name alone. It stops short of distinguishing itself from near neighbours such as fastmean_edit_parameters, fastmean_edit_values and fastmean_edit_properties, which an agent would need in order to pick correctly.

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?

Guidance is implicit rather than stated: 'Sources remain unchanged' plus 'Does not launch calculations, a window or desktop automation' sketches the boundary of the tool without ever naming an alternative or a condition for choosing it. An agent can infer this is for persisting annotations onto a copy rather than editing values or running analysis, but the exclusions (when NOT to use this instead of edit_parameters/edit_values) are never spelled out.

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