Proven Plaza Calculators & Open Data

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

Annotations declare readOnlyHint=true and openWorldHint=true, so the agent already knows this is a safe read operation that accesses the open web. The description adds what specifically gets scanned (crawler rules, llms.txt, schema.org data, etc.), which is useful behavioral context. It does not disclose rate limits, authentication needs, or runtime behavior, but with annotations covering the safety profile, a 3 is appropriate.

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 a single, front-loaded sentence that states the score, its range, and what it evaluates, ending with a clarifying exclusion. It is dense but every clause serves the purpose of explaining what the score covers. No wasted words.

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 simple read-only tool with one parameter and no output schema, the description adequately explains the score's range, its meaning, and the dimensions checked. It does not describe the url parameter's expected format, but otherwise gives enough context to call the tool correctly. Annotations cover the safety profile.

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% and the only parameter (url) has no description in the schema. The description implies the parameter points to a public business website, but adds no format details, examples, or constraints. It barely compensates for the missing schema 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?

The description clearly states the tool produces a 0-100 score of a public business website's agent-readiness, listing the specific dimensions it evaluates (AI crawler rules, llms.txt, schema.org data, etc.). It also distinguishes itself from a Google ranking score. However, it does not explicitly differentiate from sibling tools like ai_crawler_audit or agent_ready_fix_pack.

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 guidance on when to use this tool versus alternatives. It mentions it is free and not a Google ranking, but does not say when to choose it over agent_ready_fix_pack or ai_crawler_audit, nor does it state any prerequisites or exclusions.

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 and openWorldHint=false. The description usefully reinforces the closed-world behavior with 'Uses only supplied facts', warning the agent not to expect the tool to fetch the live site. It still does not explain what the caller receives (files? URLs? text blobs?) or any limits on generation.

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, front-loaded with the output artifacts and the closed-world constraint. No filler. It could be slightly tighter, but there is no wasted prose.

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 an 11-parameter, no-output-schema generator, the description is thin: it never says what form the generated artifacts take, whether they are returned inline or hosted, or how the many business-identity fields feed the templates. It answers 'what does it make' but not 'what do I get back'.

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 carry the load. It only clarifies one parameter's format ('services: one per line as Name|Price') and leaves url, name, city, region, areaServed, bookingUrl, businessType, email, phone, and description entirely unexplained. The lone format hint is valuable but does not compensate for 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?

The description names a specific verb (Generate) and the concrete artifacts produced: robots.txt AI-crawler rules, llms.txt, schema.org JSON-LD, and /.well-known/agent-catalog.json. This is far more specific than a generic 'fix' tool. It does not explicitly contrast itself with siblings like agent_readiness_score or ai_crawler_audit, but the 'generate' framing implies a difference from scoring/auditing.

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 tool versus the sibling audit/score tools, no prerequisites (e.g., needing a live site vs. just facts), and no exclusions. The only hint is the title's 'free' marker, which does not guide selection.

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 and openWorldHint=true, so the agent knows this is a safe external read. The description adds the verdict framing but says nothing about live fetching, rate limits, behavior when robots.txt is absent or unreachable, or whether results are cached. With annotations carrying the safety profile, this is adequate but thin.

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 tight sentence with the resource and the verdict scope front-loaded; every word earns its place and there is 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?

For a simple two-parameter read-only audit tool with no output schema, the description is minimally sufficient, but it leaves gaps an agent would care about: what a verdict result looks like, and how missing/unreachable robots.txt is reported. 'allow/deny verdicts' hints at the return shape but does not define it.

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%, so both url and path are fully documented in the schema, including the default '/' for path. The description adds no extra meaning (e.g. how path interacts with wildcard rules or whether it must be URL-encoded), 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 (Check), a specific resource (a public site robots.txt), and the output scope (AI crawler allow/deny verdicts), which lets an agent distinguish it from the calc_* siblings and from agent_readiness_score. It does not explicitly contrast itself with the closest sibling (agent_readiness_score), 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 phrase 'a public site' implies a precondition (the target must be publicly reachable), but there is no statement of when to use this versus agent_readiness_score or agent_ready_fix_pack, and no exclusions such as non-public/intranet sites. Usage is implied rather than guided.

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 and openWorldHint=false, so the safety profile is covered. The description goes further by disclosing the exact computation: base BTU from the ENERGY STAR area chart plus named adjustment factors (−10% shaded, +10% sunny, +600 BTU/person over 2, +4,000 BTU kitchen). It does not state the return format, but the arithmetic is fully transparent.

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: the first states the purpose and source chart, the second front-loads the formula and its adjustments. No filler, and the most decision-relevant information (what it computes and how) leads.

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 no-output-schema calculator with four optional, fully documented parameters, the description supplies the method and all adjustment rules, which is nearly everything an agent needs. The only minor gap is that the returned value (a BTU figure) is not explicitly described, though it is strongly implied.

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%, so the baseline is 3, but the description adds meaning beyond the schema by tying each input to its numeric effect: shade maps to the ±10% adjustment, kitchen to +4,000 BTU, and occupants to +600 BTU each above two. This makes the parameters' impact on the result explicit rather than merely naming them.

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+resource: it computes room air-conditioner capacity in BTU using the ENERGY STAR sizing chart. The scope is unmistakable and clearly distinct from the other calc_* siblings (slab, paint, roofing, etc.), which compute unrelated quantities.

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 name and the stated ENERGY STAR basis, so an agent can infer this is the tool for AC sizing. However, there is no explicit when-to-use guidance, no mention of when another tool (e.g. calc_appliance_energy_cost or calc_solar_panel) would be more appropriate, and no note on input expectations.

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 and openWorldHint=false, so the safe, self-contained nature of the call is covered. The description adds the computation formula, which usefully signals deterministic pure math, but says nothing about default values being applied when arguments are omitted or about the response shape.

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, zero filler: the outcome is stated first, then the exact formula. Front-loaded and fully 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 no output schema, the description does name the return values (daily and yearly kWh plus cost), which is the key missing piece. It does not mention that all four inputs are optional with defaults, but the schema covers that.

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%, so the schema already documents watts, rate_per_kwh, days_per_year and hours_per_day. The description references the same four quantities in its formula but adds no units, ranges, or defaults beyond what the schema provides — 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?

States a specific verb+resource: computes daily/yearly kWh and dollar cost to run an appliance. It clearly distinguishes itself from the construction-materials calculators, though it never names or contrasts with nearby siblings like calc_solar_panel or calc_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?

Usage is implied by 'the cost to run any appliance from its wattage, hours of use and your electricity rate,' which tells the agent the inputs needed. There is no explicit when-to-use, when-not-to-use, or alternative-tool 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 already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description goes beyond that by disclosing the exact deterministic formula and units, so the agent knows precisely how the output is derived and that density must come from the user's plant.

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 tight sentences, output unit front-loaded ahead of the formula. Nothing extraneous; every clause either names the result or defines the computation.

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 output schema, the description explicitly names the return value and unit (tons), and annotations cover safety, so an agent can call this confidently. Only minor edge-case behavior (e.g., zero/invalid inputs) 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?

Schema description coverage is 100%, so the baseline is 3, but the formula adds real value: it shows how L, W, depth (in inches, converted /12) and density (lb/cu ft) combine into tons, clarifying parameter roles and unit handling beyond the field labels.

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 ('Tons of hot-mix asphalt') with scope ('driveway or lot') and the exact inputs used. It is trivially distinguishable from sibling calculators like calc_concrete_slab or calc_mulch_gravel by material and unit of output.

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 phrase 'for a driveway or lot' implies the domain but gives no explicit when-to-use, when-not-to-use, or alternative selection guidance against the many other calc_* siblings. An agent must infer that this is the right tool for asphalt tonnage versus concrete or gravel.

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 and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral detail beyond that: the exact formula used, the default assumptions (1500 sq ft, 50% high, 9/18 sq in per unit) and that vent counts are rounded up. It doesn't discuss units-in vs units-out edge cases, but it goes well past the annotation baseline.

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 purpose ('How much attic ventilation you need...') before the formula, and the formula block is compact and sequenced logically. It is dense but each sentence carries information; 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?

