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

Annotations only give generic hints (readOnlyHint=false, openWorldHint=true, idempotentHint=false), but the description goes well beyond: it discloses the SPLITWISE_ALLOW_WRITES=1 auth gate, local oneOf validation before any call, the fact that HTTP 200 can still mean failure and how success is determined, the 403 case, and the undo tool with the returned user id. This is exemplary behavioral disclosure for a 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?

Sections are clearly headed and front-loaded (what it does, endpoint, then when/when-not, returns, examples, errors). The length is justified by genuinely distinct information — auth gate, error semantics, undo path — with 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?

Despite already having an output schema, the description still summarizes the return shape ('First Last (id N)' plus success value), and covers auth, validation, failure, and reversal. For a write tool with this complexity, 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?

Although the top-level params object carries no schema description (0% coverage signal), the description fully compensates by explaining the oneOf identity semantics (user_id OR first_name+last_name+email), that both-or-neither is rejected, and giving concrete param examples. It adds meaning the schema's per-field descriptions do not capture (the combination constraint).

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 ('add a person') and resource ('to a group') plus the two identity modes (existing user id vs. name+email invite). It explicitly names siblings it is not (splitwise_create_group, splitwise_resolve_friend, splitwise_resolve_group), so an agent can distinguish it without opening other schemas.

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?

Has explicit 'When to Use' / 'When NOT to Use' sections naming concrete alternatives and the prerequisite resolve steps for finding ids. The conditions that select this tool versus others are spelled out, 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?

Goes well beyond the annotations: discloses the SPLITWISE_ALLOW_WRITES=1 gate, comment visibility ('everyone on the expense can see the comment'), non-idempotency with an explicit duplicate-post warning, 404/403 meanings, an UNKNOWN-outcome protocol for timeouts/5xx, and the undo path. The annotations (readOnlyHint=false, idempotentHint=false) are confirmed and enriched rather than merely restated.

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 write-gate and non-idempotency warnings are front-loaded in the first two paragraphs, then sectioned into When to Use / Returns / Examples / Error Handling. Dense but every block carries actionable information, and the labeled structure makes it skimmable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutating, non-idempotent, auth-gated tool this covers the failure modes an agent needs: write gating, visibility scope, duplicate-post hazard, status-code meanings, unknown-outcome recovery, and undo. An output schema exists, so the brief Returns line is a courtesy rather than a 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 reported at 0%, so the description must carry the load; it names both `expense_id` and `content`, notes content must be non-blank plain text, and supplies a literal params example showing shape and types. It stops short of explaining id format constraints or the max comment length, so it compensates well but not exhaustively.

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 immediately distinguishes itself from siblings by naming splitwise_update_expense and splitwise_get_comments as the tools for adjacent jobs. 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?

Provides explicit 'When to Use' and 'When NOT to Use' sections with concrete triggers ('leave a note on an expense') and named alternatives for the two nearest confusable operations. Nothing about tool selection is 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 already declare readOnly=false, idempotent=false, destructive=false, and openWorld=true. The description goes well beyond those by disclosing the SPLITWISE_ALLOW_WRITES=1 gate, local pre-send validation, non-idempotency and the warning never to retry blindly after a timeout, the fact that Splitwise returns HTTP 200 even on rejection, unknown outcome on timeout/5xx, and read-back guidance. These are exactly the behavioral traits annotations cannot express.

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?

It is front-loaded with the core purpose and critical constraints, then cleanly organized into split-mode definitions, When to Use / When NOT to Use, Returns, Examples, and Error Handling. It is nevertheless verbose: the Returns section duplicates information likely available in the output schema, and lines about the REST endpoint and flattened payload formatting are not strictly necessary for an agent invoking 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?

Given the tool's complexity (three split modes, write gating, non-idempotency, timeout ambiguity) and the available annotations and output schema, the description is complete. It covers prerequisites, sibling alternatives, concrete parameter examples, and failure modes, leaving no material gap 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?

The description explains the three mutually exclusive split modes (A, B, C), identity requirements (user_id or email+first_name+last_name), the requirement that sum paid_share and sum owed_share each equal cost, the mode C rounding rule with a worked example, and the 2-decimal money-string format. This adds mode-selection semantics and validation rules that go beyond the nested schema's per-field descriptions.

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

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

The description opens with a specific verb and resource ('Create an expense') and immediately states the critical constraint of exactly one split mode. It names sibling alternatives for update, deletion, id resolution, and commenting, so an agent can distinguish it from every neighboring tool without opening other schemas.

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 contains explicit 'When to Use' scenarios and a 'When NOT to Use' section with named alternatives: update_expense, resolve_friend, resolve_group, resolve_category, and create_comment. This leaves no inference required about when this tool is the right selection.

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 safety profile; the description goes far beyond, disclosing the SPLITWISE_ALLOW_WRITES=1 gate and its exact refusal message, conditional first-name handling for invited users, the likely invitation e-mail side effect, the absence of any undo, and that a 5xx/timeout leaves the outcome UNKNOWN requiring a get_friends check before retry. That is precisely the behavioral context annotations cannot 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?

Well front-loaded: the action and the write gate appear in the first two lines, followed by clean headed sections. A few sentences carry internal-tooling noise ('the live smoke t10 confirms') that dilutes the signal, but nothing is padding in the harmful sense.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutating, non-idempotent, open-world tool this covers the full call path: config prerequisite, conditional parameter semantics, side effects, return shape, error taxonomy, and retry safety. An output schema exists, yet the 'Returns' section still adds useful confirmation format detail.

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 reported at 0% (only the nested object carries field descriptions), so the description must compensate — and it does, explaining that names are ignored for existing accounts, that user_first_name becomes required when no account exists, and providing concrete param examples for both cases. Slightly redundant with the schema's own field descriptions, so not a full 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?

States a specific verb and resource ('Add one person as a Splitwise friend by e-mail') and immediately names the underlying operation (`POST /create_friend`). It is unambiguously distinguishable from siblings like splitwise_create_friends and splitwise_add_user_to_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?

