Obolus

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the 'Calculate' wording is consistent. The description adds beyond annotations by revealing that legacy fields are 'REST compatibility inputs' and warning that 'Monetary fields in the legacy request are minor units and period-specific,' which is important behavioral context for constructing requests.

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?

Five sentences with no filler: action and scope are front-loaded, sibling routing comes second, and the remaining sentences cover field families and unit conventions. Every sentence 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?

The description is a good high-level orientation, but it says 'one country and person' while the schema supports up to two Personen records (maxItems 2, Modus 2). It also doesn't enumerate the recommended semantic fields, though the schema's own description does. For a tool with this complexity, those are notable completeness gaps despite the rich 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%, so the baseline is 3. The description adds cross-cutting semantics by distinguishing semantic vs. legacy fields ('Use semantic fields where available; legacy fields remain REST compatibility inputs') and by flagging minor-unit/period conventions, which is not fully captured by individual parameter 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 opens with a specific verb and resource: 'Calculate detailed payroll and net salary for one country and person.' It also names the sibling differentiator by saying 'For the same gross salary across two or more countries, use taxcompare,' so an agent can distinguish this 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?

It explicitly lists when to use the tool: 'Use this for tax class, region, health insurance, pension, deductions, or other country-specific inputs.' It also gives a clear exclusion rule by routing multi-country comparisons to taxcompare, leaving no ambiguity about the main alternative.

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, covering the safety profile. The description adds behavioral context by specifying what the comparison produces (gross, net pay, taxes, social contributions) and how the two gross_modes alter the comparison basis. Minor limitations like simplified assumptions live in the schema rather than the description, but with strong annotations the bar is partially met here.

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

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

Four sentences, zero filler: purpose, mode selection, prerequisites, and sibling routing each earn their place. The core capability is front-loaded in sentence one, and the sibling reference is tucked into the final 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?

An output schema exists, so the description needn't explain return values. Given the tool's 12 parameters and nested regions object, the description appropriately covers selection (what it does), configuration (which mode), prerequisites (tax_year + two countries), and fallback routing (berechne). The one gap is that the description omits the 'estimates/simplified' nature of results, but this is captured in the schema's input description.

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 detailed explanations of gross_mode, period, salary_ct, and joint_assessment, so the baseline of 3 applies. The description's mode phrasing ('same offer' vs. 'country-market benchmarks') recasts schema content in simpler terms but adds no new parameter meaning beyond what the schema already delivers.

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?

Opens with a specific verb and resource: 'Compare annual gross, net pay, taxes, and employee social contributions across two or more supported countries.' The scope (multi-country comparison) and the sibling differentiation ('Use berechne for detailed single-country payroll') let an agent distinguish this from its sibling without opening 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?

Provides explicit mode-selection guidance: 'Use shared_gross for the same offer and local_median_gross for country-market benchmarks.' It also states prerequisites ('Provide tax_year and at least two countries') and names the alternative tool for single-country scenarios. Nothing 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.