There is no output schema, so the description must convey return values, and it does — intake NFA, exhaust NFA, and vent counts. For a pure calculator with fully-described inputs and annotations covering safety, the definition gives the agent everything needed to invoke and interpret it, with only minor omission of output formatting details.

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's formula adds real meaning beyond the schema: it ties attic_floor_sqft, ratio, upper_pct, and the two NFA-per-unit fields directly into the computation and the ceiling rounding of the vent count. This clarifies how each parameter is consumed, exceeding the schema's per-field descriptions.

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 — computing attic ventilation net free area and vent counts under the 1/150 and 1/300 rules — and describes exactly what it splits into (intake vs exhaust) and returns (vent counts). It is clearly distinguishable from the many other calc_* siblings, which each cover a different material or quantity.

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?

Explains the condition that selects the rules — 1/300 as the 'balanced exception' requiring 40–50% high — which tells the agent when to use each ratio. It does not name alternatives or state exclusions, but given the tool is a single-purpose calculator with no overlapping sibling, clear conditional guidance is sufficient for a 4.

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 and openWorldHint=false, so the safety profile is covered. The description adds substantial behavioral context by disclosing the exact board-foot formula and the definition of one board foot, which helps the agent understand the computation without opening the schema.

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 output and material use, followed by the exact formula. Every element earns its place and there is 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?

For a simple read-only calculator with no output schema, the description is nearly complete: it names the computed outputs (board feet and cost), states the formula, and defines the board-foot unit. It could explicitly link cost to the price_per_bf parameter, but the schema covers that parameter and its default behavior.

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%, so the baseline is 3. The description adds value beyond the schema by giving the formula that relates thickness, width, length, and pieces, and by mentioning 'cost' in relation to the price parameter. It clarifies units and the calculation, though it does not explicitly show the price_per_bf multiplication.

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 output (board feet and cost) and resource (hardwood or dimensional lumber), making the tool's purpose clear. It does not explicitly differentiate itself from sibling calculators like calc_deck_board or calc_flooring_tile, so it falls short of full sibling differentiation.

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 explains what is calculated but gives no guidance on when to choose this tool over alternatives. It lacks when-to-use conditions, exclusions, or named siblings for comparison.

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 and openWorldHint=false, so safety is covered and the description is free to add the computational contract — the exact allowance formula and the per-AWG volume table. It does not say what the response looks like (required volume only, or required vs. available with a pass/fail), which is the remaining gap for a tool with no output schema.

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 computation and NEC citation, then the formula, then the constant table — a logical order with no filler. The single long formula sentence and the trailing allowance list are dense but each carries information an agent cannot get from the schema.

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 an 11-parameter tool with no output schema, the definition supplies the formula and constants needed to predict the result, and the all-optional schema is mitigated by the stated defaults in the parameter descriptions. It stops short of specifying the return shape (units, whether a compliance verdict is included) and what happens when box='custom' with box_volume_cuin=0.

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; the description earns above that by mapping each parameter to its role in the formula ('1 allowance for clamps', '+2 per yoke', '+1 for all grounds', 'each at the largest conductor size present') and by listing the per-AWG allowances the count_6…count_14 fields feed into. The box enum and box_volume_cuin interaction (custom box with marked volume) remains unexplained.

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 — computing required electrical box volume under NEC 314.16 — and scopes it to conductors, devices, clamps, fittings and grounds. No sibling in the calc_* family addresses box fill, so it is unambiguously distinguishable from the rest of the list.

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 phrase 'checked against a standard metal box from Table 314.16(A) or your box's marked volume' implies the sizing/compliance use case, but the description never states when to reach for this versus a generic volume or conduit calc, nor any prerequisites (e.g., know your conductor counts). Usage is inferable 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=true and openWorldHint=false, so the safety profile is covered. The description adds the exact calculation formula and default assumptions (modular brick, ⅜ in joint), which is useful behavioral context; it does not, however, describe output formatting or rounding.

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?

Three sentences, front-loaded with the purpose and defaults, then the formula. No filler; every sentence contributes to correct invocation.

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 calculator with seven optional parameters and no output schema, the description supplies the formula, defaults, and scope needed to call it correctly. It is slightly incomplete because it omits an explicit return-value description and usage guidance relative to sibling 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 coverage is 100%, so all seven parameters are documented in the schema, setting a baseline of 3. The description goes beyond that by showing how the parameters combine in the formula and by stating default brick dimensions, adding relational 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 exactly what is computed (bricks for a single-wythe wall) and the key inputs (area, brick face size, mortar joint), so the resource is clear. It does not name or explicitly contrast with sibling masonry calculators such as calc_concrete_block, so it falls short of full sibling differentiation.

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 no when-to-use, when-not-to-use, or alternative-tool guidance. An agent must infer from the tool name and sibling list that this is for brick walls rather than concrete block or other wall calculators.

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 and openWorldHint=false, so the safety profile is covered. The description goes further by disclosing the full computation chain (cartridge volume, bead area, feet per cartridge, waste factor), which lets an agent verify and explain results. It stops short of saying how the output is formatted or rounded.

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 answer-oriented statement is front-loaded, followed by the four formulas in execution order. No filler sentences; every clause carries either scope or computation detail, and the formula block is dense but each line 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?

All six parameters are optional with schema-documented defaults, there is no output schema, and the description supplies the missing piece by naming the outputs (feet per cartridge, cartridge count) and the math behind them. An agent has enough to call this correctly without further 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 100%, so the baseline would be 3, but the description adds real meaning beyond the schema: it clarifies that the triangular case uses a 'corner bead' with leg² ÷ 2, explaining how shape=tri reinterprets width_in as a leg length, and ties waste_pct directly into the cartridge formula.

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 opens with a specific verb-and-resource statement ('How many tubes of caulk or sealant to buy') and names the two quantities returned: linear feet per cartridge and cartridges for total length. The caulk/sealant resource is distinct enough from the many other calc_* siblings that an agent can route to it, though it never explicitly contrasts itself with adjacent tools like calc_paint or calc_grout.

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 rather than stated: the reader infers this is for estimating sealant purchases from joint dimensions and total length. There is no explicit when-to-use, when-not-to-use, or named alternative among the sibling calculators, so the agent must derive applicability from the resource name alone.

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 and openWorldHint=false, so safety is covered; the description goes further by disclosing the exact computation rules (area = length × width, span brackets, shorter-side − 36 in, mount thresholds). It also names what the response will contain, which matters since no output schema exists. It does not state how defaults are applied when parameters are omitted.

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 outcome before the supporting formulas, and every clause (brackets, clearance rule, mount thresholds) carries operative information. It is dense and semicolon-chained, which slightly hurts scannability, but there is 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 no output schema, the description must convey return values, and it does (span, max span, mount type). Inputs are fully documented in the schema and their roles are explained here. Minor gap: it doesn't say what happens for edge cases such as non-rectangular rooms or omitted parameters.

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 would be 3, but the description adds real semantics: width and length combine into area for span lookup, and ceiling_height_ft maps directly to the mount decision thresholds. The wall-clearance formula also clarifies that the shorter side drives the maximum-span result.

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 specific verb+resource framing ('What size ceiling fan you need for a room') and enumerates the three outputs: suggested blade span, largest span with 18 in wall clearance, and mount type. An agent can distinguish this from siblings like calc_ac_btu or calc_attic_ventilation 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?

Usage is implied by the domain framing (size a fan for a given room), but there is no explicit when-to-use/when-not-to-use guidance and no named alternative among the many sibling calculators. Nothing is misleading, but the agent must infer the triggering context.

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 and openWorldHint=false, so safety is covered. The description adds meaningful behavioral context by explaining the exact formula, the standard 1.125 blocks per square foot coefficient, and how waste is applied. It stops short of describing output format or edge 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?

The description is front-loaded with the purpose, then provides the formula and coefficient in two compact sentences. Every element directly supports understanding the calculation, with 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?

Given 7 optional parameters, no output schema, and read-only annotations, the description is largely complete: it explains what is calculated and how. It could explicitly note that all inputs are optional with defaults, but the core computation is clear enough for an agent to invoke.

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. The description goes beyond the schema by explaining how joint_in, waste_pct, and net wall area combine in the formula, giving functional meaning to several parameters rather than just repeating their 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 description states a specific calculation: number of 8×8×16 concrete blocks (CMU) for a wall. It distinguishes this from sibling calculators like calc_brick or calc_concrete_slab by naming the exact material and unit size.

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 tool name and the phrase 'for a wall,' but there is no explicit when-to-use, when-not-to-use, or alternative routing guidance. The description does not tell the agent when to choose this over other masonry calculators.

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 and openWorldHint=false, so the safety profile is covered. The description goes further by publishing the exact computation (cylinder volume, unit conversion from inches to feet, ÷27 for cubic yards, and a waste multiplier), which is real behavioral disclosure for a calculator beyond what annotations provide.

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?

