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

Annotations already declare readOnly=false, destructive=false, idempotent=false, openWorld=false, so the safety profile is partially covered. The description adds real behavior beyond them: it refuses to overwrite an existing element, verifies OpenDSS actually created it, reads properties back, and re-solves by default. That is substantive mutation-context disclosure, though permission requirements and failure modes are not spelled out.

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 purpose, then the sibling comparison, then a short Args/Returns block — no filler. The Args line largely restates the schema field names, which is the one mildly wasted sentence.

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 values need not be described, and the description still summarizes them briefly. Naming conventions, overwrite refusal, creation verification, and re-solve behavior are all covered; only explicit permission/error behavior 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?

The Args line enumerates the wrapper fields (element_class, name, properties, solve), which is mostly redundant with the schema, but 'Use element_class + name, not Class.Name in name' and the sample properties dict add phrasing/format semantics an agent cannot recover from the schema alone. With reported 0% top-level description coverage this compensates meaningfully, though it does not document each property individually.

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 ('Create a new element ... from a properties dict and re-solve') and names concrete element classes plus the sibling it replaces ('Typed alternative to opendss_run_command("New ...")'). An agent can distinguish it from opendss_run_command and the read-only siblings 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?

Explicitly positions itself against opendss_run_command and gives a concrete condition ('typed alternative', 'use element_class + name, not Class.Name'), plus the refusal behavior implies existing elements are out of scope. It never explicitly names opendss_edit_element as the alternative for existing elements, so the when-not routing is only implied.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds genuine operational context by stating it solves in snapshot mode and returns convergence/counts/losses, but it says nothing about session state effects (e.g., whether compiling replaces a currently loaded circuit) or failure behavior.

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 description is short, front-loaded with the core action, and uses compact Args/Returns sections with no filler. The Returns block is slightly redundant given an output schema exists, but the overall structure is efficient.

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?

Since an output schema exists, the return summary need not be spelled out, and the core purpose plus main input is covered. However, a mutation-leaning one-parameter tool omits the response_format option and any note on how compiling interacts with existing session state, leaving real gaps.

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 reported as 0%, so the description carries the full burden, yet it only restates the two obvious fields (dss_path and optional buscoords_path) with no format or path semantics. The third nested parameter, response_format (markdown|json), is never mentioned, leaving an agent unaware of the output-format control.

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 specific verb+resource: compile an OpenDSS model from a .dss file and run power flow, which is concrete and unambiguous. It implicitly separates itself from the sibling opendss_compile_script via 'from a .dss file on disk', but that differentiation is left for the agent to infer rather than stated.

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?

Usage is implied by the phrase 'from a .dss file on disk', which hints this is the path-based route versus a script-content route, but no alternative tool is named and no when-not condition is given. An agent can guess the context but is not explicitly routed.

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

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

Annotations declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and the description adds genuinely useful behavior beyond them: the server writes the script to a temporary file, compiles, and solves in snapshot mode. It does not contradict the annotations (temp-file write is not a destructive persistent mutation). It omits failure/convergence behavior, but the core process is disclosed.

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 action and the key constraint ('inline', multi-line), then a short paragraph on internal behavior, then Args/Returns. Every sentence earns its place; the Args/Returns blocks are slightly redundant given the schema and output schema but not wasteful.

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 an output schema present, the description need not explain return values, yet it still summarizes them (convergence, counts, losses). Combined with the annotations and the behavioral note about temp-file compilation, an agent has enough to call it correctly; only explicit sibling routing 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 description coverage is effectively low for the wrapper level, so the description carries the burden: it explains that the script is the complete multi-line DSS text, adding meaning over the schema's terse field note. However, the response_format parameter is never mentioned in the description. Adequate but partial.

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 specific verb+resource (compile an OpenDSS circuit, run power flow) and the qualifier 'from inline DSS commands' implicitly distinguishes it from opendss_compile_file. It is clear what the tool does, though it does not name the file-based sibling explicitly.

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?

