calculate_tax

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

With no annotations provided, the description must cover behavioral traits. It reveals that the tool automatically derives social-insurance contributions and standard deductions from gross figures, which is a key behavioral detail. However, it does not disclose potential side effects, authorization needs, rate limits, or what happens to conflicts with standard deductions. Given the complexity, the transparency is adequate but not thorough.

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 concise, consisting of two short paragraphs. It is front-loaded with the main purpose, followed by the model explanation, and ends with a usage guideline. There is no redundant or unnecessary information, making it easy to read and understand quickly.

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?

Given the tool has 16 parameters and an output schema, the description provides sufficient context for an agent to decide when to use it. It explains the model's behavior and mentions a sibling tool. The schema handles parameter details, so the description doesn't need to repeat them. It feels complete for a tool of 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?

The schema description coverage is 44%, so many parameters already have descriptions in the schema. The description adds context by emphasizing that only income, wealth, and family situation are needed, grouping the core parameters. It does not describe individual parameters beyond what the schema provides, but it does offer a high-level understanding. 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 clearly states that the tool computes federal, cantonal, municipal and church tax for a household. It specifies the model used (ESTV) and the inputs needed (income, wealth, family situation). It distinguishes from sibling `list_deductions` by mentioning it as a prerequisite for optional deductions, but does not explicitly differentiate from other siblings like `calculate_tax_from_taxable_amounts`.

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 explicit guidance on when to use the tool: when you have gross income, wealth, and family situation. It advises calling `list_deductions` first if you want to supply optional deductions like pillar 3a. This helps the agent understand prerequisites and when to use this tool versus a sibling. However, it does not explicitly state when not to use it.

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