Three tight sentences with no filler: purpose, geometric differentiator, then the formula. Front-loaded and self-contained, though the formula line is dense and could have been broken out for readability.

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 output schema, the description partly compensates by stating the formula's outputs (cubic feet and cubic yards), which is the core return value. It stops short of covering what bag_yield_cf produces — presumably bag counts — leaving that return dimension unaddressed for a 5-param 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?

Schema coverage is 100%, so the baseline is 3. The description earns above baseline by mapping parameters into the formula with units: diameter in inches divided by 24 to convert to feet, height in feet, count as a multiplier, and waste% added to the result. Only bag_yield_cf is left unexplained in the formula narrative.

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 (concrete volume for round columns, piers, tube forms/sonotubes) and explicitly differentiates its geometry from other concrete tools: 'Uses cylinder volume, which differs from slab math.' An agent can route this away from calc_concrete_slab, calc_concrete_footing, and calc_concrete_block 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?

Usage is implied rather than stated: the round/tube geometry tells the agent this is the right tool for cylindrical pours, and the slab contrast hints at the alternative case. However, no sibling is named and there is no explicit 'use X instead when...' statement, so selection still requires 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=true and openWorldHint=false, so safety is covered. The description adds real behavioral content beyond that: the exact cubic-yard formula, the inch-to-foot conversion convention, and the waste multiplier applied to the result. It does not explain the role of bag_yield_cf or what the response contains, but the core computation is fully 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?

Two compact sentences with zero filler; the scope and formula are front-loaded and every clause carries information an agent needs. No repetition of the title or restating of field names without purpose.

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, five-optional-parameter calculator with no output schema, the description gives the scope, unit conventions, and formula, which is nearly enough to call it correctly. The gap is that the output contents (notably any bag count derived from bag_yield_cf) go unexplained, and no output schema compensates.

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%, so the baseline is 3. The description reinforces the unit semantics of width_in and length_ft and shows how waste_pct enters the formula, but it says nothing about bag_yield_cf, the fifth parameter, so it adds only marginal meaning over 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 (compute volume) and a precisely scoped resource (continuous trench/wall footings), which cleanly separates it from siblings like calc_concrete_slab and calc_concrete_column. The unit convention (width in inches, length along the full perimeter) further pins down what is being computed.

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 phrase 'continuous trench/wall footings' implies when to use it versus the slab/column/block calculators, but there is no explicit when-to-use or when-not-to-use guidance and no named alternative. Adequate but leaves the routing inference to the agent.

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 and openWorldHint=false, so the safety profile is covered. The description goes further by publishing the exact formulas used, letting an agent predict and sanity-check the numeric output rather than treating it as a black box.

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: the purpose comes first and the formula second, with no filler. The formula sentence is dense but each symbol maps directly to a named parameter, so 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 read-only calculator with fully documented optional parameters and no output schema, the description tells the agent what the two possible returns are (cubic yards or bag count) and how they are derived. Minor gap: it says '80 lb bags' while bag_yield_cf is configurable, so the default assumption is not reconciled.

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 units and defaults are already documented and the baseline is 3. The formulas add real meaning by showing each parameter's role: thickness enters as /12, waste_pct as a (1 + waste%) multiplier, and bag_yield_cf as the divisor converting cubic feet to bags.

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 ('Estimate ready-mix cubic yards or the number of 80 lb bags') and scopes it to a rectangular slab, patio or driveway. This clearly separates it from sibling calculators dealing with footings, columns, or concrete block.

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 phrase 'rectangular slab, patio or driveway' implies when the tool applies, but no alternative is named even though siblings like calc_concrete_footing, calc_concrete_column, and calc_concrete_block are the obvious competing choices. Usage is inferable but not 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=true and openWorldHint=false, so safety is covered; the description goes further by disclosing the full computation model (riser count formula, side-profile area, volume conversion, waste and bag-yield handling) and enumerating what is produced. It discloses behavior beyond the annotations, though it doesn't state explicitly that the result is a deterministic computed report.

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?

It is dense but front-loaded: the purpose and the output list come first, followed by the formulas. The formula block is long but earns its place by making the calculation auditable. Minor redundancy between the opening list and the formula narration keeps it from a 5.

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 output schema, the description carries the burden of explaining return values and does so by listing risers, riser height, treads, landing, cubic yards and bags. Combined with the annotated read-only nature and full parameter descriptions, an agent has what it needs; only explicit unit/format of the response is absent.

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 showing how the parameters interrelate: max riser drives the riser count, waste_pct feeds the volume and bag math, and bag_yield_cf converts cubic feet to bags. This clarifies parameter roles beyond the terse schema labels.

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+resource: it computes concrete volume for solid steps, enumerating risers, riser height, treads, top landing, cubic yards and 80 lb bags. This is clearly distinct from siblings like calc_concrete_slab, calc_concrete_footing, or calc_stair_stringer, so an agent can select it 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?

There is no explicit when-to-use statement and no routing to alternatives – it never says, for example, to use calc_stair_stringer for stringers or calc_concrete_slab for flat slabs. Usage is only implied by the tool name and the formula. Selection guidance is left entirely 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 only declare readOnlyHint=true and openWorldHint=false; the description goes further by disclosing the exact computation (Table 5 areas per AWG, Table 4 area × 53/31/40% depending on conductor count) and the unusual rounding rule (round up only at .8 or more). These are real behavioral facts an agent could not infer from structured fields, though the response shape is only listed, not described.

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 and outputs, then the formula, then the limits — a logical order with no filler sentences. The partial AWG table (six values followed by an ellipsis) is slightly bulky but each listed constant is directly usable, so little 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 12-parameter, zero-required calculator with no output schema, the description covers inputs (wire types, conduit types), the governing rules, and the five result fields it returns, which is enough to call it correctly. Residual gaps are minor: no statement of units/format for the returned values or how percentages are reported, and no guidance on the all-defaults case.

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 per-parameter descriptions and defaults (count_14 defaults to 6, others 0), so the schema already carries parameter meaning and the baseline is 3. The description adds the wire-area constants and the THHN/THWN-2 restriction on wire type, but says nothing about the count_1 vs count_1_0 distinction or enum coverage for size/conduit.

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 (conduit fill for THHN/THWN-2 in EMT or Schedule 40 PVC) and enumerates the concrete results returned: total wire area, percent fill, fit verdict, smallest conduit, max same-size wires. That scope cleanly separates it from calc_box_fill, calc_wire_size, and calc_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?

The description implies when to use it (sizing conduit for a given wire complement) but never states when not to use it or points at the neighboring calculators. There is no rule such as 'use calc_box_fill for box capacity' or 'use calc_wire_size for ampacity' to route the agent among ~50 calc_* siblings.

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 and openWorldHint=false, so the safety profile is covered. The description goes beyond that by disclosing the exact computation, including the ceiling rounding and the waste multiplier, which tells the agent this is a deterministic formula-driven tool with no hidden side effects.

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, zero filler, and the purpose is front-loaded before the formula. The dense formula is justified because it is the substance of the tool rather than padding.

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 six-parameter deterministic calculator with no output schema, the description supplies the formula needed to interpret the result and the field roles needed to call it. It stops short of stating the return shape (a single integer board count) or the unit handling between the foot-based inputs and the inch-based formula.

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 per-parameter defaults, so the schema already carries the parameter burden and baseline is 3. The description's formula adds some interpretive value by showing how width, gap, board length and waste combine, but it also introduces ambiguity, writing 'width(in)' and 'deck length' without reconciling them against the schema's foot-based fields.

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 computed quantity ('Number of deck boards') with a stated scope ('rectangular deck'), which is enough to separate it from the other calc_* material calculators in the sibling list. The description names the drivers (board width, gap) up front so an agent knows exactly what domain this covers.

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: an agent can infer this is the calculator for deck board counts, and no sibling overlaps this material, so there is little risk of misrouting. But the description gives no explicit when-to-use condition, no note that it assumes rectangular geometry, and mentions no alternative for non-rectangular or diagonal layouts.

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 and openWorldHint=false, so the description's job is to add computational context, which it does: it names the data source, the band-selection logic, and the 'top of range, or your current unit's output if higher' rule. That rule is the kind of behavior an agent cannot derive from annotations or schema.

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 answer type, then the method. The formula sentence is long and compresses three steps and two conversions, but each clause carries information; nothing is redundant with the schema.

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, and the description still tells the agent what comes back (pints/day plus liters and gallons) and how it is computed, which is sufficient for a 3-param read-only calculator. Minor gap: defaults are only in the schema, not restated, which is acceptable.

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; the description goes beyond by explaining the 2,000 sq ft band split and clarifying that pints_emptied_per_day only overrides when it exceeds the chart value. That gives real meaning to an optional parameter the schema only labels 'if replacing a unit'.

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 ('what size portable dehumidifier you need, in pints per day') and anchors it to a named authority (ENERGY STAR chart). An agent can distinguish this from the many other calc_* sizing tools without inspecting 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?