It tells the agent to pass the complete script as a multi-line string and notes snapshot solve mode, which is actionable, but it gives no explicit when-to-use-this-vs-alternatives guidance (e.g. vs opendss_compile_file or opendss_run_command). Usage is implied rather than stated.

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

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

Annotations already mark this as a non-read-only, non-destructive, idempotent, closed-world operation, but the description adds substantial behavioral detail: it checks element existence, builds the Edit command, reads values back, reports convergence, and fails on unknown properties instead of silently ignoring them.

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 description is front-loaded with the core action and alternative-tool relationship, then uses compact Args/Returns sections. Some content in Args and Returns overlaps with schema and output-schema information, but it remains efficient overall.

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 annotations covering safety and idempotency, and an output schema covering return values, the description supplies the remaining important context: validation behavior, failure mode, read-back, and convergence reporting. It is nearly complete, though it could mention response_format or prerequisites such as the circuit state.

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 reported as 0%, so the description must compensate, and it does list element, properties, and solve. However, the parameter section is thin and mostly restates names or format examples already present in the schema; it does not clarify response_format or provide additional semantic constraints.

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 states a specific verb and resource: edit properties of an existing element and re-solve. It also distinguishes this from the sibling raw-command tool by calling itself the typed alternative to opendss_run_command("Edit ...").

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?

It explicitly names the alternative tool opendss_run_command and explains why to prefer this one: typed validation, existence checks, read-back, convergence reporting, and failure on unknown properties. That gives an agent clear routing guidance.

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

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

Annotations cover the safety profile (idempotent, non-destructive, closed-world), so the description only needs to add operational context. It does: it discloses that a re-solve happens and that omitting names triggers a blanket BatchEdit Class..* enabled=yes|no, which tells the agent exactly how broad the mutation will be.

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 action, followed by a compact typical-use sentence and a brief args/returns block. The arg list marginally restates schema fields, but nothing is bloated or buried.

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 one-line 'Returns: Elements affected and solve status' is a courteous extra rather than a necessity. Combined with annotations and the schema's field descriptions, an agent has enough to invoke this correctly; only the response_format option goes unmentioned.

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?

The schema's nested fields carry descriptions (element_class, enabled, names, solve), so the schema does most of the work. The description still adds meaning by enumerating the four input fields and by clarifying the semantics of the absence of names (equivalent to BatchEdit Class..* enabled=yes|no), which the schema only states as 'affect every element of the class'.

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 pair (enable/disable) and resource (elements of a class), plus scope variants (whole class vs named elements). It is clearly distinguishable from siblings like opendss_edit_element and opendss_add_element because it operates on bulk class membership toggling rather than editing a single element's properties.

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?

Gives concrete when-to-use examples: disable every PVSystem for the base case, or disable a Capacitor/RegControl to test its effect. This is clear context, though it never explicitly names an alternative tool or states when not to use this one.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=true, so the safety profile is covered. The description adds meaningful behavior beyond that: the compile prerequisite, the concrete outputs returned (fault current, 3I0, per-phase pre/post voltages, Scc, sag), and the dual-fault technique. Missing only details like state persistence across calls.

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 one-line purpose followed by Args/Returns sections; each sentence carries information. Slightly long for a single-parameter tool, but nothing is redundant.

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 an output schema present, return values need not be detailed, yet the description still summarizes them. Combined with the compile prerequisite and the fault-method guidance, an agent has everything needed to call this correctly, including the physics context.

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 reported at 0% for the top-level wrapper, and the description only summarizes 'bus name, phase, and fault resistance' without explaining phase encoding or r_fault units. The dual-fault hint (0.01 vs 1.0) is the one useful parameter-adjacent detail; response_format is never mentioned. Meets the baseline when the nested schema carries most field documentation.

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 (run), resource (single-phase-to-ground fault), and scope (at a specific bus), and the 1ph vs 3ph distinction separates it cleanly from opendss_fault_3ph and the Thévenin siblings. An agent can pick it without opening a 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?

