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

Beyond the annotations (readOnlyHint=false, destructiveHint=true, openWorldHint=true), the description discloses the two-phase confirmation behavior, the fallback confirmToken flow for clients without elicitation, and that email-based adds send an invite. This is substantive behavioral context the agent could not infer from structured 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?

Three sentences with the core action front-loaded; nothing is wasted. The final confirmation sentence is dense but earns its place by covering a non-obvious protocol.

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 no output schema and 6 parameters, the description covers the mutation semantics, parameter paths, and confirmation protocol adequately. Minor gaps remain around what the returned preview contains and error/permission cases.

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 only 50%, but the description compensates by explaining the mutually exclusive parameter combinations (user_id vs first_name+last_name+email) and their intent, plus the preferred path. This adds meaning beyond the raw schema property names.

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+resource: 'Add a user to a Splitwise group.' It is trivially distinguishable from the sibling sw_remove_user_from_group and routes the agent to sw_list_friends for name resolution, so the agent can identify it without opening a 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?

It clearly states which parameter path to use (user_id preferred, or name+email to invite by email) and names the alternative tool (sw_list_friends) for resolving a name. It lacks an explicit when-not-to-use statement, so it falls just short of 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 flag this as a destructive, idempotent, open-world write, and the description adds genuinely new behavior: it replaces any existing receipt, it does not touch cost/split/description, and it fails if Splitwise won't store the file. The confirmation flow (elicitation vs. preview-plus-confirmToken, MCP_CONFIRM_MODE) is disclosed in detail, though it doesn't say what a successful response contains — acceptable since it also implies a preview object exists.

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?

Front-loaded with the verb and the no-side-effects guarantee, and nearly every clause carries distinct information. The confirmation paragraph is long, but it encodes a non-obvious protocol an agent would otherwise get wrong.

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 nested-object mutation tool with no output schema, the description covers the file source options, replacement semantics, failure mode, and the full confirmation protocol. Nothing an agent needs in order 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; the description goes beyond it by giving the cross-tool sequencing for receipt.upload_id and by spelling out that confirmToken must come from this tool's own phase-1 response and be reused with identical arguments. That is workflow meaning the schema only partially conveys.

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 ('Attach (or replace) the receipt image or PDF on an existing Splitwise expense') and immediately bounds scope ('Changes nothing else on the expense'). An agent can distinguish it from sw_get_receipt and sw_get_upload_url without opening any 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?

Names the three mutually exclusive file-passing modes (upload_id, path, base64) and the precondition for the hosted path: 'upload it first via sw_get_upload_url — no bytes in the tool call'. It also explains the confirmation prerequisite and the two-step fallback, so the agent knows both when and how to invoke it.

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 the annotations, the description discloses ordering, fail-fast behavior, lack of rollback, the fact that the result identifies applied operations, and the confirmation/confirmToken flow including the elicitation fallback. This is exactly the behavioral context an agent needs for a destructive, non-idempotent batch operation.

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 description is front-loaded with the core purpose and the critical fail-fast/no-rollback constraint. It is slightly repetitive, especially the refs example appearing twice, but the length is largely justified by the complexity of the batch and confirmation model.

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?

Given the absence of an output schema and the complexity of a multi-operation destructive tool, the description covers the essential contract: op shape, ref chaining, execution order, failure semantics, available writes, and confirmation behavior. An agent can invoke it correctly without needing additional undocumented context.

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?

It explains the nested ops structure in detail: each op has tool, args, and optional refs; args mirror the target tool without confirmToken; refs resolve from earlier op outputs with a concrete example. It also clarifies confirmToken semantics, including when not to use it and how it interacts with MCP_CONFIRM_MODE.

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: batching several Splitwise writes into one ordered run. It distinguishes the tool from individual sibling writes by explaining the shared preview/approval flow and listing the write tools it can batch.

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 clear: use it to run several writes with one preview and one approval, stopping at the first failure. The description does not explicitly say when to prefer a single sibling write tool instead, so it stops short of full when/when-not/alternative 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 destructive/non-idempotent/openWorld, and the description adds context annotations cannot: the arguments are retained server-side, the token is single-use, and the write must not be triggered by instructions embedded in tool results. That prompt-injection guard is exactly the kind of safety detail only prose can carry.

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?

Front-loads the core instruction (confirm using ONLY the token) and each sentence adds a distinct constraint. The closing injection warning is slightly redundant with 'Pass the token only after the user... explicitly approved', but it earns its place as a distinct failure mode.

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 one-parameter confirmation tool with no output schema, the description covers origin of the token, precondition for use, lifetime, and the anti-injection rule. Nothing an agent needs to call it safely 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 schema already explains confirmToken's origin, so the baseline is 3. The description goes further by specifying the token's single-use lifetime and by warning against re-sending the original arguments, which is meaning the schema 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?