Usage context is implied by 'your space size and how damp it is', but there is no explicit when-to-use/when-not guidance and no routing against nearby siblings like calc_ac_btu or calc_pool_heater_size. An agent can infer the scenario but gets no exclusion criteria.

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 and openWorldHint=false, so the safe, side-effect-free nature is covered. The description adds real behavioral value by giving the exact formula, which tells the agent the computation is deterministic and how inputs combine. It omits rounding behavior for the sheet count.

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 purpose is front-loaded and the formula follows immediately, with no filler or restated name.

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 stateless calculator with full schema coverage and no output schema, the description supplies purpose plus computation logic. The main remaining gap is whether the returned sheet count is rounded up and what units it is in, which an agent might need to interpret the result.

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%, so 3 is the baseline. The formula goes beyond field-level definitions by showing how wall_perimeter_ft, wall_height_ft, ceiling dimensions, waste_pct, and sheet dimensions interact, which adds genuine meaning over 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 resource and output unit (number of drywall sheets for walls plus optional ceiling), which clearly separates it from the other calc_* siblings such as calc_paint or calc_insulation_r_value. It does not explicitly name an alternative, but the resource is unambiguous.

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 phrasing 'for walls and optionally the ceiling,' which signals the include_ceiling toggle, but there is no explicit when-to-use vs. when-not guidance and no alternative tool named. Adequate but not directive.

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 and openWorldHint=false, so safety is covered. The description adds genuine behavioral substance beyond that: the exact computation chain (coverage → gallons per coat → total with loss → kits) plus the derived wet-mils output, which tells the agent what the tool actually returns despite no output schema.

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 answer to 'what does this give me,' then a compact formula block. It is dense but every formula shown maps to an output or intermediate the agent needs; only the trailing wet-mils note feels slightly tacked on.

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 fully documented 6-parameter schema, no output schema, and read-only annotations, the description covers what is needed to call it correctly. The only real gap is that it never explicitly names the return fields or units of the result (gallons, kit count), though the formulas make them inferable.

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% with defaults on all six parameters, so the baseline is 3. The description earns an extra point by tying parameters into the formula (solids by volume, dry mils, area, coats, loss) and implicitly confirming that wet mils is derived rather than an input, which helps the agent map real-world data-sheet values to the right fields.

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 ('How much epoxy floor coating to buy') and enumerates exactly what is produced: coverage per gallon, gallons per coat, total with losses, and kits. This clearly separates it from neighbors like calc_paint, calc_thinset, and calc_flooring_tile, which cover different materials.

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 formula and by the parameter hints ('from the data sheet' for solids and dry mils), so an agent can infer the inputs come from a product technical data sheet. But there is no explicit when-to-use/when-not statement and no naming of alternatives such as calc_paint for non-epoxy coatings.

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 this is a safe, closed-world read (readOnlyHint=true, openWorldHint=false), so the bar is lower. The description still adds substantive context: the data source and vintage (EIA, August 2026), that a user-supplied rate overrides the state default, and the exact formulas including the charging-loss divisor. It does not say what happens to the full-charge and gas outputs when their optional inputs default to 0.

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?

Outputs are front-loaded in the first clause, followed by inputs and then the formulas, so the agent gets the gist immediately. The formula block is dense but functional rather than decorative; the only cost is that everything sits in one long run-on sentence, making the formulas harder to scan.

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 an 8-parameter, all-optional calculator with no output schema, the description supplies the calculation logic, the data source, and the sentinel default behavior. The notable gap is return shape — since there is no output schema, the agent is not told the result keys or how omitted optional outputs (gas, full charge) are represented.

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; the description earns above baseline by showing how each parameter actually enters the calculation (efficiency divided by 100 and multiplied by $/kWh, month = per-mile × miles, loss% applied as a divisor). This makes the override relationship between rate_per_kwh and state, and the role of charging_loss_pct, concrete rather than merely labeled.

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 subject (home EV charging cost) and enumerates the exact outputs: cost per mile, per month, per full charge, plus optional gas comparison. The inputs it consumes (kWh/100 mi, state electricity rate, own rate) are named, so an agent can tell this apart from sibling energy calculators like calc_appliance_energy_cost 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?

Usage context is clear — 'charging an electric car at home' — and the description signals which inputs trigger the optional branches (gas comparison needs mpg and $/gal; full-charge cost needs battery kWh). It does not name an alternative tool or state when not to use it, 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 cover the safety profile (readOnlyHint=true, openWorldHint=false), so the bar is lower, and the description adds real value by publishing the exact formulas for sections, posts and pickets, including the ceil rounding. It omits the rails formula itself and any note about waste/overage, which keeps it from a 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?

Two dense sentences with zero filler: the scope constraint leads and the computation follows immediately. Every clause carries information an agent can act on.

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 zero-required, fully documented calculator with no output schema, the description supplies the derivation logic an agent needs to predict results. It stops short of describing the return shape or units, and silence on whether waste allowance is included leaves a minor 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%, with defaults documented for all six parameters, so the baseline is 3. The formula adds meaning to length, spacing, picket width and gap, but rails_per_section is never referenced, so the description does not fully compensate beyond what the schema already 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?

States a specific computed resource set (posts, rails, pickets) and scopes it to 'a straight run of wood privacy or picket fence', which implicitly separates it from siblings like calc_deck_board or calc_concrete_slab. It does not name any sibling explicitly, 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 'straight run' qualifier implies the tool is not for corners, angled runs, or other fence geometries, which is useful scoping. However there is no explicit when-to-use statement, no alternatives named, and no mention of when this calculator should not be reached for.

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 and openWorldHint=false, so the safety profile is covered. The description adds genuine value by exposing the exact computation (Area = L × W; to buy = area × (1 + waste%); boxes = to buy ÷ coverage per box), letting the agent anticipate outputs in the absence of an output schema.

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 compact sentences: the outcome is front-loaded, followed by the formula. No wasted wording and 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?

For a deterministic calculator with no output schema, the description adequately names the outputs (square footage, to-buy quantity, boxes) and the formula that produces them. It does not specify rounding of box counts or input units/validation, but it is close to complete for a tool of this complexity.

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%, so the baseline is 3. The description goes further by giving the formula that relates the parameters — how waste_pct and box_coverage_sqft feed into the final box count — adding relational meaning beyond the individual field descriptions.

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: computes square footage, waste allowance, and box count for tile/laminate/vinyl/hardwood. It is clear what it does. It does not explicitly differentiate itself from the many sibling material calculators (calc_paver, calc_sod, calc_board_foot), which also compute area-based quantities, so it falls 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?

Usage is implied by the material list and the parenthetical hint that waste is higher for diagonal layouts. However there is no explicit when-to-use versus when-not-to-use guidance and no reference to alternative calculators, leaving the agent to infer the appropriate context.

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 and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavioral semantics beyond that: only the single highest starting surge is counted (motors rarely start simultaneously), and margin is an optional user-chosen buffer. It does not state whether margin applies to running watts, starting watts, or both, which is a real gap.

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 goal, then the formula, then supporting details, and each sentence carries information. The amps-at-240V note is mildly tangential for a generator-sizing tool, keeping it from a 5, but nothing is padded.

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?

