SparkQuote NEC calculators

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description goes further by exposing the exact pricing formula (price = break-even / (1 − margin)), which tells the agent this is a deterministic pure calculation and how margin differs from markup. It omits edge-case behavior such as a margin of 100 causing division by zero.

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?

A single front-loaded sentence that states the output, lists the inputs in logical order, and closes with the formula. No filler, nothing 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 return-value explanation is unnecessary, and all seven parameters are documented at 100% coverage. The only gap is unstated error behavior for degenerate margins (e.g., margin ≥ 100), which matters for a division-based calculation.

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 100%, so the baseline is 3, but the description adds real semantic value by naming each input's role and clarifying that margin is a target net margin applied as a divisor rather than a markup multiplier — a distinction the schema alone does not make.

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 precise computation (electrical bid price) and enumerates every input dimension — materials, markup, labor hours and rate, job costs, overhead, target net margin — and even supplies the governing formula. This is unmistakably distinct from the numeric siblings such as ohms_law, load_calculator, and voltage_drop.

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, when-not-to-use, or alternative-tool guidance. With siblings like load_calculator and panel_schedule in the same electrical domain, an agent gets no help deciding which calculator applies to a pricing question versus a load question.

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 safety is covered. The description adds genuine domain behavior beyond that: device boxes count as '2 each' and the allowance is multiplied by the Table 314.16(B) volume for the largest conductor, which tells the agent how the result is derived.

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?

A single dense sentence that front-loads the resource and standard, with every clause carrying a computational rule. No filler, though the packing of allowances into one sentence makes it slightly hard to parse.

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 explained, and all five parameters are documented in the schema. The description supplies the calculation model, leaving only when-to-use guidance as a gap, which is minor for a deterministic calculator.

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 100%, so baseline is 3, but the description adds real semantics: it clarifies that each device contributes 2 conductor volumes and that 'conductors' excludes grounds while the largest conductor drives the multiplier. These are non-obvious details not fully spelled out in the schema.

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 calculation (minimum outlet box volume) with a concrete standard (NEC 314.16(B)) and enumerates the inputs it combines, so an agent can tell it apart from siblings like conduit_fill or load_calculator. It is clear and specific, though it never names a sibling tool to further sharpen the boundary.

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 technical framing (NEC 314.16(B) box fill) implies the usage context, but there is no explicit when-to-use statement, no prerequisites, and no alternative named (e.g., conduit_fill for raceway fill). Usage must be inferred from the domain.

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, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered. The description adds that results derive from NEC Chapter 9 Tables 1, 4 and 5, which is genuinely useful provenance, but it says nothing about return shape, rounding, or edge behavior (e.g., overfill cases).

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?

A single dense sentence that leads with the computed values and follows with the qualifying constraints; no filler, no repetition of the title.

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 a full output schema, complete parameter documentation and safety annotations, the description only needs to frame scope, which it does. The remaining gap is minor: it never states that mixed conductor sizes are unsupported in so many words, relying on "of one size."

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 100% and three of four parameters carry enums with per-value explanations, so the schema does the heavy lifting. The description only restates the material scope (THHN/THWN-2, EMT/PVC-40) already encoded in the enums, adding no format or default guidance beyond it.

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 the exact outputs (percent fill and maximum conductor count) and constrains the inputs (THHN/THWN-2, single size, EMT or PVC Schedule 40), which separates it cleanly from siblings like box_fill, wire_size and nec_ampacity. It lacks an explicit verb ("calculates") and never names a sibling to avoid, 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?

There is no explicit when/when-not statement or alternative named, but the phrase "of one size" implicitly excludes mixed-size conductor runs, which is the main misuse case. Usage is inferable from the scoping rather than stated, so it stays at minimum-viable.

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/idempotent/destructive=false, so the safety profile is covered. The description adds method-level context (demand factor, minimum standard service size) but says nothing about how the results are presented or what the minimum-size output means; the omission tip is also questionable given non-zero schema defaults.

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 dense sentence plus a single operational tip, front-loaded with the method name and scope. Slightly list-heavy 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 no explanation, and annotations plus 100%-covered parameters leave little else to document. The only real gap is the unresolved tension between the 'omit to get 0 VA' tip and the non-zero defaults.

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 100%, so every parameter is already documented with units and defaults. The description's only added guidance ('leave an appliance out to count it as 0 VA') is ambiguous and appears to conflict with schema defaults such as hvac=5000, range=12000, dryer=5000, so it does not reliably add 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?

