wimm

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

Annotations already declare that this is a non-read-only, idempotent, non-destructive mutation, and the description reinforces idempotency by explaining that re-acknowledging is a no-op. It also mentions the confirmation gate, but this largely repeats the schema; it does not add further behavioral context such as authorization needs, side effects on notification state, or return behavior.

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

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

The description is two compact sentences with the core purpose front-loaded. Every sentence contributes necessary information about the action, idempotency, and the confirmation requirement.

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 simple two-parameter mutation with rich annotations and a fully described schema, the definition covers the essential action, idempotency, and required confirmation. It could be slightly more complete by indicating where to obtain notificationId or what acknowledgment affects, but no output schema exists and the core call requirements are present.

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

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

Schema description coverage is 100%, so both notificationId and confirmation are already documented in the input schema. The description reiterates that confirmation must be true but adds no syntax, format, lookup guidance, or example beyond what the schema provides.

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

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

The description states a specific verb and resource: marking a notification as acknowledged/read. It is clear enough to distinguish from read-only siblings like list_notifications, though it does not explicitly name sibling alternatives or cross-reference how to obtain a notificationId.

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

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

The description gives one important usage prerequisite, requiring confirmation: true to execute. However, it does not explain when to use this versus retrieving notifications first, nor does it state any exclusions or alternatives, so usage is mostly implied by the tool name.

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

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

Annotations already establish this is a non-read-only, non-destructive, non-idempotent mutation, and the description usefully reinforces the confirmation gate. It says nothing about whether the created transaction is returned, how invalid account_id or duplicate submissions behave, or how idempotencyKey interacts with idempotentHint=false.

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

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

Two short sentences, front-loaded with the action and followed by the gating requirement — nothing is padded. It is efficient, though so terse that it borders on under-specified rather than genuinely concise.

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

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

A 9-parameter mutation tool with one-third schema coverage, no output schema, and many adjacent transaction-creation siblings demands far more than two sentences. An agent lacks enough to choose this tool confidently or populate most parameters correctly.

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

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

Schema description coverage is only 33% across 9 params, so the description needs to carry weight and does not. It only restates the confirmation flag, whose behavior ('Must be true to execute the mutation') is already spelled out in the schema itself, leaving amount, account_id, category_id, type, and notes unexplained.

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 new transaction'), so the basic action is unambiguous. However, it never distinguishes itself from close siblings like bulk_add_transactions or add_transaction_from_photo, which an agent could plausibly confuse it with.

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?

'Requires confirmation: true to execute' gives one concrete precondition for invocation. But there is no guidance on when to pick this over bulk_add_transactions, import_from_text, or add_transaction_from_photo, and no exclusions or follow-up steps.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false. The description adds genuinely useful context beyond these: it is a non-committing draft producer, enumerates the returned fields, and states the confirmation:true requirement and the account-omission defaulting behavior. It does not cover latency/cost of vision extraction, keeping it below a 5.

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

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

Front-loaded with what the tool does and the critical 'NOT committed' caveat up front. Dense but nearly every sentence carries actionable information; only the account-defaulting sentence mildly duplicates the schema.

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

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

With no output schema, the description compensates by enumerating returned fields (amount, date, description, type, suggestedCategory, suggestedAccountId). Together with the workflow guidance and confirmation requirement, an agent has everything needed to call it and act on the result.

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

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

Schema description coverage is 100%, so parameters are already fully documented. The description's note about accountId omission (currency defaults to USD, suggestedAccountId null) largely restates the schema's own accountId description rather than adding new semantics. Baseline 3 is appropriate.

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

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

States a specific verb and resource: runs AI vision extraction on a base64 receipt/PDF and returns a PREFILLED draft, explicitly 'NOT committed'. This clearly distinguishes it from the sibling add_transaction, which it names as the follow-up persistence step.

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 two-phase workflow: this tool produces a reviewable draft, then the agent should call add_transaction or bulk_add_transactions to persist. Also flags a branching condition (if accountId omitted, agent must choose an account before committing).

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=false, so the safety profile is partly covered. The description adds real value by disclosing the hard confirmation=true gate, but says nothing about whether existing categories are merged or overwritten, or what happens on template mismatch, which matters for a seeding 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?

Two short sentences with no filler, and the effect is front-loaded before the confirmation requirement. It could be marginally tighter, but every sentence carries information.

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

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

For a mutation with no output schema, the description covers what is created and the confirmation gate, but leaves the return shape, merge-vs-overwrite behavior, and failure modes unstated. Adequate but with clear gaps.

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

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

Schema description coverage is 100%, so templateId, confirmation, and idempotencyKey are fully documented in structured fields; baseline is 3. The description only restates the confirmation gate and 'named template' framing, adding no syntax or format detail 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 description states a specific verb (seed) and the concrete resources it produces (categories, account groups, recurring-slot suggestions) plus the source (a named onboarding template). An agent can tell what it does, though it does not explicitly distinguish itself from close siblings like commit_onboarding or ingest_onboarding_files.

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 implies usage in the onboarding flow and states the confirmation prerequisite, but gives no explicit when-to-use guidance versus commit_onboarding or start_onboarding, and no exclusions or ordering advice.

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?

Strong disclosure beyond the annotations: it states the partial-success contract ("a single bad row does NOT roll back the batch"), the exact return envelope shape, replay tagging via status='replayed', and the confirmation gate. The only tension is idempotentHint=false in annotations versus the emphasis on per-row idempotency, but that is genuinely compatible — the call itself is not idempotent, only keyed rows are — so it is a nuance, not a contradiction, though the description could have made that distinction explicit.

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

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

Two tight sentences, front-loaded with the operation and then the return/behavior contract. The inline envelope notation conveys the response shape faster than prose would, and nothing is repeated or 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?

There is no output schema, so the description carries the burden of explaining return values — and it does, with the partial-success envelope and per-row results. Combined with the maxItems=25 and required confirmation in the schema, 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?

With 67% schema coverage, the schema already documents accountId, confirmation, and idempotencyKey. The description adds real meaning on top: duplicates short-circuit and return the original response tagged as replayed, and it reinforces the confirmation requirement as a call-level gate rather than just a boolean field. It does not elaborate on row-level fields like amount or date, but those are self-explanatory 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?

The opening sentence gives a specific verb and resource ("Add multiple transactions in one call") and immediately names the property that separates it from the single-row add_transaction sibling: batch scope plus per-row idempotency. An agent can tell what this does and why it exists alongside add_transaction without opening either schema.

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

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

Usage is implied rather than stated: "in one call" signals batch use and "Requires confirmation: true" is a hard prerequisite, but the description never says when to prefer this over add_transaction (e.g., how many rows justify a batch) or when not to use it. The prerequisite is useful, but there is no explicit alternative routing.

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?