Explicitly gives the prerequisite ('circuit must be compiled first with opendss_compile_file or _script') and explains the dual-call method with different r_fault values to extract Z0_th, naming the sibling alternatives by name. This is genuine when-to-use guidance, not inference.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false and idempotentHint=true, so the safety profile is already covered. The description adds value beyond that by disclosing the compile-first dependency and the exact modeled output (per-phase currents, Scc, voltage sag counts below 0.80/0.50 pu). It stops short of saying whether the applied fault mutates circuit state or must be cleared.

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 behavior and precondition are front-loaded, and the Args/Returns blocks are easy to scan. The returns are stated twice (prose sentence plus the 'Returns:' line), which is mild redundancy given an output schema already exists.

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 single-parameter study tool with an output schema present, the description supplies purpose, precondition, and expected outputs, so return-value detail is not needed. The remaining gap is sibling routing against fault_1ph/fault_sweep and any note on circuit state after the fault.

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?

The schema description coverage is reported as 0%, so the description carries the burden, and it does name the two meaningful inputs ('bus name and fault resistance'). It adds little beyond the schema's own field descriptions and omits the response_format option, leaving the parameter semantics only partially compensated.

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 uses a specific verb and resource ('Run a three-phase fault at a specific bus') and implicitly distinguishes itself from the sibling opendss_fault_1ph by specifying three-phase. It does not explicitly name a sibling to route the agent, but the scope is unambiguous from the first sentence.

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?

It states a real precondition ('The circuit must be compiled first with opendss_compile_file or _script'), which is genuine usage context. However, it never says when to choose this over opendss_fault_1ph, opendss_fault_sweep, or the thevenin tools, so alternative selection is left to inference.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false, and readOnlyHint=false, so the safety profile is largely covered. The description still adds genuine behavioral context by disclosing that the circuit is re-compiled for each bus to yield clean, independent results, which explains the cost and state implications of the sweep.

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 purpose sentence, followed by a behavioral note, a use-case line, and explicit Args/Returns blocks. Well organized and mostly waste-free, though the Args/Returns scaffolding restates information the schema and output schema already carry.

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 annotations covering the safety profile and an output schema existing, the description need not explain return values, yet it briefly does. It discloses the recompile behavior and the multi-bus scope, leaving only minor gaps around the r_fault parameter and error handling.

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?

Reported schema description coverage is 0% at the top level; the description only notes that params is a FaultSweepInput 'with list of buses.' It does not explain r_fault (default 0.0001) or response_format, so the description partially compensates for the coverage gap but leaves two parameters undocumented.

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 ('Run three-phase faults at multiple buses') plus the intent ('build a fault current curve'), so the agent understands the operation. The 'multiple buses' scope implicitly separates it from the single-bus opendss_fault_3ph sibling, but that sibling is never named, so differentiation is left to inference.

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?

Offers concrete use cases ('plotting Icc vs distance or sizing protection equipment'), which implies when this tool is appropriate. However, it never says when to prefer it over opendss_fault_3ph or opendss_thevenin_z1/z0, nor does it state any prerequisites, so selection between the fault tools remains guesswork.

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

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

Annotations already establish read-only, idempotent, closed-world, non-destructive behavior, so the bar is lower. The description still adds useful non-annotation context: results are sorted by current descending and only response_format in the params is honored.

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-loads the purpose in the first sentence, then scopes and formats, with clean Args/Returns sections. There is minor redundancy in restating return values that the output schema already carries, but no waste elsewhere.

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 format need not be spelled out, and the description still adds the sort order. Purpose, scope, and the critical param caveat are all present; the only gap is no alternative-tool routing.

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?

With schema coverage at 0%, the description must compensate, and it does the key disambiguation: it notes that of the VoltageInput fields (kv_max, kv_min, response_format) only response_format is used, warning the agent that the kV filters are ignored. It does not explain the markdown/json enum, but that is self-evident.

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: getting P, Q, and max current for every line, which is clearly distinct from voltage/load siblings. It does not explicitly name or differentiate against near-neighbors like opendss_get_loading or opendss_get_voltages, so it stops just short of a 5.

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?