Explicit 'When to Use' and 'When NOT to Use' sections route the agent to four named alternatives (splitwise_create_friends, splitwise_add_user_to_group, splitwise_get_friends, splitwise_resolve_friend), each with the condition that selects it. This is exemplary routing 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?

Goes well past the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false): it discloses the SPLITWISE_ALLOW_WRITES=1 write gate and the exact refusal message, warns that Splitwise returns HTTP 200 even on rejection so success must be read from body `errors`, notes there is no undo tool, states duplicate e-mails are rejected locally before any call, and flags that a 5xx/timeout leaves the outcome UNKNOWN. None of this is derivable 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?

Front-loaded with the purpose and the write-gate warning, then cleanly partitioned into When to Use / When NOT to Use / Returns / Examples / Error Handling. It is longer than strictly necessary — the Returns section duplicates information the output schema already carries — but each block is scannable and earns most of its space.

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 non-idempotent, open-world write tool with an output schema present, the description covers everything an agent needs: auth prerequisite, the deceptive 200-on-error behavior, partial-success read-back procedure via splitwise_get_friends, unknown-outcome semantics on transport failure, and no-undo recovery via splitwise_delete_friend.

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?

Reported schema description coverage is 0%, so the description must carry parameter meaning, and it does: it explains the flattening to users__{i}__email/first_name/last_name with 0-based indexing, clarifies that names matter only for people without an account, and supplies a concrete two-element params example. Minor gap: it does not restate the 1-50 item bound or the e-mail format constraint that live 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+resource+scope: 'Add several people as Splitwise friends in one call,' where 'several' and 'in one call' signal the bulk nature. It explicitly contrasts with the single-person sibling ('For a single person (use splitwise_create_friend)'), so an agent can route between them 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?

Contains dedicated 'When to Use' and 'When NOT to Use' sections naming concrete alternatives (splitwise_create_friend, splitwise_create_group, splitwise_add_user_to_group) with the condition that selects each. This is the textbook routing guidance an agent needs.

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 safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=true), and the description goes well beyond them: the SPLITWISE_ALLOW_WRITES=1 write gate and its exact refusal message, the local pre-call identity validation, the undo path via splitwise_delete_group, and the requested-vs-returned member count that surfaces silently dropped invites.

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 and structured under clear headings (When to Use, When NOT to Use, Returns, Examples, Error Handling), with two worked examples. It is longer than strictly necessary, but nearly every line adds operational value rather than restating structured data.

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 real prerequisites, the definition covers gating, validation, undo, error surfacing, and examples. An output schema exists, so the brief 'Returns' note is sufficient and the description need not detail the response shape further.

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 reported at 0%, so the description carries the burden and does so thoroughly: it documents the body serialization (users__{i}__user_id / email / first_name / last_name), the either/or identity rule per member, and the group_type values. This meaningfully exceeds what the raw schema exposes.

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 group') and immediately notes the auto-inclusion of the caller. The 'When NOT to Use' block names the exact sibling tools for adjacent operations, so the agent can distinguish this from splitwise_add_user_to_group, splitwise_undelete_group, and splitwise_resolve_friend 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?

Explicit 'When to Use' (new shared-expenses group: trip, flat, couple) and 'When NOT to Use' with a named alternative per exclusion case. This is the full when/when-not/alternatives pattern.

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 the write gate (SPLITWISE_ALLOW_WRITES=1), the underlying endpoint, the absence of any undelete in the Splitwise API, and the recovery path (re-post with splitwise_create_comment, new id/timestamp). It also maps 404 and 403 to concrete causes, which the destructiveHint/idempotentHint 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 operation and its destructive nature, then cleanly sectioned into usage, returns, examples, and errors. It is longer than strictly necessary, and the 'Returns' block largely restates what the output schema already declares, but no section is 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?

Covers everything an agent needs to invoke this correctly: the required id and where to get it, the environment gate that will refuse the call, what the confirmation contains, and how each error class should be interpreted. The presence of an output schema makes the Returns section a bonus rather than a 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?

Only one parameter, and the schema already describes comment_id and its source. The description reinforces the id's provenance ('get its id from splitwise_get_comments') and supplies a literal example payload, adding modest but real value over the schema alone.

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 from a Splitwise expense') and immediately scopes it against siblings by naming splitwise_delete_expense and splitwise_create_comment as different operations. An agent can distinguish this from every other delete tool in the family 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?

Has explicit 'When to Use' and 'When NOT to Use' sections, names the sibling to use instead for each excluded case (splitwise_delete_expense for the expense itself, splitwise_get_comments when only the text is known), and routes the agent to the prerequisite call that supplies the required id.

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

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

Annotations declare destructive/idempotent/openWorld, and the description adds value beyond them: the delete is a recoverable soft delete, it requires SPLITWISE_ALLOW_WRITES=1 or the server refuses, it mutates every participant's balances, and refusal arrives as HTTP 200 with success:false. This is exactly the extra behavioral context the 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?

The header-based layout is front-loaded and scannable, and each section (endpoint, gating, usage, returns, example, errors) earns its place. The undo/restore instruction is stated twice (opening parenthetical and later), which is mild 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?

Despite an output schema existing, the definition covers everything an agent needs: write gating, blast radius on balances, the undo path, the id source, and the error decoding for 200/403/404 responses. Nothing material is missing for a destructive one-parameter call.

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

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

Only one nested parameter and the schema names it with a hint about its origin, but reported coverage is 0%, so the description compensates with a concrete example ({"expense_id": 3456789012}) and ties 404/403 error meanings to the id. It stops short of explaining any format constraint, but with a single required integer that is a minor gap.

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 an expense') plus the crucial soft-delete semantics, and explicitly distinguishes itself from splitwise_update_expense, splitwise_delete_group, and splitwise_undelete_expense. An agent can identify this tool among 32 siblings 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?

Provides explicit 'When to Use' (duplicate or mistaken expense) and 'When NOT to Use' sections that name the correct alternative tool for each excluded case (update for amount/split fixes, delete_group for whole-group removal). Nothing is 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?