There are 18 optional parameters, no output schema, and no annotations describing results, yet the description never states what the tool returns (total running watts, total starting watts, amps) or how margin is applied. The calculation method is well covered, but the return contract and margin semantics are left for the agent to infer.

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%, so every per-item wattage, starting-surge value, and default is already documented in the schema. The description's param-related statements ('margin is an optional buffer you choose', 'largest other motor') largely restate the schema text, so the baseline of 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?

States a specific verb and resource ('What size generator you need for a power outage') and immediately defines the two outputs (running watts and starting watts), which cleanly separates it from siblings like calc_voltage_drop or calc_appliance_energy_cost. An agent can tell what this computes 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?

Gives clear usage context: 'add the running watts of everything you will run at once, then add the single biggest motor starting surge' and 'Enter how many of each item you plan to run at the same time.' It does not name a when-not or an alternative sibling tool, 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 and openWorldHint=false, so safety is covered; the description adds useful computational behavior — that rates are per 1,000 sq ft, that purity and germination from the seed tag are multiplied into pure live seed, and that bag counts round up. It stops short of explaining edge behavior such as what happens when the bag size is left at its zero default.

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 question the tool answers, followed by the formula chain. Density is high and little is wasted, though the run of three formulas in one sentence is slightly compressed for skimming.

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 five-parameter, fully-defaulted, no-output-schema calculator, the description supplies the underlying computation, which effectively conveys what the tool returns. The remaining omission — output units, whether bag counts appear when bag_lb=0 — is minor but real.

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 a 3 baseline would suffice, but the description adds real meaning: it tells the agent where purity_pct and germination_pct come from (the seed tag) and how they enter the formula via PLS. The one gap is bag_lb, whose 0 default is never explained in terms of the bag-count output.

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 opens with a specific verb-and-resource statement ('How much grass seed to buy for a new lawn') and immediately scopes it to new lawns with university seeding rates. It is clearly distinguishable from adjacent siblings such as calc_sod and calc_lawn_fertilizer 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?

'For a new lawn' implies the boundary (establishment, not overseeding or fertilizing), but the description never states when not to use it or names an alternative tool. Usage is implied rather than prescribed.

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 and openWorldHint=false, so the safety profile is covered. The description adds real behavioral value by disclosing the exact formula, the editable density assumption, and the waste/bag-rounding behavior (⌈pounds ÷ bag size⌉), which tells the agent precisely how inputs map to outputs.

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 supplies the formula in a compact notation. The formula is dense but every clause maps to a parameter or output, so it largely earns its space.

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 output schema, the description names both return units (pounds and bags) and explains the rounding rule for bags. All eight optional parameters with defaults are semantically covered, so an agent has everything needed to call and interpret the 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?

Schema coverage is 100%, so the baseline is 3, but the formula goes beyond the schema by showing how each input participates: L, W, J, depth, area, density, and waste all appear in the joint-share and volume equations. Density is explicitly flagged as product-dependent (~100 sanded, ~85 unsanded).

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 — computing grout quantity (pounds and bags) from tile size, joint width, joint depth, and area. This is clearly separable from the sibling calc_flooring_tile, which covers tile count rather than grout consumption.

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 (tile job grout amount) implies when to use it, but there is no explicit routing advice versus calc_flooring_tile or other tiling siblings, and no statement of assumptions or prerequisites. Usage is inferable but not guided.

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=true and openWorldHint=false, so safety is covered. The description goes well beyond them by disclosing the USDA NRCS PA-1 capacity table source, the exact runoff formula, the adequacy condition (Q <= capacity at slope), the downspout-count formula, and the max-roof-area relation. It does not explicitly state the output shape, but the behavioral mechanics are unusually transparent.

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 sentence, followed by formulas that earn their place for a complex engineering calculation. No filler or repetition, though the formula block makes it a dense read compared to simpler tool descriptions.

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 7-parameter tool with no output schema, the description is nearly complete: it explains the computation, the adequacy criterion, and the max roof area. The main gap is that it never states the shape of the result (e.g., capacity, Q, adequacy boolean, downspout count), which an agent would have to infer.

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%, so all seven parameters are already documented with defaults in the schema. The description adds formula-level meaning by showing how roof area, rainfall intensity, slope, gutter capacity, run length, and max run per downspout feed into the calculation. That is useful added context, but it stops short of per-parameter semantics beyond what the schema already 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 states a specific verb+resource: checking gutter runoff capacity in a design storm and computing the number of downspouts needed. This is clearly distinct from siblings like calc_roofing or calc_appliance_energy_cost. The agent can tell what the tool does 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?

Usage context is implied by the design-storm scenario ('Check whether a gutter can carry the runoff from your roof in a design storm'), but there is no explicit when-to-use, when-not-to-use, or named alternative. In a large calculator suite this is adequate but leaves the agent to infer when this specific calculation applies versus other calc_* 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 readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the description adds real value by disclosing the exact deterministic formula (Thickness = target R ÷ R per inch) and the secondary board-foot volume derivation, telling the agent precisely how inputs map to outputs with no side effects.

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 with zero filler; the purpose and required input are front-loaded, and the formulas are compact and directly actionable. 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?

With no output schema, the description usefully states both outputs (thickness and volume in board feet), and the annotations cover the safety dimension. Units and defaults are carried by the schema, leaving little an agent needs but doesn't have.

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 a 3 is the baseline; the description exceeds it by showing how the three parameters relate (target R ÷ r_per_inch yields thickness, and area_sqft feeds only the board-foot volume), clarifying that area is a secondary rather than primary 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 computation (thickness needed for a target R-value) and its required input (the R-per-inch from the product label), which cleanly differentiates it from the ~30 sibling calc_* tools. The formula makes the exact operation unambiguous.

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 phrase 'printed on your insulation product' implies the context in which you'd reach for this tool, but there is no explicit when-to-use vs. alternative guidance and no exclusions relative to the many sibling calculators. Usage must be inferred from the input requirements.

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 read-only, closed-world profile, so the description's added value is in disclosing the computation basis (USG published coverage) and the rounding rules ('rounded up' for pails and rolls). It does not mention edge cases such as zero area or how defaults are applied.

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 sentence is front-loaded and the formula block is terse and directly tied to the outputs. Nothing is repetitive filler; each clause maps to a returned quantity or a parameter.

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 output schema, the description carries the return-value burden and does so by enumerating gallons, pails, tape feet and rolls. For a deterministic six-optional-parameter calculator this is nearly sufficient, lacking only note on default behavior when area is omitted.

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; the description earns above baseline by showing exactly how the coverage and tape-per-1,000 parameters enter the formulas and by noting the waste multiplier applies to both materials. It does not explain units conversions or what happens if coverage values conflict with the defaults.

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 exact resource (ready-mix joint compound, pails, paper tape) and the output units (gallons, pails, rolls, ft), which cleanly separates it from sheet-counting siblings like calc_drywall. It never explicitly names a sibling to disambiguate against, which keeps it from 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?

Usage is implied by 'How much drywall mud and tape to buy ... for your square footage of drywall,' but there is no explicit when-to-use statement, no prerequisite (e.g. tape joint type, coat count), and no pointer telling the agent to use calc_drywall for board count instead.

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 a safe, closed-world read operation, so the bar is lower; the description goes further by disclosing the exact formulas, including that bags are rounded up. It does not address the edge case where bag_lb defaults to 0 (division by zero for the bags output), leaving one behavioral ambiguity.

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 answer (what you get), followed by a compact formula block that earns its space as an authoritative reference. The first sentence is a long run-on chain, and the formula block partially duplicates the schema semantics, 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?

With no output schema, the description correctly specifies the return values (per-1,000 rate, total, bags, P2O5/K2O), which is essential here. All six params are optional with full schema coverage, so the only shortfall is the undocumented bag_lb=0 behavior.

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 value by tying parameters to their roles: N rate drives product per 1,000, area drives the total, bag weight drives bag count, and P%/K% drive the phosphate and potash outputs. The one gap is not explaining what happens when bag_lb is left at its default of 0.

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: pounds of product per 1,000 sq ft and for the whole lawn, derived from N rate and N-P-K. It also enumerates the full output set (total product, bags to buy, phosphate and potash applied), which makes it unambiguously distinct from neighbors like calc_grass_seed or calc_sod 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?