'Useful for identifying overloaded lines and understanding power distribution' implies when it helps, but never states when to prefer it over alternatives such as opendss_get_loading or opendss_violations. Usage is only inferred, not directed.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description goes well beyond them: it explains the NormAmps vs EmergAmps comparison, that shunt elements are skipped, that results are sorted descending, and the non-obvious caveat that transformer loading_pct is based on normhkva (default 1.1 x kVA) rather than nameplate kVA, with loading_nominal_pct as the rated-capacity figure.

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 purpose, then caveats, then args/returns; every sentence carries real information. The Args and Returns blocks partially duplicate structured fields (the Returns list overlaps the existing output schema), which is minor redundancy rather than bloat.

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 values need not be re-explained, and the description nonetheless supplies the transformer-specific columns and the normhkva caveat an agent needs to interpret them. Combined with the argument-usage note, nothing required to call or interpret this tool 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 description coverage is reported at 0%, and the schema misleadingly documents kv_max/kv_min as if they mattered; the description corrects this by stating 'params: VoltageInput (only response_format is used)', which is essential information an agent cannot get from the schema. It stops short of describing response_format's values, but that enum is self-explanatory.

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 ('Get thermal loading (% of NormAmps) for every line and transformer') and scopes it precisely, which separates it from siblings like opendss_get_line_flows and opendss_get_loads. The definition of the metric and the element coverage are given up front.

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?

Usage is only implied: sorting by loading descending so 'overloaded elements come first' hints at the overload-screening use case, and skipping shunts clarifies scope. However, no sibling is named as an alternative and there is no explicit when-to-use/when-not-to-use guidance versus opendss_violations or opendss_get_line_flows.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: it clarifies that of the VoltageInput fields only response_format is honored, and that values are both nominal and solved — the latter implying the circuit must already be solved.

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 Args/Returns structure is easy to scan and front-loads the core behavior. The 'Returns nominal and actual kW/kvar' sentence partially restates the opening sentence, which is mild redundancy but not damaging for a definition this short.

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 fully annotated read-only tool with an output schema, explaining return values is not strictly required, and the definition is close to sufficient. However, it omits the prerequisite that a circuit be compiled and solved before loads have 'actual' values, and gives no guidance on selecting this tool over its peers.

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 reported as 0% for a single required param, so the description must carry the load. It correctly notes that only response_format is used, which is important given the inherited kv_max/kv_min fields, but it never explains the markdown/json enum options or their effect on output, leaving a real 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?

States a specific verb and resource ('Get active and reactive power for every load in the circuit') and further narrows the output to 'nominal and actual (solved) kW/kvar for each load element.' This clearly separates it from siblings like opendss_get_voltages and opendss_get_line_flows without needing to read either 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?

The description says what the tool returns but never states when to call it versus alternatives such as opendss_voltage_summary or opendss_get_loading, nor whether a circuit must be compiled/solved first. Usage must be inferred entirely from the tool name and domain knowledge.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and a closed world, so the safety profile is covered structurally. The description adds genuinely useful context beyond that: it specifies the output fields (average/min/max pu, kV base, phases, distance from source, coordinates) and the ascending sort order, and 'in the compiled circuit' quietly signals a prerequisite. No contradiction with annotations.

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 purpose, then the return fields and the filtering hint, followed by tidy Args/Returns sections. The Returns section largely duplicates the output schema, so it is slightly redundant, but the whole thing is short and every line is readable.

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 exhaustive return documentation is not required, and the description still names the key fields and sort order. The main gap is the absence of any differentiation from the sibling voltage_summary; beyond that, an agent has enough to call it correctly.

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?

The context reports 0% top-level schema description coverage, but the nested VoltageInput schema actually documents kv_min/kv_max richly (line-to-neutral reporting, default-drop behavior). The description only restates 'kv_min/kv_max filters' plus the MV/LV intent, adding little syntax detail beyond what the nested schema already provides, so the baseline 3 is appropriate.

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 states a specific verb and resource ('Get voltage magnitude (pu) for all buses in the compiled circuit') and enumerates the returned fields, so the operation is unambiguous. However, it never distinguishes itself from the close sibling opendss_voltage_summary (or opendss_violations), so an agent cannot tell which of the voltage tools to prefer without reading both schemas.

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?

