settle_up

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

Beyond the annotations, the description discloses non-obvious behavior: the settlement is actually recorded as an ordinary expense with a specific owes/pays split, and Splitwise's UI will display it as a regular expense rather than a true payment. This is substantial, non-obvious behavioral context that annotations alone do not provide.

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?

The purpose is front-loaded in the first sentence, and the follow-up paragraph explains the important Splitwise workaround. The second paragraph is somewhat long but earns its place because the behavior it describes is non-obvious and critical for correctly understanding the tool's effect.

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 mutating tool with sparse annotations, the description covers the essential call constraints and the most important behavioral caveat. An output schema exists, so return values need not be described. Minor gaps like permission failure behavior are not addressed, but the tool is sufficiently complete for correct invocation.

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 100%, so baseline is 3. The description adds meaningful cross-parameter semantics by requiring exactly one identifier per side and explaining name/id resolution against group members or the authenticated user and friends. This is valuable beyond the schema's individual parameter descriptions.

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 description clearly states the tool records a payment between users and settles part of a balance. It further distinguishes itself from create_expense by explaining that Splitwise's payment flag is not exposed, so this tool exists specifically for the settle-up 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?

The description gives explicit input constraints: exactly one from_user_id/from_user_name and one to_user_id/to_user_name must be provided, and resolution depends on whether a group is supplied. It also references create_expense as the overlapping alternative and explains why it is unsuitable, providing actionable selection guidance.

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