The opening 'How much fertilizer to put on your lawn' implies the use case, but there is no explicit when-to-use/when-not guidance and no named alternative among the many calc_* siblings. An agent must infer that this is the fertilizer-dosing tool rather than seeding or sod coverage.

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 this a safe, closed-world read operation, and the description is consistent with that. Beyond the annotations it discloses real behavioral facts: the quantity table used, that bond pattern applies corrections to both brick and mortar, that waste defaults differ for units vs mortar, and that units_per_bag=0 falls back to standard brick/block 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?

The purpose is correctly front-loaded in the first clause, but the majority of the text is a dense formula dump that an agent does not need in order to select or invoke the tool. It is one paragraph and not padded with filler, yet the formulas crowd out the usage routing that is missing.

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 output schema, the description does the necessary job of naming the three returned quantities (units, cubic feet of mortar, bags). All seven optional parameters are documented at full coverage, and the read-only annotations require no further safety disclosure; only the exact response shape and the ordering/rounding of results are 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?

Schema coverage is 100%, so the schema carries the defaults and enums, but the description goes further by showing how each input feeds the result: joint_in selects the table row, bond adds a multiplicative factor, and each waste percentage is applied to a different quantity. The 'Block = wall × 1.125' line is the weakest, since it appears without tying back to a named 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 opening clause states a specific verb and resource: compute mortar quantities (units, cubic feet, bags) for a brick or concrete block wall, and even names the data source (BIA Table 4). It is clearly distinct from generic siblings like calc_grout, but it never names the closest sibling calc_brick, which it partially overlaps by also returning unit counts.

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-to-use, when-not-to-use, or alternative routing. The agent must infer from the phrase 'Mortar for a brick or concrete block wall' that this is for masonry takeoffs, and nothing tells it whether to prefer calc_brick or calc_concrete_block for the unit-count portion.

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?

The annotations already declare this is a safe, closed-world read (readOnlyHint=true, openWorldHint=false), and the description confirms the operation is a deterministic formula. It adds that tons output is optional/density-dependent, but discloses nothing about units edge cases or rounding behavior beyond what the schema and annotations already carry.

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?

Three tight sentences: what it computes, then the two formulas. Front-loaded output statement, zero 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?

For a parameterless-required, deterministic calculator with no output schema, the description adequately supplies both the input relationship and the return values (cu yd plus optional tons). Only minor gaps remain, such as how defaults are applied when inputs are omitted, which is left to the schema.

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 already 100%, setting a baseline of 3, but the description goes further by giving the exact formula (L×W×d÷324) that links the parameters, clarifying units (ft, in) and the relationship between tons_per_cy and the tonnage output. That is genuine meaning beyond the schema's field-level descriptions.

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 computed resource (cubic yards/tons of mulch, gravel, sand or soil) for a specific application (bed or path). This naturally distinguishes it from material-specific siblings like calc_sod, calc_paver, and calc_roofing without needing to name 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?

The scope 'for a bed or path' implies the use case, but there is no explicit when-to-use guidance or any statement about when a sibling calculator is the better choice. Usage is only inferable from the material type.

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 (readOnlyHint=true, openWorldHint=false) already establish this as a side-effect-free, closed-domain calculation, so the bar is lower. The description adds real value by disclosing the exact formula, though it says nothing about precision, rounding, or units beyond gallons.

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, front-loaded with the result unit followed by the formula. Nothing is wasted, though the formula's variable names (L, W) are not explicitly tied to the parameter names.

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 output schema, the description still tells the agent the return value is a volume in gallons, and all three inputs are documented in the schema with defaults. It is essentially complete for a pure calculator; only rounding/precision expectations are unstated.

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 each parameter carries its own default and unit, so the baseline is 3. The formula adds meaning by showing the length and width are halved into radii and that depth is the average depth, but it does not clarify edge cases such as non-uniform depth.

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 resource and result unit ('Gallons in an oval (elliptical) pool'), which plainly separates it from calc_round_pool_volume and the generic calc_pool_volume by pool shape. It does not name those siblings explicitly, so it stops at 4 rather than 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 'oval (elliptical)' qualifier implicitly tells the agent when this tool applies versus the round or generic pool variants, but there is no explicit when-to-use statement or named alternative. Usage is inferred from the shape word alone.

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=true and openWorldHint=false, so the safety profile is covered. The description goes beyond that by revealing the exact deterministic computation, including the fixed per-door (20 sq ft) and per-window (15 sq ft) deductions — genuine behavioral context for a calculator.

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 tight sentences, front-loaded with the output and inputs, then the formula. Every clause earns its place with 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?

No output schema exists, but the description names the computed result ('Gallons = area × coats ÷ label coverage'), which effectively documents the return. It omits rounding/precision details, a minor gap for a pure 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 description coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: the hardcoded 20 sq ft/door and 15 sq ft/window deductions and that gallons derive from perimeter × height ÷ label coverage.

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+unit: 'Gallons of wall paint from room perimeter and height, minus doors and windows, for any number of coats.' This clearly distinguishes it from siblings like calc_drywall or calc_flooring_tile, which compute different materials.

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 formula implies the scope (paintable wall area), so an agent can infer this is for wall-painting estimates, but there is no explicit when-to-use/when-not guidance or reference to a sibling for adjacent tasks.

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 and openWorldHint=false, so safety is covered. The description goes beyond that by disclosing the deterministic computation behavior and the outputs produced (paver count plus cubic yards), which is useful context for a calculation tool.

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 dense sentences: the purpose/scope is front-loaded, then the exact formulas follow. No filler, no repetition of schema fields, and the formula detail earns its place for a 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?

For a 7-parameter, zero-required, read-only calculator with no output schema, the description covers purpose, method, and the quantities returned. It is nearly complete; only explicit output units/format naming 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?

Schema description coverage is 100% with defaults on all seven parameters, so the schema carries parameter meaning. The formulas imply how waste_pct, base_depth_in, and sand_depth_in are consumed, but this adds only marginal meaning beyond the already-complete schema. 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?

States a specific verb+resource: pavers count for patio/walkway/driveway plus cubic yards of compacted base and bedding sand. This clearly distinguishes it from the many sibling calculators (calc_mulch_gravel, calc_asphalt, calc_concrete_slab, etc.) by naming the exact material and derived quantities.

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 resource named (compute materials for a paver project), but there is no explicit when-to-use, when-not-to-use, or pointer to an alternative sibling calculator. No prerequisites or exclusions are 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=true and openWorldHint=false, so safety is covered. The description adds genuine operational context beyond that: the full dosing formulas and the chemical-addition limits (max ~50 ppm raise at a time, max 1 quart acid per 10,000 gal), which constrain how results should be acted on.

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 the empty-state intent are front-loaded, then the formula and per-chemical coefficients are packed into a few dense clauses with no filler. Slightly formula-heavy for a description, but every sentence carries information.

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, and the description compensates by naming output units for each case (lb, fl oz) so the agent knows what the result represents. With only 3 numeric inputs and full schema coverage, the definition is sufficient; it stops short of describing the response object's shape but nothing critical 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 coverage is 100%, so the baseline is 3 and the schema already documents each field's meaning and defaults. The description goes further by showing how each input is used in the formula (|target − current|, gallons ÷ 10,000), clarifying the relationship between parameters rather than restating them.

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 ('how much baking soda raises ... total alkalinity, or muriatic acid ... lowers it') and names the dosing basis (published doses per 10,000 gallons). An agent can distinguish it from the many sibling calc_pool_* tools (chlorine, salt, calcium, stabilizer) at a glance.

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 clear context: it branches on direction (raise vs lower) and names the specific chemicals and units for each case, which implicitly tells the agent when each path applies. However, it never names a sibling or states when NOT to use it (e.g., that it does not compute pH or volume).

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 a read-only, closed-world pure computation, so the safety profile is covered. The description goes beyond that by publishing the actual formulas, including the 1.2 vs. 0.9 product-strength factors and the dilution share equation, which tells an agent exactly how inputs are transformed. It does not state output units or rounding, keeping it short of a 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?

