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

Annotations already declare a non-read-only, non-idempotent, non-destructive write, so the safety profile is covered. The description adds genuinely useful behavior the annotations cannot express: rounding is deterministic in whole cents so shares sum exactly, and ambiguous names return candidate matches instead of guessing, with an instruction to ask the user. It omits auth/permission requirements and whether other members are notified.

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?

Five short sentences, front-loaded with the action, then the three main choices, then behavioral caveats. Nothing is padded, though the split-mode enumeration partially restates the schema's own enum descriptions.

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 an eight-parameter write tool with a nested split union schema and no output schema, the description covers what matters most: defaults, the group-vs-non-group branch, and the candidate-list return on ambiguous names. Currency and date defaults are left to the schema, which is acceptable given full schema coverage, but a note on whether repeated calls create duplicates would close the remaining gap.

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 the baseline is 3 and the description does not have to compensate. It reinforces the group-omission case, the paid_by default, and the three split modes, but the detailed semantics (percent must total 100, exact shares must equal cost, leftover-cent allocation) already live in the schema, so the added value is marginal.

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 first sentence gives a specific verb and resource ("Adds an expense to Splitwise"), which is enough to distinguish this from update_expense or delete_expense. It never names those siblings explicitly, so the differentiation rests on the verb alone rather than on stated contrast.

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?

It resolves the main decision points an agent faces: include a group or omit it for a friend-to-friend expense, who paid (defaults to you), and which of three split modes to use. It stops short of saying when to prefer this over alternatives such as settle_up or update_expense, so it is clear context without exclusions.

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

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

Annotations already declare destructiveHint, idempotentHint and openWorldHint, so the safety profile is covered; the description goes further by disclosing the immediate balance recalculation side effect and the fact that Splitwise can restore a deleted record from the web app. That recovery path is genuinely useful context an agent cannot infer from 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?

Three short sentences, front-loaded with the action, then the side effect, then the confirmation requirement. No filler or redundant restatement of the name.

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 single-parameter destructive tool with rich annotations and no output schema, this covers the essential risk information: immediate balance impact, user confirmation, and recoverability. The only mild ambiguity is whether expense_id also identifies a payment, given the description mentions both.

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 documents expense_id fully at 100% coverage, so the baseline is 3. The description adds no format or source hints beyond what the schema already says, but nothing is missing either.

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 ("Deletes an expense or payment") so the agent knows exactly what operation is performed. It doesn't explicitly contrast with the sibling update_expense, but the destructive framing separates it clearly enough in practice.

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?

Gives a concrete precondition — "Confirm with the user before calling" — which is the key gating rule for this tool. It does not name alternatives such as update_expense for reversibility-preserving edits, so the routing guidance is clear but not exhaustive.

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds real behavioral detail the annotations cannot: the response is split into "owes_you" and "you_owe", includes net totals per currency, and changes shape entirely when a group is supplied — important since there is no output schema.

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 core purpose, then the two modes, then the workflow cue. No filler and nothing redundant with the schema.

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 single-optional-parameter read tool with no output schema, the description covers both invocation modes and describes the returned structure well enough that an agent knows what it will get. Nothing needed to call it correctly is missing.

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 the baseline is 3, but the description adds meaning beyond the schema by explaining the behavioral consequence of supplying vs. omitting the group parameter (per-friend net view vs. intra-group debts). It does not restate the id-or-name union, which the schema already documents.

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?

"Summarises who owes whom" gives a specific verb and resource, and the description then defines the exact two modes (all friends vs. inside one group). An agent can distinguish this from list_expenses, get_group, or settle_up without opening the schema.

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?

Explicitly routes the agent: "Use this before settle_up to find the amount to settle," naming both the trigger and the downstream sibling. It lacks explicit when-not guidance or comparison to the list_* tools, which keeps it below a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds value beyond them by naming the exact fields returned and by explaining the identity mapping that other tools depend on. It does not mention failure behavior when the server is unauthenticated, which keeps it short of a 5.

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?

Two sentences, front-loaded with what is returned, followed by the one piece of cross-tool context an agent actually needs. No filler or restatement of the title.

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 no output schema, the description carries the return-value burden and does so by enumerating the account fields. For a trivial read-only zero-argument tool this is nearly complete; only error/authentication edge cases are unaddressed.

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 tool takes no parameters, so the baseline is 4 and there is nothing for the description to compensate for. No misleading parameter language is present.

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 gives a specific verb and resource ("Returns the Splitwise account this server acts as") and immediately enumerates what comes back: id, name, email, default currency. The second sentence ties the tool to the other siblings by defining that "me" in other tools resolves to this user, so an agent can place it precisely.

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?

