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

Annotations already declare readOnly=false, destructive=false, idempotent=false and openWorld=true, so the mutation profile is covered structurally. The description adds genuinely new context beyond annotations: creation consumes 10 API credits against a limited monthly quota, and the "WRITE:" prefix front-loads the mutation. It does not say whether duplicate article numbers are rejected or what the response contains.

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?

A single sentence, front-loaded with the WRITE marker and the resource, followed by the credit-cost caveat. No filler and no repetition of schema content beyond the one necessary word "price".

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 nine parameters, five required, no output schema and no nested objects, the credit cost and quota warning cover the main hidden risk. However, the description never indicates what comes back from a successful create (presumably the new proposition id needed for invoicing), nor any prerequisite/order-of-operations detail, leaving a meaningful gap for a mutation tool.

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%, so every one of the nine parameters is already documented in the schema, including the vat_rate format hint pointing at papierkram_get_proposition. The description only echoes "with a price", adding little beyond the structured fields, so the baseline 3 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 and resource ("create a stored product or service (Leistung/Artikel) with a price"), which distinguishes it from the create siblings for invoices, persons, projects, tasks and time entries by resource alone. It does not explicitly differentiate itself from papierkram_get_proposition or papierkram_list_propositions, but the write/store semantics are unambiguous.

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 only guidance is a cost warning about API credits and the monthly quota, which is a budgeting constraint rather than a when-to-use rule. Nothing tells the agent when to create a new proposition versus updating or reusing an existing one from papierkram_get_proposition, nor that this must precede invoicing.

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