'Set or change' hints that an existing category is overwritten, which is consistent with destructiveHint=true, and the confirmation gate is useful operational context. With annotations already covering readOnly/destructive/idempotent semantics, the remaining gaps (what happens to the prior category, whether category_id must pre-exist, error behavior) keep this at a 3.

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

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

Two short sentences with no filler, and the preconditions are front-loaded after the action statement. Nothing is wasted, though the brevity leaves the coverage gaps noted above.

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

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

For a mutation with annotations, no output schema, and 4 parameters, the definition conveys the mutation plus its confirmation gate, which is the minimum an agent needs to call it. It stops short on failure modes, category validation, and the idempotency behavior that the schema flags but the description never reinforces.

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 50%, and the half that is documented (confirmation, idempotencyKey) is already fully described in the schema; the description merely repeats the confirmation flag. The two core parameters, transaction_id and category_id, get no added meaning such as whether category_id must reference an existing category or accept special values.

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 ('Set or change') and resource ('the category of a transaction'), which is unambiguous standalone. It does not, however, distinguish itself from update_transaction, which plausibly also touches a transaction's fields, so sibling differentiation is missing.

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

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

The only guidance is a precondition ('Requires confirmation: true to execute'), which is a gate rather than a when-to-use rule. Nothing says when to pick this over update_transaction or how it relates to create_category when the desired category doesn't exist.

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 the mutation as destructive and non-read-only. The description adds useful behavioral detail beyond them: it explains that rows persist as transactions, an account may be materialised, and both happen inside the same DB transaction, which conveys atomicity and side effects.

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 entire definition is one tightly written sentence that front-loads the action and includes the key side effects and confirmation requirement. There is no redundant or empty text.

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

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

For a destructive mutation with rich annotations and no output schema, the description covers purpose, atomicity, side effects, and the confirmation requirement. It does not describe failure behavior or return values, but annotations and schema already carry the safety and idempotency details.

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 67%, and the description clarifies that import_id refers to a previously-previewed import and reiterates that confirmation must be true. However, it does not add meaning beyond the schema for the optional idempotencyKey, and the confirmation behavior is already described 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?

The description uses a specific verb and resource — "Commit a previously-previewed Import by id" — and states the concrete outcome: parsed rows become transactions and a suggested account may be materialised. This distinguishes it from sibling tools such as add_transaction, bulk_add_transactions, and import_from_text.

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

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

The description clearly scopes usage to committing a previously-previewed Import by id and notes the required confirmation flag. It does not explicitly name when not to use it or directly route the agent to alternatives, but the context is strong enough to select it correctly.

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

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

With destructiveHint=true, idempotentHint=false and openWorldHint=true already declared, the description still contributes meaning: 'atomically' tells the agent the operation is all-or-nothing and that accounts are created as a side effect. It does not state reversibility or what happens on partial failure, but the safety profile is covered by annotations.

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

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

Three short sentences, zero padding: purpose and atomicity first, the API mirror second, the hard precondition last. Nothing is repeated needlessly beyond the confirmation gate.

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, non-idempotent mutation with no output schema, the agent is left guessing what comes back (the created accounts? the finalized session?) and whether the session remains usable afterward. Atomicity is the main thing conveyed; the return contract and post-state are not.

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

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

Schema description coverage is 100% and all three parameters are documented in the schema, including the optional idempotencyKey's 24h cache semantics. The description restates the confirmation requirement without adding syntax or format detail, so this is baseline.

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

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

States a specific verb and resource ('Finalize an onboarding session') plus the concrete side effect ('create detected accounts atomically'), so an agent knows exactly what happens. It does not differentiate itself from the very similar commit_work_session and commit_import siblings, which an agent must infer from the 'onboarding' scope alone.

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?

'Requires confirmation: true' is a real precondition, but the schema already says 'Must be true to execute the mutation', so it adds little. There is no explicit statement of when to call this versus resume_onboarding, submit_onboarding_answer, or commit_work_session, leaving ordering 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 beyond annotations by disclosing the atomic all-or-nothing transaction semantics, idempotency on already-committed sessions, and the confirmation gate. These are valuable behavioral traits. Missing: whether permissions or a specific session state are required before commit, and what happens to existing data if the session is partial.

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

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

Two tight sentences, front-loaded with the action and atomicity guarantee, followed by idempotency and the confirmation requirement. No filler; every clause carries operational information.

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

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

For a destructive, idempotent mutation with no output schema and 100% schema coverage, the description covers the essential safety and atomicity profile. It stops short of describing the return value or post-commit state, and doesn't state preconditions (session must exist and be uncommitted), which would complete the picture.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining that confirmation must be true to execute (a gate, not just a boolean) and by tying sessionId implicitly to the 'already-committed session' idempotency behavior. Slightly above baseline due to the confirmation semantics being front-loaded.

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 (atomically finalise) and resource (work session), and enumerates exactly what gets created (accounts + transactions + rules + template application). Clearly distinguishable from sibling tools like get_work_session, submit_work_session_answer, and commit_import, which operate on different scopes.

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

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

The description implies usage through 'Atomically finalise a work session' and 'Requires confirmation: true,' suggesting this is the terminal step of a session flow. However, it doesn't explicitly state when to use this versus alternatives like submit_work_session_answer or get_work_session, nor does it note prerequisites (e.g., a session must be in a draft state).

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, and the description adds the non-obvious confirmation gate, which is genuine behavioral context. However, it says nothing about what happens on duplicate names, what the response contains, or that idempotency is opt-in via a key (only the schema notes that).

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

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

Two short sentences that lead with the purpose and follow with the execution gate; nothing is padded. The loose "etc." after the enum examples is the only minor imprecision.

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

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

For a mutation with full schema coverage and clear annotations, the description covers the essentials of calling it. It stops short of the confirmation workflow details (e.g., what happens if false, whether a retry is expected) and of any post-creation behavior an agent might need.

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

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

Schema coverage is 100%, so every parameter including the enums is documented in the schema. The description reinforces the type enum and the confirmation flag but adds no format or constraint detail beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb ("Create") and resource ("financial account") and enumerates example types, so the agent knows exactly what gets produced. It does not distinguish this from the close sibling create_account_group, which is the remaining gap.

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

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

The description conveys a key precondition (confirmation must be true) but gives no guidance on when to use this versus create_account_group or when not to use it. Usage is implied by the name only.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent, closed-world mutation. The description reinforces the confirmation gate, but adds nothing about side effects, whether the group name must be unique, or what happens to accounts already in another group.

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

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