It gives one implicit usage hint ('Filter by kv_base range to focus on MV or LV buses'), which implies when to narrow results, but there is no explicit when-to-use/when-not or any routing to alternatives such as voltage_summary or violations. Usage is suggested rather than stated.

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

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

Discloses a non-obvious side effect the annotations do not capture: 'The circuit is recompiled clean afterwards, so edits made with run_command/edit_element before the study are lost.' This is exactly the kind of operational consequence an agent needs. It falls short of 5 only because it does not reconcile that state reset with destructiveHint=false, nor describe runtime/cost or convergence-failure behavior beyond the enumerated output fields.

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 action, then prerequisites, side effects, Args and Returns in a scannable structure; nearly every sentence carries information. The Returns paragraph partially restates what the output schema would already provide, which is the only mildly redundant element.

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 multi-step study tool with nested params and an output schema, the description covers prerequisites, the recommended operating point, the side effect on prior edits, and the interpretation of both PV allocation modes. An agent has everything needed to invoke it correctly without opening any other artifact.

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?

The 'Args' line summarizes the payload ('bus list, PV steps, transformer kVA, load_mult and limits'), which maps to the required and key optional fields. Reported schema description coverage is 0% at the wrapper level, but the referenced schema itself carries per-field descriptions, so the description adds little semantics beyond name-level enumeration and does not, for example, explain pv_kw_steps ordering or how limits interact.

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 ('Run a hosting capacity study by incrementally adding PV generation') and immediately scopes the operation. It is clearly distinguishable from the sibling read/compile/inspection tools, and it enumerates the outputs (Vmin/Vmax, violation counts, binding constraint) so an agent knows exactly what class of operation this is.

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?

Gives explicit preconditions ('The circuit must be compiled from a file first (not from script)') and the condition for meaningful results ('Run it at minimum load (load_mult ~0.3): DER limits do not show at peak'). It also names the interaction with other tools (run_command/edit_element) and specifies which mode applies (uniform vs worst-case), leaving little to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed world, so safety is covered. The description adds context beyond them: the compile/solve prerequisite and the fact that the operation produces a PNG artifact on disk rather than returning analysis data. It does not say where the file is written or whether it overwrites an existing one — a mild tension with readOnlyHint that goes unaddressed.

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 action and output, followed by a compact bullet list of plot types. The Args/Returns block is conventional and short. Slight redundancy in restating the return value when an output schema exists, plus the erroneous 'kv_base' mention.

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 single nested parameter with an output schema present, the description covers the essential call-time context: prerequisite state, plot type choices, and the nature of the result. Remaining gaps are the kv_min/kv_max filter semantics and output file location/overwrite behavior, which are secondary to 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 coverage is reported at 0%, so the description must carry the parameter burden, and it largely doesn't: kv_min and kv_max are never explained. Worse, it references 'kv_base filters', a parameter that does not exist in the schema (they are kv_max/kv_min), which can actively mislead. Only the plot_type values are restated, and those are already documented in the schema itself.

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 specific verb and resource ('Generate a voltage visualization plot and save it as PNG') and enumerates the two supported plot types, which distinguishes it from data-returning siblings like opendss_get_voltages. The framing as strictly a 'voltage visualization' is slightly narrow since the topology type is a georeferenced network map, but the enumeration corrects that.

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?

