The Cable Code

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

Beyond the readOnly/idempotent/closed-world annotations it discloses source tables (NEC Ch. 9 Table 8, UL 1581 Table 30.3, IEC 60228:2004 Table 2), the 400 error behavior for unknown sizes, determinism/no-LLM, and the caveat that an ICEA K cannot be verified against an IEC Ki. It does not say what happens if both awg and mm2 are supplied, or neither, which is the one behavioral 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?

Front-loaded with the conversion scope, then inputs, then alternatives, then behavior — a sensible order with no filler sentences. It is written as a long semicolon-chained block, and the source-table parenthetical is dense, which costs a point on readability but not on content value.

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 5-parameter, zero-required, no-output-schema conversion tool it covers inputs, defaults, error behavior, sources, and sibling routing. What is only partially covered is the return shape — 'each size with its resistance and source' hints at a table but the granularity for a single-size lookup versus a full list is not spelled out.

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 meaning: awg and mm2 are mutually exclusive alternatives rather than independent filters, metal defaults to Cu, and k is specifically the ICEA constant expressed in MΩ·km with a stated comparability limitation. That goes beyond the schema's one-line property 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 transformation: AWG/kcmil ↔ IEC 60228 mm², in both directions, by area and by maximum resistance at 20 °C. It also names the two sibling tools it is not (decode_cable_code for whole designations, design_cable for sizing), so an agent can route 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?

Explicit routing: 'Use it to translate a North American size; to decode a whole designation use decode_cable_code, to size a cable design_cable.' It also states the input rule 'Send awg or mm2 (one of them)' and the metal default, so when-to-use and which-argument-to-supply are both covered.

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 safe, idempotent, closed-world read; the description adds real value beyond that by naming the rule sources (HD 603/620, NEC Tables 300.7(A)/(A), IS 1255), stating the answer carries a source and 'seen' level, and disclosing the null-with-reason fallback. It does not state the unit of the returned depth, which is a notable omission for an engineering answer.

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 resource and its varying dimensions; every clause (sources, null behavior, determinism) carries information. It is a single very dense sentence with stacked parentheticals, which costs some readability but 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?

Covers the four-parameter shape, the enum axes, the rule provenance, the failure mode, and the absence of LLM nondeterminism; with no output schema, describing the payload (depth with source and seen level) is exactly what is needed. Only the returned unit 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 coverage is 100% and three parameters have enums with their own descriptions, so the schema does the heavy lifting. The description restates the same axes (location, direct/raceway) without adding syntax, defaults, or constraints beyond what is already documented.

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 resource (minimum burial cover of a power cable), the dimensions it varies along (country, voltage, location/method) and the data provenance. No sibling tool in the list touches burial depth, so the purpose is unambiguous on its own.

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 (ask for burial depth when you need it), and the 'free, deterministic, no LLM' note hints at when to prefer it over reasoning. But there is no explicit when-to-use/when-not, no prerequisite statements, and no alternatives 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?

Beyond the readOnly/idempotent annotations, the description discloses pricing ($0.50 per calculation in USDC via x402), the free verdict counted against 2 free calls per caller per UTC day, that a bad request costs nothing, and the 50-item batch pricing. This is substantial behavioral context an agent needs before invoking.

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 is front-loaded, but the answer description is a dense run-on wall of text mixing return structure, pricing, and input semantics. It is information-rich but hard to parse, and some clauses could be split or trimmed.

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, no-output-schema tool, the description thoroughly enumerates the return structure (steps, cut-back lengths, lug, kits, creepage, fittings, PDF) and the input contract. Nothing an agent needs to call it correctly appears 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, but the description adds real meaning: it explains the pollution classes, edge/htm_lower semantics, the fittings sub-fields, and the governing rule that 'the design decides the rest, and the kit's own instruction wins over the makers' lengths.' That interaction logic is not 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 a specific verb and resource ('Prepare the end of an LV, MV or HV power cable for its termination or joint') and explicitly distinguishes itself from design_cable and commissioning_sheet. An agent can tell exactly what this tool does and does not do.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent: 'Use design_cable for the cable itself and commissioning_sheet for the tests after installation; this tool is only the end preparation.' It also states the free-vs-paid condition and that a bad request costs nothing, leaving little to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the check is deterministic with no LLM, and the result is a per-rule verdict set (required, found, pass/fail/not checkable) with source provenance down to clause, page and 'how firmly seen'. It also discloses the key limitation that this is a nominal-rule check, not a certificate or type test — useful, but short of a full account of result 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?

