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 destructiveHint=true and idempotentHint=true; the description adds real value on top by disclosing that an existing receipt is replaced, that no other expense fields are mutated, the failure mode, and the full confirmation/preview/confirmToken flow including the MCP_CONFIRM_MODE behavior. Nothing here contradicts 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?

Front-loaded with purpose and the destructive/replace behavior, then the confirmation mechanics. Four dense sentences with little waste, though the confirmation detail makes it longer than strictly necessary.

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 destructive replace, the failure condition, and the confirm flow well. It stops short of saying what a successful call returns, which is a minor gap given there is no output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all three parameters (including the nested receipt object and confirmToken) are already documented in the schema. The description reinforces 'Pass the file as receipt.base64' but adds no syntax or format detail beyond what the schema 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 and resource ('Attach (or replace) the receipt image or PDF on an existing Splitwise expense') and immediately scopes what is NOT touched ('cost, split and description are not sent'). This clearly separates it from siblings like sw_get_receipt.

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 operating context: pass the file as receipt.base64, and it fails if Splitwise does not store the file. It explains the confirmation requirement and the two-step fallback, but names no explicit alternative tool or a 'do not use when' exclusion beyond the failure note.

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=false, destructiveHint=true and openWorldHint=true, so the bar is lower; the description nonetheless discloses behavioral traits annotations do not capture — that comments are publicly visible to other participants, and that a mandatory human confirmation step gates the write via elicitation or a two-phase confirmToken.

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 core action in sentence one, with the confirmation mechanics confined to a second parenthetical sentence; 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?

