TapTax

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

Annotations already declare a non-read-only, non-destructive, openWorld=false mutation. The description adds genuinely new behavior beyond them: a 10-minute deduplication window ('The same entry added twice within 10 minutes is recorded once'). That is exactly the kind of side-effect nuance the annotations do not carry.

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

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

Three short sentences, front-loaded with the action, then the category semantics, then the dedup caveat. No filler and no repetition of schema content; every sentence carries distinct 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 a 6-parameter mutation with no output schema, the description covers the action, the categorization rule and the dedup caveat, while annotations carry the safety profile and the schema carries parameter detail. It stops short of stating auth/account requirements or what a successful response confirms, which is a minor gap rather than a blocking one.

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 83% (above the 80% baseline), and the category enum is already documented exhaustively in the schema. The description only adds the framing that a category is 'the HMRC self-employment box it belongs in' and that examples are receipts/payments, which is marginal over the structured data. 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 and resource ('Record a business income or expense in the signed-in person's TapTax') and concretizes it with examples (a receipt or a payment). The verb 'Record' cleanly separates it from list_transactions, update_transaction and create_invoice, so an agent can place it without opening the schema.

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

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

The description implies the usage context (recording business receipts/payments for tax categorization) but never states when to prefer this over create_invoice or prepare_quarterly_update, nor any exclusions. Usage is inferable rather than stated, which is the definition of a 3.

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 safety (readOnlyHint, destructiveHint false, openWorldHint false). The description adds meaningful behavioral detail beyond that, explaining the calculation flow (gain after costs, losses, annual exempt amount) and outputs (tax at each rate, payment deadline).

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

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

The description is a single front-loaded sentence that packs the tool's purpose, scope, and output components without any filler. Every clause contributes useful information for invoking the tool.

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

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

With no output schema, the description carries the burden of explaining return values, and it does so by summarizing the computed gain, tax at each rate, and payment deadline. It omits finer details like exact rate bands or BADR specifics, but the schema and assetType enum cover the necessary inputs.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds integrative meaning by connecting parameters in a calculation sequence (costs, losses, annual exempt amount, other income setting the rate) and by enumerating asset types, going slightly beyond the individual schema 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?

The description states a specific verb (Calculate) and resource (UK Capital Gains Tax on selling an asset) with a clear scope covering asset types and tax years. It distinguishes itself from sibling tax calculators by naming the exact tax and disposal scenario.

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 a clear context for use: calculating CGT when selling an asset for a given tax year. It does not explicitly name when not to use it or point to alternative sibling tools, but the resource is specific enough to imply correct usage.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe, non-mutating local computation (openWorldHint=false). The description adds the useful detail that it returns the charge, the benefit kept, and the starting income, but says nothing about rounding, threshold basis, or whether the taxYear default affects results. With annotations covering the safety profile, 3 is appropriate.

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

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

One tight sentence with the purpose front-loaded and the outputs listed as a compact clause. No filler, no restatement of the title.

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

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

For a read-only three-parameter computation whose annotations already carry the safety profile and whose schema fully documents inputs, the description covers purpose and outputs adequately. The absence of an output schema slightly raises the bar, but listing the three return values largely closes that gap; a note on the income threshold would make it 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 description coverage is 100% – each of adjustedNetIncome, annualChildBenefit, and the taxYear enum is fully documented in the schema. The description adds no syntax, format, or defaulting detail beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb ('Calculate') and a precisely named domain resource (the High Income Child Benefit Charge), and enumerates the three outputs the tool produces. It is instantly distinguishable from the many other 'calculate_*_tax' siblings because it names the exact UK charge rather than a generic tax category.

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 the use case (someone with adjusted net income above the threshold who receives Child Benefit) but never states when to reach for this tool versus siblings like calculate_tax_on_multiple_incomes or get_tax_position, nor does it mention the threshold condition or exclusions. Adequate minimum-viable framing, nothing more.

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

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

Annotations already establish this is a safe, non-destructive, closed-world read-only calculation, so the safety bar is low. The description usefully adds that the deduction applies to labour only with materials excluded, that rates vary by CIS status, and that the result also reports the net amount received and whether annual deductions will over- or under-shoot the tax due - context the annotations cannot convey.

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

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

A single front-loaded sentence opens with the verb and resource before trailing into rate variants and secondary outputs. It is information-dense with no filler, though the long clause chain makes it slightly run-on.

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

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

With no output schema, the description compensates reasonably by naming the three things returned: the deduction, the amount received, and the annual over/under comparison. Six parameters at 100% coverage leave little else unexplained; only the exact return shape remains unspecified.

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 includes the rate mapping (registered 20% / unregistered 30% / gross 0%) and per-parameter explanations, so the schema does the heavy lifting. The description's 'labour only, materials excluded' framing lightly clarifies how materialsAmount interacts with grossPayment, but adds little 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 states a specific verb (Calculate) and a precise resource (the CIS deduction on a payment), plus the rate basis and the two ancillary outputs. It is unmistakably distinct from the other calculate_* siblings such as calculate_vat or calculate_take_home_pay, 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?

There is no when-to-use or when-not-to-use guidance, no prerequisites (e.g. that this is for contractor/subcontractor CIS payments only), and no pointer to adjacent tools like estimate_self_employed_tax for the final tax position. Usage must be inferred entirely from the described scenario.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds the shape of the result (multiple routes plus a 'best route' and an equivalent PAYE salary) but discloses no defaults, assumptions, or limitations beyond what the schema states.

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

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

A single front-loaded sentence that leads with the core transformation and then lists the outputs. It is dense but every clause carries information; the long trailing list of routes makes it slightly run-on.

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

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

With no output schema, the description must carry the return-value burden, and it does enumerate the outputs (annual/monthly income, hourly equivalent, take-home pay for three routes, best route, equivalent PAYE salary). It is nearly complete, missing only assumptions and the treatment of optional cost inputs.

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

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

Schema description coverage is 100%, so every parameter including defaults ('defaults to 7.5' hours, tax-year default) is already documented in the schema. The description adds no syntax or format detail beyond it, 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 states a specific verb and resource ('turn a contractor day rate into annual and monthly income, an hourly equivalent, and take-home pay') and enumerates the routes covered (sole trader, outside IR35, inside IR35). It never distinguishes itself from siblings like compare_inside_and_outside_ir35 or compare_limited_company_and_sole_trader, which clearly overlap.

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

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

There is no when-to-use or when-not-to-use guidance, and no alternative is named. Given that compare_inside_and_outside_ir35 and compare_limited_company_and_sole_trader appear to cover the same comparison ground, the absence of routing guidance is a real gap.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: it discloses the computation includes marginal relief and that results include profit after tax and the effective rate, which tells the agent what behavior and outputs to expect from a pure calculator.

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

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

A single dense sentence that front-loads the core action and appends the computational nuance and outputs. No filler, no repetition of the title or 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 two-parameter, read-only calculator with no output schema, the description does the important work of naming the returned values (profit after tax, effective rate), which compensates for the absent output schema. Minor gaps remain around edge cases and rounding, but nothing essential to invoking 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 description coverage is 100%, with both taxableProfit and taxYear fully documented in the schema including the enum of tax years and default behavior. The description adds no additional parameter semantics (e.g. currency, rounding, or boundary behavior near the marginal relief thresholds), so the baseline 3 applies.

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

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

The description names a specific verb (Calculate), a precise resource (UK corporation tax on a company's taxable profit for a tax year), and the calculation logic (marginal relief between small profits and main rates). This cleanly separates it from the many sibling tax calculators such as calculate_dividend_tax, calculate_vat, and calculate_capital_gains_tax.

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

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

Usage is only implied: the phrase 'on a company's taxable profit for a tax year' signals the applicable scenario, but there is no explicit when-to-use, when-not-to-use, or pointer to sibling tools like calculate_dividend_tax or compare_limited_company_and_sole_trader. Adequate but with a clear gap.

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, destructiveHint=false and a closed-world scope, so the safety profile is covered. The description adds useful value by disclosing the computed breakdown (allowance, the three rate bands, effective rate), but says nothing about rounding, treatment of the personal allowance, or whether Scottish rates are handled.

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

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

A single front-loaded sentence that begins with the verb and packs inputs and outputs without filler. The trailing enumeration of rate bands is dense but earns its place by telling the agent what the calculation returns.

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 annotations covering safety and no output schema, the description usefully names the returned figures, which is what an agent needs to know this is a dividend-specific calculator. Minor gaps remain around edge behaviors (Scottish rates, allowance tapering), but nothing essential to invoking 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 description coverage is 100%, so all three parameters are already documented in the schema (including the taxYear default and enum). The description only restates 'dividends and other income' without adding format, ordering, or interaction semantics beyond the schema, 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?

States a specific verb+resource (calculate UK tax on dividends) and even enumerates the computed components: dividend allowance, basic/higher/additional rates, effective rate. However, it does not differentiate itself from close siblings like compare_salary_and_dividends or calculate_tax_on_multiple_incomes, which an agent could plausibly confuse it with.

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

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

Usage is only implied by the input framing ('given the dividends and other income'), which signals a single-stream dividend calculation. There is no explicit when-to-use guidance and no mention of an alternative tool (e.g., compare_salary_and_dividends) for the many sibling cases where dividends are mixed with salary.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that income tax, employee NI, student loan and pension percentage are all factored in, but says nothing about accuracy, rounding, or what happens when the target take-home is unreachable.

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

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

A single dense sentence that front-loads the core purpose and appends the disambiguating '(net to gross)' tag. No filler, though the mid-sentence deduction list makes it slightly heavier 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 pure calculator with full schema coverage and no output schema, the description covers what is modelled (tax, NI, student loan, pension) and the direction of the calculation. Minor gaps remain around result format and handling of unachievable targets, but nothing essential 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 every parameter (taxYear, pensionPercent, targetTakeHome, studentLoanPlan, scottishTaxpayer) is already documented in the schema. The description restates the deduction categories but adds no syntax, units, or edge-case semantics 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?

States a specific verb and resource ('work out the gross UK salary needed to take home a given amount') and pins down the direction ('net to gross'), which implicitly separates it from the gross-to-net calculate_take_home_pay sibling. It stops short of naming that sibling explicitly, so differentiation still requires the agent to infer from the direction.

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 '(net to gross)' tag implies when the tool applies, and the enumerated deductions imply the inputs it can model. There is no explicit when-to-use, when-not-to-use, or alternative named (e.g. calculate_take_home_pay for the reverse direction), leaving 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 readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so safety is covered. The description adds useful behavioral context by stating that the result includes the weekday and whether the terms exceed the statutory limit.

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

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

The description is a single front-loaded sentence with no filler. The parenthetical list of terms is dense but directly necessary for understanding the calculation inputs.

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

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

For a calculator with no output schema, the description partially explains return values by mentioning the due date, weekday, and statutory-limit flag. However, it does not describe the output format or the effect of the customer parameter, leaving a meaningful gap in a 5-parameter 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 description coverage is high at 80%, so a baseline of 3 applies. The description goes beyond the schema by mapping payment-term enum values to natural-language meanings and by noting the statutory 30-day default, though it does not explain the customer parameter.

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

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

The description states a specific verb and resource: 'Calculate the date an invoice is due from its date and the payment terms.' It clearly distinguishes this due-date calculation from sibling invoice tools such as create_invoice, send_invoice, and mark_invoice_paid.

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 purpose implies when the tool is useful, but there is no explicit when-to-use or when-not-to-use guidance. It does not name alternatives such as calculate_late_payment_interest or explain that this tool should be used before creating or sending an invoice.

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

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

Annotations already establish the safety profile (readOnlyHint, destructiveHint false, openWorldHint false). The description adds domain-meaningful behavior beyond that: it names the statutory basis, the interest rate formula, and the fact that fixed compensation is included in the claim. It does not disclose rounding, the tiered compensation bands, or the minimum claim periods, which would be expected for a statutory calculation.

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 well-formed sentence that front-loads the calculation and packs the statutory basis, formula, inputs, and purpose without any waste.

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

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

For a read-only statutory calculator with full schema coverage and no output schema, the description is largely complete: it names the law, the rate formula, and the three inputs. It omits details that would matter for a correct claim, such as the tiered fixed-compensation amounts and any minimum-days threshold, but the core is present.

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

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

Schema coverage is 100%, so the three parameters are already documented in the input schema. The description confirms the inputs (amount, due date, payment date) but adds no format, boundary, or default semantics beyond what the schema states. Baseline 3 applies when the schema carries the load.

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 (calculate) plus the exact resource (statutory late-payment interest and fixed compensation on a commercial invoice), names the statutory basis (Late Payment of Commercial Debts Act), and specifies the formula (BoE base rate + 8%). This clearly distinguishes it from siblings like calculate_vat or estimate_self_assessment_penalties.

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

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

The scope is implied by 'late-paid commercial invoice', which implicitly excludes consumer invoices, but there is no explicit when-to-use/when-not-to-use guidance and no named alternatives. Adequate but leaves the agent to infer eligibility boundaries.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond the annotations by enumerating the three returned values, which matters because there is no output schema. It stops short of noting rounding/precision behavior or constraints on the inputs.

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

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

A single front-loaded sentence with the verb first and zero filler. Every clause earns its place by naming the inputs and the three outputs.

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-parameter, read-only calculator with no output schema, the description is nearly complete because it explicitly names the return values (selling price, profit, margin). The only gap is the lack of any statement about precision or how it relates to calculate_profit_margin, which is minor at this complexity.

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

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

Schema description coverage is 100%, so both parameters (cost, markupPercent) are already documented with their meaning and bounds, establishing the baseline of 3. The description restates the two inputs but adds no units, format, or edge-case semantics 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?

Specific verb (calculate) plus resource and full input/output contract: selling price, profit, and equivalent profit margin from a cost and a markup percentage. This cleanly separates it from the sibling calculate_profit_margin, which works the opposite direction, without the agent needing to open 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?

The description makes the applicable situation implicit (you have a cost and a markup and want the resulting price/profit/margin), which is enough for a pure calculator. However, it never names the alternative calculate_profit_margin or states when to prefer one over the other, so the routing guidance 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 already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real domain context beyond that: the rates are HMRC-approved and tax-free, the passenger rate is included, and the saving depends on tax band — useful behavioural framing for a pure-computation tool. It stops short of disclosing the 10,000-mile rate threshold or rounding rules.

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 with the core action front-loaded and every clause carrying information (rates, vehicle scope, passenger rate, tax saving). No filler or repetition of the title.

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

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

With annotations covering the read-only safety profile and no output schema to explain, the description gives enough to call the tool correctly. It leaves some gaps — defaults for taxBand/vehicleType are only in the schema, and the mileage threshold that changes the rate is never mentioned — but nothing critical is missing.

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

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

Schema coverage is 80%, so the baseline is 3. The description loosely maps to parameters (vehicle types → vehicleType, passenger rate → passengerTrips, basic/higher rate → taxBand), but it adds no syntax, defaults or units, and says nothing about averageMilesPerPassengerTrip, which is undocumented in both the schema and the description.

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 (calculate the business mileage allowance) and pins the domain precisely: HMRC approved mileage rates, car/van/motorcycle/bicycle, passenger rate, and basic/higher rate tax saving. An agent can distinguish this from log_mileage_trip or get_mileage_summary purely from the description.

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 scope (an annual allowance computation) but there is no explicit when-to-use guidance, no statement of when NOT to use it, and no pointer to the obvious siblings get_mileage_summary and log_mileage_trip, which an agent could easily confuse it with.

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/non-destructive/no-open-world, so safety is covered. The description earns credit by disclosing what the calculation actually returns (relief added to the pension, reduction in the tax bill, net cost of the extra contribution) despite there being no output schema. It stops short of stating assumptions (e.g. basic-rate only, annual limits).

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 well-formed sentence with the comparison framing front-loaded and no filler. It is dense but structurally sound; splitting out the three outputs would improve scannability slightly.

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

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

With no output schema, the description carries the burden of explaining results and does so by enumerating the three computed figures. For a five-parameter, two-required calculation tool with full schema coverage this is close to complete, lacking only stated assumptions/limitations.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema, giving a baseline of 3. The description echoes the 'current vs higher personal pension contribution' and tax-year concepts but adds no syntax, defaults, or edge-case semantics 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 (compare), the resource (a self-employed person's tax / pension contribution), and the exact outputs produced (basic-rate relief added, tax bill reduction, net cost). It is clearly a pension relief calculator rather than any other 'calculate_*' sibling. It does not, however, explicitly differentiate itself from adjacent tools such as calculate_salary_sacrifice.

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

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

The phrase 'a self-employed person's tax' implies the target scenario, but there is no explicit when-to-use/when-not statement and no sibling alternative is named. An agent can infer the audience but must decide on its own when this beats calculate_salary_sacrifice or estimate_self_employed_tax.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered without description help. The description adds the two-mode computation behavior, but says nothing about validation of conflicting inputs or the shape of the result.

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

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

A single sentence that front-loads the action and packs both input modes without waste. No filler, no redundancy with the title.

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

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

No output schema exists, yet the description only loosely gestures at returns ("the profit margin and markup") and omits what happens when the optional parameters are absent or contradictory. Adequate for a simple calculator, but the conditional-input contract is left partly implicit.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning the schema cannot: price yields margin and markup, while targetMarginPercent yields the required selling price, clarifying the conditional relationship between optional params.

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 (calculate) plus resources (profit margin, markup) and an explicit statement of the two input modes. It does not, however, distinguish itself from the sibling calculate_markup tool, which overlaps with the markup half of this description.

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 two usage modes (supply price to get margin/markup, supply targetMarginPercent to get the required price), which is genuine routing guidance. But it never states when to prefer this over calculate_markup, nor what happens if neither price nor targetMarginPercent is supplied.

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, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds genuine context beyond that: it discloses that the calculation combines a pro rata adjustment with take-home pay for a tax year, which tells the agent the scope of the result.

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 efficient sentence that front-loads the core computation (pro rata salary from full-time salary and hours) before the secondary output (take-home pay). No filler, though the trailing 'for a tax year' clause is slightly tacked on.

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

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

With no output schema, the description usefully indicates the result includes both the pro rata salary and the take-home pay for a chosen tax year, which is the key return information an agent needs. It stops short of describing any breakdown fields, but for a deterministic calculator this is largely sufficient.

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

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

Schema description coverage is 100%, so all six parameters (taxYear, actualUnits, fullTimeUnits, fullTimeSalary, studentLoanPlan, scottishTaxpayer) are fully documented in the schema. The description restates the full-time/actual-units relationship but adds no formatting or unit guidance beyond what the schema already provides, so the baseline 3 applies.

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

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

The description uses a specific verb ('work out') and a clear resource (part-time/pro rata salary) and names the inputs it derives from (full-time salary and hours/days vs full time). It also states it returns take-home pay. It does not, however, differentiate itself from near-neighbours like calculate_take_home_pay or convert_hourly_rate_to_salary, which a large sibling set makes important.

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 usage by describing what computation it performs, but never states when to pick this over calculate_take_home_pay or calculate_gross_salary_for_take_home, nor any prerequisite such as having a full-time figure first. Usage is inferred rather than specified.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, so the safe read-only profile is already covered. The description adds one genuinely useful behavioral rule beyond the annotations - that mortgage interest is relieved as a 20% tax credit - but omits other behavior such as the credit's cap or what the returned figure represents.

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

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

A single front-loaded sentence that packs the computation, scope, and the four input categories with no filler. Slightly dense, but every clause earns its place.

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

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

Inputs and the notable mortgage-interest treatment are covered, but with no output schema the description says nothing about the shape of the return value (e.g., tax due, effective rate, breakdown), leaving a gap for a tax-calculation 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 description coverage is 100%, so every parameter (grossRent, otherIncome, allowableExpenses, mortgageInterestPaid, taxYear) is already documented in the schema. The description restates those inputs without adding format, units, or defaulting details 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?

States a specific verb (Calculate) and resource (UK income tax on rental profit), scoped to a landlord and a tax year. The domain is distinct enough from siblings like calculate_dividend_tax or calculate_capital_gains_tax to route correctly, though no sibling or exclusion is named explicitly.

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

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

The phrase 'for a landlord in a tax year' implies the applicable scenario, but the description never states when to use this versus alternatives such as estimate_self_employed_tax or calculate_tax_on_multiple_incomes, nor any exclusions. Usage is only implied.

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

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

Annotations already establish this as a safe read-only, closed-world calculation, so the bar is lower. The description goes beyond them by enumerating exactly what is computed: income tax, NI and student loan saved, employer NI passback, benefit-in-kind car tax, take-home drop, and cost per pound for a pension — useful output-shape disclosure for a calculator with no output schema.

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

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

One sentence, front-loaded with the comparison purpose, followed by a compact comma-separated list of outputs. It is somewhat run-on and dense, but every clause earns its place by describing a distinct computed figure.

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

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

With no output schema, the description carries the return-value burden and does so by enumerating the computed outputs for both sacrifice types. Combined with 100% parameter coverage in the schema and safe-read annotations, 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 description coverage is 100%, so the schema already documents all 8 parameters, including enums and the employerNIPassback share. The description adds no syntax or format detail beyond the schema, 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?

The description opens with a specific verb and resource ('Compare pay before and after a salary sacrifice for a pension or an electric company car'), which distinguishes it from generic siblings like calculate_take_home_pay or calculate_pension_tax_relief. It covers both supported sacrifice types, though it never names a sibling tool 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 scenario ('pension or an electric company car') rather than stated as a when-to-use condition. There is no guidance on when to prefer this over calculate_pension_tax_relief or calculate_take_home_pay, and no exclusions or prerequisites.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real behavioral value by naming what is computed (starting rate for savings, Personal Savings Allowance, tax due) and which inputs drive it, notably that other income and tax already deducted affect the result — information no structured field supplies, since there is no output schema.

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

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

A single front-loaded sentence that names the operation, the tax year scope, the inputs and the outputs. The trailing colon list is slightly dense but every element earns its place by previewing the computed components.

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

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

With no output schema, the description carries the burden of previewing returns, and it does so by naming the three computed components. Combined with the read-only annotations and a fully documented input schema, an agent has enough to call this correctly; only explicit alternative-tool routing 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 every parameter is already documented in the schema with bounds and a default for taxYear. The description restates gross interest, tax deducted and other income without adding format, band or interaction semantics, 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 gives a specific verb and resource ("Calculate UK tax on savings interest for a tax year") plus the inputs it consumes, so an agent can tell it apart from calculate_dividend_tax or calculate_rental_income_tax. It stops short of explicitly naming the sibling calculators or the boundary cases where they would be preferred, so it is clear but not routed.

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

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

There is no when-to-use or when-not-to-use guidance and no mention of alternatives among the many calculate_* siblings. The list of inputs implies a calculation context, but an agent gets no explicit condition for selecting this tool over calculate_tax_on_multiple_incomes or the other income-tax calculators.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that the calculation is jurisdiction-dependent and conditionally applies three surcharge/relief regimes, which is useful context, but it says nothing about computation assumptions, defaults applied silently, or what the result contains.

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

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

A single dense sentence that front-loads the core action and then qualifies scope by nation and relief type. No filler, though the long tail of surcharge clauses makes it slightly heavy for one sentence.

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 9 parameters, no output schema, and a sibling set crowded with similar calculators, the description covers scope well but says nothing about the returned value (a tax figure, a band breakdown?) or the defaults silently applied to country, completionDate and propertyUse. Adequate but with clear gaps for a calculator whose output is its whole point.

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 67%, and the description meaningfully fills some of the gap: it ties first-time buyer relief to firstTimeBuyer, the additional property surcharge to the other-property/replacement flags, the non-resident surcharge to ukResident, and region choice to the country enum. It leaves company, propertyUse and completionDate unexplained, so it does not fully compensate.

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 (calculate stamp duty / tax on buying property) and enumerates exactly what falls in scope: SDLT, LBTT, LTT, band-based computation, first-time buyer relief, additional property and non-resident surcharges. This distinguishes it cleanly from siblings like calculate_capital_gains_tax or calculate_vat.

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

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

The description implies when the tool is applicable (property purchases, with conditional reliefs) but never states when to use this versus the many other tax calculators, nor any exclusions or prerequisites. Usage is inferable from purpose but not explicitly guided.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the agent knows this is a safe, closed-world read. The description adds scope information (which plans and tax years are covered), but says nothing about limitations such as plan eligibility rules or what happens for defaulted tax years beyond the enum.

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

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

A single front-loaded sentence with the core action, the output granularity, and the input scope. No filler or redundant restatement of the title.

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

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

For a three-parameter, read-only calculation with no output schema, the description usefully enumerates the three repayment periods returned and the supported plans. It is largely complete; only eligibility caveats or default behavior for an omitted tax year are left to the schema.

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

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

Schema coverage is 100%, with descriptions and enums for plan, taxYear and annualIncome, so the schema carries the parameter burden. The description only restates the plan set and mentions tax year, adding no syntax or default semantics beyond 'Defaults to the current one' already 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?

Specific verb (calculate) + resource (UK student loan repayments) plus the dimensions produced (yearly/monthly/weekly) and the plan and tax-year scope. It is clearly distinguishable from sibling calculators like calculate_take_home_pay or calculate_pension_tax_relief.

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

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

The context (UK student loan repayment for a given plan and tax year) implies when the tool applies, but the description never states when to prefer it over related tools or what prerequisites exist (e.g., which plans apply). Usage is inferable from the name and scope rather than stated.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, correctly signaling a pure computation. The description adds valuable behavioral detail: it enumerates the tax jurisdictions handled (England/Wales/NI vs Scotland), output granularity (yearly/monthly/weekly), and that it returns employer NI and total cost. That is meaningfully more than the annotations provide, though it omits assumption disclosures (e.g. which tax-year rates are current, treatment of Scottish NI).

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

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

A single dense sentence that front-loads the core purpose and then lists the computed components. Efficient with no filler, though the run-on structure and one very long clause slightly reduce scannability.

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

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

With no output schema, the description correctly enumerates the return contents (breakdown by component plus yearly/monthly/weekly take-home and employer cost), and it names the tax region split. It stops short of stating default tax-year behavior or rounding/assumption caveats, so a small gap remains for a multi-jurisdiction financial calculator.

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

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

Schema description coverage is 100%, so every parameter is already documented, setting the baseline at 3. The description mentions student loan and pension contributions and the Scottish/UK tax distinction, which maps to parameters, but adds no syntax or default semantics 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?

States a specific verb (calculate) and resource (take-home pay from a UK salary) with full scope detail: income tax by band, National Insurance, student loan, pension, and employer cost. An agent can distinguish this from siblings like calculate_student_loan_repayment or calculate_pension_tax_relief because this tool aggregates them into a take-home figure.

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 usage (UK salary take-home) but offers no explicit when-to-use vs alternatives such as calculate_gross_salary_for_take_home or compare_salary_and_dividends. The inverse-direction sibling (gross from take-home) and the salary-vs-dividends comparison sibling are the most likely confusions, and neither is addressed.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that: it discloses the full computed output breakdown (income tax, National Insurance, student loan, amount left to pay, take-home) and the PAYE-offset behavior, which is not available via an output schema.

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

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

A single front-loaded sentence opens with the verb and purpose before the parenthetical detail. It is dense but every clause carries information (income types, PAYE allowance, output breakdown), 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?

With no output schema, the description correctly compensates by enumerating the return values. All 9 parameters are schema-documented and the read-only nature is annotated, so nothing critical is missing; the only gap is the absence of guidance on how the result relates to the single-source sibling calculators.

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

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

Schema description coverage is 100%, so every parameter (including the two enums taxYear and studentLoanPlan) is already documented in the schema. The description restates the income categories and mentions PAYE deduction, but adds no syntax, format, or defaulting detail beyond what the schema provides. 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 (Calculate) and resource (combined UK tax on income from several sources in one tax year) and enumerates the covered income types. The 'combined / several sources' framing cleanly distinguishes it from single-source siblings like calculate_dividend_tax, calculate_rental_income_tax, and calculate_take_home_pay.

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 multi-source scope implies when this tool is appropriate (a taxpayer with several income streams), but the description never explicitly states when to use it instead of the single-source calculators, nor any exclusions or prerequisites. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely useful context by stating what the calculation returns (net, VAT and gross amounts), which matters since there is no output schema.

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

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

A single, tightly packed sentence that front-loads the two modes of operation and ends with the output composition. No filler and nothing redundant.

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

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

For a read-only calculator with full schema coverage, the description supplies the one thing structured fields don't: the shape of the result (net, VAT, gross). Nothing critical is missing, though it could clarify whether output is a single figure or a breakdown object.

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 amount, direction and ratePercent, including the add/remove semantics. The description's mention of 20%, 5% and any other rate largely restates the ratePercent default and enum rather than adding new 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?

The description states a specific verb (add/remove VAT) and resource (a price amount), making the tool's function immediately clear and separable from siblings like check_vat_registration or check_vat_reverse_charge. It does not explicitly name or route against any sibling, which keeps it at a 4 rather than a 5.

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

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

Usage is implied: use it when you need to add VAT to a net figure or extract VAT from a gross figure. There is no explicit when-not guidance and no mention of alternative tools, so the agent must infer the context.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds domain semantics (income counted before expenses) but says nothing about what the determination returns — a boolean, a date, a threshold comparison — which matters since there is no output schema.

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

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

Two tight sentences, front-loaded with the determination being made before the qualifying-income rule. Every clause carries information the agent needs and nothing is repeated from the title or 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 two-parameter read-only check with no output schema, the description supplies the essential rule for producing a correct answer (what counts toward qualifying income). The main gap is the absence of any hint about the output form or applicable thresholds, though the annotation set covers safety concerns.

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

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

Schema description coverage is 0%, so the description must carry the load, and it does: it defines qualifying income as self-employment turnover plus property income, before expenses, and states what is excluded. It does not clarify that propertyIncome defaults to 0, nor units/currency, but the meaning of both parameters is substantially conveyed.

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 ('say whether and when') and a precise resource (Making Tax Digital for Income Tax applicability), plus the basis for the determination (qualifying income). This distinguishes it cleanly from siblings like get_mtd_deadlines (dates) and estimate_self_employed_tax (tax estimate) without needing to name them.

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

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

The description gives clear context for invoking it (anyone whose MTD status must be determined from qualifying income) and rules out misuse by stating employment and pension income do not count. It does not, however, route the agent explicitly to alternatives such as get_mtd_deadlines or prepare_quarterly_update when those are the better fit.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false, destructiveHint=false), so the description correctly focuses on behavior the annotations cannot express: a verdict-tier output, the needs_info fallback when hasMultipleJobs is absent, and the caveat that refund figures are estimates rather than amounts owed. It does not describe the full shape of the verdict or its other 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?

Three dense sentences, front-loaded with the core purpose before the edge-case rule and the estimate caveat. Every sentence carries information, though the middle sentence is packed and could be split for scanability.

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 11 parameters, no output schema, and no annotations covering inputs, the description leaves significant ground uncovered: it never explains the purpose of the many circumstance flags or how taxYear/scotland/monthsOnCode affect the result, and it only gestures at the return structure via 'verdict tier'. Adequate for the core case, incomplete for a tool of this parameter complexity.

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

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

Schema description coverage is 55% across 11 parameters, so the schema documents roughly half. The description adds real value by giving concrete tax-code formats (1257L, BR, K475, 1257L W1/M1) and by explaining the role of hasMultipleJobs, but it is silent on the many boolean circumstance flags (hasCompanyCar, hasPrivateMedical, hasMarriageAllowance, receivesStatePension, scotland, monthsOnCode) that materially change the verdict.

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 (check) and resource (UK PAYE tax code), plus the three things it does: validate, explain, and estimate over/under-payment. Sibling tools are all invoicing/transaction/mileage oriented, so this tool is unambiguously distinguishable.

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 conditional rule for a hard case: flat-rate codes (BR, D0, D1) are only judged when hasMultipleJobs is known, otherwise the verdict is needs_info. That tells the agent when the tool can and cannot give a real answer. It does not name alternative tools or state broader when-not conditions, so it falls short of a 5.

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

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

Annotations already cover the read-only, non-destructive, closed-world safety profile, so the bar is lower. The description adds real behavioral value by disclosing the computation (standard vs Flat Rate comparison, inclusion of the first-year discount) and what it returns (the cheaper scheme and the difference).

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

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

A single front-loaded sentence that opens with the primary check before layering in the comparison detail. It is dense with clauses but contains no filler, though splitting into two sentences would improve scannability.

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

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

With no output schema, the description carries the return-value burden and does so adequately by stating the tool returns the cheaper scheme and the difference. Combined with 80% parameter coverage and clear safety annotations, an agent has enough 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 80%, so the schema already documents nearly all inputs. The description references turnover, tax year, sector rate and first-year discount, but adds no format or unit detail beyond the schema, and vatablePurchases is only implied by 'VAT payable under the standard scheme'. Baseline 3 is appropriate.

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

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

The description names a specific verb (check) and resource (UK VAT registration threshold) and adds a distinct second function: comparing standard scheme vs Flat Rate Scheme VAT payable. This differentiates it from siblings like calculate_vat, but 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 only implied by the scenario (a business evaluating registration and scheme choice). There is no explicit when-to-use, when-not, or named alternative such as calculate_vat, so the agent must infer the boundary.

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 the safety profile (readOnly, non-destructive, closed-world), so the bar is lower. The description adds genuinely useful behavioral context beyond them: this is a stateful, stepwise decision tool whose response may be an intermediate question rather than a final answer, which affects how an agent must call it.

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

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

One dense sentence that front-loads the purpose, then the mechanism and the return shape. No filler or repetition.

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 explaining what comes back (next question or the outcome plus required invoice wording). For a single-parameter, closed-world check this is nearly complete; only the mapping of question ids to real-world meaning is left entirely to the schema.

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

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

Schema coverage is 100% and the enum of question ids is fully documented there, so the baseline would be 3. The description adds real meaning by clarifying that the answers are yes/no values and that partial answers are acceptable ('answers known so far'), which the schema alone does not state.

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: determining whether the domestic VAT reverse charge for construction services applies to an invoice, and names the method (HMRC's decision steps). This clearly distinguishes it from calculate_vat and check_vat_registration among the 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?

Explains the operating pattern: pass the yes/no answers known so far and get back either the next question or the final outcome. That tells an agent how to drive the tool iteratively. It stops short of naming alternative tools or stating when this check is unnecessary.

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

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

Annotations already establish readOnlyHint=true, destructiveHint=false and a closed-world computation, so safety is covered. The description adds genuine value by naming the modelled components (deemed employment payment, employer National Insurance, limited company route) and by warning that it is a pay comparison, not a status verdict.

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

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

Two tight sentences, front-loaded with the comparison itself and closing with the important scope limitation. No filler and every clause carries information about inputs or scope.

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

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

For a read-only calculator with full schema coverage and annotations carrying the safety profile, the description covers the what, the inputs, and the scope boundary well. With no output schema, a brief note on what the comparison returns (e.g. per-scenario take-home figures) would close the remaining gap.

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

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

Schema description coverage is 100%, so every parameter including taxYear's enum and the cost/expense optional fields is already documented in the schema. The description mentions day rate and working days but adds no format, default, or range semantics beyond what the schema supplies; 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 (compare) and a precisely scoped resource: inside-IR35 take-home versus outside-IR35 via limited company. It names the computation inputs (day rate, working days, tax year) and explicitly delimits scope by saying it does not decide IR35 status, so it is distinguishable from siblings like compare_limited_company_and_sole_trader.

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 when the tool applies (contractor pay comparison across IR35 regimes for a given tax year) and an explicit non-use boundary (doesn't determine IR35 status). It doesn't name a specific alternative sibling to route to for status determination, so it stops short of full when/when-not 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 readOnlyHint=true and destructiveHint=false, so safety profile is covered structurally. The description adds meaningful computational context—what components are modeled (salary, dividends, corporation tax, accountancy cost) and that it returns the annual difference and break-even profit. However, it doesn't state assumptions (e.g., default accountancy cost, dividend allowance treatment) or limitations beyond those implicit in the schema.

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

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

A single dense sentence front-loads the comparison subject and enumerates the modeled components and outputs without filler. Every clause 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?

For a read-only comparison calculator with a fully documented schema, the description gives enough to understand inputs (annual profit, tax year, accountancy cost) and outputs (difference, break-even). The lack of an output schema means the description does some work describing results, which it does. Missing only edge-case assumptions.

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

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

Schema coverage is 100%, with enums and defaults documented directly in the schema. The description notes the output includes 'the annual difference and an approximate break-even profit' but adds no syntax or format detail beyond the schema. Baseline 3 is appropriate when the schema fully handles parameter documentation.

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

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

States a specific comparison (take-home pay as sole trader vs. running the same profit through a limited company) with the exact mechanics considered—salary plus dividends, corporation tax, accountancy cost—for a tax year. Distinguishes itself from sibling compare_salary_and_dividends and estimate_self_employed_tax by naming the entity-structure comparison 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?

The description implies when this tool is relevant (deciding between sole trader and limited company structure) but never states exclusions or explicitly names alternatives like compare_salary_and_dividends or calculate_take_home_pay. Usage context is inferable but not spelled out.

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 safe, read-only, closed-world calculation, so the safety profile is covered. The description adds useful substance by disclosing the calculation order (employer NI and corporation tax come off before dividends are paid) and that all taxes plus an effective rate are returned. It does not mention anything about assumptions, limits, or defaults beyond what the schema shows.

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

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

A single dense sentence that front-loads the audience and the core computation before the deduction detail. Every clause carries information, though the sentence is long enough that the 'compare' aspect of the tool name is never resolved.

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 adequately by promising every tax plus the effective rate. For a 3-parameter pure calculation, the definition covers what is computed and from what inputs; only the comparative/optimization intent hinted at by the name is left unexplained.

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

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

Schema description coverage is 100%, so all three parameters are already documented, and the baseline is 3. The description adds marginal value by clarifying that the profit figure is consumed after employer NI and corporation tax and that dividends come from the remainder, but it gives no units, precision, or default guidance 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 computation (take-home pay from salary plus dividends), the audience that scopes it (limited company director), and the deductions included (employer National Insurance, corporation tax). It is clearly distinguishable from generic siblings like calculate_take_home_pay or calculate_dividend_tax, though it never names those siblings or explains the 'compare' framing implied by the tool name.

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

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

Usage is only implied through the audience qualifier 'For a limited company director', which implicitly excludes employee/sole-trader cases handled by siblings. There is no explicit when-to-use statement and no routing to alternatives such as compare_limited_company_and_sole_trader or calculate_salary_sacrifice.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description usefully adds that the result includes take-home pay for a given tax year, but says nothing about rounding, currency assumptions, or how UK tax bands/Scottish rates are applied, so the added behavioural value is modest.

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

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

A single front-loaded sentence that opens with the conversion and appends the tax-year take-home context; it is slightly run-on but every clause carries information and there is no filler.

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

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

For a read-only calculator with no output schema, the description conveys both the primary output (annual salary) and the secondary output (take-home pay) and the inputs that shape them. An agent has enough to call it correctly, though it lacks caveats about tax-year defaults or regional variation.

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

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

Schema coverage is 100%, so every parameter (taxYear, hourlyRate, hoursPerWeek, studentLoanPlan, paidWeeksPerYear, scottishTaxpayer) is already documented in the schema. The description only restates hours/week, paid weeks and tax year, adding no syntax, defaults or edge-case meaning 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 ('convert an hourly rate to the annual salary') and states the scope of the conversion (hours/week, paid weeks/year) plus the take-home-pay output. It is clearly distinguished from the inverse sibling convert_salary_to_hourly_rate.

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 direction of the conversion, which separates it from convert_salary_to_hourly_rate, but there is no explicit when-to-use guidance or pointer to related tools like calculate_take_home_pay or calculate_pro_rata_salary. Nothing is misleading, just unstated.

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

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

Annotations already establish this is a safe, read-only, closed-world computation. The description adds useful context that it returns both gross hourly rate and take-home pay per hour and that results are tax-year specific, but says nothing about assumptions (UK tax regime, NI/student loan handling) beyond what the schema hints at.

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

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

A single front-loaded sentence that conveys the core transformation and the key inputs without padding. It is somewhat dense but every clause earns its place.

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

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

With no output schema, the description usefully names the two return values (gross hourly rate, take-home pay per hour), which is exactly what an agent needs to know. It is complete enough for a read-only calculation tool, though it could note that results are UK-specific.

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

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

Schema description coverage is 100%, so all six parameters including enums are already documented. The description restates hours a week, paid weeks a year, and tax year without adding format or default semantics beyond the schema (e.g. that paidWeeksPerYear defaults to 52 is only in 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+resource (convert an annual salary to gross hourly rate and take-home pay per hour) with clear directionality, which implicitly distinguishes it from the reverse-direction sibling convert_hourly_rate_to_salary. It doesn't explicitly name that sibling, but the direction is unambiguous from the text.

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

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

Usage is only implied by the description's scope — an agent can infer it is for salary→hourly conversion given hours/week and paid weeks/year, but there is no explicit when-to-use, when-not-to-use, or reference to the reverse tool or to calculate_contractor_day_rate. Adequate but with clear gaps.

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

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

Annotations only cover the generic safety profile (non-readonly, non-destructive, non-idempotent, closed-world). The description goes well beyond that: the invoice is numbered in the user's sequence, it inherits saved business details, it is not sent, and free plans are capped at 3 invoices versus unlimited on paid plans — a quota limit an agent cannot infer from any structured field.

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

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

Front-loads the core action and required inputs in the first sentence, then packs prerequisites, side effects and plan limits into three dense follow-ups. Every sentence carries information, though the plan-quota sentence is slightly tangential to 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 a 9-parameter mutation tool and no output schema, the description covers the important invocation context: required inputs, prerequisites avoided, numbering/business-detail side effects, and draft (not sent) state. It does not indicate what the call returns (e.g. an invoice id or number) that a caller would need to subsequently pay or send it, which is the remaining gap.

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

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

Schema description coverage is 56%, with the schema itself documenting unitPrice, dueDate, dueInDays, issueDate and clientEmail. The description adds useful meaning for clientName and items (no saved client required, one or more line items) but says nothing about notes, clientAddress, vatRatePercent or item quantity/description, leaving a meaningful portion of the 9 parameters undocumented here.

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 ('Create and save a draft invoice') plus the minimum inputs required, and scopes it to the signed-in person's TapTax account. This clearly separates it from siblings like send_invoice, list_invoices and generate_invoice_numbers, all of which could otherwise be confused with invoice creation.

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 tells the agent it does not need a saved client, a prior invoice or a client email, and that the email only matters later for sending — which implicitly routes the agent to send_invoice for delivery. It never names that sibling or states exclusions in tool-name terms, so it stops short of a full when/when-not 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 this is a read-only, non-destructive, closed-world operation, so the safety profile is clear. The description adds that it estimates based on days late, but does not disclose any further behavioral traits such as whether it's a point estimate, whether it uses current HMRC rates, or any limitations. Minimal added context beyond annotations.

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

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

A single, well-structured sentence that front-loads the purpose and efficiently lists the three penalty types and the required inputs. No wasted words.

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

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

For a read-only estimation tool with full schema coverage and annotations, the description is adequate but not thorough. It lacks any mention of output structure, assumptions (e.g., current HMRC rates), or edge cases. An agent has enough to invoke it, but could benefit from more context about the estimate's nature.

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%, meaning every parameter is fully documented in the schema. The description only restates the high-level inputs and adds no syntax, format, or default information beyond what the schema already provides. Baseline 3 is appropriate when the schema does all the work.

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 (Estimate) and precisely enumerates the resource (Self Assessment late filing penalties, late payment penalties, and late payment interest on tax due). It clearly distinguishes itself from siblings like calculate_late_payment_interest by covering all three penalty types.

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 usage by stating the inputs (days late, tax paid), but provides no explicit when-to-use or when-not-to-use guidance. It does not mention the alternative calculate_late_payment_interest or when this broader estimate should be preferred. Usage context is only implied.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: figures come from HMRC's published rates for the stated tax year, no account is required, and the response contains effective/marginal rates and payments on account. It doesn't discuss rounding, rate-update lag, or limitations of the estimate, so not 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?

One dense sentence, front-loaded with the core purpose and inputs before the output list. Every clause carries information, though the trailing enumeration of outputs makes it slightly long; still efficient overall.

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 8 parameters, no output schema, and read-only annotations, the description compensates well by enumerating the returned figures (take-home, effective/marginal rates, payments on account, tips) and clarifying the no-account scenario. Minor gaps remain around assumptions and edge cases for out-of-range or unsupported tax years.

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 88%, so the schema already documents nearly every parameter, including enums for taxYear and studentLoanPlan. The description only echoes 'turnover and allowable expenses' and adds no format, unit, or interaction detail (e.g. how businessMiles interacts with expenses) 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?

Names a specific verb (Estimate), precise resource (UK income tax and Class 4 NI for a sole trader), and the inputs it works from (turnover, allowable expenses). It also enumerates what comes back (take-home, effective/marginal rates, payments on account, tips), which clearly separates it from sibling tools like get_tax_position or check_tax_code.

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 clause 'Works from the figures given, without a TapTax account' tells the agent when this tool is appropriate: standalone what-if estimation rather than account-based lookups. It does not explicitly name an alternative sibling (e.g. get_tax_position) or state exclusions, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds that generation preserves prefix and zero padding, but says nothing about determinism, duplicate risk, or the count limit beyond what the schema states.

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 with the core purpose front-loaded. It is long but every clause carries content, so nothing obvious should be cut.

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 7 optional parameters, no output schema and no required fields, the definition is adequate but not complete: it never states what the returned value looks like (a single string vs. a list for count>1) or confirms the output format. For a read-only generator this is a modest gap rather than a fatal one.

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 71%, so most parameters are documented. The description adds genuine value by mapping parameters to modes (lastNumber for next-after; prefix/separator/datePart/digits for a run) and explaining the zero-padding behavior, going beyond the schema's field-by-field listing.

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 ('Generate invoice numbers') and enumerates the two operational modes: next-after a given number, or a run in a chosen format. This is clearly distinct from invoice-writing siblings like create_invoice/list_invoices, though it never names them explicitly.

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

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

The two modes and the parameters that select each one are spelled out ('next number after a given one...' vs. 'a run of numbers in a chosen format'), giving clear implied context for choosing parameters. No when-not guidance or explicit alternatives are given, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds useful scope ('signed-in person's own') and enumerates the returned summary content, which is real added value, but says nothing about pagination, date-window limits, or behavior when no trips exist.

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 front-loaded sentence that states the resource, the audience scope, the parameter, and the returned fields 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 read-only, single-parameter tool with no output schema, the description usefully enumerates the summary contents an agent should expect, which compensates for the missing return schema. Minor gaps remain around optionality and empty-state behavior.

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

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

There is a single taxYear parameter with 0% schema description coverage, so the description must carry the load. It does convey that the parameter is a tax year, but gives no format or range hints (the enum supplies '2024-25' etc.) and does not note that the parameter is optional per 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 ('Read') and resource ('the signed-in person's own mileage log'), and scopes the output ('total miles, the deductible amount ... most recent trips'). It implicitly separates itself from log_mileage_trip (write) and calculate_mileage_allowance (calculator), but never names an alternative, so it falls just short of a full 5.

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

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

The only usage context is 'for a tax year'. There is no guidance on when to reach for this versus calculate_mileage_allowance or log_mileage_trip, and no mention of prerequisites or when the data may be empty.

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, non-destructive, and closed-world, so the safety profile is covered. The description adds useful domain context ('Updates are cumulative from 6 April') and implies a next-deadline indicator, but says nothing about return shape, ordering, or behavior for years outside the enum.

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 sentence plus one short supporting clause, front-loaded with the core action and resource. No filler; the cumulative-updates note earns its place by explaining the deadline structure.

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

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

For a read-only, single-optional-parameter lookup with full annotation coverage, the description gives enough to call it correctly. Without an output schema it could say a bit more about what the returned list looks like, but nothing critical is missing.

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

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

Schema description coverage is 100% and the single taxYear parameter carries its enum and default ('Defaults to the current tax year') in the schema. The description's 'Updates are cumulative from 6 April' adds interpretive context for the returned periods but no parameter-level detail beyond the schema, 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?

States a specific verb (list) and resource (Making Tax Digital quarterly update periods and deadlines), plus a distinctive extra output ('which one is next'). The scope is clear enough to separate it from check_mtd_status and prepare_quarterly_update, though no sibling is named explicitly.

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

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

Usage is only implied: an agent can infer this is for looking up statutory MTD deadlines, but there is no explicit when-to-use, when-not-to-use, or pointer to an alternative such as prepare_quarterly_update for acting on a deadline.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: the data is scoped strictly to the signed-in person's own account, requires no user-supplied figures, and the values are the filing-rule counts shown on their dashboard. It stops short of noting freshness/caching or what an empty/unfiled year looks like.

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 sentence, front-loaded with the verb and subject, then a colon-list of the returned fields. It is dense but every listed element maps to a real output field and is justified since there is no output schema. Slightly heavy as a single run-on sentence, but not padded.

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

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

With no output schema, the description must describe the return value, and it does so thoroughly (income, expenses, profit by filing rule, income tax and Class 4 NI, undecided transaction count, filed quarterly updates, next deadline). Annotations cover the safety profile and the schema covers the only parameter, so an agent has everything needed to call and interpret 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% and the single taxYear parameter is fully documented with an enum and a stated default, so the schema carries the parameter meaning. The description never mentions that the year can be selected, adding nothing beyond the schema; baseline 3 applies when the schema does the work.

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 the signed-in person's own account / tax year so far) and enumerates exactly what it returns, which is more than most siblings do. It distinguishes itself from the calculate_* and list_* siblings only implicitly, by framing the output as a single aggregated dashboard view rather than a computation or a raw list.

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

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

There is a usage cue – 'Needs no figures from the person: everything comes from their records' – which tells the agent it can call with no input, and by omission points away from the calculate_* tools that need figures. However, no alternative is named and no condition selects this tool over get_mtd_deadlines or list_transactions, so usage is only implied.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds real behavioral information: results are ordered newest first, status is computed live (a sent invoice past its due date reads as overdue), and aggregate outstanding/overdue totals are returned. It does not mention pagination or the default/cap on result count.

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

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

A single sentence, front-loaded with the verb and resource, with no filler. Every clause (ordering, live status, totals, no-required-input) carries information an agent can act on.

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

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

No output schema exists, so the description must describe the return payload — and it does: per-invoice live status plus outstanding and overdue totals. With only two optional parameters, no required inputs, and full annotation coverage, nothing material 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 only 50%: the status enum carries a description ("unpaid = sent, viewed or overdue") but limit is undocumented. The description is consistent with and reinforces the derived-status semantics of the status filter and explains the ordering that limit interacts with, but it never explains limit or its 25/100 default/cap. Baseline 3 is right given partial coverage.

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

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

States a concrete verb (read/list) and resource (the signed-in person's own invoices), plus scope-limiting details: newest-first ordering, live status, and outstanding/overdue totals. It clearly separates itself from the mutation siblings (create_invoice, send_invoice, mark_invoice_paid), though it never explicitly contrasts with the read-side sibling list_transactions, so an agent must infer the invoice-vs-transaction boundary.

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

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

"Needs no details from the person" implies the tool is called with zero required arguments and is the natural read-side entry point, which is useful. However, there is no explicit statement of when to prefer this over list_transactions or when to follow up with mark_invoice_paid, so usage guidance is only implied.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so safety is covered. The description adds genuinely new behavioral context: results are newest-first, scope is limited to the signed-in person's own records, and no extra identifying details are required. It omits pagination/limit behavior, which is a real gap for a list tool.

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

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

Two dense sentences with the core purpose and scope front-loaded, followed by filter semantics. Tight overall, though the trailing 'Needs no details from the person beyond what to look for' is slightly padded phrasing for a simple no-extraneous-input point.

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 conveys record shape (income/expense records, newest first) and the review-queue concept. For a 7-parameter list endpoint it would be stronger if it mentioned the result cap (limit default 25, max 100) or how to page through more than the default.

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 only 43%, so the description must compensate, and it does for the key ambiguous params: needsReview is explained as 'still waiting for a business-or-personal decision (the review queue)' and type/taxYear/search are described in prose. The limit parameter and its default/cap are not addressed.

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 and search the signed-in person's own income and expense records in their TapTax account') plus the result ordering ('newest first'). This clearly separates it from add_transaction, update_transaction, and the invoice tools in the sibling list.

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

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

Explains the available filter axes and points to a concrete use case ('needsReview=true ... the review queue'), giving clear context for when to reach for it. It never names an alternative tool or states exclusions, so it stops short of the top score.

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

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

Annotations only declare the generic mutation profile (readOnly=false, idempotent=false, destructive=false); the description adds real behavioral context: automatic pricing at the approved rate, tiering after 10,000 car miles, and a Pro-plan gating requirement. It stops short of saying what the response contains or whether entries can be amended.

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?

Four short sentences, front-loaded with the action and then progressively adding pricing, the eligibility exclusion, and the plan gate. Every sentence carries distinct information, though the pricing/tiering detail is useful context rather than action-critical.

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 6-parameter mutation with no output schema, the description covers the semantic rules an agent most needs: what counts as business mileage, how it is priced, and the plan restriction. Remaining gaps (return value, permissions beyond plan gating) are moderate.

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 low (33%), so the description carries more weight than usual. Its mention of 'car miles' and the tiering rule indirectly signals that the vehicle type affects pricing, but it adds nothing about from/to/date/purpose, leaving most parameters documented only by their bare schema types.

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

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

States a specific verb+resource ('Record a business journey in the signed-in person's mileage log'), clearly distinct from the read-only sibling get_mileage_summary. An agent can identify this as the write-side mileage tool without opening the schema.

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

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

Provides a clear exclusion rule ('Commuting to a permanent workplace is not business mileage') and a prerequisite ('Mileage tracking is on the Pro plan'). It doesn't explicitly name get_mileage_summary as the read counterpart, so routing guidance is good but not exhaustive.

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 destructiveHint=true, idempotentHint=true and non-read-only, so the safety profile is covered. The description adds genuinely new behavior: the payment date is forced to today and payment reminders are stopped as a side effect — context an agent cannot derive from annotations alone.

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

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

Two short sentences with zero waste; the core action is front-loaded and the side effect follows. Nothing is padded.

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

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

For a one-parameter mutation tool with annotations covering idempotency and destructiveness, the description supplies the two non-obvious facts (date defaults to today, reminders stop). Only minor gaps remain, such as authorization requirements or behavior when the invoice is already marked paid.

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

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

Schema description coverage is 0% and the single invoiceId parameter has no textual explanation, but its meaning is self-evident from the name and the format/pattern constraints in the schema. The description adds only an implicit reference to 'an invoice' rather than parameter-level 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 resource ('Record that the client has paid an invoice') with clear scope, and the sibling tools (create_invoice, send_invoice, list_invoices) are distinct enough that the action is unambiguous. It does not explicitly name a sibling to differentiate against, keeping it just short of a 5.

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

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

No guidance on when to use this vs alternatives such as add_transaction, nor any prerequisites or exclusions. The mention of '(dated today)' implies a usage constraint but is stated as a side effect, not as usage guidance.

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

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

Annotations declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the agent already knows this is a safe, closed-world calculation. The description adds useful output context beyond the annotations: what the tool returns (amounts, running totals, deadlines, payments on account). It doesn't describe edge cases, rate limits, or error behavior, but with annotations covering safety, this is a reasonable 3.

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, well-structured sentence that front-loads the core purpose then enumerates outputs. It's dense but every clause adds information. Slightly long but no wasted words.

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

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

With no output schema, the description usefully enumerates what the tool returns (income tax, Class 4 NI, student loan, monthly/weekly amounts, running totals, deadlines, payments on account), which is valuable. Combined with the schema's parameter documentation and the annotations, an agent has enough to call this correctly. Minor gap: no explicit when-to-use-vs-siblings guidance, keeping it from a 5.

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 each parameter (annualProfit, studentLoanPlan, quarterlyProfits, firstYearOfTrading) is already documented in the schema. The description adds context about how profits map to the calculation ('from the year's profit or each quarter's profit') and mentions the first payment on account, which relates to firstYearOfTrading. Baseline 3 is appropriate when the schema does the heavy lifting.

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?

Clearly states the verb (plan/set aside) and resource (tax set-aside amounts) with specificity about the sole trader / Making Tax Digital context. It's distinguishable from siblings like estimate_self_employed_tax or calculate_student_loan_repayment because it explicitly names the combined output: income tax, Class 4 NI, student loan, monthly/weekly amounts, running totals, deadlines, and payments on account. However it doesn't explicitly name a sibling it differs from, so it's a clear 4 rather than a 5.

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

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

The description implies usage via 'from the year's profit or each quarter's profit' and 'under Making Tax Digital', giving context that this is for sole traders planning quarterly set-asides. But it doesn't say when to use this vs alternatives like estimate_self_employed_tax or calculate_tax_on_multiple_incomes, nor any exclusions. Implied usage only.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description goes further by explaining the data flow ('details travel in the link itself and are not stored by TapTax') and the human-in-the-loop step. It does not mention validation failures or limits, but the added privacy/no-persistence context is genuinely useful.

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

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

Three sentences, front-loaded with the document types before the behavioral detail, with no filler. Slightly longer than needed but every sentence carries information.

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

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

With no output schema, the description correctly fills that gap by describing the return ('the totals and a link') and the downstream workflow. Combined with read-only annotations it is nearly complete, though the sparse parameter documentation leaves the input side thin.

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 only 46% across 13 parameters, so the description is expected to compensate. It merely echoes the kind enum (invoice/quote/receipt/credit note/pro forma) and says nothing about lines, VAT rate, date, template, or the client/from fields, so the under-documented half stays undocumented.

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 concrete verb (Prepare) and the exact resource set (invoice, quote, receipt, credit note, pro forma invoice), and pins the channel ('TapTax's free document generator, without a TapTax account'). That framing distinguishes it from account-bound siblings like create_invoice and send_invoice without needing their schemas.

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 'without a TapTax account' and 'opens the generator... downloads the PDF' framing implies the intended scenario, so usage is inferable. However, it never names an alternative (create_invoice, send_invoice) or states when-not to use this tool, leaving the agent to guess between the document-producing siblings.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely new behavior: the output is a card with a button that opens TapTax, filing is out-of-band, and HMRC receives device details from the filing device. This goes well beyond the structured fields, though it doesn't discuss auth or rate limits.

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

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

Two sentences, front-loaded with the core purpose followed by the filing constraint. Every clause earns its place, though the second sentence is dense and could be trimmed slightly.

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

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

With no output schema, the description carries the return-shape burden and does so by naming the figures returned and the card/button artifact. Combined with the filing-location disclosure, an agent has what it needs, leaving only minor gaps around permissions or freshness of the data.

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

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

Schema description coverage is 100%, so both quarter and taxYear are fully documented in the schema (quarter maps to 5 July/5 Oct/5 Jan/5 Apr, taxYear defaults to current). The description's mention of '6 April to the end of the quarter' loosely reinforces the period semantics but adds no syntax or format detail beyond the schema, 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?

States a specific verb+resource ('Get the signed-in person's Making Tax Digital quarterly update ready') and then enumerates exactly what it produces: cumulative income, expenses, profit for the period, review items, and a TapTax card. This clearly separates it from siblings like check_mtd_status or get_mtd_deadlines, which report status/deadlines rather than assembling an update.

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 establishes a clear boundary — it prepares the update but filing 'always happens in the TapTax app, never from the chat' — which tells the agent not to expect to file. It lacks explicit routing guidance against alternatives (e.g. when to prefer check_mtd_status), so it is clear context without named 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 declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, but they cannot convey the confirm-before-send safeguard. The description adds real behavioral context: it opens a non-destructive confirmation card and no email is dispatched until the user presses Send, which resolves what would otherwise look like a write tool.

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

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

Three tight sentences, front-loaded with the action, then the card contents, then the no-email safeguard. Nothing is redundant, though the parenthetical listing of card fields is slightly enumerative.

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 only 0%-covered params, the description carries most of the burden and does so adequately: it explains the effect (card preview) and the safety guarantee (nothing sent until confirmation). It stops short of describing the tool's return value or the eventual send path.

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 0% and the single invoiceId is only described as a UUID pattern. The description compensates partially by scoping it to 'one of the signed-in person's invoices', implying an ownership constraint, but it adds no guidance on obtaining or validating the id.

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

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

States a specific action: fetching one of the signed-in user's invoices and surfacing it as a preview card with PDF, recipient, lines and total. That is concrete, but the very close sibling send_invoice_from_card is never named, so the agent must infer the preview-vs-send split rather than being told.

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 statement that nothing is emailed until the user presses Send implies this is the pre-send preview step, which is useful implied usage. However there is no explicit when-to-use/when-not against send_invoice_from_card, create_invoice, or list_invoices, so the agent gets context only by inference.

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

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

Annotations already cover the safety profile (destructiveHint=true, idempotentHint=false, openWorldHint=true, readOnlyHint=false), so the bar is lower. The description still adds real context: the operation is triggered by a human pressing Send and requires a one-time token issued to the card, which tells the agent the call is not freely repeatable.

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 with the action and the trigger front-loaded, and no padding. Slightly compressed wording ('the one-time token the card was given') costs a little clarity but nothing is wasted.

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

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

For a non-idempotent, destructive email send with no output schema, the description covers the trigger and the auth token but says nothing about failure modes (expired token, already-sent invoice) or the relationship to send_invoice. Enough to attempt the call, not enough to use it confidently.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains sendToken as a one-time token the card was given, which is useful, but invoiceId is left entirely to the schema's uuid format with no explanation of which invoice qualifies.

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 (emails) and resource (the invoice shown on a TapTax send card) to its client, which is more precise than the bare title. It implicitly separates itself from the generic send_invoice sibling via the card context, but never names that sibling, so the differentiation is left to 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?

Gives a triggering condition ('when the person presses Send on that card'), which is genuine usage context. However it never states when to use this instead of the sibling send_invoice, nor what to do if the card/token is stale, so the guidance is implied rather than explicit.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=true, idempotentHint=true), and the description is consistent with them; it adds the ownership prerequisite, which is useful context. However, it never explains the destructive aspect or whether omitted fields are left unchanged, so it adds only modest value beyond the structured hints.

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

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

A single sentence with the action and scope front-loaded and the review-queue insight parenthetically attached; no filler or restated name/title 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?

For a mutation tool with no output schema, the description covers purpose, ownership restriction, mutable fields, and the review-queue workflow, while annotations carry the safety profile. The remaining gap is partial-update semantics (what happens to fields omitted from the call).

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

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

Schema description coverage is 0%, so the description carries the burden, and it names five of the six parameters (businessOrPersonal, category, description, amount, date), with id implied by the ownership constraint. It adds no format detail (date pattern, amount bounds, allowed category values), so it compensates well but not completely.

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 ('Change a transaction') tied to the resource and constrains it to records 'the signed-in person owns', then enumerates exactly which fields are mutable (business/personal flag, category, description, amount, date). This clearly separates it from add_transaction and list_transactions without needing the schema.

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

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

It supplies real usage context: marking business/personal 'is how the review queue is cleared', which tells the agent when this tool is the right choice. It stops short of naming alternatives or stating when not to use it, so it earns a 4 rather than a 5.

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