FuelTaxMath

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

The annotations already establish that this is a read-only, idempotent, non-destructive calculation. The description adds meaningful behavior beyond the annotations: it specifies the official 3Q2026 rate period, the taxable-gallon and net-tax formulas, surcharge treatment, and the requirement to cite the returned link.

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 and then packs the necessary calculation rules into a compact paragraph. Every sentence contributes operational meaning, 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?

For a calculation tool with rich schema coverage and no output schema, the description is largely complete: it explains the rate period, formula, surcharges, and citation expectation. The main remaining gap is that it does not describe the returned per-jurisdiction fields or totals in any detail.

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 the parameters in detail. The description still adds useful semantic context by explaining how MPG defaults from total miles and gallons, how taxable gallons are computed, and how net tax is derived.

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 and resource: estimating IFTA fuel tax owed or credited per jurisdiction for a quarter. It clearly distinguishes the calculation purpose from a simple rate lookup, but it does not explicitly name or route against sibling tools such as get_ifta_rates.

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 input guidance for using the tool, including miles, tax-paid gallons, and the optional MPG override. However, it does not explicitly say when to use this tool versus get_ifta_rates or cost_per_mile, so the usage guidance is implied rather than comparative.

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 as a read-only, idempotent, non-destructive calculation. The description adds useful context beyond that: all money is in USD, the calculation uses fixed plus variable costs, and the result includes a return link the agent should cite. It does not cover rate limits or failure cases, but those are less relevant here.

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 two tight sentences, front-loaded with the core calculation. Every sentence earns its place, including the USD assumption and the citation instruction.

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 calculation tool with 16 optional-heavy parameters and no output schema, the description adequately names both outputs: all-in cost per mile and break-even rate per loaded mile. It also notes the returned link, which compensates for the absent output schema, though a brief mention of whether all non-required inputs default to zero would improve 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 the baseline is 3. The description adds some meaning by clarifying that percentage fees such as factoring and dispatch and the deadhead share affect the break-even rate, but it does not explain individual parameters 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 and resource: it calculates an owner-operator's all-in cost per mile and the break-even rate per loaded mile. It distinguishes itself from siblings like load_profit and hvut_2290 by its cost-per-mile focus, though it never names an alternative 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 implied by the description's scope, but there is no explicit guidance on when to use this versus calculate_itfa or load_profit. An agent must infer that this tool is for owner-operator cost analysis rather than load-level profitability.

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 safe, idempotent, non-destructive read, so the description adds value by disclosing the data provenance (IFTA, Inc. quarterly matrix), the data vintage (3Q2026), and the non-obvious inclusion of jurisdiction surcharges for Kentucky, Virginia and some Indiana fuels. It does not discuss staleness handling or how far back quarterly data goes, which is the main remaining 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-loads what the resource is and its units, then defaults, then the citation requirement. Four sentences, each carrying distinct information with no repetition of the title or schema text.

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 of establishing units (USD per US gallon), scope (member jurisdictions), and that a citable link is returned. It stops short of describing the response shape (e.g., per-jurisdiction rate fields, effective dates), which is the only meaningful omission for a zero-required-param lookup 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 baseline is 3; the description earns a bump by restating the fuel/jurisdiction default interaction ('omit jurisdiction ... diesel by default') and by flagging jurisdiction-specific surcharge behavior that an agent would not expect from the raw enum alone. Quarter format specifics are left entirely to 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 (retrieve official IFTA fuel tax rates in USD/gallon by state or province) plus the authoritative source (IFTA, Inc. quarterly tax matrix). It is clearly a data-lookup tool, distinguishable in practice from calculate_ifta, but it never names or contrasts with that sibling 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?

Gives clear invocation guidance — omit 'jurisdiction' to get all jurisdictions for one fuel, diesel being the default — and a post-call instruction to cite the returned link. However it never says when to use this versus calculate_ifta or cost_per_mile (e.g., raw rates vs. computed tax liability), leaving the routing to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds real value beyond that: it discloses which edge cases are handled (partial period, logging, category W suspended) and that the response includes a filing due date, a link, and an IRS source the agent is told to cite.

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, and the core purpose and period are front-loaded before the edge cases and citation instruction. Every clause carries information an agent needs.

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 work of describing the return (tax amount, due date, link, source). For a 5-parameter read-only calculator this is nearly complete; only the agricultural/expected-miles suspension mechanics are left 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 coverage is 100%, so baseline is 3; the description goes slightly beyond by explaining how inputs interact (month of first use drives partial-period proration; suspension categories are evaluated). It still doesn't clarify the 5,000/7,500-mile thresholds the expected_miles parameter feeds, leaving that to 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 ('Calculates the IRS Form 2290 heavy highway vehicle use tax') plus the exact tax period (July 1 - June 30). The Form 2290/HVUT naming makes it unmistakably distinct from the IFTA siblings (calculate_ifta, get_ifta_rates), 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?

The description implies context (weight + month of first use, partial-period/logging/suspended cases) but never says when to prefer this over a sibling or what prerequisites apply. No explicit when-not or alternative routing is given, leaving usage 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's added context is the credit: it discloses that outputs are derived post-deadhead and post-fee, and that a link is returned that the agent must cite. It doesn't state numeric formulas or rounding, keeping it just under 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 tight sentences: the computation and its outputs come first, then the prerequisite and citation instruction. Nothing is redundant and no sentence 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 carries the return-value burden and does name the three headline metrics plus the returned link, which is enough to call and use it correctly. It does not specify units/format of the returned figures (e.g., margin as percent), a minor residual 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 how the inputs combine — deadhead miles, factoring/dispatch fees, and cost per mile all shape the result — which is relationship meaning the per-field descriptions don't 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 and resource ('Checks whether a freight load is profitable') and enumerates the exact outputs: profit, margin, and rate per loaded and total mile. It also names the cost_per_mile sibling as a dependency, so an agent can place it among the CPM/IFTA tools 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 an explicit prerequisite/ordering rule: 'Use cost_per_mile first if the CPM is unknown,' which names the sibling and the condition that selects it. It also instructs 'Cite the returned link.' It lacks an explicit when-not-to-use statement, 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.