Front-loaded with the verb and the three input modes, then rule sets, output shape and caveats — a sensible order. The long standards roll-call is condensed but overlaps the schema's exhaustive list, and the important 'not a certificate' caveat sits at the very end where it is easy to skim past.

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 carry return-value information, and it does: every rule is returned with required, found, verdict and source provenance. For a 4-parameter tool with nested objects and dozens of rule sets, the remaining gap is operational — behavior when no standard matches, output size or limits on the rule list — rather than conceptual.

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 description earns one above it by explaining the semantics of the modes rather than restating them — construction is characterized as what 'a maker's datasheet or tender offer states', including layer thicknesses and screen/armour data, which links the parameter to extract_datasheet/read_tender workflows. The standards list in prose largely duplicates the schema's enumerated values, limiting the added value.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb and resource ('Check a power cable against a standard's nominal rules') and enumerates the three checkable input forms. It implicitly distinguishes itself from design_cable by referring to 'the design field of a design_cable answer', and the closing caveat ('not a certificate or a type test') bounds the claim. It never names a sibling as the alternative for an adjacent task, so a 5 is not warranted.

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 through the three accepted input forms (designation, design, construction) and the 'auto' default for standards the cable claims, which tells the agent what to supply. There is no explicit when-to-use/when-not-to-use statement relative to extract_datasheet, read_tender, decode_cable_code or design_cable, and no guidance on what to do when a standard cannot be matched.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that: it is always paid ($0.50 per calculation in USDC via x402, no free allowance, per-item billing for up to 50), uses a stored table with no outside call, and enumerates the four verdict values. That is genuinely useful behavioral context.

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 is front-loaded, but the description is one sprawling run-on sentence with stacked parentheticals (data source, GeoNames, pricing) that makes it harder to parse than necessary. Every element is relevant, yet the structure could be broken into discrete sentences without losing content.

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 discloses the verdict vocabulary, the data source, the resolution behavior for coordinates, and the payment model, which is sufficient to call it correctly. It omits what happens for an unknown place or how 'unknown' verdicts arise, a minor gap for a read-only computation 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 would be 3, but the description adds meaning the schema lacks: the input object shape {place, month}, place as a GeoNames id or a "lat, lon" string resolved to the nearest table place with distance, month bounded 1-12, and how sentence/spec/design/items substitute for each other. It adds genuine constraints beyond the schema's passthrough objects.

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 long-term mean daily minimum and mean temperature for a place in a month from NASA POWER, compares it to the design's minimum laying temperature, and returns a verdict. It names the data sources and even distinguishes itself from design_cable, which it consumes as input, so an agent can separate it from siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies the usage condition clearly (checking a site/month against the cable's laying limit) and explains the three input modes: sentence, spec/design from design_cable, or a batch list. It does not explicitly contrast with alternatives such as burial_depth or check_cable, so it stops short of full when/when-not 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?

Goes beyond the read-only/idempotent annotations by disclosing pricing ($0.50 per calculation in USDC via x402), absence of a free allowance, per-item charging for up to 50 items, and that the output is a PDF with fields for recording results. It does not contradict the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One dense paragraph front-loads the purpose but then packs in standards citations, an inline input schema, and payment terms. The inline 'input: {...}' largely repeats the schema and makes the description heavier than necessary.

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 nested tool with no output schema, the description covers the output type (PDF with result fields), the input's test-row default, and important payment constraints. It leaves the roles of alternative top-level inputs (spec, design, sentence, items, lang) to the schema, which is fully described.

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 parameters like input, spec, design, sentence, items, and lang. The description adds a little context by repeating the input sub-fields and default behavior, but mostly duplicates the schema's input description rather than adding new semantics.

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 artifact: generating a Pro commissioning sheet PDF for post-installation tests of a design, with test rows, voltage, duration, and source. It is clearly distinct from siblings like design_cable or check_cable, though the core purpose is buried behind standards references and inline input syntax.

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 by saying it is a separate paid call for a design's after-installation tests, and notes that tests default to every row. It does not explicitly say when to choose this over related siblings such as check_cable or design_cable, nor when not to use 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 cover the read-only/idempotent/closed-world profile, so the description's marginal value is in disclosing output content — fill percentage, jam ratio for three conductors, per-conductor area with its table, and named gaps in a table — plus the 'deterministic, no LLM' guarantee. That is meaningful behavior beyond structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single dense sentence, front-loaded with the subject and scope, and every clause carries information (tables, percentages, jam ratio, defect reporting). The nested parentheticals and the '...' raceway ellipsis make it slightly harder to scan than it could be.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description compensates by stating what the result contains (fill, jam ratio, areas with their table, missing rows). Combined with full schema coverage and annotations, little an agent needs to invoke it correctly 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 parameters are already documented. The description still adds real semantics not in the schema: the 53/31/40% Table 1 limits, the 60% nipple exception, and that a cable may be supplied by diameter — clarifying how inputs map to the calculation.

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 a specific computation — the smallest raceway trade size that holds a given conductor list — and scopes it to NEC Chapter 9 fill. An agent can distinguish it from tray_fill (cable tray) and pull_cable (installation), and it names the governing tables (1, 5, 5A, 8).

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 domain context (conduit fill sizing) implies when to call it, and the nipple flag hints at a branch condition, but there is no explicit statement of when to prefer this over siblings like tray_fill or design_cable, and no prerequisites or exclusions are given.

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 read-only, idempotent, closed-world behavior, so the description is not required to restate safety. It adds genuinely new behavioral context: deterministic with no LLM involvement, and a partial-coverage disclosure ('62 more of its 69 coding systems'), which signals that some systems are unsupported. It does not say what happens with an unrecognized or ambiguous code.

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 in a single sentence plus a short trailing clause, with zero filler. The 'Deterministic, no LLM.' fragment is terse enough to be acceptable, though it sits slightly apart from the main flow.

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 previews the return shape (conductor, insulation, screen, armour, sheath, each with its symbol source), which is the key thing an agent needs to trust the result. What is missing is error behavior for codes it cannot decode.

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 both parameters are documented there with an example code and the language enum, so the description adds no parameter-level meaning beyond the schema. 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?

