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

Goes well beyond the annotations by disclosing partial-update semantics (omitted fields stay untouched), replacement semantics for consumption.periods, and — most valuably — that values are recorded as assistant-entered and must be confirmed by the customer before ordering. That the tool writes to a draft and commits nothing aligns with and enriches destructiveHint=false and idempotentHint=true.

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-loads the verb and resource, then layers the highest-risk gotchas (unit conversion, whole-building consumption, partial update) in descending order of importance. Dense and slightly run-on — the middle sentences could be split — but nearly every clause prevents a real data-entry error.

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?

Covers the failure modes an agent would otherwise hit on a deeply nested, German-domain data-entry tool: unit and conversion factors, the Liegenschaft-vs-flat trap, synonym tolerance, and append-vs-replace behavior. Return values are summarized (current order plus open points) even though an output schema exists, and the non-committal framing is stated outright.

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?

Adds domain meaning the schema can't carry: server-side unit conversion (m3 gas with Brennwert and Zustandszahl, litres of oil, kg of pellets), the rule to take the building-wide Gesamtverbrauch rather than a single flat's share, and that synonyms like 'Gas' or 'heat pump' are accepted for carrier values, which matters because no parameter exposes an enum. Some of this restates nested field descriptions already present in 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?

States a specific verb and resource — "enters or corrects data of a draft order" — and the closing "Orders nothing" draws a hard line between it and siblings like request_confirmation, review_order or start_order. An agent can tell which stage of the order flow this belongs to 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?

Gives clear conditions for the call (draft order, data read off bills) and an explicit exclusion of the ordering step. It does not name a sibling as the alternative for reading existing data (get_listing_facts) or for finalizing (request_confirmation), so the routing is inferable rather than spelled out.

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