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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description layers on real behavioral substance: the PA taper rule above £100,000, the 60% trap, region-specific band sets including 2026/27 Scottish starter/basic bands, 2026/27 student-loan thresholds, and the explicit return shape (net pay per year, month, week). It also discloses provenance and vintage ('Figures copied from gov.uk and HMRC in Oct 2026'), which matters for a tax calculator whose correctness is date-sensitive.

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

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

It is a single front-loaded paragraph with zero filler; every clause carries either a calculation rule or an input/output fact. It is dense and slightly list-heavy in one sentence, which costs a point on readability, but nothing is extraneous.

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

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

For a 9-parameter, non-destructive calculation tool with no output schema, the description supplies what the structured data cannot: the return values (annual/monthly/weekly net), the rule set applied, the supported years and regions, and the data vintage. An agent has everything needed to call this correctly and interpret the result.

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

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

Schema coverage is 100%, so a baseline of 3 would apply, but the description adds genuine meaning beyond the schema: that pension_method=salary_sacrifice reduces pay before tax, NI and student loan while relief_at_source is grossed-up, that the PA taper is £1 per £2, and which tax-code families (1257L, S1257L, K475, BR, D0) are accepted. These are interactions the schema's per-field descriptions do not convey.

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

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

States a specific verb and resource ('Calculates UK take-home pay for an employee in tax year 2025/26 or 2026/27') and enumerates the exact components computed: income tax by band, employee Class 1 NI, student loans, pensions. This clearly distinguishes it from get_uk_tax_bands (rate lookup), marginal_rate_at_income (single-point rate) and compare_salaries (comparison), so an agent can select it without opening the schema.

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

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

The description makes the use case explicit through the scope it claims: full net-pay computation for a given tax year, region, tax code, NI category, pension and loan plans. It does not name the sibling tools or state when to prefer them (e.g. use get_uk_tax_bands for raw band tables), so the routing is inferable rather than 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 cover the safety profile (readOnly, idempotent, closed-world), yet the description still adds substantive context: the modelled deductions, the break-down of returned figures (net pay per year/month/week, effective and marginal rates, pay-rise retention), taper detection, and the data vintage ('HMRC 2025/26 and 2026/27 rates fetched in Oct 2026'). That vintage disclosure is unusually valuable for a tax tool where rate freshness affects trust.

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

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

Front-loaded with the core capability, then the outputs, then the taper edge case and data source. Dense but each sentence carries information; the specific 60%/69.5% taper figures are borderline detail but do signal a headline feature of 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 9 parameters, no output schema and no nested objects, the description does the heavy lifting well: it names the deductions modelled and the main returned figures. It stops short of describing the response structure or error behaviour, but an agent has enough to call it and read results correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a genuine cross-parameter semantic: region, tax code and all options apply uniformly to every salary in the array, and the first salary is the baseline for the 'how much of each pay rise you keep' calculation. That interpretation is not obvious from the schema alone.

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

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

States a specific verb and resource ('compares 1 to 5 UK gross salaries after tax') with the exact deductions modelled. The multi-salary, shared-options framing clearly separates it from the single-salary sibling calculate_uk_take_home and the band/rate lookups get_uk_tax_bands and marginal_rate_at_income.

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 comparison framing and the 'same region, tax code and options for each' constraint, but the description never says when to prefer this over calculate_uk_take_home or when a single-salary call is enough. No exclusions or prerequisites are stated.

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

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

Annotations already declare read-only, idempotent and non-open-world, so the bar is lower. The description still adds genuine value: it names the data source and retrieval date (gov.uk and HMRC, Oct 2026) and commits to a behavior — unpublished figures are marked 'unannounced, never guessed' — which is exactly the kind of trust/accuracy disclosure an agent needs for financial data.

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, front-loaded paragraph that begins with the return value. The long parenthetical Scottish rate list is the only heavy element; it is informative but could be trimmed since the rates are returned data rather than invocation guidance.

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 carries the burden of describing return contents and does so thoroughly, including the two band representations and the 'unannounced' marker. The only meaningful gap is that it never tells the agent when to call a sibling calculator instead.

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 both params enumerated, so the baseline would be 3. The description goes beyond the enum by explaining that the region choice is semantically meaningful — Scotland gets a distinct band set with different rates (19/20/21/42/45/48) while England/Wales/NI shares another — and that tax_year selects between two published table sets.

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 ('Returns the official UK income tax bands') with the exact scope of data included (taxable-income bands, gross-salary bands, allowance taper, Class 1 NI, student loan thresholds). The implicit contrast with calculation siblings is clear from 'official ... bands' framing, though it never names them.

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

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

Usage is implied: an agent can infer this is the lookup tool for published bands rather than a calculator. But there is no explicit when-to-use, when-not-to-use, or pointer to marginal_rate_at_income / calculate_uk_take_home for the derived figures this tool stops short of computing.

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 (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely new context: data provenance and staleness ('gov.uk and HMRC, fetched Oct 2026'), supported tax years, and the non-obvious 60%/67.5% PA-taper behaviour including the Scotland difference. The return shape is only partially implied — there is no output schema and no statement of whether the result is a single number or a component breakdown.

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

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

Front-loaded with the core purpose and kept to a tight block with no filler sentences; the worked 60%/67.5% examples earn their space by pinning down the non-obvious behaviour. It is dense and clause-chained, which makes it slightly harder to scan than a cleanly bulleted spec, but nothing is padding.

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

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

For a 10-parameter domain calculator with no output schema, this covers what is needed: what is computed, which deductions are combined, the measurement convention (change over `step`), supported regions/years, and the data vintage. Return details are the only residual gap, and the description at least names the components that make up the rate.

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

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

Schema description coverage is 100% and each of the 10 parameters is documented there in detail (enums, defaults, K/BR/S/D code support, pension method semantics), so the baseline is 3. The description adds only light framing — the meaning of `step` and the mention of salary sacrifice / relief at source — without new syntax or interaction rules beyond what the schema states.

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

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

States a precise verb and resource — 'returns the true UK marginal rate on the next pounds of salary' — and enumerates what the rate comprises (income tax, employee NI, student loan, PA taper). It never names the siblings (calculate_uk_take_home, get_uk_tax_bands, compare_salaries), so the contrast with 'total take-home' is left implicit rather than stated.

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

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

The framing 'marginal rate on the next pounds' implies the use case (rate on incremental pay, not total burden), and 'measured as the change in deductions over the next `step` pounds' clarifies the measurement model. However there is no explicit when-to-use statement, no when-not, and no routing to the alternative take-home or band tools for questions this tool does not answer.

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