States a specific verb (decode) and resource (cable type designation) and enumerates the standards families covered (DIN VDE, HAR, BS/IEC, NEC, TS, UTE, CEI-UNEL) plus LAN and fibre. An agent can distinguish this from siblings like check_cable or design_cable 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 by the description ('as printed or listed' designations get parsed) but there is no explicit when-to-use or when-not-to-use guidance, and no sibling such as check_cable or find_equivalents is named as an alternative. The agent must infer that this tool parses a designation while check_cable validates one.

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?

Goes well beyond the readOnly/idempotent annotations: it discloses the answer's shape (a band, not a point), the model's assumptions and their warnings (drum turns, sheath, uniform start, no chemistry), that a supplied calibration replaces the band, and the commercial trait that every call is paid at $5.00 via x402 with no free allowance, including per-item billing in list mode. That payment behavior is invisible in the annotations and is exactly what an agent needs before calling.

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 core answer is front-loaded in the first clause, but the body is a single semicolon-chained paragraph that mixes outputs, warnings, standard comparison, input recital and pricing with no visual hierarchy. The input enumeration largely repeats the schema's own description string, so several lines do not earn their place twice.

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 and a deeply nested, free-form input, the description carries the full burden and does: it enumerates the returned band, the 50/20/10/5 % cases, the curve, the per-temperature times with sources, notes and warnings, plus the AEIC CS8-20 comparison for MV. Cost, calibration override and list-mode billing are all covered.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The free-form 'input' object is only meaningful through this text: ranges and defaults for tempC (20–80, default 70), target (0.01–0.9, default 0.1), byproduct, compound, heatupH, the 'both or neither' coupling of startPpm/targetPpm, and the calibration sub-fields with fallback behavior. It loses a point only because the same block is duplicated verbatim in the schema's own input description rather than adding fresh 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 a precise verb and resource: how many days an XLPE core stays in the oven until a given share of crosslinking by-product remains, and names the mechanism (Fick diffusion) and coefficient sources. It also explicitly distances itself from standards ('never a standard's result') and from the AEIC printed value, so an agent can tell exactly what this returns versus a generic cable-design sibling.

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?

Applicability is implied rather than stated: MV up to 46 kV, XLPE cores before the metallic sheath, calibration when a factory measurement exists. There is no explicit 'use this when…' or 'do not use when…' and no routing to or from siblings other than design_cable as an input format reference.

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

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