For a 3-parameter mutation with annotations covering the safety profile and no output schema, the description covers the non-obvious interactive flow and the social visibility of the side effect. The remaining gap is the absence of any statement about the post-write response.

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 already documents its phase-1 origin and non-reuse rules in detail, so the baseline is 3. The description only reinforces this flow and cross-references MCP_CONFIRM_MODE rather than adding new parameter-level meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Add a comment to a Splitwise expense') and adds the scope qualifier '(visible to other participants)', which implicitly separates it from the read-only sw_get_comments and the destructive sw_delete_comment siblings.

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 explains the invocation protocol (confirm-first, preview/confirmToken fallback, MCP_CONFIRM_MODE) but never states when adding a comment is appropriate versus leaving the expense alone, nor any precondition like participation or expense state.

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 flag readOnly=false, destructive=true, openWorld=true; the description goes well beyond them by disclosing the actual side effects ('puts charges on every participant's balance and notifies them') and the entire two-phase confirmation protocol including the preview/confirmToken fallback and the MCP_CONFIRM_MODE reference. That is exactly the kind of impact disclosure a mutation tool needs.

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?

Single paragraph, front-loaded with the core action before the split mechanics, side effects, and confirmation protocol. The confirmation sentence is long but carries non-redundant information; nearly every clause earns its place, though the paragraph could be split for scanability.

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 tool with nested objects and no output schema, the description covers split logic, receipt attachment, side effects, and the confirmation handshake well. It never states what a successful (non-confirmation) call returns, but everything needed to invoke it correctly is present.

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 interaction-level meaning the schema cannot: the paid_share/owed_share decimal-string convention tied to custom splits, the receipt-in-same-call option, and the fact that confirmToken is only valid on a repeat call after approval. These clarify how parameters combine into a workflow rather than just restating field docs.

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 opening sentence 'Create a Splitwise expense' gives an unambiguous verb+resource, and the split-mode and receipt details make the tool's remit concrete. Sibling differentiation is only implicit (attaching a receipt 'in the same call' implicitly contrasts with sw_attach_receipt, and 'create' contrasts with sw_update_expense), but no sibling is named, 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?

It clearly states the branch conditions for the two split modes ('use split_equally:true ... or provide a users array') and thoroughly explains when each confirmation path applies. It does not route the agent away from any alternative tool by name, so it lacks the explicit exclusions a 5 requires.

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 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?

Annotations cover the read-only/open-world safety profile, and the description adds a genuinely non-obvious behavioral warning: the returned text is third-party and untrusted, so it must be treated as data, not instructions. That is real context beyond the annotations. It still says nothing about paging semantics or result size beyond what the schema carries.

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 purpose before filters and the security note. No filler, though the parameter-usage sentence restates schema information that could have been replaced with genuinely additive guidance.

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 9-parameter list tool with no output schema and no required params, the description is adequate but thin: it does not describe the shape of the result set, ordering, or how offset paging interacts with limit beyond the schema text. The untrusted-data note is the strongest completeness contribution.

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 every parameter including view, limit/offset paging, and the date filters is already documented in the schema. The description repeats group_id and the date-range parameters without adding format or interaction detail, 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 ('List or search Splitwise expenses') and clarifies the scope is a collection with optional filters, which separates it from the singular sw_get_expense without naming it. Clear, but no explicit sibling contrast.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Says all filters are optional and which parameters serve which filtering intent (group_id for groups, dated_after/dated_before for ranges), which hints at usage. It never states when to prefer this over alternatives such as sw_get_expense for a single record, so the routing guidance is only implied.

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?

Annotations already declare destructiveHint=true and a write operation, but the description adds substantial context beyond them: the charges are re-applied to every participant's balance and participants are notified, and it discloses the confirmation-gating protocol (prompt vs. preview + confirmToken fallback). This is exactly the kind of side-effect information an agent needs before invoking an irreversible-feeling mutation.

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 core action, then side effects, then the confirmation mechanics. Three sentences, each carrying useful information, though the final sentence packs two modes (elicitation vs. token fallback) densely.

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 a 2-parameter write tool with no output schema, the description is complete: it covers what is restored, the side effects, and the full confirmation return/retry protocol, including the meaning of the phase-1 response. 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 description coverage is 100%, so both parameters are already documented in the schema, including the detailed confirmToken contract. The description reinforces when a repeat call with the token is valid, but adds little beyond what the schema already states. 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+resource: 'Restore a soft-deleted Splitwise expense.' It is unambiguously distinct from sw_delete_expense and sw_undelete_group, and the agent can identify the exact target object 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 operational context (it is a gated write, requires user confirmation) and details the two confirmation paths, which tells the agent exactly how to sequence calls. It does not explicitly contrast itself with sw_delete_expense as the inverse operation, but the restore semantics make the usage 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?

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 flag destructive and openWorld, but the description adds substantial non-obvious behavior: the full users array replaces the entire split, a receipt-only call replaces any existing receipt, and — critically — the two-phase confirmation protocol with preview and confirmToken that governs whether the mutation actually executes. This is exactly the kind of 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?

Front-loaded with the core action, then ordered by increasing specificity: field editing, split semantics, receipt handling, confirmation flow. Every sentence carries information, though the confirmation sentence is dense and could be split for readability.

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 mutation tool with no output schema, the description covers the risky areas well, including the shape of the confirmation-required response (preview + confirmToken), which substitutes for missing output documentation. It does not address permission requirements or error behavior, leaving a small 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 coverage is only 55%, and the description compensates on the highest-risk parameters: it states that any subset of fields may be changed, that users must be provided in full, that receipt alone is a valid receipt-replacement call, and that confirmToken is only for the fallback path. Lesser parameters (cost, date, category_id, currency_code, description, details) get nothing beyond the thin schema, 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?

Opens with a specific verb+resource: 'Edit an existing Splitwise expense.' An agent can immediately distinguish this from sw_create_expense and sw_delete_expense without inspecting the schema, and the following sentences clarify the fields and special cases (receipt, splits).

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 when-to-use context for the main path and for two special paths (custom split replacement and receipt-only updates), which is real routing guidance. However, it never mentions the sibling sw_attach_receipt, which an agent might reasonably prefer for receipt attachment, so the alternative-selection guidance is incomplete.

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.