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

Annotations only declare that this is a non-read-only, non-destructive, non-open-world write. The description goes beyond them by disclosing that auto_post causes every issued document to be booked and requires posting rights, plus the explicit instruction to confirm with the user first. It also explains the derived behavior when product_code is given (name, unit, price and tax are inherited where the patch omits them). It stops short of describing what the call returns or what happens to an existing schedule's unmentioned fields.

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 create-or-update statement comes first, then field semantics, then the safety instruction on auto_post. The key list in the second sentence duplicates the schema's patch description, which is slightly wasteful, and a few sentences run long, but almost nothing is filler.

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 mutation tool with a nested free-form patch, no output schema and only generic annotations, the description supplies the field vocabulary, the enum values, the tax-code lookup path, the product-derived defaults, and the posting-right caveat for auto_post. What an agent needs to invoke this correctly is present; return-value detail is not required since no output schema exists and the write semantics are clear.

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 leaves patch as an untyped additionalProperties bag, so the description carries all the weight: it enumerates the fourteen accepted keys and defines the non-obvious ones — frequency's four allowed values, next_on as the first day of the next period, until as the last day a period may start, tax_code referencing the company's code list, and indexation's internal shape (index, formula, base, base_on, next_on). This is meaning the schema does not provide.

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 opening sentence gives a specific verb and resource: it adds an invoicing line to a contract on its own rhythm, or changes an existing one when schedule_id is supplied. The create-vs-update split is stated explicitly. It does not contrast itself with nearby siblings such as contracts_upsert, contracts_amend or instalment_plan, so an agent still has to infer which of those handles which case.

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?

There is real guidance for parameter use: look up tax codes via list_accounts or describe_pack and never pass a rate, and ask the user before enabling auto_post. However, there is no guidance on when to choose this tool over contracts_upsert, contracts_amend or instalment_plan, so tool selection is left to inference.

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