Beyond the annotations (destructiveHint=true, idempotentHint=true), the description discloses the write gate (SPLITWISE_ALLOW_WRITES=1), the underlying endpoint, the critical quirk that Splitwise returns HTTP 200 even when it refuses so success must be read from the body, that there is no undelete, and how 404 should be interpreted. This is exactly the extra context annotations cannot 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?

Sections are clearly labeled and front-loaded with the destructive/write-gate warning first, which is the right priority. It is longer than strictly necessary — the Examples block largely restates the schema's own example — but no section is 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, gated, non-idempotent-in-practice mutation, the description covers preconditions, failure modes, refusal handling, and recovery (re-add via splitwise_create_friend). Return values are also summarized even though an output schema exists, so nothing an agent needs to call this 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 reported as 0%, though the single friend_id property does carry an inline description. The description reinforces that the parameter is the friend's user id, supplies a concrete example ({"friend_id": 4821}), and adds error semantics tied to the id (404 means the id is not a friend). With only one parameter this is close to fully covered, but it stops short of adding format constraints 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?

The opening line states a specific verb and resource ('Remove a friendship (unfriend a user)'), and the surrounding text makes clear it operates on the friend relationship rather than group membership. An agent can distinguish it from splitwise_remove_user_from_group and splitwise_create_friend 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?

