set_aging_bucket_config

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

Annotations already flag destructiveHint=true and idempotentHint=true, and the description adds exactly the context they lack: the change is view-only, re-partitions the same receivables total and can never alter it, the reconciliation to 1100 Debitoren holds for any boundary set, and a repeat call under the same idempotencyKey writes nothing. That reassures the agent about the blast radius of a 'destructive' operation without contradicting the annotations.

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?

Four sentences, front-loaded with the action and value format, then effect, then domain framing, then idempotency. Every clause contributes either parameter semantics or blast-radius information; 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 3-parameter mutation with no output schema and annotations covering safety, this covers value format, invariants, and idempotency well. It omits permission/role requirements and error behavior for invalid boundary lists (e.g. non-increasing values), which would complete the picture for a write 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 coverage is 0%, so the description has to carry the load: it does for boundariesDays (strictly increasing, positive day counts, default example) and implies the contract for idempotencyKey ('a repeat call under the same idempotencyKey writes nothing'). workspaceId is left as conventional/undocumented, which is the only material gap.

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?

Opens with a specific verb and resource ('Redefine where the aging buckets cut') and immediately defines the accepted value form with a concrete default example ([30,60,90] -> 0-30, 31-60, 61-90, 90+). It also carves itself away from the dunning configuration tools by stating it is 'not a dunning deadline (A15 owns those)', so an agent can place it against get_aging_bucket_config / aging_report without opening schemas.

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?

Clear about the conditions and effects of use ('changes the VIEW only', 'not a statutory figure'), and it explicitly excludes the dunning-deadline territory owned by another tool. It stops short of naming the read-side sibling (get_aging_bucket_config) as the alternative, and gives no prerequisite/authorization guidance, so it is strong but not a full when/when-not map.

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