Names the specific standard and method (NEC 220.82 optional method) and enumerates exactly what it computes: lighting VA/ft², small-appliance and laundry circuits, fixed appliances, demand factor, HVAC, and minimum service size. This clearly separates it from siblings like nec_ampacity, voltage_drop, or bid_calculator.

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 one practical usage tip ('Leave an appliance out to count it as 0 VA'), but no statement of when to prefer this optional method over the standard method or which sibling to use for related calculations. Usage is implied by the NEC reference 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 declare readOnlyHint, idempotentHint, non-destructive, closed-world, so the safety profile is covered. The description adds real behavioral context the annotations cannot: the table's ambient/conductor-count assumptions and the fact that adjustment, correction, and 240.4(D) limits are NOT applied — a misuse guard. It stops short of noting table/edition or lookup 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?

A single engineered sentence with the subject (allowable ampacity) front-loaded and all caveats compactly following. No filler sentences. It is dense to the point of being parenthesis-heavy, which slightly hurts scanability, 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?

Given an output schema exists and annotations cover the safety traits, the description supplies the missing piece: the validity envelope of the lookup value. What is missing is only routing guidance among the nine siblings. For a deterministic table lookup, that is a minor rather than a blocking 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 100% and every parameter is an enum with its own explanation (AWG/kcmil forms for size, 60/75/90 column guidance for temp, cu/al for material). The description adds no parameter-level meaning beyond what the schema already provides, so the baseline 3 applies.

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+resource (allowable ampacity of one insulated conductor) and pins the exact source table (NEC 310.16) plus its scope conditions. It also implicitly distinguishes itself from sizing siblings like wire_size by stating the value is 'before any adjustment or correction factors and before the 240.4(D) small-conductor limits.' An agent can tell exactly what quantity is returned.

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 scope qualifiers (≤3 current-carrying conductors, 30°C ambient, no adjustment/correction factors) tell the agent when the returned value is valid, which is genuinely useful. However, it never states when to prefer this tool over siblings such as wire_size or voltage_drop, nor any exclusions. Usage is implied rather than 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, so the safety profile is covered. The description adds real behavioral content beyond that: it is a two-in/two-out solver that computes the remaining quantities rather than a single-value converter. It does not say what happens with invalid input counts (zero, one, or three values).

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?

