Gross-to-Net Salary Calculator (Germany & UK)

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

Annotations already cover safety (readOnly, idempotent, non-destructive), but the description adds real behavioural value: the method (bisection), the precision guarantee (to the cent), and the fact that it returns the full breakdown PLUS the remaining difference to the target — which tells the agent the target may not be exactly achievable. No performance or convergence-time disclosure keeps it from a 5.

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

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

Two tightly written sentences with zero filler. The core purpose and precision guarantee are front-loaded, and the return-value sentence earns its place by clarifying the 'remaining difference' output.

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?

An output schema exists, so return values need no elaboration, and the description still usefully notes the remaining-difference field. With 6 params at full schema coverage and rich nested docs, nothing critical is missing; the only gap is no explicit statement of country/period scope that the schema carries.

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%, including rich nested DE/UK profile docs, so the baseline is 3. The description adds only the notion of a 'target net' and 'gross pay', which the schema titles already convey; no period, country, or year semantics are elaborated beyond what the schema documents.

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

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

States a specific verb and resource (find gross pay for a target net) with a precise scope qualifier: the SMALLEST gross to the cent. Combined with 'bisection over the same engine as /net', the agent immediately understands this is the inverse of the net calculator, distinguishing it from calculate_net_salary and compare_net_salaries.

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 inverse framing ('net pay reaches the target') makes the when-to-use case clear relative to calculate_net_salary, and the 'same engine as /net' note signals shared semantics. However, it never explicitly names the sibling to use when going the other direction, nor states any exclusions or prerequisites (e.g. country coverage), so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered. The description adds that output is line-by-line with the applied rule and its source, plus employer cost, annualisation and stated assumptions – useful behavioral context, but it overlaps heavily with the existing output schema and says nothing about failure modes or input validation.

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 operation, no filler. The second sentence is a long list of returned artefacts but each item is informative rather than decorative.

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

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

For a stateless, deterministic calculator with full schema coverage, rich annotations and an output schema, the definition is close to sufficient. Coverage gaps are minor: no mention that results are periodised/annualised inputs are mutually dependent, and no guidance on the DE/UK profile requirement linkage to country.

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 (country, gross, period, year, de/uk profiles) is already documented in the schema. The description only echoes 'gross pay', 'one pay period' and the country-specific algorithm, adding no syntax or constraint detail beyond 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 with direction and scope: 'Computes net pay from gross pay for one pay period with the country's official payroll algorithm.' That cleanly separates it from the inverse sibling calculate_gross_salary in substance, though the description 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?

The gross-to-net direction and 'one pay period' scope imply the intended situation, but there is no explicit when-to-use, when-not-to-use, or routing to calculate_gross_salary / compare_net_salaries. 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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: the 8-scenario cap, the exact output breakdown, and the important constraint that amounts remain in each country's currency with no FX conversion.

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

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

Two sentences, zero filler, and the core capability plus the output shape are front-loaded. Every clause carries information the agent needs.

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

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

With an output schema present, return values need not be re-specified, and the description still summarizes them plus the currency caveat. What is missing is any statement of prerequisites or failure modes (e.g. the DE 67+ birth-year rejection noted only in 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 description coverage is 100%, so the baseline is 3, but the description earns extra credit by surfacing the maxItems=8 limit and the currency semantics (local currency, no FX), which the schema only implies via "in EUR (DE) or GBP (UK)". It still doesn't hint at the country-specific profile objects inside each scenario.

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

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

The description states a concrete verb and resource ("Runs up to 8 gross-to-net scenarios and returns them side by side") and enumerates the returned quantities (net, deductions, employer cost, tax/social split). It clearly reads as a multi-scenario comparison tool, but it never names the sibling calculate_net_salary to explain why an agent would pick this one over a single-scenario calculation.

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 "up to 8 scenarios ... side by side" and the "no FX conversion" caveat, which tells the agent results are not directly comparable across currencies. However, there is no explicit when-to-use sentence and no mention of the alternatives (calculate_net_salary for a single case), so the boundary with siblings is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and openWorld=false, so the safety profile is covered. The description adds one useful behavioral fact beyond the annotations - that each value carries its official source - but says nothing about caching, freshness across tax years, or whether missing country/year combos error out.

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 lists the returned data classes immediately, with no filler. It is a fragment rather than a complete sentence, but every phrase 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 an output schema present, return-value structure need not be explained, and the read-only annotations cover the safety profile. The description adequately conveys what data comes back for which country/year, though it omits any hint about failure cases or parameter defaults.

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

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

Schema description coverage is 100%, including the UK start-year convention and the DE/UK/GB enum note, so the schema does the heavy lifting. The description only restates 'for the country and year' without adding format or constraint detail beyond the schema.

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

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

The description names a specific resource set - allowances, tax bands, contribution rates and ceilings for a country and year - which is clearly distinguishable from the calculate_* siblings that perform computations. It stops short of a verb ('retrieve'/'fetch') and leans on the title, but the resource is unambiguous.

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

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

There is no statement of when to use this tool versus calculate_gross_salary, calculate_net_salary, or list_salary_countries, and no prerequisites or exclusions. The intended use (fetching raw reference data rather than computing a salary) can only be inferred.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safe-read profile is conveyed structurally. The description adds real value by disclosing that the payload includes engine test data and future/planned countries, which an agent would not expect from a plain country list. It says nothing about how the data is scoped or versioned, so it stops short of rich behavioral disclosure.

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 topic label 'Coverage:', with no filler or repetition of the title. It is slightly list-heavy and lacks a closing verb clause, but it stays compact and every clause names a distinct piece of covered 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 an output schema present, return values need no explanation, and a zero-parameter read-only tool has few open questions. The one remaining gap is workflow context — when in a calculation sequence this should be consulted versus the sibling get_payroll_parameters — which the description does not address.

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

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

The tool takes zero parameters, so the baseline score of 4 applies. The description's mention of 'pay periods', 'profile fields' and 'tax years' describes the shape of the returned coverage rather than any inputs, and with no parameters there is nothing further to document.

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 enumerates exactly what the tool reports (countries, tax years, accepted pay periods and profile fields, test data, roadmap countries), which reads as a clear coverage/discovery resource distinct from the calculate_* siblings. It never states an explicit verb like 'returns' or 'lists', so the action is inferred from the name rather than the text. Still, an agent can tell this is a metadata lookup, not a calculation.

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

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

No when-to-use guidance is given. The description never says to call this before calculate_gross_salary/calculate_net_salary to validate country or tax-year support, nor does it distinguish itself from the sibling get_payroll_parameters, which plausibly exposes overlapping configuration. The roadmap content hints at a pre-flight use case but leaves the agent to infer it.

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