opendss_get_loading

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.