The purpose statement is front-loaded and the formula block follows as compact reference material with no filler sentences. It is dense but every clause carries calculation-relevant information; a slightly clearer split between the raise and lower cases would improve scannability.

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 five-parameter, all-defaulted, read-only calculator with a fully described schema and no output schema, the description supplies the relationship between inputs and the two possible results ('lb' of calcium chloride, gallons to drain). Output units are only implied by the formulas, so it falls just short of fully self-contained.

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, and the description earns an increment by tying parameters into the formulas: pool size, fill-water hardness, and product strength (77% flake vs. 100% anhydrous) are all given operational meaning in context. It adds the reasoning behind the numbers rather than restating 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 opens with a specific verb-and-resource statement ('how much calcium chloride raises your pool's calcium hardness, or how much water to replace to lower it') and covers both directions of the calculation. It does not name a sibling tool, but the pool-chemistry prefix and the calcium-specific framing make it distinguishable from calc_pool_chlorine and calc_pool_alkalinity.

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 dual-mode framing implies when each branch applies (raise via chemical vs. lower via dilution), but the description never states prerequisites (e.g. 'use this when current < target') or explicitly routes to alternatives such as a volume or alkalinity calculator. Usage is inferable rather than prescribed.

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 and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: it exposes the exact formula, unit conversions, and the assumption that trade percent is grams of available chlorine per 100 mL. It omits output rounding/precision, but is transparent for a pure calculator.

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 sentence, followed only by the formula and unit conversions needed to understand the calculation. There is no filler; every sentence contributes to understanding the result.

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 simple 3-optional-parameter calculator with full schema coverage and read-only annotations, the description supplies the output unit, input relationships, and formula. With no output schema, the first sentence still specifies the returned measure (fluid ounces), leaving no essential gap for 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 description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by showing how the three parameters relate in the formula and by defining strength_pct as trade percent grams of available chlorine per 100 mL, which is not stated 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?

States the specific output (fluid ounces of liquid chlorine / sodium hypochlorite) and the goal (raise free chlorine by a target ppm) from named inputs (pool volume, product strength). This clearly distinguishes it from pool salt and pool volume siblings, even without naming them 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?

No when-to-use guidance or alternatives are given. The description explains the calculation but never says when to choose this over calc_pool_salt or calc_pool_volume, nor does it state prerequisites, exclusions, or typical scenarios.

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, closed-world behavior, so the description does not need to restate safety. It adds useful behavioral context by naming the DOE formula, clarifying the coldest-month temperature-rise assumption, and noting that warm-up hours exclude losses.

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 primary output is front-loaded, followed by formulas and assumptions. It is dense but technical content is mostly necessary; a few phrases could be tightened, but there is little 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?

There is no output schema, but the description names the key outputs and explains the formulas and assumptions needed to interpret them. It does not specify exact return field names or structure, which keeps it from being fully complete for an agent expecting structured results.

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 parameter descriptions already do the baseline work. The tool description adds value by explaining how the parameters relate mathematically, especially temperature rise, rate-factor multiplication, gas input from efficiency, and warm-up time from gallons and output.

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 and resource: heater output in Btu/h for an outdoor pool, plus gas input, matching heat pump size, and warm-up time. It is clearly distinguishable from siblings like calc_pool_volume, calc_pool_turnover, and calc_tankless_water_heater_size.

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 outdoor-pool framing and DOE formula imply the intended use, but the description does not explicitly say when to choose this tool over related pool or heater calculators. No exclusions or alternatives are named.

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 and openWorldHint, and the description is fully consistent with a pure computation. It adds real behavioral disclosure beyond that: the 12.2 constant when TDS exceeds 1,000 ppm, and the table-lookup rule that a between-rows reading takes the next greater row. It stops short of stating output precision or rounding.

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 formula, then the lookup and balance-pH rules — every sentence carries computational meaning. It is dense and slightly run-on, packing two formulas and a lookup rule into a compact block, but nothing is 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 no output schema, the description compensates by naming the two return values (the SI and the pH for SI = 0), and it explains the factor-table derivation, which is materially useful. It does not state rounding/precision or the valid input ranges for each reading, a minor gap for a calculation tool with no output schema.

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 earns above baseline by explaining the two non-obvious parameters: the `method` choice (table vs interpolation, with the 'next greater row' tie-break spelled out) and the TDS threshold that switches the constant from 12.1 to 12.2. Those are semantic rules 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 computational verb and named index (Langelier Saturation Index) plus the exact inputs it consumes, so an agent can distinguish it from the neighboring single-chemistry calculators (calc_pool_alkalinity, calc_pool_calcium_hardness, calc_pool_chlorine). The formula is given inline, removing any ambiguity about what is produced.

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 chemistry context (assessing overall water balance from four readings) but there is no explicit statement of when to reach for this versus the individual pool-chemistry siblings, nor any prerequisites. An agent can infer the fit, but must reason about it.

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 and openWorldHint=false, so the safety profile is covered. The description goes further by publishing the exact formula and the ceiling-rounding rule for bags, letting the agent predict the output precisely. It doesn't note the defaults or edge cases (e.g. current above target), but adds real value beyond 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?

Three sentences, front-loaded with the outcome, then the formula. Every element earns its place; no filler or repetition of the schema.

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, and the description fully specifies the return values (pounds of salt and whole bags) plus the rounding convention. An agent has everything needed to call it and interpret the result.

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%, so baseline is 3. The formula adds genuine meaning by showing how each parameter is used and clarifying that target_ppm comes from the chlorine generator's requirements, which is more than the schema's unit labels alone convey.

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 (compute pounds and bags) and resource (pool salt for a saltwater pool), with the exact quantity returned. It is clearly distinguishable from siblings like calc_pool_chlorine and calc_pool_volume 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?

The context ('raise a saltwater pool from its current salt level to the target your chlorine generator needs') implies when the tool applies, but it never explicitly routes the agent away from siblings such as calc_pool_chlorine or states prerequisites. Usage is inferable 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 declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description goes beyond that by publishing the exact formulas used for both the raise and dilution paths, which is genuinely useful behavioral disclosure for a deterministic calculator. It stops short of noting edge behavior (e.g., what happens when current <= target in the drain formula, or that the result is expressed in ounces/gallons).

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 outcome and then the supporting formulas; nothing is wasted. The formula notation ('÷ 10 × gallons ÷ 10,000 × 13') is dense and slightly hard to parse, but it is compact rather than padded.

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 output schema, the description should clarify what is returned; it implies ounces of stabilizer and gallons to drain but never states the output units or result shape explicitly. Defaults (target 40, current 0, 15000 gal, fill 0) live only in the schema, and the no-op case for lowering is unaddressed, leaving modest gaps for an agent relying on the description alone.

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. The description adds value by showing how each input participates in the math — current and target in the raise formula, fill_water_ppm specifically as the dilution denominator alongside pool_gallons — giving the agent a functional understanding of the parameters beyond their schema labels.

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+resource pair (raise cyanuric acid by adding stabilizer, or lower it by draining/refilling) and scopes it precisely to CYA. Among the many calc_pool_* siblings (alkalinity, chlorine, salt, calcium hardness), this is unambiguously the stabilizer/CYA one.

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 clearly frames the two operating modes (raise to target vs. dilute down to target), which tells the agent the tool's two use cases. However, it never names a sibling alternative or states a condition for choosing this tool over calc_pool_alkalinity or calc_pool_volume, so routing guidance 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?

Read-only/open-world annotations already cover safety, and the description adds substantial behavioral detail by giving the exact formulas for required flow, actual turnover, and filter max flow. It still omits edge-case behavior such as how the schema's '0 to skip' inputs are handled and what exact output shape is returned.

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 with no filler: the result set is front-loaded, followed by compact formulas. The first sentence is dense but still 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?

For a calculator with no output schema, the description does a good job naming the three outputs and explaining the formulas behind them. It is slightly incomplete on return structure and zero/skip handling, but the schema covers most input semantics.

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%, so parameter meanings and defaults are already well documented. The description restates variables inside formulas but adds no new semantics beyond the schema, 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?

It enumerates the three results clearly: required pump flow, actual turnover, and filter adequacy. The scope is specific and distinguishable from pool-volume or chemistry siblings, though it does not use an explicit verb or name alternatives.

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 implies when it is useful, such as targeting a turnover time, using a flow-meter reading, or checking filter size. It gives no explicit when-not guidance and does not route the agent to related pool calculators.

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 and openWorldHint=false, and the description adds value by disclosing the exact computation (average depth, 7.48052 gal/cu ft), letting the agent sanity-check results. It does not state unit assumptions or error behavior for negative/inverted depths, which keeps it below a 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?

Two sentences: what it computes, then the exact formula. Zero filler and the scope qualifier 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 output schema, the description correctly names the output unit (gallons) and gives the full formula, and defaults live in the schema. It omits edge-case handling (flat-bottom pool where shallow equals deep, zero or inverted depths), which is a minor but real gap for a 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 the baseline is 3; the description goes beyond the per-parameter blurbs by explaining how shallow_ft and deep_ft are combined into an average depth and how length_ft and width_ft enter the product. It adds real semantic linkage rather than restating types.

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 (calculating gallons) plus a shape qualifier ("rectangular pool") and a geometric precondition ("sloped bottom, using average depth"). The word "rectangular" implicitly separates it from the oval and round pool-volume siblings, but no sibling is named 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?

Usage is only implied by the shape adjective; the description never says "use this for rectangular pools, use calc_round_pool_volume / calc_oval_pool_volume otherwise," nor does it address flat-bottom pools or other alternatives. An agent can infer the routing but must do the work itself.

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 and openWorldHint=false, so safety is covered. The description goes further by disclosing the exact deterministic formulas used (pitch factor, ridge rise, angle via atan), which lets an agent predict output precisely. It stops short of stating output units, which would complete the behavioral picture.

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 computed outputs, followed by a compact formula block that is terse and information-dense. The three formula sentences each carry distinct value, though the notation is dense enough that plain-prose framing would aid readability slightly.

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 output schema, the description correctly enumerates the three return values (rafter length, ridge rise, roof angle), which is exactly what the agent needs. The remaining gap is output units (rafter/ridge presumably feet, angle degrees) and the fact that all three parameters are optional with 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 description coverage is 100%, so the schema already documents run_ft, pitch_rise and overhang_in with units and defaults, establishing a baseline of 3. The description's formula adds the relationship between overhang and run (added together before multiplying by pitch factor), but no meaning beyond that.

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 precise verb+resource: computes common rafter length, ridge rise and roof angle from run and pitch, plus optional overhang. This clearly separates it from siblings like calc_roofing (material estimation) or calc_stair_stringer (different geometry), so an agent can select it 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?

The description explains the required inputs but gives no when-to-use guidance, no prerequisites, and no mention of when to choose calc_roofing instead. Usage is only inferable from the formula, which the calibration treats as insufficient 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 already declare it a read-only, closed-world calculation, so the safety profile is covered. The description adds real behavioral value by disclosing the underlying method (Texas Manual on Rainwater Harvesting), the exact formula, and the rounding rule for barrels.

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 output description, then the method, then formulas — no filler. Slight deduction because 'First flush = roof ÷ 1,000 × 10 gal' hardcodes the default rate rather than referencing the parameter, which reads as a fixed constant.

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 five optional params and no output schema, the description carries the burden well by naming the three returned metrics and the computation path. Minor gaps: no statement that defaults are applied when params are omitted, and no note on units of the returned first-flush value.

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 goes further by showing how each input enters the math (rain × footprint × 0.62 × efficiency, gallons ÷ barrel size, roof ÷ 1000 × 10), clarifying roles the schema only labels.

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 quantities computed (gallons collectible, barrels filled, first-flush diversion) and the inputs driving them, which separates it cleanly from neighbors like calc_gutter_size or calc_roofing. An agent knows precisely what it gets back.

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?

Implies usage through phrases like 'from a storm, a month or a year of rain,' which hints at the rainfall input, but gives no explicit when-to-use/when-not guidance and never names an alternative calculator for adjacent questions (e.g., gutter sizing).

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 and openWorldHint=false, so the safety profile is covered. The description adds substantial behavioral context: exact formulas, default assumptions, edge clearance handling, lap splice logic, waste allowance, and ASTM A615 weight basis.

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 definition is front-loaded with the purpose, then packed with formula details. It is dense and every sentence contributes, though the single-paragraph formula block could be more readable if structured as separate lines or bullets.

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 complex calculator with 8 fully described optional parameters, read-only annotations, and no output schema, the description supplies enough detail to call it correctly. It names the outputs (bar count, splices, linear feet, sticks, weight) and the governing formulas.

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. The description goes beyond the schema by linking parameters through formulas: clear span from width/length and edge clearance, bar count from spacing, lap length from bar diameters, and weight from ASTM A615 lb/ft.

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 rebar quantity for a rectangular slab grid, including bar count, lap splices, linear feet, sticks, and weight. This clearly distinguishes it from sibling calculators like calc_concrete_slab and calc_board_foot.

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 clear context by specifying it is for a rectangular slab grid and gives the complete formula, so an agent knows when it applies. However, it does not name alternatives or state when not to use it, such as for irregular slabs or other rebar shapes.

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=true and openWorldHint=false, so the safety profile is already covered. The description adds genuine context beyond that: block sizes are editable because product lines differ, drainage rock is straight-wall-only, and the exact formulas disclose how each figure is derived so results can be sanity-checked.

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 output scope are front-loaded in the first sentence, followed by defaults and formulas. For a formula-driven calculator the equations earn their place, and there is 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 13 parameters, no required fields, and no output schema, the description carries real weight. It exposes the formulas so an agent can infer the returned quantities, though it never explicitly names the return fields or output format for a fully zero-argument-defaultable 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?

Schema coverage is 100%, so the baseline is 3, but the description maps parameters to roles in the formulas (bury ratio, cap height, trench width, drain zone) and explains the straight-vs-circle run substitution, adding interpretation the schema alone does not provide.

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 (retaining wall block count) and enumerates every output component: buried course, cap units, base gravel, drainage rock. An agent can distinguish it from calc_concrete_block, calc_paver, and calc_brick from the description alone.

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 clarifies the two supported shapes (straight wall or a circle for fire pits/tree rings) and notes drainage rock applies to straight walls only, which implies usage. However, it never states when to choose this over sibling calculators like calc_paver or calc_concrete_block, and offers no exclusions.

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 and openWorldHint=false, so the safety profile is covered. The description goes further by disclosing the exact algorithm (pitch factor √(1+(rise/12)²), overhang added to both dimensions, waste multiplier), which tells the agent this is deterministic, side-effect-free math and exactly how inputs combine. It stops short of noting defaults are silently applied or how results are formatted.

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?

Three sentences, front-loaded with the purpose, then the math. The formulas are dense but each one earns its place by defining an otherwise ambiguous conversion. Slightly formula-heavy for a description, but no filler or 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 no output schema, the description carries the return-value burden and largely does so by naming the computed outputs (area, squares, bundles) and units. It omits the exact response shape and the fact that all six parameters default when omitted, which slightly under-serves an agent preparing a call, but the core contract is present.

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 formula adds real meaning beyond the schema text: it shows overhang_in is applied to both length and width, pitch_rise feeds rise/12, and waste_pct is a multiplicative allowance. It does not, however, show how bundles_per_square is used to reach the bundle count, leaving that one parameter's effect implicit.

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 with named outputs: roof area from footprint and pitch, converted to roofing squares (100 sq ft) and shingle bundles. An agent can tell this is a roofing-material takeoff calculator without opening the schema, and it is distinguishable from generic area tools like calc_sod or calc_paint by the pitch-factor and bundle output.

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 formula and units (squares, bundles), which signals the roofing-takeoff scenario, but the description never states when to use this versus siblings like calc_asphalt or calc_rafter_length, nor any prerequisites (e.g., that it works from a rectangular footprint only). The guidance is inferable, not explicit.

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 and openWorldHint=false, so the safety profile is covered. The description adds value by disclosing the exact formula (constants 7.48052 and 5.875), letting the agent reason about the computation, but it says nothing about output format or rounding 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?

Two compact sentences, front-loaded with the resource and then the formula. No filler, though the two equivalent formula forms are slightly 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?

For a deterministic calculator with full schema coverage and readOnly annotations, the definition is essentially complete — the output unit (gallons) is stated and no write/precondition concerns exist. It would only improve by naming the alternative pool-volume tools.

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%, so both parameters (diameter_ft, avg_depth_ft) and their defaults are already documented in the schema. The formula restates that D and depth feed the calculation, adding no new syntax or constraint beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.