Explicit 'When to Use' and 'When NOT to Use' sections name the exact alternatives for adjacent intents: splitwise_remove_user_from_group for group removal, splitwise_create_expense for settling balances, and splitwise_resolve_friend / splitwise_get_friend when the id is uncertain. Routing conditions are fully specified.

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 and readOnlyHint=false, but the description adds substantial context beyond them: exactly what gets destroyed (every member's expenses), a write-permission gate (SPLITWISE_ALLOW_WRITES=1), a specific undo path (splitwise_undelete_group), and error semantics including the tricky HTTP 200 + success:false case, 403, and 404.

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 destructive scope, then organized under clear headers (When to Use, When NOT to Use, Returns, Examples, Error Handling). Every section earns its place; nothing is padded.

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, the description covers blast radius, permission gating, undo, error mapping, and parameter prerequisites. An output schema exists, so the Returns section is slightly redundant but harmless, and nothing an agent needs to invoke this 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?

Only one parameter, and the schema already describes group_id. The description still adds value by giving a concrete example ({"group_id": 12345}) and warning not to pass a group name, directing the agent to splitwise_resolve_group first.

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 (delete) and resource (group), plus the blast radius ('all its expenses — for every member, not just you'), which immediately separates it from splitwise_remove_user_from_group and splitwise_delete_expense. The endpoint POST /delete_group/{id} is named explicitly.

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

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

Has dedicated 'When to Use' and 'When NOT to Use' sections that name the exact alternatives: splitwise_remove_user_from_group for leaving, splitwise_delete_expense for single expenses, splitwise_resolve_group for name resolution. Prerequisites (confirm id with splitwise_get_group, preview with splitwise_get_expenses) are called out.

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 readOnly/idempotent/non-destructive/openWorld, and the description adds substantial behavior beyond them: the underlying call (GET /get_friends), the sign convention that positive means owed-to-you, that the currency filter is applied locally because the endpoint takes no filter, that malformed amounts are shown raw, flagged, and excluded from totals, and the 401/429/Retry-After error semantics.

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 a one-line summary and cleanly sectioned (When to Use / When NOT / Returns / Examples / Error Handling), so navigation is fast. However, the Returns section is long and partly restates what an existing output schema already conveys, so a little trimming is possible.

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 tool with annotations, an output schema, and only one nested params object, the description covers everything an agent needs: scope, alternatives, filtering semantics, output shape for both formats, the 50-row cap, and failure modes. Nothing material 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?

Although the top-level 'params' object has no schema description (0% coverage per the signal), the description carries the parameters: it explains include_zero's effect (zero balances hidden unless true), the currency filter being a 3-letter local filter that is rejected before any call, and what response_format switches between, plus three concrete parameter examples.

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 states a specific verb and resource ('Summarise who owes you and whom you owe, per friend and per currency') and the When NOT to Use block explicitly routes to splitwise_get_group_balances for single-group balances. An agent can distinguish it from every sibling 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?

Explicit 'When to Use' triggers ('who owes me money', before settling up) and an explicit 'When NOT to Use' list naming the three alternative siblings (splitwise_get_group_balances, splitwise_get_friends/get_friend, splitwise_resolve_friend) with the condition that selects each. Nothing is 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 already declare read-only, idempotent, open-world and non-destructive, but the description adds substantial behavior beyond them: a 24 h in-process cache with refresh override, the rule that failed fetches are never cached and a failed refresh retains the prior list, locale-dependent names with globally stable ids, and a 401 meaning an invalid/regenerated key. This is exactly the extra context annotations cannot 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?

Long but front-loaded and sectioned (behavior, When to Use, When NOT to Use, Returns, Examples, Error Handling). Every block carries distinct, non-redundant information – caching rules, subcategory-id constraint, locale caveat, call examples – so no sentence is 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?

The tool's output shape is spelled out (markdown table vs raw JSON with icons and nested subcategories) even though an output schema exists, the caching/auth failure modes are covered, and the subcategory-id requirement closes the main misuse risk. Nothing an agent needs to invoke this 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?

The schema already documents parent (substring/numeric id match), refresh (bypass cache) and response_format (markdown vs json), so the description's marginal value is mostly on refresh cache semantics, the empty-parent-match fallback, and the 50-parent cap. It reinforces but rarely surpasses the schema text for the individual parameters.

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 ('List Splitwise's expense categories: each parent with its subcategories and their ids') and immediately distinguishes itself from splitwise_resolve_category and splitwise_get_currencies by name. An agent knows exactly what this tool returns and what it is not for 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?

Explicit 'When to Use' / 'When NOT to Use' sections with named alternatives: name-to-id lookup goes to splitwise_resolve_category, currencies go to splitwise_get_currencies. It even states the prerequisite workflow (browse categories before creating/recategorising an expense).

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 readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: the System vs User comment-type semantics, truncation behavior (50 rows, 2,000 chars, with counts of what was cut), and error semantics (404 = nonexistent/deleted expense, 403 = not a member, errors returned as strings never raised).

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 a one-line purpose, then clearly sectioned into When to Use / When NOT / Returns / Examples / Error Handling. Every section earns its place, though the Returns paragraph restates part of what the output schema already carries, making it slightly 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 read-only list tool with an output schema, the description closes the remaining gaps an agent would hit: authorization failure modes, the meaning of each comment type, and the truncation limits on the rendered output. Nothing needed to call it correctly is missing.

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

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

Schema descriptions exist for both fields, but the description adds meaning: it explains that response_format chooses between a rendered table and raw comment objects, and provides two concrete worked payloads for expense_id. It stops short of describing any constraint on expense_id beyond what the schema already says.

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

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

States a specific verb and resource ('List the comments on one Splitwise expense') and immediately disambiguates from siblings like splitwise_get_expense and splitwise_get_notifications. The agent can distinguish this from every other get_* tool 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?

Explicit 'When to Use' (read discussion/edit history, find a comment id before splitwise_delete_comment) and 'When NOT to Use' sections that name three concrete alternative tools and the condition that selects each. This is exactly the routing guidance an agent needs.

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?

Despite readOnlyHint/idempotentHint already covering safety, the description adds substantial behavior: a 24 h in-process cache, refresh semantics, the 50-row cap, 401 meaning a missing/regenerated key, and the fact that failed fetches are never cached and empty results are messaged rather than silently empty.

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 and organized under clear headers; the examples are concrete and useful. It is on the long side, and the Returns block partially restates what the output schema already carries, but no section is padding.

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?

Covers caching, refresh, filtering, output shape (including the row cap), auth failure mode, and no-match behavior — everything an agent needs to call this correctly and interpret the result, even with a nested params object and no per-parameter coverage in the 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?

Schema description coverage is reported as 0%, so the description must compensate, and it does: it explains that query is a case-insensitive substring match over code or unit (with a symbol example), that refresh bypasses the 24 h cache, and that response_format selects table vs raw objects.

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 states a specific verb and resource: listing currency codes accepted by Splitwise. It also distinguishes itself from siblings by explicitly naming splitwise_get_balances and splitwise_get_categories as the tools for other per-currency/category needs.

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?

Explicit 'When to Use' and 'When NOT to Use' sections give concrete scenarios (validating a currency_code before an expense, resolving a symbol like "€") and name the alternative tools for out-of-scope needs. Nothing is 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 already declare readOnly/idempotent/openWorld, so only additive context is needed, and the description delivers: 401 means the API key is missing/mistyped/regenerated (with the URL to fix it), every failure returns an `Error ...` string, and the markdown rendering is shaped as `First Last (id N)` specifically so the id can be chained into other tools. This is genuinely useful behavior an agent cannot get from the annotations or schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Well front-loaded and clearly sectioned (When to Use, When NOT to Use, Returns, Examples, Error Handling), so an agent can scan it. However, the field enumeration in the opening paragraph largely repeats the fuller enumeration in Returns, which is mild redundancy in an otherwise efficient layout.

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 an output schema exists, the description already exceeds the bar by documenting return shapes and error semantics. Combined with explicit routing to siblings, examples, and auth failure behavior, an agent has everything needed to select and call this tool correctly.

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

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

The single `response_format` parameter is given concrete invocation examples (`params = {}` and `params = {"response_format": "json"}`), and the Returns section explains what each mode produces, which goes beyond the bare schema description. It does not add much more than the schema already states about the enum, so 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?

States a specific verb and resource ('Get the Splitwise user the API key belongs to') and enumerates the returned fields (name, id, email, currency, locale, notifications). It also implicitly distinguishes itself from `splitwise_get_user` by scoping to the API key's owner, which the When NOT to Use section makes 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?

Provides explicit When to Use and When NOT to Use lists, each naming the concrete alternative for the excluded case (`splitwise_health_check` for key state, `splitwise_get_user` / `splitwise_resolve_friend` for other people, `splitwise_get_balances` / `splitwise_get_friends` for balances, `splitwise_update_user` for edits). Nothing is 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 already declare readOnlyHint/idempotentHint/destructiveHint=false, so the safety profile is covered. The description goes well beyond that by disclosing the sign convention (Net = paid − owed), the fact that a deleted expense remains readable and is flagged, the concrete return shape (shares table, From → To repayments, comments), and status-code semantics (404 wrong id, 403 not a participant, 401 key problem).

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?

Headers (When to Use / When NOT to Use / Returns / Examples / Error Handling) make it scannable and the purpose is front-loaded in the first sentence. It is on the long side and the 'Returns' block partially duplicates the existing output schema, but nothing is truly 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?

For a single-parameter read tool this is complete: purpose, routing, output shape, examples and error mapping are all present. An agent has everything needed to call it correctly and interpret common failure modes without further inference.

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?

Top-level schema description coverage is reported at 0%, so the description must compensate, and it does: it clarifies expense_id provenance ('from splitwise_get_expenses'), contrasts markdown vs raw JSON, and supplies two concrete param examples. It stops short of documenting edge cases like id format or the exclusiveMinimum constraint, so not a full 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?

The opening line states a specific verb and resource ('Read one expense in full') and enumerates the scope: cost, group, category, shares, repayments, comments. It is immediately distinguishable from splitwise_get_expenses (list/search) and splitwise_get_comments (thread only), which are named explicitly.

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

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

Provides explicit 'When to Use' triggers (pre-update inspection, 'who paid for dinner', post-create verification) and a 'When NOT to Use' block that routes to splitwise_get_expenses, splitwise_get_comments and splitwise_get_balances. This is the strongest possible form of routing 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 read-only, idempotent, non-destructive and open-world, and the description adds genuinely non-obvious behavior: deleted expenses are returned but hidden and counted, tagged '[deleted]' / '[settle-up]', the net-balance sign convention, refusal when group_id and friend_id are both passed, and 401/403/429 handling with Retry-After.

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 core purpose and well-organized with headings, but the Returns section substantially duplicates the output schema and the Pagination paragraph restates the schema's limit default, making 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?

Covers filtering, pagination, response formats, mutual exclusion, tags and error codes; since an output schema exists, the return-format detail is a bonus rather than a gap. An agent has everything needed to call this 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?

Adds meaning well beyond the schema: the sign convention for current_user_id's 'Your net' column, that deleted rows still consume the offset, that markdown caps at 50 rows, and that group_id/friend_id are mutually exclusive and refused. This is interpretive information the schema alone cannot 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?

Opens with a specific verb, resource, ordering and filter scope: 'List expenses, newest first, optionally filtered by group, friend and date range.' Combined with the When NOT to Use section that names splitwise_get_expense, splitwise_get_balances and splitwise_get_group_balances, an agent can distinguish this from every sibling 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?

Gives explicit positive cases (cost per group, expenses with a friend, finding an id before update/delete, date-window review) and negative cases with named alternatives for each. Nothing about when to choose this tool is 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 already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond them: the sign convention (positive = they owe you), the markdown-vs-json output shape, and the 404/401 error meanings. It stops short of describing pagination or rate-limit behavior, but for a single-entity read that is a minor omission.

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 purpose and sign convention before the routing guidance, and each section (usage, returns, examples, errors) earns its place. It is somewhat long for a one-parameter read tool, with mild redundancy between the 'Returns' section and the response_format explanation.

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?

Covers routing, endpoint, rendering format, sign convention, examples, and error codes for a tool whose annotations already establish the safety profile and whose output schema exists. An agent has everything needed to select and invoke 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?

Reported schema coverage is 0%, so the description must carry the load, and it does: it shows the id flows into GET /get_friend/{id}, gives a concrete example value (4821), and explains that response_format='json' returns the raw friend object versus markdown for a readable summary. It lacks detail on valid id ranges or failure modes per format, hence a 4 rather than 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?

States a specific verb and resource ('Get one Splitwise friend') and immediately scopes the payload to overall and per-group balances. It is unmistakably distinct from splitwise_get_friends, splitwise_resolve_friend, and splitwise_get_user, all of which it names.

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?

Provides explicit 'When to Use' and 'When NOT to Use' sections with three named alternatives (splitwise_get_friends, splitwise_resolve_friend, splitwise_get_user) each paired with the condition that selects them. No inference is required from the agent.

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/idempotentHint/destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: the sign convention (positive = they owe you), the 50-row cap with overflow note, and error semantics (401 = missing/revoked key, 429 = back off and retry). The only mild gap is that it doesn't note anything about pagination beyond the row cap.

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 purpose followed by cleanly labeled When to Use / When NOT to Use / Returns / Examples / Error Handling sections; every sentence carries information. It is longer than strictly necessary, since the Returns block partly duplicates an existing output schema, which keeps it from a 5.

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 two-parameter read tool with an output schema, annotations covering safety, and a large sibling set, this description supplies everything an agent needs: purpose, routing alternatives, parameter semantics, return shapes, examples, and error handling. Nothing material 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?

Reported schema coverage is 0%, so the description must carry parameter meaning — and it does, describing only_with_balance ('list only the friendships that are not settled up') and response_format ('Raw objects with per-group balances') with concrete param examples. It doesn't add syntax or type detail beyond the schema, so it falls just short of 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?

States a specific verb (list) and resource (Splitwise friends) and immediately narrows scope with 'with their balance per currency'. Combined with the explicit 'When NOT to Use' routing to splitwise_resolve_friend, splitwise_get_balances, splitwise_get_friend and splitwise_get_group_balances, an agent can distinguish this tool from every similar sibling without reading 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?

Contains an explicit 'When to Use' block with three concrete scenarios and a 'When NOT to Use' block naming four alternatives plus the condition that selects each. This is the strongest form of usage guidance: both positive triggers and exclusions are spelled out.

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 cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial non-obvious behavior: member/debt rendering formats, the balance sign convention, fallback from simplified to original debts, 50-item caps with a note, and 403/404 error semantics. This 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?

Long but highly structured and front-loaded: one-line purpose first, then endpoint/format details, then When to Use / When NOT to Use, Returns, Examples, Error Handling. Every section carries call-relevant information; no filler sentences.

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 an output schema existing, the description still specifies return shape (markdown block contents, caps, JSON alternative), gives concrete call examples, and documents the two likely error codes with remediation. Nothing an agent needs to invoke this 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?

The schema gives minimal per-parameter prose (coverage reported at 0%), but the description clarifies group id 0 as the non-group-expenses pseudo-group and explains that response_format=json returns the raw group object versus default markdown. It adds real meaning, though response_format is partly a restatement of the enum.

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+scope: 'Read one group: its members with balances, who owes whom, and the invite link.' It also names the underlying endpoint (GET /get_group/{id}) and explicitly distinguishes itself from splitwise_get_groups, splitwise_resolve_group, and splitwise_get_expenses, 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?

Contains dedicated 'When to Use' and 'When NOT to Use' sections with named alternatives for each exclusion (splitwise_get_groups for listing, splitwise_resolve_group for name lookup, splitwise_get_expenses with group_id for expenses). The selection logic is fully explicit.

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 readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: the sign convention (positive = owed by group), the simplified_debts → original_debts fallback and that it says so, the 50-row cap, raw-and-flagged behavior for unparseable amounts, and 403/404 error semantics. This is unusually rich behavioral disclosure.

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?

Well front-loaded and sectioned with headers, so the length is scannable rather than rambling. However, the detailed 'Returns' section partially restates content already available in the output schema, which is minor 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?

Given the group/currency/settlement complexity, the description covers the sign convention, debt-source fallback, member-name resolution, error codes, and the pseudo-group trap. Combined with the existing output schema, an agent has everything needed to call and interpret this 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 description coverage is reported at 0%, so the description must carry the burden, and it does: it explains group_id 0 as the non-group pseudo-group whose only member is you, and what response_format 'markdown' vs 'json' returns. It also supplies concrete example param objects.

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 with scope ('each member's balance in one group and who should pay whom to settle it'), and explicitly distinguishes itself from splitwise_get_balances, splitwise_get_group, and the group-mutation siblings. An agent can pick this tool without opening another 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?

Has dedicated 'When to Use' and 'When NOT to Use' sections naming concrete alternatives (splitwise_get_balances for all-friend balances, splitwise_get_group for details, splitwise_resolve_group for id lookup) and an explicit edge case (group_id 0 pseudo-group returning only you). Nothing is 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 already declare readOnly/idempotent/non-destructive, and the description adds substantial behavior beyond them: 50-per-call pagination with next-offset, the sign convention for balances, the group id 0 pseudo-group, response-format behavior, and 401/network error handling. This is rich operational context rare in tool descriptions.

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 and key caveats are front-loaded, then cleanly sectioned into When to Use / When NOT to Use / Returns / Pagination / Examples / Error Handling. Every section carries unique information; no sentence is 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 read tool with both annotations and an output schema, this description covers everything an agent needs: selection guidance, pagination continuation, sign interpretation, and failure modes. Nothing material is left for the agent to guess.

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

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

Despite the low reported schema coverage signal, the description fully explains each parameter's effect: offset ties to the 50-per-call window, current_user_id changes whose balance is shown and flips the sign convention, and response_format governs the return shape. Worked examples show concrete parameter combinations.

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 states a specific verb and resource ('List every group you belong to') plus the returned columns (members count, balances per currency). It also disambiguates from close siblings like splitwise_get_group and splitwise_get_balances via the When NOT to Use list.

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?

Explicit When to Use and When NOT to Use sections name concrete alternatives (splitwise_resolve_group, splitwise_get_group, splitwise_get_balances) and the conditions that select them. An agent can route correctly without inferring anything.

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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description goes well beyond them: 50-row cap with overflow counted, 2,000-character text cap, HTML flattening with `~~old~~` convention, undocumented codes rendered as `unknown (N)`, pre-call validation of inputs, and 401/error-as-string semantics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded and the sectioned layout (When to Use / When NOT / Returns / Pagination / Examples / Error Handling) is easy to scan. It is somewhat long for a three-parameter read tool and re-states a few details that also live in the schema, but almost every line is actionable.

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 an output schema present, the definition supplies everything an agent needs: trigger conditions, exclusions with alternatives, pagination model, output shapes for both formats, and failure modes. Nothing material 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?

With schema description coverage reported at 0%, the description carries the load and does so fully: `limit` (0 = server maximum, can be large, prefer a number), `updated_after` (ISO-8601, bare date = midnight UTC), and `response_format` behavior, plus concrete parameter examples and guidance to combine the two.

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

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

The first sentence states a specific verb (list) plus resource (recent Splitwise activity/notifications) and ordering (newest first), then details exactly what each row contains. It is immediately distinguishable from siblings like splitwise_get_expenses and splitwise_get_comments.

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?

There are explicit 'When to Use' and 'When NOT to Use' sections, and the negative cases name the correct alternative for each scenario (splitwise_get_expenses, splitwise_get_comments, splitwise_get_balances). No inference is left to the agent.

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 readOnly/idempotent/non-destructive/openWorld, and the description still adds a non-obvious access constraint (only friends, group co-members, or self), the underlying endpoint, the full error contract (403/404/401) and the fact that failures return as `Error ...` strings. It also distinguishes `confirmed` vs. `dummy`/`invited` user states, which the 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 purpose, then cleanly sectioned by usage, returns, examples and errors; the examples section is somewhat redundant given the schema. Well-sized overall but slightly longer than strictly necessary for a one-parameter read.

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?

Covers the access model, both output formats, the endpoint, and every failure mode. Even though an output schema exists (so return values are technically redundant here), the extra detail about the registration-status field meaning makes a one-parameter read tool fully self-contained.

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 schema documents both properties inline, and the description reinforces them with concrete example payloads (`{"user_id": 491923}`) plus the access precondition on user_id and the meaning of response_format. It adds example values and the friend/group requirement, though it doesn't explain edge cases beyond the schema's own notes.

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?

Starts with a specific verb+resource+scope: "Get another Splitwise user's public profile by id" and enumerates the returned fields (name, email, registration status). It explicitly names the sibling tools it is not (splitwise_get_current_user, splitwise_resolve_friend, splitwise_get_friend), so an agent can route 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?

Has dedicated "When to Use" and "When NOT to Use" sections, the latter naming four concrete alternatives with the condition that selects each (self vs. other, name-to-id vs. id-to-name, balances vs. profile). This is as explicit as routing guidance gets.

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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds substantial context beyond them: the SPLITWISE_ALLOW_WRITES kill-switch, the exact endpoint called, the 401 remediation path, and the fallback behavior when no key is configured (returns config state without hitting the API).

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 purpose and cleanly sectioned with headers, which suits an agent scanning for a diagnostic tool. It is slightly long — the Returns section partially overlaps the existing output schema — but every block still carries operational value.

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-param diagnostic tool with an output schema, this is fully complete: it discloses the endpoint, the kill-switch, error semantics (401 vs connection error), and no-key behavior. An agent has everything needed to call it and interpret both success and failure.

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 per the rubric the baseline is 4. Nothing about argument semantics needs explaining, and the description correctly stays silent on params rather than inventing 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 ('Verify connectivity and the API key against Splitwise, and report the write kill-switch') and even names the endpoint it calls (GET /get_current_user). It explicitly distinguishes itself from siblings like splitwise_get_balances and splitwise_get_current_user by defining its diagnostic role.

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?

Provides explicit 'When to Use' (first call after config, learn own user id, debug 401) and 'When NOT to Use' sections with named alternatives for each exclusion. Nothing is left to inference about when this tool is the right pick.

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 far beyond them: the HTTP 200 + success:false quirk, the SPLITWISE_ALLOW_WRITES=1 gate, the refusal on non-zero balance, the 403 meaning, and the exact undo call. This is unusually rich behavioral disclosure for a mutation tool.

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 a one-line purpose and emoji-flagged destructiveness, then sectioned into scannable blocks. It is long for a two-parameter tool, but every section (guard railing, returns, error handling) carries information an agent needs, 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?

Covers the destructive/auth prerequisites, the ambiguous-success failure mode, the undo path, and error mapping, so nothing needed to invoke or interpret the call is missing. An output schema exists, yet the extra success/errors interpretation guidance still adds value.

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 schema's nested properties do carry short descriptions, but the description reinforces them with a concrete example ({"group_id": 12345, "user_id": 5823}) and adds the rule that a group NAME must first be resolved via splitwise_resolve_group. That name-to-id guidance is meaningfully 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 ('Remove a member from a group') and immediately distinguishes it from siblings like splitwise_delete_group and splitwise_add_user_to_group. An agent can identify the tool's scope 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?

Explicit 'When to Use' and 'When NOT to Use' sections name three alternatives (delete_group, get_group, resolve_group) plus the balance-settled precondition. Routing decisions are fully enumerated rather than 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 already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds substantial context beyond them: the shared 24 h cache and what refresh does, the exact resolution thresholds (1.000 exact, unique_strong ≥ 0.85), the ambiguity rules (prefix collision, 4+ char fuzzy minimum, digit matching), locale-dependent naming, and error handling (401 = missing/regenerated key, failed fetches never cached). This is far richer than the annotations alone.

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 one-line summary, then clearly headed sections (When to Use / When NOT to Use / Returns / Examples / Error Handling). Highly dense and mostly earns its length, but the deep dive into scoring internals (difflib on accent-folded text, the 'phone' → TV/Phone/Internet example) is more than an agent strictly needs to invoke 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?

For a fuzzy-resolution tool with an output schema, everything an agent needs is present: prerequisite sequencing before expense creation, cache/refresh behavior, locale caveats, ambiguity outcomes, and error handling. The Returns section is redundant with the output schema but harmless.

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?

Although coverage is reported low, the description adds real meaning beyond the schema: refresh is explained in terms of the 24 h cache, response_format is tied to the concrete json/markdown shapes, and query is given crucial semantics the schema lacks — query in the user's Splitwise locale language, 4+ characters required for fuzzy matching, digits must align, and 'other' alone is ambiguous and must be qualified with a parent.

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 line states a precise verb and resource ('turn a category name into the subcategory id an expense needs') plus the scope of output ('ranked fuzzy candidates'). It is immediately distinguishable from splitwise_get_categories, which the description explicitly routes the browser to. An agent can tell which tool to pick 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?

Dedicated 'When to Use' and 'When NOT to Use' sections name the exact upstream callers (splitwise_create_expense / splitwise_update_expense) and the alternative tools for browsing and for people/groups. The condition that selects each alternative is stated, not 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial behavior beyond them: the endpoint is uncached, the scoring algorithm, the exact-match-only resolution rule, the danger of a wrong id, and that sub-4-character or digit-differing queries get no fuzzy candidate. This is exactly the extra context annotations cannot 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?

Long but well-sectioned (purpose, when-to-use, when-not-to-use, returns, examples, error handling) with the core purpose front-loaded. Every section adds distinct value; only minor tightening is possible.

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?

Covers the ambiguity/resolution model, the exact/probable/ambiguous/none states, error handling (401, empty friend list), and usage examples. An agent has everything needed to call it correctly and to know not to auto-pick a fuzzy match.

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?

Reported schema coverage is 0%, but the description compensates: it explains that `limit` bounds the top-N candidates, that `query` is 'the name as the user said it,' and fully specifies the `response_format`='json' payload shape. Semantics for each param are grounded in behavior rather than just restated.

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: 'Turn a friend's name (or email) into their Splitwise user id, with ranked fuzzy candidates.' It is immediately distinguishable from siblings like splitwise_get_friends or splitwise_resolve_group, which are named explicitly later.

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?

Dedicated 'When to Use' and 'When NOT to Use' sections name the prerequisite tools (splitwise_create_expense, splitwise_add_user_to_group, etc.) and route non-friend lookups to splitwise_get_balances, splitwise_resolve_group, and splitwise_create_friend. Explicit alternatives with conditions.

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 cover the read-only/idempotent safety profile, but the description goes well beyond them: the endpoint is uncached because groups change, scoring uses difflib.SequenceMatcher on case/accent-folded text, resolution succeeds only on an exact unique match (with the 'Peru trip' vs 'Peru trip 2026' ambiguity rule), short/numeral-differing queries yield no fuzzy candidate, group id 0 is the pseudo-group, and a 401 means the API key is missing or regenerated. This is unusually rich behavioral disclosure.

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?

Well front-loaded with the core purpose first, then structured sections. It is long, and the 'Returns' block partially duplicates the output schema, but each section earns its place given the resolution semantics an agent must get right.

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 an output schema exists, the description still supplies the resolution-state machine (exact/probable/ambiguous/none), the always-present ambiguous_count, the conditional resolved/probable keys, error handling, and the fallback instruction ('ask the user, do not pick'). Nothing an agent needs to call or interpret this tool 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?

The schema itself documents limit (1-25 range) and response_format, and the description reinforces both with the example call and the JSON return shape. It adds real semantic value for `query` by explaining the folding/scoring and <4-character and numeral-mismatch behavior — meaning the schema cannot convey — though it does not spell out the maxLength=100 or required-only constraints.

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 precise verb+resource+outcome ('turn a group's name into its Splitwise group id, with ranked fuzzy candidates') and explicitly distinguishes itself from sibling resolvers and from splitwise_get_groups. An agent can identify this as the name-to-id resolver 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?

Has dedicated 'When to Use' and 'When NOT to Use' sections naming the concrete downstream tools that require a resolved id (create_expense, get_group, get_expenses, add_user_to_group, delete_group) and routing list queries to splitwise_get_groups and person/category lookups to splitwise_resolve_friend / splitwise_resolve_category.

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 the SPLITWISE_ALLOW_WRITES=1 gate and its refusal message, the side effect that balances change again via restored shares, and detailed error semantics (200-on-refusal, 404 vs 403). This is exactly the behavioral context annotations cannot 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 action, then routes via labeled sections; nearly every line earns its place. The 'Returns: The success value Splitwise returned.' line is largely redundant given an output schema exists, costing the top score.

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 an unavoidable auth/environment prerequisite, the definition covers the gate, side effects, alternatives, a call example, and error mapping. An agent has everything needed to invoke it correctly, and return values are covered by the 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 0%, so the description must compensate. It provides a concrete example call with a nested params wrapper and an integer id, which usefully disambiguates the envelope shape, but adds no further semantics for the single expense_id field.

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 (a deleted expense) in the first line, and explicitly distinguishes itself from the sibling splitwise_undelete_group. An agent can route to it 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?

Dedicated 'When to Use' and 'When NOT to Use' sections name the exact triggering operations (undo splitwise_delete_expense, recover `[deleted]` rows from splitwise_get_expenses) and point to the correct alternative for groups.

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 the HTTP-200-with-success/errors quirk, the write gate requiring SPLITWISE_ALLOW_WRITES=1, the failure transformation into an Error, the undo path, and the refusal message text. These are exactly the behaviors an agent cannot derive from readOnlyHint/destructiveHint/idempotentHint alone.

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 purpose line followed by tight labeled sections (When to Use, When NOT to Use, Returns, Examples, Error Handling). Dense but every sentence contributes actionable information with 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?

Covers the mutation's failure modes, environment gating, return-value interpretation, and error surface, which is more than enough for a one-parameter write tool even though an output schema exists. An agent has everything needed to call and interpret 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?

One required param with reported 0% schema coverage, so the description carries the burden: it supplies an example params block and, crucially, warns that a group NAME must first be resolved to an id via splitwise_resolve_group. That adds real semantic value, though it does not restate the schema's own '0 is not a real group' constraint.

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 ('Restore a deleted group (and its expenses)') and mirrors the exact endpoint POST /undelete_group/{id}. An agent can distinguish it from splitwise_delete_group and splitwise_undelete_expense 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?

Provides explicit When to Use / When NOT to Use sections and names each alternative with the condition that selects it (splitwise_undelete_expense for one expense, splitwise_add_user_to_group for re-adding members, splitwise_resolve_group for name-to-id resolution). Nothing is 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?

Goes well beyond the annotations: it discloses the SPLITWISE_ALLOW_WRITES=1 write gate, that shares REPLACES the whole split and silently drops omitted participants, the no-undo requirement to re-read and re-send, and the trap that Splitwise returns HTTP 200 even on failure so a non-empty 'errors' body must be inspected. Annotations only say readOnly=false, idempotent=true, destructive=false; the description supplies the operational consequences those hints do not.

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 behaviour and the shares warning, then organises the rest under headers (When to Use / When NOT to Use / Returns / Examples / Error Handling). It is long, and the shares-replacement warning is repeated in both the body and the shares paragraph, but the redundancy is on the highest-risk failure mode and every section 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 stateful mutation tool with a nested share sub-object, it covers the write gate, replacement semantics, arithmetic constraints, confirmation payload, worked examples, and a full error taxonomy (refused-local, 200-with-errors, 404 wrong id, 403 not your expense, possibly-landed writes). Nothing an agent needs before or after calling it 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?

Adds cross-field meaning the schema cannot express: Σ paid_share and Σ owed_share must each equal the new cost (or the current cost if cost is omitted), that a mismatch is refused before sending, and that changing cost without shares defers the split to Splitwise. group_id 0 = no group is also clarified. Some of the shares warning duplicates the schema's own field description, which is why this is 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?

States the specific verb and resource ('Change an existing expense'), the endpoint it calls, and the partial-update semantics ('only the fields given are sent'). It also names sibling tools for adjacent operations (create/delete/undelete/resolve), so an agent can distinguish it from every neighbouring write tool.

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?

Provides explicit 'When to Use' and 'When NOT to Use' lists that map each alternative (create_expense, delete_expense, undelete_expense, resolve_*) to the case that should select it. The prerequisite for safe share edits (read the current split with splitwise_get_expense first) is stated up front, not 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 safety/idempotency profile; the description adds far more: the SPLITWISE_ALLOW_WRITES=1 gate, that email/password are structurally impossible, that there is no undo (with the read-back-and-recall recovery pattern), the partial-confirmation semantics for locale/currency, and that a timeout/5xx leaves the outcome UNKNOWN. This is exactly the behavioral context an agent needs beyond 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?

Well-organized with clear headers and front-loaded purpose and write-gate warning. It is long, and the 'Returns' section partly restates what the output schema already conveys, so not every line is strictly additive, but nothing is 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 write tool with annotations and an output schema, the definition still covers auth gating, reversibility, partial-success behavior, and error mapping (403/400/timeout). An agent has everything required to invoke and recover 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?

The description reinforces the 'at least one field' constraint, gives worked examples with concrete currency/locale values, and explains the locale pass-through-vs-validated distinction. The schema itself already documents each field, so the description mainly adds the cross-field constraint and example syntax rather than new per-parameter 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?

The opening sentence names a specific verb (Update) and resource (your Splitwise profile) and enumerates the exact mutable fields. It is trivially distinguishable from siblings like splitwise_get_current_user or splitwise_update_expense.

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?

Explicit 'When to Use' and 'When NOT to Use' sections name the concrete alternative for reads (splitwise_get_current_user) and rule out email/password edits and editing other users. The routing is unambiguous.

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