It clearly signals when the tool is needed: whenever another tool's "me" identifier must be resolved to a concrete account. There are no explicit exclusions, but with zero parameters and no overlapping sibling (none of list_groups, get_expense, etc. return the acting account), there is little ambiguity left to resolve.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful return content (each person's paid and owed share), which matters since there is no output schema, but it omits not-found behavior and any auth/permission context.

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?

One sentence, front-loaded with the verb and resource, with the return-content clause appended. No redundant or filler wording.

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 single-parameter read tool with no output schema, the description covers both the input (by id) and the shape of the response (per-person paid/owed shares). Only error/edge-case behavior is missing.

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% and the single expense_id parameter is fully documented as the Splitwise expense id. The description's only added nuance is that a payment id may also be passed, which is a marginal gain over the schema.

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 ("Returns one expense or payment by id") and the singular/id-based framing implicitly distinguishes it from list_expenses and search_expenses. It stops short of naming a sibling or exclusion explicitly.

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 is only implied: fetch a single record when you already have an id. There is no explicit statement of when to prefer this over list_expenses or search_expenses, and no mention of what happens for an unknown id.

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds useful behavior beyond them: the result includes debts between members and these are simplified when the group has debt simplification enabled, meaning output shape varies per group. It says nothing about permissions, lookup failure behavior for unknown names, or ambiguities when a name matches multiple groups.

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?

Two tight sentences with the return content front-loaded and the conditional debt simplification in a parenthetical. The trailing 'Accepts a group id or name' is mild redundancy against the schema, but nothing else is wasted.

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?

There is no output schema, so the description carries the return-value explanation and does so well by enumerating members, balances, and debts. For a single-parameter read tool this is nearly sufficient; only the no-match/ambiguous-name behavior is left unaddressed.

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% and the schema already documents that the group parameter accepts an id or case-insensitive partial name. The description's 'Accepts a group id or name' merely restates that, adding no extra meaning. Baseline 3 applies when the schema does the heavy lifting.

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: it returns one group's members with balances plus inter-member debts, and notes the debt-simplification variation. The phrase 'one group's' signals it is the single-group counterpart to list_groups, though no sibling is named explicitly.

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 is only implied — the description makes clear this is a single-group lookup, from which an agent can infer it follows list_groups. It gives no explicit when-to-use, when-not-to-use, or named alternative such as get_balances for cross-group balances.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description goes beyond them by disclosing sort order ('newest first'), the content of each returned record ('what every person paid and owes'), and the default hiding of deleted records — genuine behavioral context an agent needs before calling.

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 short sentences with purpose front-loaded, then filters, then return content, then the one important default. No filler, no restatement of the name, and the most surprising behavior (hidden deleted records) is called out explicitly rather than buried.

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 read-only list tool with full schema coverage and annotations covering safety, this is close to complete: it covers purpose, filters, ordering, hidden-by-default semantics, and a sketch of the return shape in lieu of an output schema. Only the relationship to search_expenses is missing.

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 every parameter including limit/offset and the date formats is already documented, making 3 the baseline. The description adds only the default-hidden semantics of include_deleted, which is partly redundant with its schema description ('Include expenses that were deleted'), and says nothing extra about group/friend accepting either id or name.

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 opens with a specific verb and resource plus a behavioral detail ('Lists expenses and payments, newest first'), which distinguishes it from get_expense (single item) and create/update/delete siblings. It stops short of naming or contrasting with search_expenses, which is the closest alternative, so the differentiation is incomplete.

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 filter set ('Filter by group, friend and date range') implies the browse/list use case, but there is no explicit statement of when to choose this over search_expenses or get_expense. The one true conditional it does give is 'Deleted expenses are hidden unless include_deleted is true', which is useful but does not double as usage guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds real semantic value beyond that: balances are aggregated per currency and the sign convention (positive = friend owes user, negative = user owes friend) is spelled out, which the agent cannot get from any structured field. It does not mention pagination, ordering, or rate limits.

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?

Two sentences, front-loaded with the purpose and followed by the one piece of interpretation guidance an agent actually needs. Every sentence earns its place with no filler or restatement of the title.

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?

There is no output schema, so the description is the only source of return-value information, and it covers only the balance figures and their sign. It says nothing about the other likely fields (friend id, name, email) that an agent would need to chain into create_expense or settle_up, leaving a meaningful gap for a zero-parameter listing 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?

The tool takes zero parameters, which is the baseline-4 case; there is nothing for the description to disambiguate. The description does not waste space re-explaining schema details and instead spends its words on output semantics.

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 gives a specific verb+resource ("Lists the user's Splitwise friends") and names the payload (overall balance per currency), which clearly separates it from siblings like list_groups, list_expenses, and settle_up. It stops short of the 5 mark because it never distinguishes itself from get_balances, which plausibly overlaps on balance data.

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 is only implied: an agent can infer this is the way to enumerate friends and obtain their balances, but the description never says when to prefer it over get_balances or when friend data is a prerequisite for other calls. No exclusions or alternatives are named, so routing depends on inference from the tool name.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: it discloses that member names accompany each group and, critically, the sign convention for balances (positive = group owes user, negative = user owes group). It omits nothing major for a zero-argument read, though it does not say whether all groups are always returned.

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?