It states a concrete precondition: 'The circuit must be compiled and solved first,' which tells the agent the ordering relative to opendss_compile_file/opendss_run_command. It does not name an alternative for when numeric voltage data is wanted instead of a plot (e.g., opendss_get_voltages), so no true when-not guidance exists.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the mutation profile is covered structurally. The description adds the useful 'after compilation' timing constraint but says nothing about what happens on an invalid command, error handling, or the scope of arbitrary text execution, so it does not go far beyond the annotations.

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-loads the operation in the first sentence, then uses clearly delimited Args/Returns blocks. No filler, though the 'or confirmation of execution' hedging on returns is slightly soft.

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 optional and the description covers it anyway. For a tool that executes arbitrary DSS text, the description omits any caution about command validity or failure modes, leaving it only minimally adequate given the annotations.

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?

One parameter with 0% schema description coverage, and the description only offers 'RunCommandInput with the DSS command string' – effectively restating the parameter. There is no example command syntax, format, or delimiter guidance to compensate for the coverage gap on an arbitrary-string input.

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: 'Execute a single OpenDSS text command on the currently loaded circuit.' An agent can distinguish it from bulk compilation siblings, but it never explicitly contrasts itself with the structured edit siblings (opendss_edit_element, opendss_add_element) that overlap in purpose.

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?

Provides implied usage context ('useful for modifying the circuit after compilation'), which orients the agent toward post-compile mutation. However, it names no alternative and gives no when-not-to-use guidance, which is a real gap given three siblings that also add/modify circuit elements.

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

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

Annotations declare non-readOnly, non-idempotent, non-destructive, and closed-world, so the safety profile is covered; the description adds the prerequisite state requirements and the nature of the result (convergence status plus final-state voltage summary). It does not disclose cost/duration or failure behavior for long yearly runs (8760h), so a 4 rather than 5.

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 and mode support are front-loaded, then prerequisites, then args and returns — a logical order. Slight redundancy between the separate sentences about LoadShapes and the Args block, but nothing is wasted.

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 simulation tool with an output schema present, the description supplies the prerequisite workflow (compile, define LoadShapes), the mode options, and the argument list, which is close to complete. The unmentioned monitor_bus and response_format parameters are the only notable 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?

The Args section names only mode, stepsize, and number of steps, omitting monitor_bus and response_format from the nested QSTSInput. With low reported schema description coverage, the description partially compensates but leaves meaningful parameters undocumented, landing at the baseline.

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 names a specific verb and resource ('Run a quasi-static time series (QSTS) simulation') and enumerates the supported modes (daily, yearly, dutycycle), which distinguishes it from the many sibling run_*/get_* tools that never perform time-series solving. An agent can identify this tool without opening the 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?

It states clear prerequisites ('circuit must be compiled first', 'LoadShapes must already be defined'), which is real when-to-use guidance for a simulation tool. It does not name alternatives or say when not to use it, so it stops short of the top score.

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

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

Annotations mark this as a non-readOnly, idempotent, non-destructive operation, and the description adds real substance: the dual-fault methodology, the requirement for a prior compile, and that Z1 is computed as a byproduct. It stops short of describing side effects on simulation state or any rate/iteration cost of running two faults.

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 a one-line purpose, then method, then Args/Returns. Every section is relevant; the Returns line is mild redundancy since an output schema exists, but overall it is tight and well organized.

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 values need not be spelled out, and the description still summarizes them (R0_th, X0_th, Z0_th plus Z1). Combined with the compile prerequisite and method explanation, an agent has enough to call the tool correctly; only explicit sibling-routing guidance 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?

The schema exposes bus, rf1, rf2, phase, and response_format, and the description re-states the meaningful ones (bus name, phase, two fault resistances) plus the dual-resistance rationale. It omits response_format and the defaults, but adds method context the schema cannot express.

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: 'Extract zero-sequence Thévenin impedance (Z0) at a bus,' and even names the method (dual-fault with 1F-G faults). The positive-sequence counterpart opendss_thevenin_z1 is never named, so routing relies on the reader inferring 'zero-sequence' vs 'positive-sequence' from the description and sibling names.

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?