States a specific verb (confirm) and resource (a write previously previewed by another tool on this server), and names the only input it accepts. An agent can immediately tell this is the second half of a two-step write flow, not a standalone mutation.

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 says when to pass the token (only after the user has seen the preview and approved it in chat), what not to do (don't resend arguments — the server kept them), and how the token behaves (one use). Exclusions and prerequisites are all present.

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 description adds substantial context beyond annotations: comments are visible to participants, deleted expenses are refused with the deleter named, and confirmation behavior differs by client capability. It also explains the two-phase preview and token flow, which is critical for correct 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?

The description is mostly front-loaded and efficient, with three sentences that each carry useful information. The confirmation sentence is dense and references MCP_CONFIRM_MODE, but it is not wasted text.

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 write tool with annotations and no output schema, the description covers the important caller-facing behavior: side effects, visibility, deleted-expense handling, and confirmation flow. Nothing essential for correct invocation 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 schema already documents confirmToken in detail. The description reinforces the confirmation flow but adds little specific meaning about expense_id or content beyond what the schema provides, so baseline 3 is appropriate.

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: add a comment to a Splitwise expense. It also clarifies visibility to other participants, which distinguishes it from read/delete comment siblings and makes the effect understandable 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?

It gives an explicit prerequisite for deleted expenses and names the alternative action: restore with sw_undelete_expense first. It also explains the confirmation path, but does not broadly contrast when to use this versus other comment-related siblings beyond that edge case.

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?

Goes well beyond the destructiveHint/openWorldHint annotations: it discloses that this posts charges to every participant's balance and notifies them, that a confirmation prompt or preview+confirmToken two-step guard prevents accidental writes, and what the preview contains (inferred_category, possible_duplicates, including deleted expenses). It also describes the batch-mode return value (expense_id).

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?

Front-loads purpose and split modes, then moves to inference, duplicates, receipts, side effects and confirmation — a logical order. It is a dense single block, though; splitting the confirmation flow and the receipt rules into their own sentences would improve scannability.

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 15-parameter, nested-object, destructive mutation with no output schema, the description covers the side effects, confirmation mechanics, category inference and duplicates that an agent cannot infer elsewhere. The only gap is that it never states what a successful (non-batch) create returns, which an agent may want to know for follow-up calls.

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 schema already documents all 15 params, but the description adds real semantic value: how split/split_equally/users interact, that paid_share/owed_share are decimal strings, the category fallback behavior, and the exactly-one-of upload_id/path/base64 receipt rule. That meaning goes beyond the schema text in the split-mode interplay.

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+resource ("Create a Splitwise expense") and immediately disambiguates the three split modes, so an agent knows exactly what this tool does and how the split variants differ. It is clearly distinct from sw_update_expense/sw_attach_receipt by the create verb and the inline receipt option.

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 states when each split form applies (split_equally when you paid, split:"equal" + paid_by when someone else paid, users for custom shares) and when note/upload_id/path apply for receipts. It also tells the agent to inspect possible_duplicates before confirming. It stops short of naming sibling tools (e.g. sw_update_expense, sw_attach_receipt) as alternatives, keeping 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?

Goes well beyond the annotations by disclosing that an invite email is dispatched (matching openWorldHint), and fully describes the two-path confirmation behavior: a client-side prompt where supported, otherwise a preview-plus-confirmToken round trip per MCP_CONFIRM_MODE. This is exactly the extra context an agent needs before mutating external state.

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 action and its side effect, followed by the confirmation protocol. Dense but each clause carries information; the parenthetical reference to MCP_CONFIRM_MODE is the only slightly compressed fragment.

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 destructive, open-world mutation tool with no output schema, the description covers the essentials: what it creates, that an invite is sent externally, and the exact confirmation contract. An agent has enough to call it correctly on both client types.

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 schema already documents user_email, confirmToken, and the name fields in detail. The description reinforces the confirmToken flow but adds no syntax or format beyond the schema, so the baseline 3 applies.

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 ('Add a Splitwise friend by email') and immediately notes the side effect ('sends them an invite'), which cleanly distinguishes it from siblings like sw_delete_friend and sw_list_friends.

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 clear context for the friend-creation flow and the confirmation requirement, but never names an alternative or states an explicit exclusion (e.g. versus sw_add_user_to_group). Usage is clear, alternatives are left to inference.

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 only declare the generic mutation profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true). The description adds genuinely new behavior not in annotations: the two-phase preview/confirmToken handshake and the MCP_CONFIRM_MODE dependency. It does not say what permissions are required or what happens on cancellation, keeping it out of 5 territory.

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, purpose front-loaded, and the confirmation behavior stated right after. Dense but every clause carries weight; the parenthetical MCP_CONFIRM_MODE reference is a small bit of indirection that costs a little clarity.

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 4-param mutation tool with no output schema and full schema coverage, the description supplies the one thing structured fields cannot: the two-step confirmation protocol. Missing details about side effects or default group state are minor given the schema already documents all inputs.

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%, and the confirmToken parameter is already documented in depth in the schema, so the description's restatement of the token flow adds little parameter-level meaning. Baseline 3 is appropriate; nothing about name, group_type, or simplify_by_default is clarified beyond 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 ('Create a new Splitwise group'), which cleanly separates it from the read/update/delete siblings (sw_get_group, sw_update_user, sw_delete_group). It does not name or contrast with any sibling explicitly, so it stops short of a 5.

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 explicit procedural guidance: confirm first via client prompt when available, otherwise call once for a preview, then repeat with the confirmToken. It covers the 'how/when to invoke' question well but offers no guidance on when to prefer this over alternatives such as adding the user to an existing group.

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=true and readOnlyHint=false, but the description goes well beyond them by disclosing the two-phase confirmation protocol, the preview-plus-confirmToken fallback, its dependency on MCP_CONFIRM_MODE, and the elicitation path. This is exactly the behavioral detail an agent needs to avoid an unintended destructive call.

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?

