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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real substance on top: results split known from unknown components and knownTotal deliberately excludes unknowns, a decision that prevents misreading the output. It stops short of explaining how enum value 'unknown' propagates through the calculation or what errors look like beyond refusal.

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?

Dense but front-loaded: the scope, the conditional components, and the output contract (knownTotal excludes unknowns) arrive before the refusal rule. The single long sentence cramming eligibility, surcharge, and notary logic is slightly harder to parse than a short list would be.

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, nested quotes, an output schema, and full annotation coverage, the description supplies exactly the missing layer: which components are conditional, what happens to unknowns, and what input domain is rejected. An agent can call this correctly and interpret the result without further documentation.

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?

At 56% schema coverage the description must compensate, and it does for the highest-risk fields: it ties eligibility/balance inputs to 'only when confirmed', maps the municipal surcharge to a confirmation requirement, and explains that notary figures are either tariff-estimated or supplied as quotes. financing and the exact purchaseKind semantics remain undocumented in both places.

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?

Names a specific computation (Luxembourg resale purchase costs) and the exact inputs that drive it (price and main-home use), then enumerates the cost components it produces. It also carves out an explicit exclusion (new-build/VEFA is refused), which separates it from the mortgage, affordability, and buy-vs-rent siblings.

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 a clear when-not (VEFA purchases are refused) and conditional guidance for the Bëllegen Akt credit and Luxembourg City surcharge ('only when confirmed'). It does not name a sibling to use instead for new-build or for pure financing math (calculate_mortgage), so an agent must infer the handoff.

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