Gives one important prerequisite ('The circuit must be compiled first'), which is genuinely useful context. However, it never says when to prefer this over opendss_thevenin_z1, opendss_fault_1ph, or the sweep tools, leaving the selection decision to inference.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is partly covered. The description adds real method detail beyond that — the dual-fault approach, two 3-phase faults with differing R_fault, and the algebraic solve — which tells the agent how the measurement is obtained and that the circuit is perturbed. It does not state whether the applied faults are removed afterward.

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 purpose, then method, then a clear Args/Returns block; no sentence is wasted. The Args/Returns headers are slightly boilerplate given the output schema already exists, but the content is tight.

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?

The precondition and method are stated, and an output schema exists so return values needn't be enumerated (though they are). What's missing is how this relates to the z0/fault siblings and whether circuit state is restored after the dual faults — minor gaps for a single-parameter analysis tool.

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?

Reported schema description coverage is 0% at the top level, so the description must compensate. It names the meaningful inputs ('bus name and two fault resistances') and explains their role in the dual-fault solve, but omits response_format and the default values of rf1/rf2, leaving the compensation partial.

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 and resource ('Extract positive-sequence Thévenin impedance (Z1) at a bus') and the 'positive-sequence' qualifier implicitly distinguishes it from the sibling opendss_thevenin_z0, which handles zero-sequence. An agent can route between the two without opening either 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?

States a concrete precondition ('The circuit must be compiled first'), which tells the agent when the tool is callable. It gives no explicit exclusions or sibling routing (e.g., when to prefer z0 or a single fault tool instead), so it falls short of the top band.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds useful context the annotations do not carry: the per-phase voltage semantics, the default thresholds (0.95/1.05 pu, 100% NormAmps), and the implicit precondition that a solve must exist first. It does not discuss performance or behavior on an unsolved case.

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 purpose is front-loaded in the first clause, followed by the two most decision-relevant facts (defaults, standards) and a workflow instruction. The Args/Returns block is largely redundant with the schema and slightly dilutes an otherwise tight description.

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 an output schema present, the description need not detail return contents, and annotations cover the safety profile. Together with the stated defaults and workflow placement, an agent has enough to call it correctly; only sibling routing is left implicit.

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?

The context reports 0% schema-description coverage at the top level, so the description must carry the load, and it does add meaning beyond defaults: it explains that limits are per-phase and must be set to the governing standard when it differs. It mentions the optional kV base filter only in passing and leaves kv_min/kv_max semantics to the nested schema definitions.

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 first sentence states a precise verb and dual resource: 'report buses outside [v_min, v_max] pu and elements above loading_max %'. This clearly distinguishes it from voltage-reading siblings (get_voltages, voltage_summary) and loading siblings (get_loading, get_line_flows), since it produces a pass/fail compliance report rather than raw values.

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?

'Use it after every solve to verify the case before reporting results' gives clear placement in the workflow, and the instruction to pass applicable-standard limits (NTC 1340 / CREG) explicitly says when to override defaults. It does not name alternative siblings (e.g. when to prefer voltage_summary), so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine context beyond that: the exact statistic set and the concrete violation thresholds (below 0.95 pu, above 1.05 pu) that define what 'violation counts' means.

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 core purpose is front-loaded in the first sentence, with the threshold detail immediately after. The trailing 'Returns: Voltage statistics summary' is redundant given the enumerated stats and the existing output schema, a minor waste.

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 read-only summary tool with an output schema and full annotation coverage, the description supplies the statistic set and threshold definitions an agent needs. The only meaningful gap is its relationship to the overlapping violation/voltage siblings.

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 reported at 0%, so the description should compensate; it only names the kv_min/kv_max filters without explaining their semantics (the actual kV-base meaning lives in the nested schema descriptions). This is a minimum-viable baseline rather than real added meaning.

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 ('Get voltage statistics') and enumerates exactly what is returned (min, max, mean, std, violation counts). It is distinguishable from most siblings, though it does not explicitly separate itself from the overlapping opendss_violations or opendss_get_voltages tools.

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?

'Provides a quick overview of the voltage regulation status' implies the high-level use case, but no explicit when-to-use or when-not-to-use guidance is given, and the related sibling opendss_violations is never mentioned as an alternative. Usage is left to inference.

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