Front-loads the core action, then the confirmation behavior. Two dense sentences with a long parenthetical, but each clause carries actionable information about the call sequence rather than 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 destructive, single-purpose tool with full schema coverage and no output schema, the description covers the critical unknown: the multi-step confirmation contract, including what phase-1 returns and how to proceed. It omits whether deletion is reversible or how threaded replies are handled, which is a minor gap given the sibling set has no undelete_comment.

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% and the confirmToken parameter is itself documented at length in the schema, so the description adds little parameter-level meaning beyond the baseline. The narrative does contextualize confirmToken's lifecycle, but the mechanics are already in 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 ('Delete a comment by id') that is unambiguous and not confusable with siblings like sw_get_comments or sw_create_comment. The scope is narrow and clearly delimited.

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 clear invocation context: confirm-first flow, when confirmToken applies (client without elicitation), and that the token must come from the phase-1 response. It doesn't discuss alternatives or exclusions, but for a terminal delete operation no alternative routing is needed.

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?

Goes well beyond the destructiveHint/openWorldHint annotations: it discloses that deletion is soft/reversible, gives the response shape ({success: true}), and describes the two-phase confirmation protocol including the preview-plus-confirmToken fallback and the MCP_CONFIRM_MODE switch. That is exactly the operational context an agent needs before a destructive call.

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 sentences, purpose front-loaded, and the confirmation caveat placed after the core action. The trailing 'see MCP_CONFIRM_MODE' reference is a slight density cost but does not bury the key information.

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?

Despite no output schema, the description supplies the return value, reversibility, and the full confirmation lifecycle, which is complete for a destructive two-step tool. Nothing an agent needs to invoke it safely 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 description coverage is 100%, and the schema itself fully documents the careful semantics of confirmToken ('never on the first call, never invented, never reused'). The description reinforces the flow but adds no syntax or meaning beyond the schema, so the baseline 3 applies.

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?

'Soft-delete a Splitwise expense by id' states a specific verb and resource, and 'soft' distinguishes it from a hard delete. It names the sibling sw_undelete_expense, so an agent can route correctly without opening any 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 names the restore alternative (sw_undelete_expense) and lays out the confirmation requirement and when the confirmToken path applies. It does not cover when a caller should prefer update_expense over deleting, but the conditions for this tool are clear.

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 flag destructiveHint=true and openWorldHint=true, and the description goes well beyond them by disclosing the confirmation protocol, the preview/confirmToken fallback, and the MCP_CONFIRM_MODE dependency. An agent understands the destructive action is gated and how the gate works.

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, purpose front-loaded, then the confirmation contract. No filler and no repetition; every clause carries actionable information.

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 destructive, open-world mutation with no output schema, the description covers the safety protocol adequately and the annotations carry the risk profile. It stops short of describing the downstream effects of severing a friendship (e.g. shared expenses, balances), which an agent might want before confirming.

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% and the confirmToken field already spells out its phase-1 origin, first-call prohibition, and elicitation behavior. The description only restates that lifecycle and adds the MCP_CONFIRM_MODE pointer, so it adds little beyond the schema's own documentation.

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 ('Remove') plus resource ('a Splitwise friendship') and the keying parameter ('by user id'), which clearly separates it from siblings like sw_create_friend and sw_list_friends. An agent knows immediately what this does 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?