A single sentence that front-loads the domain and immediately states the input contract. No filler, no restatement of the title.

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, and the description covers the core compute contract. The one gap is the interaction between 'exactly two' and the schema defaults (r and v), which an agent could read as satisfying the two-value rule on their own.

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 100%, so the baseline is 3, but the description adds a constraint the schema lacks entirely: exactly two of the four quantities must be supplied. This matters because the schema exposes defaults (r=24, v=120) with no minProperties/maxProperties, leaving ambiguity the description partially resolves.

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 the specific domain (Ohm's law and power) and the exact operation (solve for the two missing quantities), which clearly separates it from siblings like watts_to_amps or voltage_drop. It does not, however, explicitly contrast itself with any sibling tool, so it stops 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?

The 'give exactly two of voltage, current, resistance and power' rule is a genuine usage constraint that tells the agent how to call the tool. It gives no guidance on when to prefer this over watts_to_amps or load_calculator, and no exclusions or edge-case handling.

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, destructiveHint=false, so the safety profile is covered. The description adds useful behavior beyond that: it discloses that a per-phase load total plus an imbalance figure is produced. It does not say how circuits are assigned to phases or whether balancing is optimized, so it only partially extends 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?

A single dense sentence that front-loads the action and the panel types. Nothing is wasted, though it could have spent one more clause on when to prefer it over load_calculator.

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 a 100% covered schema, an output schema, and safe-read annotations, the description needs only to frame the purpose and it does that adequately. The gap is the absence of any guidance on phase assignment strategy or how the tool relates to the other load/wire calculators.

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 100%, including enum meanings for system and spaces and the 'description, breaker A, poles, VA' line format for circuits, so the schema carries the parameter burden. The description echoes the two voltage systems but adds no syntax or format detail beyond the schema, making the baseline 3 correct.

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 action and object: it lays circuits out on a panel and totals load per phase with imbalance, naming the supported systems (120/240 V single-phase, 208Y/120 V three-phase). This is clearly distinguishable from pure calculation siblings like ohms_law or voltage_drop, though it does not explicitly name a sibling it replaces.

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 gives no when-to-use guidance, no prerequisites, and no routing hints against load_calculator or the other electrical siblings. Usage is only inferable from the purpose statement itself, which is below the 'implied usage' threshold of an explicit context cue.

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 the safety profile is covered. The description goes beyond them by disclosing the exact computational method (VD = 2·K·I·L / CM with the √3 three-phase variant) and the data source (NEC Chapter 9 Table 8), which tells the agent this is a deterministic table-driven calculation rather than a heuristic estimate.

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 dense sentence, front-loaded with the resource and scope, with the formula and standard packed into a parenthetical. 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?

With an output schema present, return values need not be explained, and annotations plus a fully documented schema cover inputs. The description supplies the methodology and standard; the only real gap is sibling routing guidance, which is not its only job here.

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 100% and all six parameters are enum- or unit-documented, so the schema does the heavy lifting. The description adds only the clarification that length is one-way and that phase may be single or three, which is marginal value beyond the schema.

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 computation (voltage drop) with its inputs and both phase cases, so the agent knows exactly what is calculated. It never names or excludes the closely related siblings (wire_size, ohms_law, nec_ampacity), so differentiation relies on the agent's own 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?

Usage is only implied by the formula and the NEC reference; there is no statement of when to pick this over wire_size or ohms_law, no prerequisite or boundary conditions. Adequate but leaves routing 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuinely useful behavior not in the annotations: it reports the 125% continuous-load value in addition to the raw current, which an agent must know to interpret the result correctly.

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?

A single front-loaded sentence stating the computed quantity, its inputs, the phase scope, and an extra output value, with no filler. Every clause earns its place.

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 not required, and the parameters are fully described in the schema. The one meaningful gap is the absence of any guidance about when this tool is preferable to its overlapping electrical-calculation 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 100%, including enum labels for phase and voltage, so the schema already documents all four parameters thoroughly. The description mentions voltage and power factor but adds no syntax, unit, or default detail beyond what the schema provides.

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 the specific computation (current drawn by a load, in watts, at a given voltage and power factor) and its scope (single- or three-phase), which is enough to identify it as a watts-to-amps conversion. It does not, however, distinguish itself from siblings like ohms_law or load_calculator, which could plausibly overlap.

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 guidance, no prerequisites, and no mention of alternatives despite several overlapping siblings (load_calculator, ohms_law, nec_ampacity). The scenario implied by the formula is the only hint at appropriate use.

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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely non-obvious behavior: that the EGC is upsized under 250.122(B) when voltage drop increases conductor size, which an agent could not infer from the annotations or schema alone.

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?

A single front-loaded sentence leading with the deliverable, then the rule set. Dense with code jargon but no filler; every clause corresponds to an actual computation step.

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, and all 7 required params are schema-documented. The remaining gap is sibling routing among ten electrical calculators, which the description does not address.

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 100% with enums on temp/phase/volts/material, so the schema carries parameter meaning. The description references termination temperature and voltage-drop limit conceptually, mapping loosely to `temp` and `limit`, but adds no syntax or format detail beyond the schema.

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+resource: computes 'minimum conductor size for a circuit', and enumerates the governing rules (310.16 ampacity, 240.4(D), voltage drop, 250.122 EGC). This implicitly separates it from the narrower siblings nec_ampacity and voltage_drop, though it never names them.

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 guidance: nothing tells the agent to pick wire_size over voltage_drop or nec_ampacity, which cover sub-parts of the same computation. The scope is inferable from the rule list but never stated as a selection condition.

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