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

Annotations already establish readOnlyHint=true, idempotentHint=true, openWorldHint=false, so the safe, deterministic, offline nature of the call is covered. The description adds genuinely new behavioral context: each statutory line cites its legal basis and source, amounts are in EUR, and a broker commission cap check is performed. It omits any statement about output shape or performance, keeping it short of 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?

Front-loaded purpose sentence, then trigger, then two short factual notes, then exclusions — no padding and each sentence carries information. The middle two sentences ('Every statutory line cites its legal basis and source', 'Amounts in EUR') are terse but additive rather than 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 pure read-only computation with no output schema, the description covers what is computed, when to use it, currency, and hard exclusions. It stops short of describing the returned breakdown (line items plus total) or citing the covered legal-period window, which the agent only learns from 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% and the field descriptions are already rich (VAT-exclusive commission, 'zzgl. 20% USt' example, defaults for contractFeePct and mortgage factor). The description's parameter-relevant content ('broker commission with a check against the legal maximum', 'each with VAT where it applies') largely restates what the schema already says under sellerPaysCommission and the fee fields, so the 3 baseline 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 ('one-off costs of buying residential property in Austria / Kaufnebenkosten'), then enumerates the exact cost lines included (Grunderwerbsteuer, land-register fees, broker commission, lawyer/notary costs). That level of scope detail makes it unmistakable next to a generic rules lookup like get_rules or an underwriting tool.

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 trigger ('Use when someone asks what buying a specific flat or house in Austria costs in total') and explicit exclusions ('Not covered: bank or valuation fees, purchases within the family, exemptions for a primary residence'). It does not name or route to sibling alternatives (get_rules, underwrite_property), so it falls short of a full 5.

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