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

Annotations declare only readOnlyHint. The description adds rich behavior: the detuning thresholds (p >= 5.67% detuned, 4-5.67% tuned near the 5th, <4% above the 5th), the 1.10·Un continuous check, the >24 kV fallback where no class is suggested, and parallel-resonance evaluation with scc_MVA.

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?

Dense but front-loaded: it states what it computes, then the either/or input, then the outputs, then edge-case rules. Every sentence carries technical content; the only cost is a slightly run-on middle section.

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?

No output schema exists, but the description enumerates the returned quantities (elevated capacitor voltage V/(1−p), reactor current, effective reactive Q/(1−p), tuning frequency, IEC 60831 voltage class), so an agent knows what comes back. Required params Q_kvar and tensao_kV are the remaining 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?

With 0% schema description coverage, the description must carry parameter meaning, and it explains p_pct (XL/XC factor, e.g. 7 or 14), the L_mH alternative, Un_cap_kV, and scc_MVA's role. It leaves Q_kvar, tensao_kV, and api_key unexplained, so coverage is strong but not complete.

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?

Opens with a precise verb+resource: it sizes a detuned bank or tuned filter (series reactor with capacitor), which is clearly distinct from siblings like corrigir_fator_potencia. It does not name an alternative sibling, but the technical scope is unmistakable.

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 useful invocation guidance ('Informe p_pct ... OU L_mH'), and conditional behavior for Un_cap_kV above 24 kV and scc_MVA. However, it never says when to choose this tool over alternatives like corrigir_fator_potencia, so usage is implied rather than framed against siblings.

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