categorize-transactions

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 safe read-only profile is covered. The description adds behavioral value beyond annotations by specifying the output contents and the conditional nature of the closing balance ('when the file carried one'), which is useful context an agent cannot infer from structured data.

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

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

Two sentences, zero waste. The first sentence front-loads the action and output fields; the second provides routing guidance. Every clause earns its place, including the conditional closing-balance caveat.

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 list tool with full annotation coverage and no output schema, the description carries the necessary burden: it documents the return contents, notes the conditional field, and tells the agent where to start in the workflow. Nothing needed for correct invocation is missing.

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

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

The tool has 0 parameters, so the baseline is 4 per the rubric. The description adds no parameter semantics (none exist) but does add scope context by clarifying it lists 'imported' accounts rather than all possible accounts.

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 ('List') and resource ('imported accounts'), then enumerates the exact fields returned: bank, currencies, transaction count, first/last date, and closing balance. It also differentiates from siblings by positioning itself as the source of account names for transactions_list and statement_export.

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 closing sentence gives explicit usage context: 'Start here for the account names transactions_list and statement_export take.' This tells an agent when to use this tool relative to two named alternatives, but it does not state exclusions or cover the other 12 siblings.

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

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

Annotations already flag destructiveHint=true, and the description adds the genuinely useful consequence: only the file goes away, while transactions_list and the summary still see the imported transactions. It stops short of stating irreversibility or what happens if the name doesn't match.

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, zero filler, with the destructive scope stated first and the data-retention caveat immediately after.

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 description covers the main blast-radius question but omits how to identify the target file and what an unknown name returns, leaving the agent to guess at invocation 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?

The single required parameter `name` has 0% schema description coverage, and the description never clarifies whether it is a filename, an ID, or where to obtain it (maxLength 70 hints at a filename but the schema says nothing). With one undocumented required param, the description should compensate and does not.

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

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

States a specific verb and resource: "Delete one statement file stored for your token." That is unambiguous and separates it from bank_upload and bank_files by action, though it never names those siblings 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 note that imported transactions survive gives an implicit condition for using it (cleanup without data loss), but there is no explicit when-to-use/when-not guidance and no pointer to bank_files for discovering the file name.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful context by stating that files are scoped to the caller's token and that sizes are returned. However, it does not describe ordering, pagination, or any return-shape details beyond file sizes.

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, efficient sentence with zero waste. The core operation and useful detail, file sizes and token scoping, are front-loaded 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 zero-parameter, read-only listing tool with annotations covering safety, the description is largely complete. It states what is listed and that sizes are included. The main omission is return-shape detail such as ordering or pagination, but given the low complexity and full annotation coverage, this is a minor gap.

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

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

The tool has zero parameters, so parameter semantics are inherently simple. The schema is empty and schema description coverage is 100%, so there are no undocumented parameters for the description to compensate for. A baseline of 4 is appropriate for a zero-parameter tool.

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: 'List the statement files stored for your token, with their sizes.' This clearly identifies the tool as a read operation over uploaded statement files. It does not explicitly distinguish itself from sibling tools such as bank_upload, bank_delete_upload, or statement_summary, 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 description gives no guidance on when to use this tool versus alternatives. It does not mention when to prefer bank_files over statement_summary, statement_import, or bank_upload, nor does it state exclusions or prerequisites. At best, the purpose implies a simple listing use case, but no explicit usage guidance is provided.

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?

Far beyond the annotations: 10 second fetch timeout, max 3 redirects, public http(s) only, 1 MB fetch cap, delimited-text-only validation (PDFs refused), 256 KB request body cap, and per-token persistence between calls. The gap is the destructiveHint=true annotation — the description never says what an upload with an existing name does to the prior file, nor does it explain the idempotency the annotations claim.

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 critical constraint — upload once, pass `name` as `path` downstream — is front-loaded, and the three-way content choice follows immediately. It is dense and sentence-heavy, but nearly every clause carries a limit or exception an agent would otherwise get wrong.

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

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

Complete on inputs and on the downstream workflow, including the caps that force chunking a large export by month, which is exactly the trap an agent would hit. With no output schema, however, the description never says what comes back (a confirmation? the stored name? a file listing?), which is the one thing an agent must guess.

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

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