The description gives explicit operational context for the two calling modes: elicitation-capable clients prompt first, others use a preview + confirmToken round trip. It does not name alternative tools, but no sibling performs friendship removal, so the usage path is unambiguous.

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 only give the generic destructive/open-world profile, while the description adds substantial specifics: that deletion is soft (recoverable), that user confirmation is required, and the exact two-step preview/confirmToken protocol with the rule that the token is never sent on the first call or reused. This is exactly the extra behavioral context annotations cannot convey.

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 with the core action front-loaded and no filler. The confirmation sentence is dense and somewhat convoluted, but every clause carries information the agent needs.

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 usefully describes the phase-1 preview/confirmToken return and the confirmation gating. It stops short of noting that the soft-deleted group can be restored via sw_undelete_group, a relevant detail for this destructive operation, but is otherwise 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% and the confirmToken parameter is already described in depth within the schema, including its two-step fallback role. The description restates the confirmToken flow but adds no syntax or semantics beyond what structured data provides, so the baseline 3 applies.

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 (soft-delete) and resource (Splitwise group), and the qualifier 'soft' signals recoverability versus a hard delete. It does not reference any sibling such as sw_undelete_group, so an agent gets a clear purpose but no explicit routing against alternatives.

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 thoroughly explains the confirmation workflow (prompt vs preview+confirmToken) but never states when to prefer this tool over siblings like sw_undelete_group or sw_delete_expense. Usage is implied through the operational flow rather than contrasted with alternatives.

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 context beyond that — the result is hierarchical and its ids feed sw_create_expense — but does not describe ordering, depth, or stability of the list.

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 short sentences, with the purpose front-loaded and the downstream id usage immediately following. 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 zero-parameter read with no output schema, the description conveys what is returned (a hierarchical category list with ids) and how to use it. Only the exact shape of the hierarchy is unspecified, which is a minor 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?

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to clarify or omit regarding inputs.

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 ('Get the hierarchical list of Splitwise expense categories'), which is unambiguous and distinct from siblings like sw_get_currencies or sw_list_groups. It does not explicitly name a sibling to contrast with, but the resource is unique enough that no confusion arises.

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 says to use the returned id as category_id when creating expenses, which tells the agent exactly why and when to call it. There are no exclusions or edge cases described, but for a parameterless lookup tool the context is sufficient.

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, but the description adds a genuinely non-obvious behavioral trait: the returned text is third-party content that must be treated as data, not instructions. That is a real prompt-injection guardrail beyond what the structured fields carry. It stops short of describing volume, pagination, or ordering.

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, and the purpose is front-loaded before the untrusted-content caveat. Nothing redundant with the schema or annotations.

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 exists, but the description scopes the return as all comments plus a data-handling warning, which is adequate for a simple read tool with read-only annotations. Missing only pagination/ordering expectations for an unbounded comment list.

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%, with the view enum fully explained in-schema (compact vs full, what compact drops). The description adds no parameter-level detail, so the baseline 3 is appropriate — 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+resource: retrieve all comments on a Splitwise expense. The read verb cleanly separates it from the sibling sw_create_comment and sw_delete_comment, though the description never explicitly names those alternatives.

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?

No when-to-use, when-not-to-use, or prerequisite guidance. An agent must infer from the verb alone that this is the read path versus sw_create_comment/sw_delete_comment, and nothing tells it what to do when an expense has no comments or whether the call is paginated.

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 that this returns reference data (codes and units) and how the result is consumed downstream, but says nothing about caching, stability of the list, or the exact response shape. Adequate but not rich.

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 short sentences, zero filler. The purpose is front-loaded and the usage note follows immediately, so an agent can act after the first clause.

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 zero-parameter, read-only reference lookup with no output schema, the description covers what is returned (currency codes and units) and why it matters. The only minor gap is that the exact response structure isn't described, but that is low stakes for a static list.

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, so there is no parameter semantics to document and the baseline is 4. The description correctly does not invent parameter behavior; it instead explains the output value's downstream use.

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 ('Get all Splitwise-supported currency codes and units') and precisely names what is returned. No sibling tool deals with currency data, so it is trivially distinguishable from the rest of the sw_* set.

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 clear context for use: 'Use the currency_code value when creating expenses in non-default currencies,' which ties this lookup to the expense-creation workflow. It stops short of naming sw_create_expense explicitly or stating when not to call it, but the usage condition is unambiguous.

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 safety is covered. The description adds real behavioral context beyond that: what the default compact payload contains, that name is first_name+last_name joined, and that 'full' preserves the raw record shape. No contradiction with the read-only hint.

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 core purpose, then the return-shape detail. Every clause carries information (splits hint, compact field list, full-form rationale), though the em-dash clause is slightly dense.

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 fully describes both possible return shapes and the one optional enum parameter. For a zero-required-param read tool, nothing an agent needs 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 baseline is 3, but the description adds a rationale not in the schema: the 'full' form is what sw_update_user consumes, which tells an agent why to choose it. It largely restates the schema's own explanation of compact vs full, hence not a 5.

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?

