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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds genuinely useful context beyond that: it is a screening classifier, not an AC power-flow simulation, which sets correct expectations about fidelity and cost.

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 and compact: the core function plus scope plus one exclusion, with no filler. The trailing fragment is slightly awkward but 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?

An output schema exists, so return values need not be explained. However, for a non-trivial analytical tool with opaque network IDs and asset types, the description leaves the agent without guidance on parameter meaning or expected fidelity, which is a meaningful 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 0%, so the description carries the full burden for 4 parameters (network_id, proposed_capacity_kw, asset_type, connection_node) and says nothing about any of them. The enums are somewhat self-describing, but the description adds no meaning about units, enum semantics, or how parameters 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?

The description states a specific action (classify which physical constraint binds first: Voltage, Thermal, or N-1 SCR) and names the scope across LV/MV/Transmission. The verb+resource is clear enough that an agent can distinguish it from the AC-power-flow siblings, though the framing term '3D Master Vertical Grid Matrix' is unexplained jargon.

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 'Does NOT run AC power flow' clause implicitly routes AC studies to run_tier2_ac_study, but usage is only implied rather than stated. There is no explicit 'use this when...' guidance versus siblings like run_tier1_screen or screen_connection_application.

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, and closed-world, so safety is covered. The description adds that the computation is deterministic and emits a SHA-256 hash, which is genuine value for reproducibility, but says nothing about cost, failure modes when the node is unknown, or output size. A 3 against strong annotation coverage.

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 short sentences: the output list first, the usage rule and boundary second. No filler, nothing to cut.

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 needn't be described, and annotations cover safety. However, the omittable connection_node parameter is undocumented in both the schema and the description, which is a real gap for a tool an agent is told to call first.

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 0%, so the description must carry the burden, and it does not. network_id is self-evident from its enum values, but connection_node (nullable, default null) is never explained — the agent cannot tell whether omitting it inspects a default PCC or fails.

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 (extract) and a concrete set of outputs (Thevenin impedance, R/X ratio, fault level, dV/dP, hash) tied to a named location (PCC). The explicit 'Does NOT run AC power flow' separates it from run_tier1_screen and run_tier2_ac_study, so an agent can pick it apart from siblings without opening 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?