Beyond the readOnly/idempotent/closed-world annotations, it discloses that the engine is deterministic with no LLM, that results are a nominal calculation rather than a datasheet, and that unspecified inputs fall back to defaults which are listed in the answer. That is exactly the kind of trust-calibration context annotations cannot express; only runtime cost or output size handling is left unaddressed.

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 verb-and-resource lead is front-loaded, but the whole body is one sprawling semicolon-chained sentence with deeply nested clauses ('with an HD 620 section that lays three single cores up...'). It is dense with real content rather than filler, yet the structure makes it hard to scan, and several standard references duplicate what the schema already documents in far more detail.

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 well: it lists what comes back (per-layer thickness with cited standards, diameter, designation decode, weight, bend radius, pulling force, colours, field stress, current/voltage-drop/short-circuit ratings) plus the selectable file formats. What it omits is that at least one of sentence/spec/design must be supplied, since the schema marks nothing required.

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 and the schema already explains every parameter, including the large nested installation and load objects. The description adds a little framing — that 'sentence' and 'spec' are alternatives and that a bare designation parses as a sentence — but no parameter-level detail beyond the schema.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ('Design and size a cable') and enumerates the cable families (power, control, LAN, coaxial, fibre) plus the concrete outputs (layer thicknesses, diameter, designation, weight, ratings, export formats). It is clearly distinguishable in substance, but it never names or contrasts any sibling such as check_cable, decode_cable_code or iec60287_rating, so the boundary is inferred rather than stated.

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 tells the agent the two entry modes — a free-text sentence in any of 15 languages, or a structured spec — and notes 'a bare designation works as the sentence'. That is usable input guidance, but there is no explicit when-to-use-this-instead-of-X guidance against the many sibling tools, nor any stated 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 cover read-only, idempotent and closed-world safety, yet the description adds cost and quota behavior ("Free, outside the daily free calls, no LLM") that no annotation conveys. With no output schema, it also describes the return fields of both arrays, including that presets carry the exact sentence design_cable expects — a genuinely useful behavioral detail.

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 sequencing are front-loaded, and the long enumeration of preset families is reference detail rather than filler. It is dense and runs as one long clause, which slows scanning slightly, but no sentence 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 single-optional-parameter read tool with no output schema, the description carries all the needed weight: it explains both returned arrays field by field, what design_cable does with them, and the cost model. Nothing an agent needs to invoke it correctly 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%, and the schema already documents the lang enum, its 15 values and the default. The description's "Takes only lang" adds no meaning beyond that, so the baseline of 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?

States a specific verb and resource ("List what the cable designer builds") and immediately names the two arrays returned, presets[] and spec_standards[]. It also distinguishes itself from design_cable by positioning itself as the lookup that precedes that tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit usage rule: call this before design_cable to learn the acceptable preset ids and spec.standard values. It does not state when not to call it or name a competing alternative, but the sequencing guidance is concrete enough that an agent knows exactly where this fits.

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

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

Beyond the read-only and idempotent annotations, it discloses the nested-winding geometry, capacity differences from manufacturers' tables and loose winding, source and seen-level reporting, datasheet precedence, and when load checking is omitted. The reeling-standard scope and deterministic, no-LLM operation add further useful reliability context.

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 and nearly every clause contains relevant technical information. However, the single long, semicolon-heavy paragraph packs calculation rules, catalog coverage, standards, caveats, and optional modes together, making it unnecessarily difficult 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 a complex 19-parameter calculator, the description and fully documented schema cover the principal modes, assumptions, data coverage, and important limitations. With no output schema, it could better summarize the main result forms and more explicitly organize the input combinations for catalog selection versus a dimensioned drum.

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?

Although schema description coverage is 100%, the description adds substantive physical meaning to the length/capacity calculation, allowance and freeboard behavior, and the interaction between reeling and layers. It also clarifies consequential behavior such as omitting load_ok when no maker load rating exists.

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 clearly states two distinct jobs: selecting a cable drum for a required cable length and calculating how much cable one drum holds. It does not explicitly differentiate the tool from the sibling drum_loading, so that selection boundary requires inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear usage contexts for length-based drum selection, capacity calculation, and optional motor-driven reeling derating with layer-dependent behavior. There is no explicit when-not guidance or named alternative, but the main invocation scenarios are understandable.

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 read-only, closed-world, idempotent behavior, and the description adds substantial context beyond them: free calls are capped at 2 per caller per UTC day, full answers require full:true or payment, and pricing is $0.50 per calculation/item via x402. It also notes that custom vehicle input is full-mode only.

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 a dense run-on that packs purpose, usage, schema, and pricing into a few long sentences; the first sentence alone is overloaded with lists. It front-loads purpose, but it repeats schema text and would benefit substantially from paragraphing 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 planning tool with nested input and no output schema, the description covers the inputs, free/paid modes, list mode, and what the plan includes: vehicle counts, positions, securing, and sources. It still does not specify the exact full-answer format or error behavior, so it is strong but not fully complete.

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%, and the description mostly repeats the same input string already present in the schema, including vehicle enum, dt, width, gross, qty, mat default, and custom fields. The only added semantics are minor clarifications such as mat as the friction factor and custom being full-mode only, so baseline 3 fits.

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 sentence names a specific planning task: how many vehicles a drum quantity needs by space and payload, plus rows/positions, chocks, securing, and vehicle comparisons. It explicitly distinguishes this from drum_fit, so an agent can select it without inspecting siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It tells the agent to use drum_fit first to choose the drum, then this tool to plan how filled drums travel. It also explains the free-verdict versus full paid-answer split and states that list mode is always full and paid per item.

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 cover read-only/idempotent safety, and the description adds genuinely non-structured context: the tool is members-only, costs $0.50 per calculation in USDC via x402 with no free allowance, and a 50-item list bills per item. This is exactly the kind of payment/auth disclosure annotations can't carry, though return format details (units, rounding) remain unstated.

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 cost are front-loaded, which is good, but the body is a dense run-on packed with parentheticals that duplicates the schema and is hard to parse. Several clauses repeat the nested input definition verbatim 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 a nested-object tool with no output schema, the description does explain what the calculation returns (losses, present cost, payback, with formula and source) and discloses payment terms. The main gap is the ambiguous sentence/spec/design/items alternation, which isn't fully clarified.

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 already documents every parameter including the nested input fields. The description largely restates that same input text (amps, hours, mu, price, years, interest, lengthM, ambientC, freq, extra) rather than adding new semantics, so it sits at the baseline.

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 (economic size of an MV/HV design via IEC 60287-3-2) and enumerates the outputs: energy lost per year for this size and one/two sizes up, present cost, and discounted payback. It's clearly distinguishable from siblings like design_cable, though it doesn't explicitly announce that distinction beyond referencing 'as design_cable takes it'.

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 through the input contract and the sentence/spec/design/items alternatives, but there is no explicit statement of when to choose this tool over design_cable or mv_electrical, nor of prerequisites or exclusions. The 'Always paid' note hints at a gating condition but doesn't frame tool 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?