Specific verb+resource ('Get the authenticated Splitwise user's profile') that also distinguishes it from the sibling sw_get_user by scope (current/authenticated vs arbitrary user). It names sw_update_user to connect the 'full' output form to a downstream consumer, so an agent can place the tool 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?

Gives concrete downstream guidance ('use the returned id when building custom expense splits') and an explicit condition for choosing view:'full' (that's the form sw_update_user takes). It never states when NOT to use it or when to prefer sw_get_user instead, so it falls short of 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 partly covered. The description does add genuinely useful non-structured context: the response text is third-party authored and must be treated as data rather than instructions. It stops short of stating failure behavior for an unknown id or noting the 'compact' default that quietly drops avatars and reminder/transaction blocks.

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 short sentences, zero filler, and the action is front-loaded before the safety caveat. Every clause carries information.

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-per-required read tool with no output schema, the definition covers identification and the key safety concern. The one gap is that the view parameter's default and its effect on the returned record are left entirely to the schema, and nothing is said about an id that does not exist.

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% and the view enum is documented in the schema in far more detail (what compact drops versus what full returns) than anything in the description. The description adds only 'by id', so the baseline 3 applies.

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 (get a single expense) and pins the scope to one record identified by id, which implicitly separates it from sw_list_expenses, sw_create_expense and sw_update_expense. The only wobble is 'full details' when the default view is actually 'compact', so the stated purpose slightly overshoots the default behavior and no sibling is named outright.

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 implied by 'single expense by id' — an agent can infer this is the lookup-by-identifier path while sw_list_expenses is the discovery path — but there is no explicit when-to-use, when-not-to-use, or prerequisite (e.g. that an id must first come from sw_list_expenses).

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 that the response includes members and balances, which is genuinely useful return-content context, but says nothing about permissions, error behavior for invalid/deleted group IDs, or the fact that 'view' changes response shape (only the schema explains that).

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?

A single front-loaded sentence that names the operation, the resource, the scope ('single'), and the returned payload. Zero wasted words.

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 burden of describing the return and does indicate members and balances. It is largely complete for a read tool whose annotations cover safety, though a note on how 'view' alters the result (already in schema) or behavior for missing groups would round it out.

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%, and the schema already explains both 'id' and the compact/full 'view' tradeoff in detail. The description adds no parameter-level meaning beyond the schema, so the baseline of 3 applies.

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 (Get) and resource (details of a single Splitwise group) and names the payload contents (members and balances). The word 'single' implicitly distinguishes it from sw_list_groups, though it does not name that sibling 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 group's details when you have its ID. There is no explicit when-to-use, when-not-to-use, or routing to alternatives such as sw_list_groups for enumeration or sw_get_user for member data.

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, but the description adds a genuinely important trait those annotations do not convey: the returned text is third-party authored and untrusted, and must be treated as data rather than instructions. It does not disclose how many notifications are returned, ordering, or any pagination/window size for 'recent'.

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 filler, with the purpose stated first and the security caveat immediately after. Every sentence earns its place.

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, single-optional-parameter tool with no output schema, the description covers purpose and the key behavioral risk adequately. It stops short of describing the notification volume/recency window, which an agent might want when deciding whether one call suffices.

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% and the single 'view' enum parameter is fully documented in the schema, including what compact drops. The description adds nothing about parameters, so the baseline 3 applies.

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 (Get) plus resource (Splitwise activity notifications) and scopes it to 'the current user', so an agent knows exactly what it retrieves. No sibling tool covers notifications, so there is no ambiguity to resolve against the rest of the family.

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 wording 'recent' implies a context (checking for new activity) but there is no explicit when-to-use, when-not-to-use, or alternative tool named. Usage is inferable from the name and purpose rather than stated.

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 declare readOnlyHint=false and openWorldHint=true, and the description adds substantial context beyond them: default write destination ($SPLITWISE_OUTPUT_DIR, else ~/Downloads/splitwise-mcp), the conditional write behavior when inline/extract_text is set, the 4194304-byte inline cap, and a clear prompt-injection warning about third-party-authored text. This is rich behavioral disclosure that the annotations alone do not convey.

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?

Front-loaded with purpose and the 401 rationale, then mode semantics, then the untrusted-data warning. It is dense and somewhat long, but nearly every clause carries operational information (paths, size cap, fallback behavior), so little 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?

With no output schema, the description takes on the burden of describing return shapes: bytes for inline, extracted text for extract_text, or a file path on disk. Combined with the credential rationale and the untrusted-text warning, an agent has everything needed to call it 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?

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning, e.g. how write interacts with inline/extract_text and output_dir placement. This clarifies the conditional defaults in a way the per-field schema text alone does not fully surface.

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+resource: 'Download the receipt image or PDF attached to a Splitwise expense.' This clearly distinguishes it from sw_get_expense (which fetches expense metadata/URLs) and sw_attach_receipt (which uploads). An agent can select it without ambiguity.

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 explains why this tool exists rather than fetching the URL directly: the URLs need server credentials and return 401. It then routes the caller between three modes (inline bytes, extract_text for PDFs, or file write) based on capability, which is exactly the when/when-not guidance needed.

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 only declare readOnlyHint and openWorldHint; the description adds substantial context: the URL is short-lived (~10 min), the accepted formats and 10 MiB limit, that the bytes must not go through the tool call, that the original file needs no shrinking, and the hosted-vs-local and shell-vs-base64 fallbacks. That is well beyond what the annotations convey.

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?

Densely packed but front-loaded: the core purpose and the byte-avoidance mechanism come first, then the fallbacks. Nearly every clause carries actionable information, though the run-on construction is slightly heavy.

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 exists, but the description explains the return value's usage (the signed URL/curl command and the upload_id to pass downstream) and all the constraints needed to call it correctly. Nothing essential is missing for a 2-param 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 100% and both parameters are documented in the schema, so the schema carries the load. The description adds only indirect context by showing how the result feeds receipt: {upload_id, filename}; it does not add format or syntax detail beyond the schema, so baseline 3 is appropriate.

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: get a short-lived signed upload URL for a receipt file. It also explains the mechanism (curl, without bytes in a tool call) and names the sibling tools that consume the result (sw_attach_receipt, sw_create_expense, sw_update_expense), so an agent can distinguish it from those siblings immediately.

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 says when to use it (hosted server), when not (locally use receipt.path), and gives a concrete alternative for the no-shell case (receipt.base64). The conditions that select each path are stated, not inferred.

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 safe-read profile is covered. The description adds genuine behavioral context about the compact view merging first_name/last_name into name, which is beyond the annotations, but omits auth requirements, rate limits, or error behavior.

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 core action and then the shape detail. Efficient overall, though the name-merging detail partially duplicates the schema's `view` description.

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 exists, but the description compensates by describing the return shape of both view modes, which is the key thing an agent needs. Auth/permission behavior for reading another user's profile is 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%; both `id` and `view` are fully documented in the schema, including the compact-vs-full field lists. The description's note on the merged name field largely restates what the `view` schema description already says, so it adds little beyond the baseline.

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+resource+scope: 'Get another Splitwise user's profile by id'. The word 'another' immediately distinguishes it from the sibling sw_get_current_user, so an agent can route without opening either 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?

Usage is clearly implied by the 'another user's profile by id' framing, which contrasts with sw_get_current_user, and it references the sibling for shape comparison. However, it never explicitly states when to prefer it over sw_get_current_user or what happens with an invalid/foreign id, so no true exclusion 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 mark this read-only and idempotent, but the description adds valuable behavioral context: it never returns the credential itself, resolves the credential through the same path as real tools, and performs exactly one authenticated request. There is no contradiction with 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?

The description is compact and front-loaded: purpose first, then output details, then the read-only caveat, then the trigger condition. Every sentence earns its place and there is no 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?

Even without an output schema, the description enumerates the returned diagnostic fields (credential source, acceptance, round-trip time, failure hint) and the failure classes it distinguishes. For a zero-parameter healthcheck tool, this is sufficient for an agent to understand and interpret the result.

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 has zero parameters, so the description carries no burden to explain parameter meaning. Per the baseline for zero-parameter tools, this is appropriately handled; the description instead clarifies what the tool reports, which is what matters for invocation.

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 precise diagnostic purpose: resolve credentials the way real tools do, make one authenticated request, and report which hop broke. This clearly distinguishes it from sibling data and mutation tools, so an agent can select it for healthcheck rather than for normal CRUD operations.

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 explicitly tells the agent when to call it: 'Call this when a real tool fails and you want to know which hop broke.' It provides clear context for use, though it does not explicitly say when not to use it or name alternatives.

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?

Goes well beyond readOnlyHint/openWorldHint: it splits which filters run server-side by Splitwise versus which run locally while paging (up to 1000 records per call), states that up to `limit` matches return with a next_cursor, and warns the returned text is third-party and must be treated as data, not instructions. That pagination and prompt-injection disclosure is exactly the behavioral context annotations can't carry.

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 and front-loaded with the core list/search statement first, then paging, then view choice, then the untrusted-data warning last. The long enumerations of parameter names in the server-side/local-filter sentence partially duplicate the schema but earn their place by explaining the execution split.

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 17-parameter tool with no output schema, it covers return shape for view:"rows" (field-by-field), pagination continuation via next_cursor, and the untrusted-content caveat. It leaves the compact/default return shape to the schema rather than describing it, a minor gap given the number of parameters involved.

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 would be 3, but the description adds genuinely new semantics: two distinct filter execution classes (server-side vs local paging filters) and the practical limit on local filtering results (limit = max matches). It does not restate individual parameter formats, which the schema already handles.

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 pair and resource ('List or search Splitwise expenses') and immediately scopes it ('All filters are optional'), so the agent knows this is a bulk/query tool rather than the single-record sw_get_expense. It never names a sibling explicitly, so the differentiation is implied rather than stated.

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 concrete usage conditions: view:"rows" for reconciliation, include_comments:true to see why entries were deleted, and the default that deleted expenses are included unless include_deleted is false. It lacks explicit 'use X instead when...' routing to siblings such as sw_get_expense or sw_get_comments.

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 safety is covered and the bar is lower. The description adds real behavioral detail: the default compact payload's exact field set, the joined name field, and what view:'full' returns. It omits pagination/ordering/rate-limit behavior, keeping it below 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 with the action and routing hint front-loaded, followed by return-shape detail. The second sentence is dense and slightly long, but every clause carries information an agent needs; no 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?

There is no output schema, so the description must carry return-value information, and it does: it enumerates the compact fields and explains the full variant. Combined with the view param being fully specified, this is nearly complete, with only ordering/pagination left unstated.

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 enum param is already documented, so 3 would be the baseline. The description goes further by explaining the practical difference between compact and full ('compact drops fields the response already carries elsewhere') and spelling out the joined-name consequence, adding value beyond 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+resource ('List all Splitwise friends') and immediately distinguishes itself from siblings like sw_get_user / sw_get_current_user by framing the operation as bulk name-to-user_id resolution. An agent can pick this over the per-user getters without opening either 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 names the downstream workflow ('resolve a friend's name to a user_id before adding them to a group or building a custom expense split'), which tells the agent when to reach for it. It stops short of naming an explicit alternative or an exclusion condition, but the context is concrete.

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?

With readOnlyHint and openWorldHint already declaring the safety and scope profile, the description adds useful behavioral value by disclosing the return contents (id, name, members). It does not mention response size or pagination behavior, which the schema touches on for the 'full' view, but the annotation-covered baseline is met.

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 operation and its scope, then return shape, then usage. No filler; every sentence carries distinct information.

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 no output schema and a fully documented parameter, the description covers purpose, scope, and return fields adequately. It stops short of describing ordering, pagination, or how many groups may be returned, which would fully close the loop.

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%, and the single 'view' parameter is richly documented in the schema itself (compact vs full, what gets dropped). The description adds nothing about the parameter, so the baseline 3 is appropriate.

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 ('List all Splitwise groups') plus scope ('the current user belongs to'), which cleanly separates it from sw_get_group (single group) and sw_create_group. An agent can identify the operation 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?

Gives concrete usage context: 'Use this to resolve a group name to its id.' That is a clear when-to-use statement, but it does not name alternatives such as sw_get_group or note any exclusions, so it falls short of the explicit alternative-routing that earns 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 flag destructive=true, readOnly=false, but the description goes well beyond them: it discloses the two-step confirmation fallback, the existence of a preview response, the confirmToken contract (never on the first call, never invented, never reused), and the MCP_CONFIRM_MODE reference. This is exactly the behavioral detail an agent needs before performing a destructive operation.

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?

Purpose is front-loaded in the first sentence and the confirmation protocol follows compactly with no filler. The second sentence is dense but every clause (client support, preview, token, repeat call) carries distinct information.

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 destructive tool with no output schema, the description covers the most important unknown: what the agent sees before the removal actually happens and what it must do to proceed. It does not cover permission requirements, failure behavior on a bad token, or side effects on group balances, leaving minor gaps.

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% and the confirmToken property description already spells out its usage rules, so the description mainly restates the same protocol at a higher level and points to MCP_CONFIRM_MODE. No new syntax or format detail is added beyond 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 (remove a user from a Splitwise group) with the object of the mutation named precisely. It is trivially distinguishable from the sibling sw_add_user_to_group and from group-level tools like sw_delete_group.

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 clear procedural context for invocation: a confirmation prompt is used when the client supports it, otherwise phase 1 returns a preview plus confirmToken and phase 2 repeats the call. It does not explicitly compare against sibling tools or state prerequisites such as who may remove members, so it stops short of the top score.

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?

Goes well beyond the annotations: it discloses the re-read/verification step, the failure mode (still-deleted raises an error naming who deleted it and when), the side effects (charges reapplied to every participant's balance and notifications sent), and the confirmation gating with its MCP_CONFIRM_MODE fallback. This is exactly the destructive-write 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?

Front-loads the action and return shape, then side effects, then confirmation mechanics – a sensible ordering. It is dense and runs long, but nearly every clause carries decision-relevant information; only the confirmation sentence overlaps with the schema's confirmToken description.

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 exists, yet the description defines the return payload (post_state fields), the error condition, and the confirmation protocol. An agent can invoke this correctly without consulting anything else.

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, but the description adds tool-level meaning by explaining that confirmToken comes from phase-1 and that a repeat call with identical arguments is what proceeds. That contextualizes the token's lifecycle slightly beyond the schema's own wording.

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+resource ('Restore a soft-deleted Splitwise expense') and immediately distinguishes itself from the destructive sibling by scope ('soft-deleted'). It also names the observable outcome (post_state with deleted_at/deleted_by), so the agent knows exactly what it gets back.

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 conditions for use: only for soft-deleted expenses, and only via the confirmation flow (client prompt or two-step preview+confirmToken). It does not explicitly name sw_delete_expense as the inverse or spell out when not to restore, but the context is unambiguous.

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?

Goes well beyond annotations by disclosing concrete side effects: charges return to every participant's balance and participants get notified. It also describes the full confirmation flow (preview + confirmToken, or elicitation), which is exactly the operational context an agent needs for a destructive write.

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?

Front-loads the purpose, follows with side effects, then the confirmation protocol. Three dense sentences with no redundancy; the confirmation-token detail earns its place because it changes how the agent must call the tool.

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?

A destructive mutation tool with no output schema, yet the description covers side effects, notification behavior, and the two-step fallback protocol. Nothing material to correct invocation 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 description coverage is 100%, so both 'id' and 'confirmToken' are already fully documented in the schema; the description adds no new per-parameter syntax. Baseline 3 applies since 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 ('Restore') and resource ('soft-deleted Splitwise group'), making it immediately distinguishable from sibling sw_delete_group. An agent can tell exactly what happens 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?

Explains the applicability condition (soft-deleted groups) and the gating/confirmation requirement that governs when the call will actually proceed. It does not explicitly name sibling alternatives, but the usage context is clear and actionable.

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 and openWorldHint, but the description goes further and discloses the confirmation protocol: an elicitation prompt where supported, otherwise a preview phase returning a confirmToken that must be echoed on a repeat call. It also warns that the API replaces the entire split and replaces any existing receipt — exactly the destructive semantics an agent must know 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 sentences, each carrying distinct operational information, with the destructive confirmation detail placed last where a reader will still reach it. The trailing reference to MCP_CONFIRM_MODE is a bit of an unexplained dangling pointer, a minor structural blemish.

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 11-parameter destructive mutation with nested objects and no output schema, the description covers what matters: what gets replaced, how to target sub-updates (split vs receipt), and the full confirmation handshake including the confirmToken lifecycle. An agent has everything needed to call it correctly without guessing.

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 55%, and the description compensates for the important gaps: it explains the all-or-nothing semantics of the users array, the mutual-exclusion pattern for receipt-only updates, and precisely how confirmToken must be obtained and reused. Trivial params like date, details and category_id get no extra prose, which is fine, but date format and validation remain undocumented in both places.

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+resource pair ('Edit an existing Splitwise expense') and immediately distinguishes itself from the create path by requiring expense_id. An agent can tell this is the mutation-on-existing-record tool in the expense family 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?

Gives concrete conditional guidance: pass expense_id plus changed fields normally, send a full users array for custom splits, and pass expense_id with receipt alone to attach or replace a receipt. It does not name the sibling sw_attach_receipt or say when to prefer it over the receipt-only mode here, 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?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=true, openWorldHint=true) by disclosing the confirmation protocol: an elicitation prompt where supported, otherwise a two-phase preview-plus-confirmToken flow referenced to MCP_CONFIRM_MODE. It also pre-empts an agent error by ruling out credential 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?

Three sentences, purpose front-loaded, then the field exclusion, then the confirmation protocol. Dense but every clause carries actionable information; the parenthetical '(see MCP_CONFIRM_MODE)' is the only loose reference.

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 6-parameter mutation tool with no output schema and 33% schema coverage, the description covers the highest-risk dimensions: confirmation flow, id constraint, and forbidden fields. Remaining gap is value format semantics for locale and default_currency, which neither the schema nor description supplies.

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 only 33% (locale, first_name, last_name, default_currency are undocumented). The description partially compensates by naming the settable concepts ('name, locale and default currency') and explaining confirmToken's origin elsewhere, but it does not map 'name' to first_name/last_name or give any format guidance for locale or currency.

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 ('Update the current user's profile fields') and enumerates the settable fields (name, locale, default currency). An agent can distinguish it immediately from the read siblings sw_get_user / sw_get_current_user, and the 'current user only' constraint is explicit.

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 clear usage context: only the current user's id is valid, and email/password cannot be changed here because credentials live in the Splitwise app. It does not name a sibling alternative or state when to prefer this over, say, leaving profile data alone, but the scope boundaries are unambiguous.

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