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

Annotations already declare it is a non-destructive write in a closed world, so the description's job is to add scope, which it does: every couple already has both partners and "together" pre-seeded, and instalment-to-payer assignment happens in the dashboard rather than via this tool. It stops short of saying what happens on duplicate names or whether payers can be removed later.

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?

Three short sentences, front-loaded with the action and followed by the pre-existing-default context and the out-of-scope note. No filler, though the two quoted terms in the second clause read slightly awkwardly without more framing.

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?

No output schema or rich annotations exist, and the description still tells the agent what the tool creates, what already exists by default, and which behaviour deliberately lives elsewhere (instalment assignment in the dashboard). That is sufficient to call a single-parameter create tool correctly.

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?

Only one parameter, and the schema gives it no description, so the description carries the burden. The example "Ouders Elian" usefully signals that the name is a human-readable label for a person or group rather than an ID or email, which is meaning the schema alone does not convey.

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?

"Adds someone who pays part of the wedding" gives a specific verb plus resource and an illustrative example ("Ouders Elian") that pins down the domain concept. It also names get-budget as the read counterpart, though it does not explicitly distinguish itself from other add-* siblings like add-expense or add-budget-category.

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?

Usage context is implied: use this when a new person or group contributes to the wedding budget, and check get-budget to see balances. There is no explicit when-not guidance (e.g., duplicates, whether a payer must exist before an expense can reference it) and no stated prerequisites.

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