Two sentences, zero waste. The resource and returned fields come first, and the balance-sign interpretation follows because it is the one detail an agent could otherwise misread. No restatement of the name or title.

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 no input schema and no output schema, the description carries the burden of explaining the return shape, and it does so at a useful level: groups, member names, per-user balance, and sign semantics. Only minor gaps remain, such as ordering or whether an empty list is possible.

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 tool takes no parameters, so the baseline is 4; there is no parameter semantics to compensate for. The description correctly spends no words on inputs and instead explains output meaning.

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 ("Lists the user's Splitwise groups") and enumerates the returned content: member names and the user's balance in each group. This implicitly separates it from the singular get_group sibling, though no sibling is named explicitly.

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 is only implied: an agent can infer this is the entry point for enumerating groups before calling get_group or list_expenses. There is no explicit when-to-use, when-not, or pointer to alternatives such as get_balances for aggregate totals.

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

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

Beyond readOnlyHint and openWorldHint, it discloses client-side scanning, newest-first order, the scan_limit bound, and case- and accent-insensitive matching. This makes the potentially incomplete historical coverage and the reason for it visible before invocation.

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?

Two dense sentences front-load the purpose and matching behavior, then explain the non-obvious implementation constraint and its mitigation. The examples and operational details earn their space without 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 seven-parameter read-only search, it covers the essential matching, ordering, scope, and scan-bound behavior while the schema supplies defaults and formats. It would be slightly more complete if it explained how scan_limit exhaustion is represented in results, particularly because there is no output schema.

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?

Despite 100% schema coverage, the description adds substantial meaning: query is an all-words normalized match with examples, scan_limit bounds a newest-first client-side scan, and filters help extend effective historical reach. It adds operational semantics rather than merely repeating schema text.

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?

It specifies the verb, resource, searched fields, and all-word matching rule, clearly distinguishing keyword search from list_expenses and get_expense. The examples make the intended query style concrete.

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?

It explicitly advises narrowing with group, friend, or dates when searching further back, providing actionable guidance for the scan limitation. It does not explicitly route unfiltered browsing or listing needs to list_expenses, so sibling-selection guidance is not exhaustive.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent, open-world write. The description adds real value by clarifying the operation is record-only and does not transfer funds, plus the balance-settling semantics. It stops short of describing what happens if no outstanding balance exists, whether the record is reversible, or how identities are resolved.

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 core purpose, then the key caveat, then the balance-omission rule. No filler or redundancy.

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 7-parameter mutation tool with no output schema, the description covers the essential behavioral nuance (record-only, full-balance settlement) that an agent needs to invoke it correctly. Minor gaps remain around error behavior and multi-currency requirements, which live partly in the schema.

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 86%, so the baseline is 3, but the description goes further by explaining the interaction between omitting 'amount' and the presence of 'group' — meaning that is not expressed in the schema. It does not clarify accepted identifier forms for 'from'/'to' beyond what the schema already says.

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 uses a specific verb and resource ('Records a payment from one person to another') and disambiguates the concept with 'This does not move money; it records that money changed hands.' It does not explicitly name the nearest sibling (create_expense) as a contrasting option, so it falls short of full sibling differentiation.

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?

It gives useful conditional guidance for the amount parameter: omit it to settle the full balance, scoped to a group if supplied, otherwise the overall friend balance. However, there is no guidance on when to choose settle_up versus create_expense or get_balances, and no stated preconditions or exclusions.

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

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

The annotations already declare this as a destructive, idempotent, open-world mutation. The description adds non-obvious behavioral context: partial updates, proportional share rescaling when cost changes alone, redistribution via split, payer changes via paid_by, and the recommended read-before-update flow.

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 short sentences are front-loaded with the core behavior and parameter consequences. Every sentence provides useful guidance without unnecessary repetition.

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 an eight-parameter mutation tool with no output schema, the description covers the key side effects, prerequisite read, and update semantics. It leaves return-value details and some less risky fields to the schema, which is adequate but not exhaustive.

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 high at 88%, so the schema carries most parameter detail. The description still adds meaningful cross-parameter semantics not captured in individual schema fields, especially that changing cost alone rescales shares and that split or paid_by must be used to redistribute or change the payer.

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 states a specific verb and resource: 'Edits an existing expense.' The word 'existing' distinguishes it from create_expense and delete_expense, and 'Only the fields you pass change' clarifies the update scope.

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?

It explicitly tells the agent to 'Read the expense with get_expense first so you can confirm the change with the user,' which is a clear prerequisite. It also explains when to pass split versus paid_by, though it does not state explicit exclusions or when not to use this tool.

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