'Call this tool FIRST' gives explicit ordering guidance, and the negative clause rules out the AC-power-flow path. It stops short of naming the specific sibling it precedes (run_tier1_screen / run_tier2_ac_study), so the routing is clear but not fully closed.

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, closed-world, non-destructive behavior, so the safety profile is covered. The description adds genuine scope context beyond that: the result is catalog metadata only, with no computed study results, which prevents the agent from expecting analysis output. It could say more about what fields each catalog entry carries, but the output schema handles that.

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 short sentences with no waste. The enumeration of supported network classes comes first and the scope-limiting clause follows, so the most important information is front-loaded.

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 no parameters, rich annotations, and an output schema covering return values, the description supplies everything needed to decide to call it. The only small gap is that it does not hint at how many entries to expect or whether the list is exhaustive across all supported studies.

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 tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline for a no-parameter tool is 4, and the description does not wrongly suggest any filtering options.

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 (list) and concrete resource scope: ARENA/CSIRO 415 V LV feeders, 11-20 kV MV benchmarks, and NEM 132-500 kV substations. This is clearly distinguishable from the sibling analysis tools (run_tier1_screen, run_tier2_ac_study, sweep_connection_capacities) because it explicitly frames itself as a catalog, not a computation.

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 exclusion sentence 'Does NOT run short-circuit or AC power-flow calculations' tells the agent when not to use it and implicitly routes calculation work to the run_*/sweep_* siblings. It stops short of naming the specific alternative to call instead, so it is clear context without an explicit routing instruction.

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, and non-destructive, so the safety profile is covered structurally. The description adds useful domain context that results are OpenDSS-verified and that the DOE is deterministic snapshot-derived rather than live predictive, but does not describe runtime behavior, limits, or prerequisites.

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 main purpose is front-loaded, but the multi-line note is verbose domain jargon that consumes significant length without adding actionable clarity for selection. Structure is reasonable but the note is not tightly earned.

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 9 parameters at 0% schema description coverage, a complete description should explain at least the key inputs like proposed_capacity_kw and network_id usage. The presence of an output schema reduces the need to explain return values, but the input-side gap remains unaddressed.

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 0% across 9 parameters; the schema only provides titles and enums. The description supplies essentially no parameter-level meaning—the '(5kW/3kW)' hint is ambiguous and does not explain proposed_capacity_kw, feeder_background_scale, or operating_load_factor. 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 names a verb ('Synthesize') and specific resources (Static Operating Envelopes, snapshot-bounded DOEs, TX system-strength options), but the heavy domain jargon makes it hard to map the name 'propose_mitigations' to a concrete action. It also does not distinguish this tool from siblings like sweep_connection_capacities or run_tier2_ac_study, leaving the agent to infer which to pick.

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 guidance on when to use this tool versus alternatives such as sweep_connection_capacities or run_tier2_ac_study. The note distinguishes a snapshot DOE from a predictive WLT forecast, but that clarifies terminology rather than when-to-invoke rules.

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 cover safety (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial operational context beyond them: sub-10ms runtime, season-stratified voltage calibration at 1.0752 pu, thermal margin checks, post-contingency N-1 SCR threshold (NER S5.2.5 SCR >= 2.0), and Pareto joint hosting capacity. It also names the two output flags that drive escalation decisions.

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 correctly: what it does, what it returns, and what it is not, before the technical detail. The middle paragraph is dense with domain jargon and could be tightened, but nothing is clearly 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?

An output schema exists, so the description need not document return values, and the safety profile comes from annotations. However, for an 8-parameter tool with zero schema description coverage and multiple enums (network_id, asset_type, inverter_mode), leaving every parameter undocumented makes the definition only minimally viable.

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?

All 8 parameters have 0% schema description coverage, so the description must supply meaning and it supplies none — asset_type, bess_power_kw, inverter_mode, connection_node, operating_load_factor, and feeder_background_scale are never mentioned or explained. The numeric thresholds quoted (1.0752 pu, SCR >= 2.0) are screening criteria, not parameter semantics, so they do not close the 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 ('Calculates fast short-circuit and voltage screening'), declares the output type ('Returns a pass/fail'), and explicitly negates the adjacent capability ('Does NOT run full AC power flow'). This cleanly separates it from run_tier2_ac_study 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?

Gives an explicit escalation rule: use `fast_clear_eligible` and `flagged_for_tier2` to decide whether to escalate to `run_tier2_ac_study`, naming the alternative directly. It stops short of stating preconditions (e.g., that network_id should come from list_networks) or cases where Tier 2 should be run first, so it is clear but not exhaustive.

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?

Beyond the annotations (readOnly/idempotent/non-destructive), the description discloses genuinely non-obvious behaviour: the solve runs in an isolated child process with a hard subprocess timeout, and by default the raw trajectory array is pruned to protect LLM context tokens with a `trajectory_resource_uri` returned for on-demand retrieval. It also bounds expectations by stating what the tool does not iterate over. This is exactly the operational context annotations cannot convey.

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 core capability in the first sentence, then layers scope, exclusions and trajectory behaviour in descending order of importance. Every sentence carries information. Slightly dense with parenthetical state counts and backticked identifiers, but no filler sentences.

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 explained, and the description does cover scope, exclusions and the trajectory URI pattern. However, for a 12-parameter simulation tool with zero schema coverage it leaves too much unexplained about how parameter values map to the two solver regimes (e.g. which network_ids are LV vs MV/TX, what connection_node expects, what feeder_background_scale=5 means). Adequate to invoke, risky to invoke correctly on the first try.

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 12 parameters at 0% schema description coverage, the description carries the full explanatory burden and only partially delivers: it explains study_type's two values and include_trajectory's pruning behaviour. It says nothing about network_id (10 opaque enum codes with no LV vs MV/TX mapping), proposed_capacity_kw, bess_power_kw, export_cap_kw, inverter_mode, connection_node, solver_timeout_sec, operating_load_factor, or feeder_background_scale (default 5). Roughly 10 of 12 parameters remain semantically opaque.

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 with real technical precision: 'Run isolated child-process unbalanced 3-phase OpenDSS AC power flow (LV) or exact 2-bus N-0/N-1 AC contingency solve (MV/TX)'. An agent knows exactly what computational work happens and that the model differs by voltage regime. It stops short of naming the obvious sibling (run_tier1_screen) or saying how this relates to it, so differentiation is implied only by the 'tier2' naming and the study-depth language.

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 distinguishes the two study_type modes ('snapshot' evaluates 17 LV / 8 MV-TX worst-case seasonal peak states vs 'time_series' evaluating the chronological 30-min diurnal trajectory) and adds a clear when-not statement: it does NOT run the full-year 17,520/35,040-interval telemetry simulation. It also gives guidance on the include_trajectory default. What it does not give is any routing against siblings (run_tier1_screen, sweep_connection_capacities) or prerequisites for choosing a network_id.

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?

Beyond the annotations (readOnlyHint=false, idempotent, non-destructive), the description discloses genuinely useful behavior: a supervisory sanity gate, a possible requires_human_review outcome, a regulatory_override path, and a SHA-256 AuditReceipt. It also explains the token-saving default and points to the trajectory resource and plot.svg when raw arrays are omitted. It still does not say anything about runtime cost, solver failure behavior, or what the verdict tiers mean.

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 short paragraphs, front-loaded with the operation and then the default-output behavior, with no filler sentences. Density of unexplained jargon costs some readability, 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?

An output schema exists, so return values need not be described, and annotations cover the safety profile. But for a 12-parameter, zero-coverage, end-to-end orchestration tool, the description leaves the majority of inputs and the tier/human-review decision logic unexplained, so an agent cannot confidently call it with meaningful arguments.

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 0% across 12 parameters, so the description must compensate and it does not — only include_trajectory is explained. Key domain parameters (force_tier2, asset_type, network_id, inverter_mode, operating_load_factor, feeder_background_scale, solver_timeout_sec) are left entirely to bare enum values and defaults, with no explanation of what force_tier2 or the fidelity tiers actually mean.

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 verb is "execute" and the object is "end-to-end progressive-fidelity triage" of a connection application, so the general domain is inferable, but the phrasing is a noun pile of internal jargon ("progressive-fidelity triage", "Supervisory Sanity Gate") rather than a plain statement of what is computed. It never explicitly says it orchestrates Tier-1 + Tier-2 screening, which is what would distinguish it from siblings run_tier1_screen and run_tier2_ac_study.

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 statement of when to use this versus run_tier1_screen, run_tier2_ac_study, classify_screening_regime, or sweep_connection_capacities — all of which overlap heavily in intent. The only usage-like guidance is about the include_trajectory default, which is a parameter preference, not tool selection. An agent must guess that "end-to-end" means this is the umbrella call.

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 that results carry cost tier and scope metadata, which is real context, but it omits important behavior: what an empty query returns (the only parameter defaults to ""), how many results come back, and whether matching is prefix, substring, or fuzzy.

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?

One sentence, front-loaded with the action and resource, with the return payload appended rather than buried. 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?

With an output schema present, return-value explanation is not needed, and annotations cover safety. What's missing is the operational context an agent needs: what "scope metadata" means for tool coverage, and the behavior of an empty query given the unlabeled default.

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% and the single parameter has no description, so the description carries the burden. It clarifies that matching is "by keyword" rather than exact or regex, but says nothing about the empty-string default — presumably listing everything — which is the most consequential semantic for this one parameter.

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 ("search available MCP screening tools") and names the matching dimension (keyword) plus the payload returned. It is clear what the tool does, though it never makes explicit that this is the catalog/meta-tool as opposed to the domain tools (run_tier1_screen, classify_screening_regime) that appear as siblings.

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 when-to-use or when-not-to-use guidance: nothing says to call this before invoking a screening tool, whether discovery is required or optional, or how it relates to the sibling domain tools. An agent must infer that this is the entry point for finding tools.

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 destructive=false, idempotent=true, openWorld=false, so the safety profile is covered. The description adds genuinely useful behavior: evaluation happens natively server-side in Python with the bound `1 <= steps <= 20`, and it returns a compact inflection table. However it omits cost/latency (each step appears to be a power-flow study) and how `halt_on_violation` changes the run, leaving meaningful behavioral gaps for a heavy operation.

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 sentences, front-loaded with the action and then the rationale for server-side execution. No filler, though the line break mid-sentence and the backtick bound make it slightly less tight than it could be.

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 no explanation, but for an 11-parameter, computationally heavy sweep tool with 0% schema coverage, the definition is thin. It gives no guidance on how the sweep relates to tier1/tier2 screening, no sense of runtime cost, and no clarification of the many numeric/enum knobs an agent must set.

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 0% across 11 parameters, so the description must compensate and largely doesn't: it only clarifies `steps` (the 1-20 bound). The sweep range (start_kw/end_kw), asset_type, network_id, bess_power_kw, inverter_mode, halt_on_violation, operating_load_factor and feeder_background_scale are left entirely to bare titles and enums.

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 server-side N-point hosting-capacity sweep' with the goal of locating 'the exact constraint inflection point'. That is clearly distinct from list_networks or inspect_connection_point, but the description never contrasts itself with run_tier1_screen or run_tier2_ac_study, which are the real alternatives for capacity studies.

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?

'Shields the LLM context window from N sequential tool round-trips' implies the usage pattern (prefer this over looping a single-capacity call N times), but the competing tools are never named and there is no when-not guidance, e.g. when a full tier2 AC study is still required.

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