Two short sentences, front-loaded with the core action and the side effect, with the crucial confirmation requirement trailing. No wasted words.

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

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

For a 4-parameter mutation with no output schema, the description is adequate but thin: it says nothing about the return value (e.g. the new group's ID), name-uniqueness behavior, or interplay with the optional idempotencyKey that the schema exposes.

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

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

Schema coverage is 100%, so parameters are already fully documented in structured form. The description only restates that accountIds is optional and that confirmation must be true; it adds no constraint or format detail beyond the schema.

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

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

States a specific verb and resource ('Create an account group') plus the secondary effect of attaching existing accounts. It is clearly distinguishable from sibling create_account, though it does not explicitly contrast with it.

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?

Implies usage ('optionally assign existing accounts') and gives the confirmation prerequisite, but there is no statement of when to prefer this over create_account or how to handle account ownership prerequisites beyond what the schema says.

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

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

The annotations already declare this is a non-read-only, non-destructive mutation, and the description adds the notable execution gate ('Requires confirmation: true'). However, that requirement is also spelled out in the schema, and the description says nothing further about what happens on failure or how the created category is returned.

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

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

Three short sentences, front-loaded with purpose, then sequencing, then the execution gate. No filler, and the most operationally important detail (confirmation) is last and easy to scan.

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

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

For a 6-parameter create tool with no output schema, the description plus a fully documented schema covers what an agent needs to invoke it correctly. The only remaining weakness is that it doesn't mention the TRANSFER category type that the schema accepts.

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

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

Schema description coverage is 100%, so every parameter including confirmation and idempotencyKey is already documented in the input schema, which sets the baseline at 3. The description only echoes the confirmation flag and mentions INCOME/EXPENSE, omitting the TRANSFER enum value the schema actually permits, so it adds no meaning 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 description gives a clear verb-and-resource pair ('Create a new spending/income category') and parenthetically names the domain values, which separates it from sibling mutations like create_category_rule or create_account. It is a bit narrower than the schema, which also allows TRANSFER, but the core purpose is unmistakable.

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 names a concrete ordering context ('Useful before calling categorize or set_budget'), which tells the agent when this tool belongs in a workflow. It stops short of stating exclusions or naming a competing create path, so it is clear context rather than full when/when-not 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 readOnly=false, destructive=false, and idempotent=false, so the safety profile is covered. The description adds the useful scoping detail that categorization applies to 'future' transactions only, but it does not explain precedence against existing rules or error behavior, and the confirmation note merely restates a schema requirement.

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

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

Two short sentences, front-loaded with the purpose and ending with the confirmation precondition. It is efficient, though the 'Requires confirmation: true' clause largely duplicates the schema's confirmation field description.

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

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

With five parameters, a mutation annotation profile, and no output schema, the description covers the essentials: purpose, temporal scope, and the confirmation gate. It leaves gaps around rule conflicts with existing rules and what is returned on success, which an agent would benefit from knowing.

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 80%, so pattern, match_type, confirmation, and idempotencyKey are already documented in the schema. The description adds no syntax, format, or matching-behavior detail beyond what the schema provides, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Create a rule') plus the effect ('auto-categorize future transactions matching a pattern'), which tells the agent this is not the same as create_category. It does not explicitly distinguish itself from the closely related create_category_rules_bulk sibling, so it falls short of a 5.

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

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

The when-to-use is implied by 'future transactions matching a pattern', and the confirmation gate is noted. But there is no guidance on when to prefer this over create_category_rules_bulk, or whether existing historical transactions are affected.

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

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

The description is highly valuable by disclosing critical operational details: 'per-rule isolation' (meaning batch failure doesn't abort the whole call) and the exact structure of the return value (created, ids, failed). This goes well beyond what the annotations provide.

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

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

The description is front-loaded and highly efficient, immediately conveying the primary function and the critical error-handling behavior in a very short 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?

Despite not having an output schema, the description provides all necessary operational context—how failures are reported, how transactions are processed (in bulk), and the security requirement (confirmation)—making it complete.

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 33% schema coverage remaining, the description adds value by clarifying that the 'confirmation' parameter is mandatory for execution and by framing the 'idempotencyKey' functionality within the context of bulk processing isolation.

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 title and description clearly state the function (create multiple category rules) and distinguish it from singular creation methods available in siblings by specifying the 'bulk' nature of the operation.

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

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

The name 'bulk' and the description explicitly state the purpose is to handle multiple rules, effectively guiding the user toward this tool over singular alternatives like 'create_category_rule'.

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 the mutation profile (readOnly=false, destructive=false, idempotent=false), and the description adds real mechanics beyond that: it computes the first nextDate and persists the rule. The confirmation note is somewhat redundant with the schema's own "Must be true to execute the mutation", and return behavior is unspecified.

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

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

Two dense sentences that lead with the action and put the confirmation gate last where it belongs. The parenthetical enumeration is somewhat redundant with the schema but costs little.

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 10-parameter mutation with no output schema, the description covers the material behavior an agent needs: it persists a rule rather than posting a transaction now, it computes nextDate, and it requires explicit confirmation. What is returned after creation is left unstated.

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

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

Schema coverage is 100%, so the baseline is 3. The parenthetical field list (amount, type, description, account, frequency, interval, startDate) largely restates the schema and omits the optional categoryId and idempotencyKey, adding no format or default semantics of its own.

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 ("Create a recurring-transaction schedule") and enumerates the fields that define the schedule, so an agent can tell it apart from add_transaction. It never explicitly names the one-off sibling as the alternative, which keeps it from a 5.

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

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

"Requires confirmation: true to execute" is a genuine precondition for use, but there is no guidance on when to create a schedule versus using add_transaction or apply_template, and no mention of what happens when confirmation is false or omitted.

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, idempotentHint=true, readOnlyHint=false, so the safety profile is known. The description's confirmation gate is behaviorally relevant but merely restates the schema-embedded requirement ("Must be true to execute the mutation"). It never says whether the delete is reversible, what related records are affected, or what the result looks like.

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

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

Two short sentences with no filler, and the safety gate is front-loaded after the action. It is efficient, though brevity here shades into under-specification rather than disciplined density.

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?

This is an irreversible mutation with no output schema and an undocumented required parameter; the description should say what deletion entails (permanence, cascade to linked data, error behavior on missing IDs) but covers only the confirmation gate that the schema already states.

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 only 67% schema description coverage, the description should compensate, but it adds nothing beyond the confirmation flag already documented in the schema. The required transaction_id parameter is undocumented in both places, leaving the agent to guess its format.

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?

"Delete a transaction" states a specific verb (delete) and resource (transaction), so the core action is unambiguous and clearly distinct from update_transaction or add_transaction. It offers no explicit sibling differentiation or scope detail (e.g., soft vs. hard delete, cascade effects), but the purpose itself is clear.

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

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

The description gives no when-to-use or when-not-to-use guidance. With siblings like update_transaction and get_transaction available, an agent gets no help deciding whether removal is the right call versus modification, and no prerequisites (permissions, ownership) are mentioned.

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

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

Annotations already declare this is a safe, idempotent, read-only, closed-world operation, so the description is not carrying the safety burden. It adds a useful gloss on what 'anomaly' means (spending outliers) but says nothing about how outliers are determined, thresholds, or the result shape.

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

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

A single short sentence with the purpose and scope front-loaded and no filler. The brevity is close to under-specification, but nothing in the sentence is wasted.

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

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

With only two required date params and full annotation coverage, the essentials for calling it are present. However, there is no output schema, and the description does not indicate what an anomaly result contains or how many are returned, which is a meaningful gap for a detection-style tool.

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

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

Schema coverage is 100% and both parameters are fully documented with ISO date formats, so the reference to a 'date range' in the description adds nothing beyond start/end. Baseline 3 applies when the schema already does the work.

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 ('find') and resource ('unusual transactions'), and glosses the resource as 'outliers in spending', which is more informative than a bare restatement of the name. It does not explicitly distinguish itself from siblings like search_transactions or find_subscriptions, which also scan transactions.

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

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

The description gives no when-to-use guidance, no exclusions, and never names an alternative. An agent must infer on its own whether to call this versus search_transactions or spending_by_category when it wants to surface odd spending.

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 disclose that this is a read-only, idempotent, non-destructive operation, so the safety profile is covered. The description adds only that results are heuristic ('look like subscriptions') but does not explain the detection criteria, false-positive behavior, return shape, or limitations, leaving meaningful behavioral gaps.

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

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

The description is a single front-loaded sentence with no wasted text. Its brevity is appropriate and the key resource and behavior are placed immediately.

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 has no output schema, so the description would need to clarify return values or result shape, but it does not. It also omits routing guidance versus siblings and leaves the meaning of 'look like subscriptions' unspecified, which is a significant gap for a heuristic detection 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 100%, and the single min_recurrence parameter is fully documented with a default in the schema. The description adds no additional parameter semantics beyond what the schema already provides, matching the baseline for high schema coverage.

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

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

The description states a specific verb and resource: 'Find recurring transactions that look like subscriptions.' It clearly identifies the tool as a heuristic subscription detector, though it does not explicitly differentiate itself from siblings such as find_anomalies, list_transactions, or search_transactions.

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

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

The description gives no explicit guidance about when to use this tool versus alternatives, nor does it state when not to use it. The phrase 'look like subscriptions' implies a detection use case, but the agent must infer routing from tool names alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so safety and determinism are covered. The description adds only that balances are current; it does not say whether archived/closed accounts are included, ordering, or result size. With annotations carrying the safety profile, this is adequate but thin.

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

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

A single front-loaded sentence with no filler. Nothing is wasted and the key noun phrase comes first.

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

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

For a zero-parameter, read-only listing tool with full annotation coverage and no output schema, the description is sufficient to call it correctly. Minor gaps remain around whether the list is filtered (e.g., archived accounts) or ordered, but these are marginal given the tool's simplicity.

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

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

The tool takes zero parameters, so the baseline is 4. There are no arguments whose meaning could be clarified or omitted.

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

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

States a specific verb and resource ('List all user accounts') plus the payload ('current balances'), which distinguishes it from mutation siblings like create_account and update_account_balance. It does not explicitly separate itself from the closely related get_balances sibling, leaving some ambiguity about which to choose.

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 is no explicit statement of when to use this tool versus alternatives such as get_balances, which sounds like an equally plausible source of balance data. Usage is only implied by the name and one-line description.

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, closed-world), so the description's marginal job is behavioral detail. It instead adds a claim ('optionally converted to display currency') that implies a caller-selectable option the tool's zero-parameter schema cannot express, which risks sending the agent hunting for a nonexistent argument. It also says nothing about scope questions such as whether liabilities or hidden accounts are included.

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

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

A single front-loaded sentence with the verb and resource first; no filler. The only questionable clause is the currency-conversion phrase, which is short but misleads.

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

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

With no output schema, the description is the only source for return-value expectations, yet it never says what the summary contains (net total? per-account rows? which currency is the default?). Annotations cover safety, so this is adequate but with clear gaps for an aggregation 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?

Parameter count is zero, so the baseline is 4 and schema coverage is moot. The description lowers that baseline by discussing an 'option' that has no corresponding parameter, creating false parameter semantics rather than adding 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?

Names a specific verb and resource ('Get balance summary across all accounts'), and 'summary across all accounts' hints at an aggregate rather than per-account listing, distinguishing it loosely from get_accounts. It never names a sibling or states the aggregate-vs-listing distinction explicitly, so differentiation is inferred rather than declared.

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 is no when-to-use guidance, no exclusion, and no named alternative. An agent must guess whether to call this, get_accounts, or get_budget_status to obtain balances; 'optionally converted' is the only conditional and it is not actionable.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds nothing further — no mention of what is returned, what happens when no budget exists for the category, or whether an unset budget yields an error or empty result.

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

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

One short, front-loaded sentence with zero filler. It is arguably too terse rather than padded, so the issue is under-specification, not verbosity.

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

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

There is no output schema, so the description is the only place to explain the return value, yet it says nothing about what a 'budget' contains (amount, period, spent-to-date) or not-found behavior. Given the close sibling get_budget_status, this gap makes correct tool selection harder.

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

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

Schema coverage is 100% with a single required category_id, so the schema carries the parameter documentation. The description's 'by category ID' merely restates it without adding format or source hints (e.g., where to obtain a category ID).

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

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

States a specific verb and resource (get a budget) plus the lookup key (category ID), which is enough to know what it does. It does not differentiate from the sibling get_budget_status, so an agent must infer whether this returns the budget configuration or its current usage.

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 is no indication of when to use this versus get_budget_status or set_budget, and no prerequisites or exclusions. The agent is left to guess based purely on the name.

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

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

Annotations already establish that this is a safe, read-only, idempotent operation. The description adds only the 'active budgets' scope and no details about return format, freshness, or pagination, so it provides modest additional context.

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

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

The description is a single short sentence with the key scope front-loaded and no wasted words.

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

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

For a simple, zero-parameter, read-only tool with full annotation coverage, the description is nearly complete. It does not explain the exact shape of 'progress/status,' but no output schema exists and the basic purpose is clear.

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

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

The tool has zero parameters, so there are no parameter semantics to explain. Per the baseline for parameterless tools, this is adequately specified.

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

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

The description uses a specific verb and resource: get budget progress/status. The scope 'for all active budgets' is clear, though it does not explicitly contrast with the sibling get_budget 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?

The description states what the tool returns but gives no guidance on when to use it versus alternatives like get_budget or spending_by_category. Usage is only implied by the tool name and scope.

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, non-destructive, and closed-world behavior, so the safety profile is fully covered. The description adds no behavioral context beyond that — it does not say whether archived/deleted or built-in default categories are included, nor how results are ordered.

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

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

A single front-loaded sentence with no filler or redundancy. Nothing is wasted, and the key scope qualifier ('all user categories') appears immediately.

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 read tool with rich annotations and no output schema, the description is minimally sufficient to trigger correct invocation. However, it does not describe the returned shape (which category fields come back) or inclusion rules for archived/default categories, which the missing output schema leaves undocumented.

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

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

The tool takes zero parameters, so there is no parameter semantics to document; the baseline for a no-param tool applies. The description's scope word 'user' is the only qualifier and is not developed, but no gap exists in the schema itself.

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

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

The description states a specific verb ('List') and resource ('user categories'), which is unambiguous and matches the tool name and title. It does not differentiate from nearby siblings like spending_by_category or create_category, but the read-only list intent is clear.

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

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

Usage is only implied by the verb 'List'; there is no explicit statement of when to prefer this over spending_by_category (which groups spending, not category definitions) or when category creation via create_category is warranted. An agent can infer the intent, but nothing is 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 declare readOnly, idempotent, closed-world and non-destructive behavior, so the safety profile is fully covered. The description adds genuinely useful context that the result is scoped to the authenticated user and mirrors a REST endpoint, but says nothing about error behavior for unknown/foreign ids or what the 'projection' contains.

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

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

Two short sentences with the action and scope front-loaded and the provenance/authorization note second; nothing is padded or repeated from the title.

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

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

A simple, well-annotated single-parameter read, so not much is required; but with no output schema the description could say what a session projection returns (state, steps, answers) or how it differs from get_work_session. It is adequate but leaves the return shape and sibling relationship unaddressed.

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

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

Single required sessionId parameter with 100% schema description coverage, so baseline is 3. The description only echoes 'by id' and adds no syntax, format, or source hint (e.g., where to obtain a sessionId) beyond the schema.

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

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

States a specific verb and resource ('Get an onboarding session projection by id'), which is unambiguous and distinct from list_work_sessions or start_onboarding. It stops short of naming which sibling to prefer in ambiguous cases, but the read-a-single-session purpose is clear.

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

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

No when-to-use / when-not-to-use guidance and no named alternatives, despite siblings like get_work_session, resume_onboarding, and list_work_sessions that an agent could easily confuse it with. The only usage constraint given is the implicit 'by id' and that it is scoped to the authenticated user.

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

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

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds only retrieval scope and does not disclose anything beyond annotations such as not-found behavior, authorization needs, or response shape.

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 a single front-loaded sentence with no wasted words. For a simple by-ID lookup, this is appropriately concise.

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 low-complexity lookup with complete schema coverage and rich annotations, the description is sufficient to select and invoke the tool. The only minor gap is that it does not describe the returned transaction shape, and there is no output schema to cover that.

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

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

Schema description coverage is 100% for the single transaction_id parameter, so the schema already documents it. The description adds only the phrase 'by ID', which is consistent but not materially richer than 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 description has a specific verb and resource, 'Get a single transaction', and scopes it by ID. This clearly distinguishes it from list/search/update/delete siblings, though it does not explicitly name those alternatives.

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

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

It implies use when a transaction ID is known, but provides no explicit when-to-use guidance, no alternatives such as list_transactions or search_transactions, and no prerequisites or not-found behavior.

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 closed-world, so the safety profile is covered. The description adds genuinely new context: it discloses the access boundary ('Scoped to the calling user') and the shape of the payload (current state plus outstanding pendingQuestions and onboarding progress), which an agent cannot learn from annotations.

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

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

Two sentences with no filler; the resource and lookup key lead, and the payload contents and access scope follow. Every clause carries information.

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

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

With no output schema, the description does the necessary work by naming the notable returned fields and the user scoping. Minor gaps remain, such as behavior for an unknown or foreign sessionId, but the essentials for a correct read-only call are present.

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

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

Schema coverage is 100% and the single parameter is fully documented as 'WorkSession id'. 'By id' in the description adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get the current state of a single work session by id') and enumerates what the response covers: pendingQuestions and onboarding progress. The word 'single' implicitly distinguishes it from the plural sibling list_work_sessions, but no sibling is named explicitly.

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

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

Usage is only implied — an agent can infer this is the tool for polling one session's state rather than enumerating sessions. There is no explicit guidance on when to choose this over list_work_sessions or get_onboarding_session, and no stated prerequisites.

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 safety (readOnly=false, destructive=false, openWorld=true), so the description's value-added context is the two-phase behavior (preview now, commit later), the returned importId + preview rows, and the side effect that a suggestedAccount gets auto-created on commit. That is meaningful disclosure beyond structured fields; only error/failure behavior is left unstated.

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

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

Four short telegraphic sentences, front-loaded with what it creates, followed by the return shape, the follow-up tool, and the mutation precondition. Nothing is redundant enough to cut.

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

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

For a nested 4-parameter mutation with no output schema, the description covers return values, workflow position, and the confirmation gate. It stops short of describing what the preview rows contain or how parse failures surface, which would matter for an agent building on the preview.

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 75%, and the description adds meaning the schema does not: it clarifies hint.accountId vs hint.suggestedAccount and, crucially, that the suggested account is created only at commit time. The content parameter's dual string/object form is restated rather than enriched, which keeps it below 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 ("Create a new Import") and immediately enumerates the two accepted input modes (raw string vs pre-parsed structured content). It also names the follow-up sibling commit_import, so the agent can place this tool in the workflow without guessing.

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?

"Use commit_import to persist" gives an explicit handoff to the correct next tool, and the returns-a-preview note clarifies this is a non-persisting staging step. It does not, however, say when to choose this over the other ingestion siblings like bulk_add_transactions or add_transaction_from_photo.

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

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

The annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the safety profile is covered; the description adds little beyond restating the confirmation flag that the schema already documents. Useful extra context is limited to the REST endpoint mapping and the fact that files are statements/receipts; it says nothing about what ingestion does (parsing, dedupe, draft state) or any file count/size limits.

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

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

Three short front-loaded sentences with the core action first, then the endpoint mapping, then the hard prerequisite. Nothing is padded, though the REST route reference earns only marginal space for an agent that cannot call REST directly.

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

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

For a mutation with no output schema, the description never says what the agent gets back or what state the session lands in after ingest (are transactions created? queued for commit_onboarding?), nor any constraint on file volume or accepted content types. An agent can fire the call but cannot predict or verify the outcome from this text.

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 75% and sessionId, confirmation and idempotencyKey are documented in the schema; the description's "statement/receipt files" adds semantic narrowing on what belongs in the undescribed files array. It adds nothing about batching, per-file requirements, or how contentBase64/contentType are interpreted, so 3 (schema does the heavy lifting) is right.

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 + target scope: ingesting statement/receipt files into an onboarding session, and pins it to the underlying REST route POST /api/onboarding/:id/ingest. It is clearly distinct from generic siblings like import_from_text or add_transaction_from_photo because it names the onboarding session as the destination, though it does not explicitly say so.

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?

"Requires confirmation: true" gives a hard prerequisite, and the mention of an onboarding session implies this belongs to the onboarding flow rather than the general import path. However, no sibling is named and there is no explicit when-to-use vs when-to-use-something-else (e.g. add_transaction_from_photo, import_from_text, commit_onboarding) guidance, so routing must be inferred.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely new behavioral context — results are scoped to the authenticated user and returned most recent first — but says nothing about pagination, limits, or result volume.

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

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

Two short sentences, zero padding, with the core behavior and ordering front-loaded before the optional filter detail.

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 simple single-parameter read tool with full annotation coverage and no output schema, the description covers identity scope, ordering, and the filter. Only pagination/limit behavior is absent, which is a minor gap for a notification list.

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

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

Schema coverage is 100% and the single parameter is already documented as "only unacknowledged notifications." The description's "Optional unreadOnly filter" restates rather than enriches that, so the schema does the heavy lifting.

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

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

States a specific verb and resource ("List the notifications") plus the scope (current authenticated user) and ordering, which lets an agent distinguish this from the write-oriented sibling acknowledge_notification. It stops short of naming that sibling explicitly.

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

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

Usage is only implied: an agent can infer this is the read path for notifications, and the optional unreadOnly filter is mentioned, but there is no explicit when-to-use guidance, no exclusion, and no pointer to acknowledge_notification for the follow-up action.

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

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

The annotations already declare readOnly=true, idempotent=true, destructive=false, openWorld=false, so the safety profile is fully carried by structured data and the bar is lower. The description adds no further behavioral context — nothing about default ordering, pagination behavior (even though limit/offset exist), or result volume — so it earns no credit above the annotated baseline.

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

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

A single well-formed sentence with no filler and the resource front-loaded. It is efficient, though the content is largely a recap of parameters the schema already documents.

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

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

For a 9-parameter tool with a nested date_range object and no output schema, the description is thin: it says nothing about return shape, default ordering, pagination semantics, or how results relate to search_transactions. An agent could invoke it, but not confidently predict or scope the output.

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 89%, so the schema already documents every filter, its format (ISO dates, IDs, substrings) and the limit default/max. The description's filter list merely restates the schema's parameter names and adds no semantics, so the baseline 3 applies.

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

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

Specific verb+resource (list transactions) with an enumeration of the filterable dimensions, which lets an agent recognize it as a filtered collection read. However, it never distinguishes itself from the sibling tools search_transactions or get_transaction, so an agent cannot tell from the description which one to reach for.

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?

'Optional filters for...' implies a retrieval-with-filtering use case and makes clear that all criteria are optional, but there is no explicit when-to-use/when-not guidance and no steering toward search_transactions versus this tool.

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, non-destructive and closed-world, so safety is covered. The description usefully adds the privacy constraint that other users' sessions are never returned, but says nothing about pagination, result ordering, or volume, which matters for a list endpoint.

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

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

Three short sentences, front-loaded with the operation and its key scoping constraint. Nothing is redundant or 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 simple two-optional-parameter read tool with full annotations and complete schema documentation, the description covers what it is and who sees what. Only list-shape concerns like pagination or result size are unaddressed, a minor gap.

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

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

Schema coverage is 100% with both parameters enum-documented, so the schema does the heavy lifting. The description's 'state/type filters' merely restates the parameter names without adding semantics such as whether filters combine or default behavior when omitted.

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

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

The description gives a specific verb and resource ('List the work sessions') plus a clear scope ('belonging to the current authenticated user'). It implicitly separates itself from the singular get_work_session sibling by being a list operation, but it never names a sibling to differentiate 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?

Mentioning 'Optional state/type filters' hints at how to narrow the results, but there is no explicit guidance on when to use this versus get_work_session or whether the filters are combinable. Usage is implied rather than stated.

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

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

Goes well past the annotations by disclosing exactly what the mutation produces (one ADJUSTMENT transaction sized to targetBalance − currentBalance), that there is no write when drift is zero, that the amount is denominated in the account's own currency, and that confirmation:true is a hard gate. These are precisely the behavioral facts an agent needs before invoking a destructiveHint=true 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?

Three tight sentences, front-loaded with the action, then mechanism, then the safety gate. No filler and nothing repeated from the schema verbatim.

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 mutation with no output schema, it covers currency, no-op semantics, and confirmation. It stops short of saying what is returned (drift amount, created transaction ID) or whether the adjustment can be undone, which are the remaining unknowns for an agent.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: the drift formula clarifies the sign/direction implied by targetBalance and the confirmation gate is restated as a precondition rather than a field. idempotencyKey behavior is left entirely to the schema.

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

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

States a specific verb and resource (reconcile an account to a target/statement balance) and explains the mechanism — computing drift and creating a single ADJUSTMENT transaction. This implicitly distinguishes it from update_account_balance, but no sibling is named explicitly, leaving the agent to infer the distinction.

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

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

Gives a clear use condition (account should match a statement/actual balance) and notes the no-drift no-op case, but never names alternatives such as update_account_balance or add_transaction, nor says when reconciliation is the wrong choice. Usage is implied rather than directed.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety and repeat-safety profile is known. The description adds little beyond that — 'Mirrors GET /api/onboarding/resume/:token' restates the read-only nature already covered by annotations, and says nothing about what state is returned or whether resuming mutates session progress.

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

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

Two short sentences with the action front-loaded in the first clause; nothing is buried or padded. The trailing sentence about mirroring the REST endpoint is low-value for an agent but short enough not to hurt.

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

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

With no output schema, the description should indicate what a resume returns (session state, next unanswered question, or completion status) since that governs what the agent does next. Annotations cover safety and the schema covers the only parameter, but the result shape and the relationship to commit_onboarding/submit_onboarding_answer remain unexplained.

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?

There is a single required parameter with 100% schema description coverage, so the schema already documents resumeToken. The description only restates that the token is the key, adding no format, source, or validity information beyond the schema — baseline 3 applies when the schema does the work.

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 ('Resume an onboarding session by resume token'), which is more concrete than a bare name restatement. However it does not distinguish itself from close siblings like get_onboarding_session or start_onboarding, so an agent must infer the difference between resuming, fetching, and starting a session.

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

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

Usage is implied by 'by resume token' — the agent knows it needs a token in hand — but there is no explicit statement of when to prefer this over get_onboarding_session or start_onboarding, and no exclusions or prerequisites (e.g., token expiry, whether the session must already exist).

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=false, so the safety profile is fully covered by structured data. The description adds nothing beyond that: no mention of what the query can express, how many results come back, or whether the search spans all accounts.

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

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

A single short sentence with the core intent front-loaded and no filler. It is efficient, though its brevity contributes to the missing usage and scope detail rather than being a virtue on its own.

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 search tool with no output schema, the description should at least hint at result shape or scope (which accounts/categories, any result limit, ordering). It provides none, leaving an agent unable to predict what comes back or how to phrase constraints.

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

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

Schema coverage is 100% and there is only one required parameter, so the schema does the documenting. The description adds a small nuance by framing the input as free-form natural language rather than structured filters, but that is largely redundant with the parameter name and schema text.

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

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

States a specific verb (search) and resource (transactions) plus the query modality (natural language), which lets an agent distinguish it from a plain retrieval tool. However, it never contrasts with the obvious sibling list_transactions, so the boundary is left implicit.

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

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

No when-to-use or when-not-to-use guidance at all. With list_transactions, find_anomalies, spending_by_category and spending_by_merchant in the sibling set, an agent gets no help deciding which to pick for a given question.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true, so safety is covered. The description adds the concrete confirmation:true execution gate, which is useful, but does not explain what the destructive aspect means (does an existing budget get overwritten? is it keyed by category+period?) or what is returned. With annotations carrying the safety profile, this is adequate but not rich.

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

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

Two short sentences with the core action front-loaded and zero filler. It is appropriately sized for the tool, though the second sentence is a gate rather than added semantic depth.

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, idempotent mutation with six parameters and no output schema, the description covers the confirmation gate but omits outcome semantics: whether an existing budget is replaced wholesale, how category/period combination identifies the target, and what a caller observes on success. Annotations and schema fill much of the gap, so it lands at adequate rather than inadequate.

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 83%, so the schema already documents amount, period, name, confirmation, and idempotencyKey; only category_id is undocumented and the description's 'for a category' partially compensates. The description adds no format or uniqueness semantics beyond the schema, so the baseline 3 applies.

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

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

States a specific verb pair (create or update) and resource (budget) scoped to a category, which clearly separates it from read siblings like get_budget and get_budget_status. It does not explicitly name those siblings, but the mutation framing is unambiguous.

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

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

The description says nothing about when to use this versus get_budget/get_budget_status or create_category, nor does it state any prerequisites beyond the confirmation flag. The confirmation requirement is a gate, not usage guidance; an agent must infer when budget-setting is appropriate from context alone.

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 explicitly warns the call is not read-only and discloses the concrete side effects — lazy provisioning of the referral code and enrolment of a Freemius affiliate plus coupon on the first eligible call. This reconciles neatly with readOnlyHint=false, idempotentHint=true (effects fire only once) and openWorldHint=true (external Freemius service), giving the agent real cost/consent context.

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

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

Two sentences, both earning their place: the first front-loads the returned fields, the second front-loads the side-effect warning with 'Not read-only'. No filler, no restatement of the tool name or title.

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

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

With no output schema and no parameters, the description carries the burden of describing the return value and does so by naming every field. It also covers the mutation behaviour an agent must know about before invoking it, so 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?

Zero parameters and 100% schema coverage, so there is nothing to document; the baseline of 4 applies. The description correctly spends no space restating an empty input 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?

A specific verb-plus-resource with the exact return payload enumerated: referral code, registration URL, friends coupon code, and three named stats. No sibling tool in the list touches referrals, so there is no ambiguity to resolve, and the agent knows precisely what it gets back before calling.

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

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

Usage is only implied — an agent can infer this is the tool for surfacing a user's referral/friends programme info, and there are no alternatives to disambiguate against. It does not state prerequisites (e.g. whether the user must be logged in, or what makes a call 'eligible'), which is the only real guidance gap.

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, and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that: it doesn't say whether uncategorized transactions appear as a bucket, how categories are keyed, or how totals are shaped, which for an aggregation tool is where the real ambiguity lives.

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

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

A single front-loaded sentence with no filler or repetition. It is efficient, though its brevity is partly the source of the gaps in the other dimensions.

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 simple two-param read tool with full schema coverage and complete annotations, the essentials are present. But with no output schema, the description should say roughly what an aggregated-by-category response looks like, and it doesn't.

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

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

Schema coverage is 100%, with both start and end documented as ISO YYYY-MM-DD, so the schema carries the load. 'For a date range' adds nothing the schema doesn't already provide, making the baseline 3 correct.

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

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

The description states a specific verb and resource ('Get spending aggregated by category'), so an agent knows exactly what it returns. It does not, however, distinguish itself from the near-identical sibling spending_by_merchant, which a one-clause contrast would have settled.

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

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

The only usage signal is the phrase 'for a date range', which restates the required params. There is no statement of when to prefer this over spending_by_merchant, list_transactions, or search_transactions, all of which could surface overlapping data.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world behavior. The description adds aggregation and date-range scope, but does not describe return shape, pagination, auth needs, or rate limits; with annotations covering safety, a 3 is appropriate.

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

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

A single front-loaded sentence with the verb and resource stated immediately. It contains no boilerplate and is appropriately sized for a simple two-parameter 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?

The tool is simple and read-only, with annotations covering safety and the schema covering both required parameters. However, there is no output schema, and the description does not explain the aggregation return shape or fields, leaving a notable gap.

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

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

Schema description coverage is 100%, and start/end are already documented as ISO YYYY-MM-DD dates. The description only restates the date-range concept and adds no syntax or meaning 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 ('Get spending'), a specific aggregation resource ('by merchant/description'), and a scope ('for a date range'). The merchant/description grouping differentiates it from the sibling spending_by_category aggregation.

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 no explicit when-to-use guidance, prerequisites, or routing to alternatives such as spending_by_category. The intended usage is only implied by the aggregation dimension.

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

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

Annotations already declare this is a non-destructive, open-world mutation. The description adds real value by disclosing the confirmation gate ('Requires confirmation: true to create the session') and the underlying REST endpoint. It does not explain what a started session returns (session id? first question?) or what happens if a session already exists, so the behavioral picture stays incomplete.

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

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

Three short sentences, front-loaded with the action and input. 'Mirrors POST /api/onboarding/start' earns less of its place than the confirmation requirement, but it is one clause and aids debugging.

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

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

With annotations and a fully described 4-param schema, the core call contract is covered. What is missing is the outcome: nothing tells the agent that starting yields a session handle needed by submit_onboarding_answer or get_onboarding_session, which is the obvious next step an agent must take.

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

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

Schema description coverage is 100%, so all four parameters are already documented, including the confirmation gate and the idempotency-key caching behavior. The description only restates situationText and confirmation, adding no syntax, format, or length guidance beyond the schema.

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

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

States a specific verb and resource ('Start an onboarding session') and names the input it consumes ('from situation text'). It implicitly distinguishes itself from resume_onboarding and commit_onboarding via the word 'start', but never explicitly routes the agent away from those siblings.

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

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

Usage is implied rather than stated: it is the entry point that takes free-text situation input, and it names the confirmation prerequisite. There is no explicit 'use this instead of resume_onboarding when…' guidance and no note on what to do after starting.

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 state that this tool is a mutation, not destructive and not idempotent, and the description adds that a confirmation flag is required and that the tool mirrors a REST endpoint. These additions are useful. However, they do not say what happens to the session after an answer is accepted, whether existing answers are overwritten, or what the caller gets back.

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

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

Two short sentences lead with the action, and the confirmation requirement follows immediately. 'Mirrors POST /api/onboarding/:id/answer' adds developer-facing detail that an agent gains little from. Aside from that sentence, it is lean.

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?

This is a 5-parameter mutation with no output schema and no annotation-level detail about side effects. The description covers the action and the confirmation gate, but it says nothing about what a successful submission returns (for example, the next question) or whether a wrong answer can be corrected.

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

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

Schema coverage is 100% and every parameter, including the optional idempotencyKey and the 24-hour cache scope, is documented in the schema itself. The description adds only the redundant 'Requires confirmation: true' restatement and no new semantics for sessionId, questionId, or answer, so the baseline 3 applies.

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

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

The description names a specific verb and resource: submit an answer to a generated onboarding question. It is clear what the tool does, but it never distinguishes itself from the near-identical sibling submit_work_session_answer, so the agent has to infer which question-answering tool applies to which context.

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

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

The description gives no when-to-use guidance, no prerequisites beyond the confirmation flag, and no exclusions. It does not say which sibling to use first (get_onboarding_session for the question, ack/commit tools for the session lifecycle), so the sequencing of this tool must be inferred from the sibling list.

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 non-read-only, non-idempotent, non-destructive, closed-world. The description adds real value beyond that: it discloses the side effect that remaining questions may be regenerated and that a confirmation flag is mandatory. It does not, however, explain when regeneration is triggered or what happens to previously answered questions.

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

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

A single compact sentence with the key action and its confirmation gate front-loaded. The parenthetical is dense but not wasteful; there is no padding to cut.

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

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

For a mutation tool with no output schema, the description leaves the most consequential behavior vague: 'possibly regenerate the remaining questions' gives no condition, scope, or consequence for existing answers. An agent can call it, but cannot predict what it changes.

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

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

Schema description coverage is 100%, so all four parameters are already documented, including the confirmation precondition. The description restates the triple and the confirmation requirement without adding new syntax or format detail, so baseline 3 applies.

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

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

States a specific verb (Record) and resource (an answer against a work session question) and names the identifying triple sessionId/questionId/answer. The 'work session' framing implicitly separates it from submit_onboarding_answer, but no sibling is named explicitly.

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

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

The prerequisite 'Requires confirmation: true to execute' is stated, which is useful context, but there is no guidance on when to choose this over submit_onboarding_answer or how it fits into the broader work-session flow (commit_work_session, get_work_session). Usage is only implied.

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

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

Annotations already flag destructive, idempotent, and non-read-only behavior, but the description adds valuable detail: it creates a signed ADJUSTMENT transaction for the difference, is a no-op when unchanged, rejects exchange-managed accounts, and requires confirmation. There is no contradiction with the annotations.

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

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

Three compact sentences are front-loaded with the action and then cover side effects, constraints, and execution requirements. Every sentence adds useful 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?

For a destructive balance mutation with no output schema, the description supplies the key behavioral details an agent needs: adjustment transaction creation, no-op behavior, account-type exclusion, and the confirmation requirement. It is complete enough to call correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds meaning beyond the schema by explaining the consequence of the balance value and the no-op behavior when unchanged, though it leaves idempotencyKey entirely to 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 description uses a specific verb and resource: set an account's balance to a new value. It also explains the resulting side effect, a signed ADJUSTMENT transaction for the difference, which distinguishes it from add_transaction and reconcile_account.

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

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

It gives clear usage context by requiring confirmation: true and explicitly rejecting exchange-managed accounts as a when-not condition. It does not name sibling alternatives such as reconcile_account, so it falls short of full alternative 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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description usefully surfaces the mandatory confirmation gate that must be set before execution, but it says nothing about partial-update semantics — critically, whether omitted fields (amount, category_id, date, notes) are preserved or cleared — nor about reversibility or audit effects for a destructive 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?

Two short sentences with the core action first and the execution prerequisite second — nothing is padded or buried. The terseness is close to under-specification rather than bloat, but structurally it is efficient and front-loaded.

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

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

For an eight-parameter destructive mutation with no output schema and 25% schema coverage, the description leaves far too much implicit: partial-update behavior, required permissions, what the response contains, and the meaning of most parameters. The confirmation note is a good start but does not carry the burden the thin schema and annotations place on it.

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

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

Schema description coverage is only 25%: of eight parameters, only confirmation and idempotencyKey carry descriptions, and the description text merely echoes the confirmation rule already stated in the schema. Six parameters (date, notes, amount, category_id, description, transaction_id) are undocumented in both places, including whether transaction_id identifies the record and whether nulls clear values.

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?

"Update an existing transaction" names the verb and resource, but it is essentially a restatement of the tool name and title, adding only the word "existing." It does not distinguish the tool's scope from siblings like add_transaction, delete_transaction, or bulk_add_transactions beyond what the name already implies.

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 is no guidance on when to reach for this tool versus add_transaction (for new records), delete_transaction (for removal), or get_transaction/list_transactions (for reads). The only usage-adjacent statement is the confirmation requirement, which is a gate rather than a routing rule.

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