Goes well beyond the readOnly/idempotent/openWorld annotations: it discloses the commercial model ('Always paid: the site gives it to members only', '$0.50 per calculation in USDC with x402; no free allowance', per-item billing for lists up to 50), and states the substantive caveat that it never asserts interchangeability. It also says each value carries its source and 'seen level', which no structured field conveys.

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 and the sibling contrast, but the body is one densely nested paragraph of table citations (UL 44, UL 83, UL 1072, IEC 60502-1 Table 15, UL 1581 Tables 50.231 and 50.182) that a selecting agent does not need. The implementation path 'server/pro/equivalence.ts' is noise for tool 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?

With six parameters, nested objects and no output schema, the description compensates by describing the return shape (lines plus a Markdown/txt report file) and the payment flow. The only gap is that it never clarifies the mutual exclusivity of sentence vs spec vs design vs items on the input side.

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 already defines lang, spec, design, sentence, input and items. The description adds only marginal meaning beyond it — the per-item price for lists and the format enum mirrored from the schema — and never explains how sentence/spec/design relate as alternatives.

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

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource with scope: an IEC power cable in mm² compared against its North American counterpart 'value by value', returned 'as lines and as the report file (Markdown or plain text)'. It explicitly demarcates itself from the closest sibling: find_equivalents is 'a quick verdict across many countries' standards', while this is 'the one IEC to NEC / UL pair, value by value'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit alternative and the condition that selects it ('For a quick verdict across many countries' standards use find_equivalents (cheaper...)'), plus the domain of use ('for bids', 'a member downloads it under the equivalents panel'). It also warns the buyer's specification decides, which frames when the output should not be used.

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?

Goes well beyond the readOnly/idempotent/openWorld annotations: it discloses that extraction is LLM-based, that it 'decides nothing', that unreadable and uncertain values are surfaced separately, and that page/row provenance is attached. One tension it does not address is how an LLM read squares with the idempotentHint, since repeat calls may yield different readings.

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 verb and resource, and the long field enumeration is dense rather than padded. It still runs three heavy sentences, and phrases like 'the values that could not be read and the ones the reader is unsure of' could be tightened.

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 full burden and does: it enumerates the returned constructions, their provenance fields, uncertainty reporting, and the optional embedded rule-engine verdict with clause and source. An agent knows what comes back and what to do with 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 coverage is 100%, so all four parameters are already documented in the schema. The description reinforces `url`, `text` and the effect of `standard`, but adds no syntax or edge-case guidance for `hint` and nothing beyond what the schema says about 'auto' resolution, so 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?

Specific verb (read/extract) plus resource (power cable datasheet) plus the exact output shape (constructions with sizes, layers, thicknesses, screen/armour, diameters, standards). It also names the downstream consumer check_cable / POST /api/v1/check, which separates it from the design and lookup siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states the accepted input forms (maker PDF, https link, pasted datasheet or tender text) and routes the agent: set `standard` to have rows checked in the same call instead of a separate check_cable round trip. It adds the caution to review values before relying on a verdict, but gives no explicit 'do not use this for X' exclusion.

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?