Schema coverage is 100%, so the schema already documents all four parameters, which sets the baseline at 3. The description does add real value on top (mutual exclusivity, header row required, why base64 exists), but it stops short of adding anything the schema descriptions don't already imply.

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 and resource ('Send a bank export to this hosted endpoint') with the crucial reframing that there is no filesystem, so the file is uploaded once and referenced by name in statement_import. This cleanly separates it from statement_import, bank_files and statement_export without opening their schemas.

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

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

States the selection rule explicitly — 'exactly one of content, content_base64 or url' — and gives the conditions that pick each: plain text/CSV is the normal case, base64 for UTF-16 Excel exports, url recommended above ~10 KB instead of pasting base64. It also routes lifecycle questions to the siblings bank_files and bank_delete_upload.

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 transparently states that passing rules REPLACES the whole stored list, but the annotations declare destructiveHint=false. Replacing an entire stored list is an overwriting/destructive operation, so the description contradicts the annotations, which is a serious inconsistency.

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

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

The description is compact and front-loaded, with every sentence carrying useful operational information. The replacement semantics, matching behavior, safety constraint, and rule limit are all stated without filler or repetition.

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

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

The description covers the key behavioral details and the schema fully documents parameters, but the 'Free: 5 rules' phrase is ambiguous about what happens when more than five rules are supplied. The destructive nature of replacement is also contradicted by the annotations, which undermines the completeness of the context.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds meaningful semantics beyond the schema: plain matches are substrings, regexes that can backtrack exponentially are refused, empty matches are rejected, and there is a 5-rule limit. This helps the agent understand validation behavior not captured 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 clearly identifies the resource (category rules) and the two operations supported: reading the current rules or replacing the whole list. It does not explicitly distinguish itself from siblings, but the resource and operation semantics are specific enough that the agent can tell it apart from the listed tools.

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

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

The description explains what a caller can do but gives no guidance on when to choose this tool over alternatives, such as transaction_categorize, nor any when-not-to-use conditions. There are no exclusions or routing hints to other siblings.

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 indicate this is not read-only and not destructive, and the description adds useful behavioral detail: existing data under the token stays, and a wrong or expired key changes nothing. This goes beyond the annotation hints by explaining failure semantics and safety of the operation.

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

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

The description is two sentences with no filler. It front-loads the core action, then gives the key format and safety guarantees, and closes with the verification tool. Every sentence contributes essential information.

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

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

For a single-parameter activation tool with annotations covering the safety profile, the description is complete: it states what the tool does, what input is needed, what happens on failure, and how to confirm success. There is no missing critical information for an agent to call it correctly.

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

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

The schema already documents the key parameter and its format with 100% coverage. The description adds meaning by specifying that the key must be issued at checkout for this server or the bundle, which clarifies validity requirements not present 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: it 'turns Pro on' for the connection using a license key. It also distinguishes itself from the sibling license_status tool by saying license_status confirms the activation. This leaves no ambiguity about what the tool accomplishes.

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 provides clear context for use: the key must be an MCPL1.<payload>.<signature> issued at checkout for this server or the bundle. It does not explicitly list exclusions or alternative tools, but it does reference license_status as the confirmation path, giving the agent a sense of the workflow.

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. The description adds useful context beyond annotations by specifying the JSON response contents and stating 'nothing changes,' reinforcing the read-only nature of the call.

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

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

Two dense sentences cover output, purpose, usage context, and side-effect guarantee. Every sentence earns its place and the most important information is 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?

With no output schema, the description sufficiently describes the return value. With no parameters, annotations covering safety, and a clear use case, nothing essential is missing for an agent to invoke this tool correctly.

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

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