Goes well beyond the readOnly/idempotent annotations: it discloses the processing model (cable rebuilt under each rule set layer by layer, values traced to their source), that it is deterministic with no LLM, the three verdict categories with their outputs, and an important limitation ('never a statement of interchangeability; the buyer's specification decides'). That is exactly the kind of behavioural context annotations cannot 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?

Front-loads the purpose in the first clause and the key caveat at the end, with no filler sentences. The long standards enumeration and parenthetical details make it dense for one paragraph, but each element 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?

With no output schema, the description does the necessary work by describing the per-standard verdicts, included differences/reasons, and local-language names. It is slightly thin on defaults (all countries/standards) and on whether the source decoding is echoed back, but an agent has enough to invoke it correctly.

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 80%, and the description's standard list (IEC 60502, HD 603, HD 620 J/M/D/C/K, BS..., EN 50618, HD 627) is only a sample of the 60+ enum values, so it adds framing rather than new per-parameter meaning. Nothing is said about how 'country' and 'standard' interact when both are supplied.

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 ('find the equivalents of a power cable in other countries' standards') with a concrete example gloss. It's clear what the tool does, but it never contrasts itself with nearby siblings like decode_cable_code or equivalence_report, so the agent must infer the split.

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 example phrasing and the note that a 'design as the designer link carries it (design_cable links.designer)' implies the two input routes, which is a useful hint. However there is no explicit when-to-use/when-not, no steering between this tool and equivalence_report or decode_cable_code, and the 'default: all' behaviour is only in the schema.

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

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

Annotations already cover the safety profile (readOnly, idempotent, closed-world), but the description adds substantial value by disclosing what comes back: rule lines with sources and seen levels, makers' declarations flagged as such, NEC listing ladders, or a not_found with a stated reason. That is valuable because there is no output schema. 'Free, deterministic, no LLM' also sets cost/latency expectations.

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, but the first is overloaded: a nine-item parenthetical and a seven-country list duplicate the enum values already in the schema. The genuinely useful part (return shape, not_found behavior) is stacked behind that enumeration instead of being 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?

For a two-required-enum lookup with no output schema, the description does the necessary work by explaining the returned payload and the not_found outcome, and by routing the decoding case to a sibling. It does not address behavior for a country/place combination outside the supported rules set beyond the generic not_found note.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and all three parameters are enums with documented values, so the schema already carries the semantics. The description restates the same place list and country list but adds no format, default, or edge-case guidance beyond what the schema provides, so the baseline 3 applies.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description identifies a specific resource (the lowest fire class or listing a country requires) and the scoping dimensions (country set, nine building/space types), and explicitly differentiates itself from decode_cable_code. It falls short of 5 because the purpose is delivered as a long noun phrase rather than a crisp verb-first statement, so the core action is somewhat buried.

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 states the use case directly ('Use it to choose the fire class to ask for') and names the alternative plus the condition that selects it ('to read the class a designation prints use decode_cable_code (cpr_printed)'). No explicit when-not guidance is given beyond that split, which keeps it from 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?

Beyond the readOnly/idempotent annotations, the description discloses that the tool is always paid at $5 per calculation (also per item for lists up to 50, one payment), what happens when site data is unknown (IEC default values), and exactly what the response contains: every step with value, unit, clause, page, notes, and reasons when no rating is given.

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 dense paragraph that repeats the entire input schema verbatim and states the pricing model multiple times ('Always paid', '$5.00 per calculation', 'no free allowance', 'list of up to 50 items at $5.00 per item, one payment'). These redundancies make it bloated and poorly 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?

For a complex calculation tool with six parameters, nested objects, and no output schema, the description covers standards references, input defaults, output detail, scope exclusions, and payment behavior. Nothing essential for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents every parameter and the nested input object in detail. The description largely repeats that same input block verbatim, adding little new syntax or meaning beyond what the schema provides.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a precise verb and resource: the continuous current rating of one circuit of three single cores, with explicit laying, formation, and bonding options. It distinguishes itself from siblings by referencing design_cable for the spec/design input and by listing exclusions such as armour, three-core cables, and duct banks.

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 'Not covered' list and the note about default site conditions give clear scope boundaries. However, it never explicitly states when to choose this tool over design_cable or other siblings; the guidance is implied by the described applicability rather than phrased as a routing rule.

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

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

Annotations already declare readOnly/idempotent/closed-world, and the description correctly adds things annotations cannot express: it is always paid (members only), $0.50 per calculation in USDC via x402, no free allowance, and a 50-item list is charged per item under one payment. It also discloses provenance behaviour (IEC 60287-1-1, IEC 60502-2) and that unsourced values are reported as missing. It stops short of describing failure/error behaviour.

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 and value list are front-loaded and earn their place, and the payment sentence is essential. But the block repeating 'input: {freq: 50 | 60, trefoilMm?, flatMm?} (axis spacing, mm; absent: touching)' duplicates the schema description word for word and could be dropped, and the pricing detail is told twice.

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 six optional, deeply nested parameters and no output schema, the description does carry a lot: what values come back, that each carries a source, that gaps are flagged missing, and the full billing model. It is weaker on the shape of the response (no structure, units or nesting described) and on the alternative spec/design inputs, which an agent must learn from design_cable.

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 restates the input object verbatim from the schema (freq, trefoilMm, flatMm, 'absent: touching') rather than adding new meaning, and it says nothing about the lang, spec or design parameters. Its only extra signal is that items are always returned in full and billed per item.

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 concrete deliverable and enumerates it: capacitance, charging current, inductive reactance (trefoil/flat), a.c. resistance with skin and proximity effects, dielectric loss and impulse levels, each with its source and explicit gaps where no source exists. That is far more specific than a restated title. It does not, however, say in one line how it differs from the closest sibling (design_cable), which it references only as the source of the input format.

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 implies usage by explaining the three alternative input forms (sentence, spec, design) and the batch form (items, up to 50), and points at design_cable for the spec/design shape. But there is no explicit when-to-use-this-versus-that guidance against siblings like check_cable, design_cable or economic_size, so the agent must infer the routing.

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

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

Annotations already declare readOnly, idempotent and closed-world, so the basics are covered; the description adds cost/allowance behavior ('priced like a decode, on the same free allowance'), determinism ('no LLM'), and provenance labelling ('seen standard' vs 'seen draft'). It also discloses what each row contains and that the ACSS build is supplied alongside the standard row, which goes well beyond the annotations. It stops short of describing how multiple matches or pagination behave when a code hits many country tables.

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 core purpose is front-loaded, but the body is a single run-on construction with deeply nested parentheses and clause citations, making it hard to scan for the actionable parts. The information is largely earned, but it would be materially clearer split into separate sentences for input forms, return content and routing.

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 enumerates the returned fields (stranding, areas, diameters, mass, rated tensile strength, d.c. resistance at 20 °C, tolerances, lay) plus the ACSS build and its draft provenance. Input forms, defaults, and the sibling to use instead are all covered, so an agent has everything needed to call it correctly.

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 relational meaning the schema does not: 'table' with 'row' selects one line of that table, 'table' alone answers every row, and 'core' defaults to ST6A or the ACSS code's own core wire. That clarifies how the four parameters combine rather than merely 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?

Specific verb+resource: 'Look up a bare overhead line conductor', qualified by conductor families (AAC, AAAC, ACSR, ACSR/AW) and the governing standards (EN 50182:2001 4.5, FprEN 50540 clause 4). It explicitly distinguishes itself from decode_cable_code for insulated cables, so an agent can separate it from that sibling without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

States the two intended uses ('read an overhead conductor code or compare one country's table with another's') and names the alternative for the adjacent case ('for insulated cables use decode_cable_code'). The three accepted input forms (code, ACSS code, Annex F table) are each tied to their own condition of use.

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

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

Adds substantial context beyond the annotations: pricing ($0.50 per calculation in USDC via x402), free-tier semantics (verdict counted against the designs' 2 free calls per caller per UTC day), that any paid call answers in full, that a batch of up to 50 items is one payment, and that pdf: true appends a calculation sheet. These are exactly the cost and output-shape facts an agent needs before committing.

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 opening clause, which is good. But the definition is a dense run-on that duplicates the entire input schema text already present in the schema descriptions, padding length without adding 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?

For an 8-param, nested-object, no-output-schema tool with readOnly annotations, the description covers what the answer contains, cost/free-tier behavior, batch semantics, and the pdf option. Minor gap: the lang parameter (15 languages) is not surfaced in the description, though the schema documents it fully.

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 largely restates the input schema verbatim rather than adding meaning. It does add one genuinely new semantic – items are 'always in full, paid per item' – but leaves the lang and spec/design alternative-resolution behavior to the schema alone.

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 and enumerates exactly what the calculation returns: tension per segment from either end, sidewall bearing pressure at bends, jam ratio, clearance and fill, against allowable limits with sources and the governing limit. This is clearly distinguishable from siblings like conduit_fill (fill only) or design_cable (design), which an agent can route without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Guidance is present for modes (free verdict vs full/paid, pdf adds a sheet, items batch always in full and paid per item), which tells the agent how to invoke at a chosen cost tier. However, it never says when to choose pull_cable over conduit_fill, tray_fill, or design_cable, so selection against siblings is left 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 declare only readOnly/openWorld/idempotent, and the description adds the traits that actually govern invocation: it is a long-running job that returns a poll link, results live in memory for one hour then disappear, the file is never stored, and the poll payload shape (thecablecode.tender/v1, job/status/pages/reading) is named. It also discloses pricing tiers, the 80-page/20 MB ceiling, free retry of a failed paid reading, and de-duplication of the same file within the hour.

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?

Nearly all content is load-bearing, but it is delivered as one semicolon-chained sentence that forces the reader to parse async behavior, output shape, and pricing in a single pass. Splitting into short labeled clauses (scope / behavior / routing / cost) would preserve the content and cut scan cost; nothing should be removed, only restructured.

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 asynchronous, paid, open-world tool with three inputs, the description covers what is produced, how it is delivered, how long it persists, what failure costs, input limits, and sibling alternatives. No output schema exists, and the poll response fields are described inline, so nothing an agent needs before calling 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% and the schema already explains hint and lang, so the baseline is 3. The description adds meaning the schema cannot: page counting is 1,700 characters per page and PDFs must be routed to the POST endpoint rather than passed in text, which directly affects how the caller fills the required text 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?

States a specific verb and resource ('Read a project or tender document') and enumerates exactly what the answer contains: cables built as designs, requirement mapping, conflicts, and missing sections. It explicitly separates itself from siblings ('For one cable use design_cable or check_cable; for one maker's datasheet, extract_datasheet'), so an agent can route 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?

Gives explicit routing rules to alternatives and the condition that selects each: design_cable/check_cable for a single cable, extract_datasheet for a maker's datasheet. It also states the input-mode split ('Here the document's text; a PDF goes to POST /api/v1/tender'), which is the main way an agent would otherwise misuse this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the free tier (2 calls per caller per UTC day), the $0.50 USDC x402 price, per-item billing for lists, and that pdf: true attaches a calculation sheet. It does not describe the shape of the returned verdict beyond 'pass or fail' and 'derated ampacity with its table', which is the main remaining 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 opening sentence front-loads the purpose well, but the middle is a dense run-on mixing mode selection, pricing, and a verbatim copy of the input object shape that already appears in the schema. The free-allowance rule and the $0.50 rate are effectively restated in two places, and the inline schema blob is redundant rather than additive.

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 tool with nested objects, no output schema, and a paid/free split, the description covers purpose, alternatives, billing, and the nested input shape. What it lacks is any statement of the response structure (field names for the fill verdict or ampacity table) and error behavior for invalid widths or cable combinations.

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 a 3 is the baseline, but the description adds real meaning on top: width must be 'a width the table lists', covered/layout enums are paired with their valid values, and full/pdf/items are tied to their billing consequences. It stops short of explaining units or defaults for depth, ambientC, mv/kv, or the cables array fields beyond their names.

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 (NEC cable tray fill per 392.22 and cable ampacity per 392.80) with the exact code tables cited, and explicitly names the two siblings it is not (conduit_fill for raceways, design_cable for single-cable IEC ratings). An agent can route correctly 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?

Gives explicit alternative routing (conduit/raceway → conduit_fill, single-cable IEC → design_cable) plus the mode selection rule: omit full for the free verdict, set full: true or make any paid call for the complete answer, and use items instead of input for a batch. Exclusions and preconditions are stated rather than inferred.

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

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

Annotations already declare readOnlyHint/idempotent, but the description adds substantial context beyond them: the tool is deterministic with no LLM, it returns documents rather than persisting anything (resolving what the 'write' in the name would otherwise imply), it specifies the output carriers (Markdown, plain text, CSV, JSON rows), and it flags the result as a draft to verify against standards editions in force.

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 is front-loaded in the opening clause, but the body is a dense, comma-spliced run-on with long parentheticals ('rodent, termite, UV, cold, oil, watertightness, fire, armour and more...'). Nearly every fact is useful, yet the lack of sentence breaks and ordering makes it harder to scan than it needs to be.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 9-parameter, nested-object tool with no output schema, the description carries the full return-value burden and does so thoroughly — section-by-section tender ordering, both output formats, and the GTP column semantics. It also points to GET /api/v1/spec/requirements for the option catalogue, closing the only real discovery 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 coverage is 100%, so the baseline is 3; the description earns above that by explaining the either/or relationship between sentence, spec, design and cables ('Instead of a sentence / Instead of one cable, a project') and by spelling out what the requirements entries mean for the output — REQUIRED filled with each value's source, OFFERED left blank. It adds the semantic frame the schema can't express, though it doesn't clarify precedence if both sentence and spec are supplied.

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 — 'Write the cable specification for a tender' — and enumerates exactly what comes back: the tender-ordered specification plus the required/offered schedule (GTP). It also distinguishes itself from the sibling design_cable by describing this tool's inputs as 'as design_cable takes it', so an agent knows design_cable produces the design while this turns it into a tender document.

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: 'for a tender', one cable or a project of up to 30, and frames the output as 'a draft to check against the editions in force' and 'the same text a Pro member downloads from the designer'. It does not give an explicit when-not-to-use or name a competing sibling for an overlapping case, 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.