There are zero parameters and the schema already fully documents that fact. The description explicitly says 'No arguments,' which is accurate and reinforces the schema without needing further elaboration.

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 begins with a specific verb ('Report') and a precise resource ('this endpoint's licence state for your token'), and enumerates the exact output fields: product, tier, reason, and checkout URL. This clearly distinguishes it from sibling tools like license_activate.

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

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

The description explicitly states when to call it: 'Call it to explain a free-tier refusal.' This is clear contextual guidance, though it does not name alternatives or explicitly state when not to use it.

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

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

The description states 'Read-only,' but the annotations set readOnlyHint=false, which is a direct contradiction. No other behavioral details are disclosed beyond the report categories and plan 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?

The description is compact and front-loaded: matching rule, outputs, read-only claim, and plan limitation are all in a few sentences. There is no filler or redundant restating of the tool name.

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

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

The description covers output categories and plan constraints, and the schema covers the parameters. However, with no output schema and the contradictory read-only claim, the actual behavioral profile is unclear, and the Free-tier limit behavior is underspecified.

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 parameters are already documented. The description adds matching semantics like 'same currency and amount, date within a few days,' but it does not meaningfully clarify the individual parameters 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 names a clear operation: match bank debits against mcp-expense-tracker entries using currency, amount, and date proximity. It also lists the report outputs, which distinguishes it from sibling list/import/export tools.

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 a clear context for when to use the tool: reconciling bank debits with ledger entries and seeing unmatched items. It does not explicitly name sibling alternatives or exclusion conditions, but the intended niche is easy to infer.

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 are all present but largely negative, so the description still carries the burden of behavioral disclosure. The description does add useful context by describing the result composition and the free-tier limit, but it does not state whether the tool has side effects, consumes quota, or requires licensing. No contradiction with the annotations is present.

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

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

The description is compact and front-loaded with the primary action ('Find charges that come back') followed by the useful output dimensions. The wording is slightly dense with several comma-separated output attributes, but there is no filler and every sentence earns its place.

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

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

For a moderate-complexity tool with three well-documented parameters and no output schema, the description provides enough context: it names the grouping logic, output fields, and the free-tier limit. It does not spell out output formatting or edge cases, but the key invocation-relevant behavior is covered.

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 each parameter already has a meaningful description, so the description is not required to repeat parameter details. The description adds no per-parameter semantics beyond what the schema provides; the free-tier note is a service limitation rather than parameter meaning.

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

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

The description uses a specific verb and resource: it 'find[s] charges that come back' and identifies subscriptions/recurring debits grouped by counterparty and currency. It clearly conveys the tool's purpose without naming sibling tools, so it is clear but does not explicitly differentiate itself from siblings like transactions_search or statement_summary.

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 about when to use this tool versus alternatives such as transactions_list, transactions_search, or statement_summary. The 'Free: 3 months, 5 charges' line is a limitation/constraint rather than a usage guideline, and no explicit when/when-not conditions are provided.

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, but the description adds non-redundant behavioral specifics: 'return a download link valid for one hour' and 'Nothing partial is ever written.' These go beyond the annotations, offering an atomicity guarantee and output lifetime that an agent would otherwise not know.

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

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

Two sentences, front-loaded with the core action and key details, followed by a usage statement. No filler. The description is compact and every clause earns its place.

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

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

No output schema exists, but the description explicitly explains the return value (a download link valid for one hour) and the file formats. It also covers the intended use case. Given the tool's simplicity and full schema coverage, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% and the descriptions for from, to, format, path, account, and category are already clear. The description does not add meaning beyond what the schema provides – it only restates the date range and formats. With full schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the action (export), the resource (bank transactions), the date range scope, and the file formats (.csv/.json). It also explicitly positions the tool as the one for 'export September' once a statement has been imported, distinguishing it from sibling tools like statement_import or transactions_list.

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

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

Provides explicit context for when to use: 'once a statement has been imported.' This gives a clear precondition and implies the alternative (statement_import) without naming it. The format guidance ('csv for a spreadsheet, json for a program') further clarifies usage decisions.

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 goes beyond the all-false annotations by disclosing line-level deduplication ('stored lines skipped'), locale-sensitive amount parsing, and the detected/stored/skipped return summary. It does not contradict the annotations: idempotentHint=false is not incompatible with this line-level dedupe claim.

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 deliver the purpose first, then parsing/dedupe behavior and return value. Every sentence adds useful information, and there is no repetition of schema content.

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 appropriately summarizes the return as detected/stored/skipped and covers key runtime behaviors. It does not mention the bank_upload prerequisite in prose, though the schema's path parameter does; this is a minor gap given full schema coverage.

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?

All five parameters already have rich descriptions in the schema, so the baseline is 3. The description adds file-format context such as header detection and locale behavior, but does not add per-parameter meaning beyond what the schema already 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 action: 'read a bank CSV into the local ledger' and names the key outcome counts. This clearly distinguishes importing from sibling operations like bank_upload or statement_export, even without naming them.

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 opening phrase 'Call this tool to read a bank CSV into the local ledger' provides a direct trigger condition. It does not explicitly compare with alternatives or list when-not-to-use cases, but the intended context is clear.

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

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

Annotations already cover read-only and non-destructive behavior. The description adds useful behavioral detail beyond annotations: totals are per currency, never summed or converted, and the source is the bank account. This helps the agent understand output semantics without contradicting the annotations.

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

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

The description is three short sentences: function, use case, and a key caveat. Every sentence earns its place and the essential purpose is front-loaded. No redundant or filler content.

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

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

Given the rich schema and annotations, the description covers the core behavior, grouping, currency handling, and an example use case. There is no output schema, so a bit more detail about the exact return shape could help, but the description already conveys that results are grouped totals per currency.

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 like from, to, top, account, and group_by are already fully documented. The description adds no parameter-level detail beyond the schema, which matches the baseline of 3 for complete 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 clearly states the tool summarizes spent/received amounts over a date range for the bank account, with explicit grouping options (category, month, account, counterparty). This distinguishes it from transaction-level siblings like transactions_list and transactions_search by emphasizing aggregation and grouping.

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 a concrete use case ('what did I spend in August') and notes the prerequisite that data must be imported. It provides clear context for when this tool is appropriate, though it does not explicitly name alternatives or state when not to use it.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false. The description adds valuable behavioral context: 'Every id is checked first, so one unknown id refuses the whole call.' This discloses an all-or-nothing validation behavior that is not visible in the schema or annotations. It doesn't mention side effects or permissions, but the annotations cover the safety profile, so a 4 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?

Three sentences with zero waste. The core action is front-loaded, the all-or-nothing behavior is stated, and the sibling distinction is given. Every sentence earns its place.

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

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

For a two-parameter tool with 100% schema coverage and annotations covering the safety profile, the description is nearly complete. It explains the one-off use case, the validation behavior, and the alternative. It doesn't describe the return value, but there is no output schema and the tool is a simple mutation, so this is a minor gap.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds the semantic that 'category' can be cleared by passing an empty string, which is already in the schema ('Pass an empty string to clear it'). The description doesn't add much beyond the schema, so baseline 3 is 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 ('Set or clear'), a specific resource ('category on transactions by id'), and explicitly contrasts itself with category_rules ('matches by text instead'). This clearly distinguishes it from the sibling tool category_rules, which is the main alternative for categorization.

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

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

The description explicitly says when to use this tool: 'for a one-off no rule is worth writing for.' It also names the alternative (category_rules) and the condition that selects it ('matches by text instead'). This gives an agent clear 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 readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds the behavior that totals are per currency and never summed across currencies, which is useful. It does not describe pagination or sorting, but these are not essential given the schema's limit parameter and the tool's straightforward nature.

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 sentences with zero waste. It front-loads the core purpose (listing transactions in a date range) and immediately provides the key behavioral caveat about currency totals. No redundant phrases.

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

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

Given the absence of an output schema, the description could be expected to explain the return format, but as a list tool the return is self-evident. It covers the main functionality, optional filters, and the currency behavior. It does not mention pagination, but the limit parameter in the schema addresses row counts.

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

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

The schema descriptions cover all six parameters with clear explanations (e.g., ISO dates, default values, limit behavior). The tool description does not add meaning beyond the schema, so it meets the baseline of 3 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 clearly states it lists stored transactions in a date range with optional filters for account, category, or uncategorized. The verb 'list' distinguishes it from the sibling 'transactions_search', though the description does not explicitly call out this differentiation.

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

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

The description implies usage for listing transactions in a range with optional filters, but it does not explicitly state when to prefer this tool over alternatives like transactions_search or statement_summary. There is no mention of exclusions or when not to use it.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description adds materially useful behavioral detail: case-insensitive substring matching, literal (non-regex) matching, and the safety consequence that bracket-containing queries cannot hang the server. This shapes how an agent should construct queries and calibrates expectations.

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 description is a single front-loaded sentence that states the core behavior first and then adds a precise, relevant caveat about regex behavior. Every part earns its place; there is no filler or repetition of schema content.

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 covering the safety profile and schema covering all parameters, the description is sufficient for an agent to invoke this simple search tool correctly. It does not describe the return shape or ordering, but the tool's behavior is straightforward and the lack of an output schema lowers the burden.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by clarifying that the query parameter is matched as a case-insensitive substring against four specific fields, which the schema does not state. It does not add anything about to/from or limit, but those are already adequately documented 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 ('Find') and resource ('transactions'), and explicitly enumerates the searchable fields: description, counterparty, category, or account. It clearly communicates the tool's purpose, though it does not explicitly name sibling tools to differentiate from them.

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 this is the right tool when you need to locate transactions by text contained in certain fields, but it gives no explicit guidance about when not to use it or how it compares to transactions_list or statement_summary. The 'never a regex' note is a behavior constraint, not usage guidance.

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