Server Quality Checklist

Tool Scores

• get_spending_breakdownB
  3.2/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, so the read-only nature is known. The description adds useful context about minor units, category label resolution, confirmed-category bucketing with an 'uncategorised' fallback, and null household views. However, it describes 'views' without a corresponding parameter in the schema, which is confusing and potentially misleading about how to select a view.

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

  Conciseness3/5

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

  The description is relatively short, but the 'Views:' portion is long and lists definitions for four views without explaining how they are selected or returned. It could be more concise and better aligned with the actual schema.

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

  Completeness2/5

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

  For a tool with no output schema, the description explains some return details (per-month, minor units, category labels, uncategorised) but leaves the view structure unexplained. It is unclear whether the tool returns all views or requires a view selection that is not present in the input schema, which is a significant gap for an agent comparing this tool to siblings.

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

  Parameters3/5

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

  The schema fully describes the only parameter 'months' with format and default. Description coverage is 100%, so the description adds no additional parameter meaning beyond what the schema already provides, resulting in the baseline score.

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

  Purpose4/5

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

  The description clearly states the tool returns per-month income and spending totals broken down by category, with units and label resolution. However, it does not explicitly distinguish this from sibling tools like get_categorisation_stats or aggregate_transactions, and the 'views' detail introduces some ambiguity about the tool's scope.

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

  Usage Guidelines3/5

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

  The description implies usage for monthly income/spending breakdown by category but provides no explicit guidance on when to use this tool versus alternatives, nor any exclusions or when-not-to-use conditions.

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

• get_vitalsA
  3.7/5.0
  Behavior4/5

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

  Beyond the readOnlyHint annotation, the description adds meaningful behavioral details: values are in 'minor units,' each section has personal/household views with household potentially null, and metrics are defined with calculation context (e.g., rolling average, month-end cash balance). It doesn't cover edge cases like missing data, but the added null behavior and view structure are useful context beyond the annotation.

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

  Conciseness5/5

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

  The description is a single, information-dense sentence that efficiently defines every metric and notes the view structure and units. It is front-loaded with the resource name and contains no filler or redundancy, earning its length.

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

  Completeness3/5

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

  The description thoroughly defines the output metrics and view structure, but it leaves ambiguity about whether the result covers a single month or multiple months (since the 'months' parameter is an array), and what the top-level return shape looks like. With no output schema, the description should clarify this aspect to be fully complete.

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

  Parameters3/5

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

  The schema fully describes the only parameter 'months' (format, default), so schema coverage is 100%. The description does not mention this parameter at all, which is acceptable per the baseline rule; it neither adds nor detracts from the schema's explanation of parameter semantics.

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

  Purpose4/5

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

  The description clearly enumerates the specific metrics (monthlySurplus, steadyOutgoings, addingWealth, emergenciesCovered) that this tool returns, distinguishing it from sibling tools like get_net_worth or get_spending_breakdown. However, it lacks an explicit verb like 'returns' or 'retrieves,' presenting the resource as a noun phrase instead.

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

  Usage Guidelines3/5

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

  The description implies that this tool is for reviewing monthly financial health by defining the vitals, but it does not provide explicit guidance on when to use it over alternatives, nor does it state any exclusion conditions. Usage context is inferred rather than stated.

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

• list_holdingsA
  4/5.0
  Behavior4/5

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

  With readOnlyHint=true, the description adds value by explaining the scope ('on the balance sheet') and defining key response fields (ownershipPercent, latestValue). This clarifies what data the user will receive. It does not address pagination or ordering, but the read-only annotation already covers the safety profile.

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

  Conciseness5/5

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

  The description is two sentences, concise and front-loaded with the core purpose. The first sentence lists what is included, the second defines two important fields. Every word adds value with no redundancy or filler.

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

  Completeness4/5

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

  Given the tool's simplicity (one optional param, no output schema), the description provides enough context: it specifies what holdings are included, the optional filter, and the meaning of two key fields. It does not explicitly state that omitting nature returns both types, but 'All holdings' implies this. The lack of an output schema is mitigated by the field definitions.

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

  Parameters3/5

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

  Schema description coverage is 100% for the only parameter 'nature', which already explains its purpose and enum values. The description does not add any additional parameter semantics beyond what the schema provides. It does mention asset and liability categories that align with the enum, but this is redundant.

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

  Purpose5/5

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

  The description clearly states what the tool does: it lists all holdings on the balance sheet, distinguishing assets and liabilities with examples. The verb 'list' is implicit in the name and the description's 'All holdings' makes the purpose unambiguous. It also differentiates from sibling tools like list_accounts (accounts vs holdings) and get_holding (singular vs plural).

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

  Usage Guidelines3/5

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

  The description implies usage: use this tool to get a full list of holdings, optionally filtered by nature. However, it provides no explicit guidance on when to choose this over alternatives like list_accounts or get_holding, nor does it mention any exclusions. The context of siblings is present but the description itself does not reference them.

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

• get_top_merchantsA
  4.2/5.0
  Behavior4/5

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

  Despite readOnlyHint=true annotation, the description adds meaningful context: it restricts to DEBIT items, defines valueMinor as total spend in minor units, and hints at a time window. These details go beyond what the annotation alone gives, without contradicting it.

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

  Conciseness5/5

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

  The description is concise, using two sentences with zero waste. It front-loads the main purpose and then clarifies the spend unit, making it easy to parse quickly.

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

  Completeness4/5

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

  With no output schema and only two optional parameters, the description covers the core output fields (merchants, spend, visits, category) and relevant details like DEBIT and valueMinor. The only minor gap is the ambiguity of 'window', but overall it is sufficiently complete for selection and invocation.

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

  Parameters3/5

  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 does not add extra meaning about the parameters; it only explains valueMinor, which is a return field, not a parameter. Thus no additional value beyond the schema.

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

  Purpose5/5

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

  The description clearly states the tool retrieves the user's most visited merchants by spend, specifying DEBIT items, visit counts, and category. This is a specific verb+resource that distinguishes it from sibling tools like get_merchant_summary or get_spending_breakdown.

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

  Usage Guidelines4/5

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

  The description implies its use case: when you need top merchants by spend. It provides clear context but does not explicitly mention when not to use it or alternatives, which would push it to a 5. Still, there's enough implied guidance for an agent to select it appropriately.

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

• get_holdingA
  4.3/5.0
  Behavior4/5

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

  The readOnlyHint annotation already ensures the agent knows this is a safe read operation. The description goes beyond annotations by specifying what content will be returned: valuation history, and for liabilities the rate, term, secured-on links, and recorded payments. This gives valuable context about the tool's output behavior, which is particularly useful given there is no output schema.

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

  Conciseness5/5

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

  The description is a single, tightly packed sentence that front-loads the core concept ('One holding in full') before detailing what is included. Every part of the sentence earns its place, with no filler or redundancy. It is appropriately sized for the tool's simplicity.

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

  Completeness5/5

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

  Given the tool has one parameter, no output schema, and a readOnly annotation, the description is fully sufficient. It tells the agent exactly what will be returned (valuation history; for liabilities, terms and payments), covers the main distinctions, and is complete for the tool's purpose. There is no missing critical context for selecting or invoking this tool.

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

  Parameters3/5

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

  The input schema already provides full coverage with a clear description for holdingId ('Holding id from list_holdings.'), so the baseline is 3. The tool description does not add any additional parameter semantics or usage notes beyond what the schema already states. It correctly points to list_holdings as the source of the ID, but this is already in the schema.

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

  Purpose5/5

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

  The description clearly states this tool returns the full detail of a single holding, including valuation history and for liabilities the terms and recorded payments. It distinguishes itself from sibling tools like list_holdings, which would provide an overview rather than full detail. The phrase 'One holding in full' immediately conveys the scope and purpose.

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

  Usage Guidelines4/5

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

  The description implies use this tool when you need complete details of a specific holding, as opposed to list_holdings which likely provides a summary. It doesn't explicitly name alternatives or exclusions, but the context is clear that this is for single-holding deep-dive, not list-level operations. This is stronger than mere implication but falls short of explicit 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.

• get_merchant_summaryA
  4.3/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds useful behavioral context about the anonymous cohort benchmark being null when unavailable and the window options, but does not disclose other behaviors such as rate limits or authentication requirements, which are not 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.

  Conciseness5/5

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

  Two concise sentences that front-load the tool's purpose and output contents, followed by a practical source for the required parameter. No redundant or wasted language.

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

  Completeness5/5

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

  For a simple read-only tool with no output schema, the description thoroughly covers purpose, inputs, outputs (visits, totals, averages, first/last, benchmark), the null case, and how to obtain the required ID. It also mentions window options. This is sufficient for an agent to invoke it correctly.

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

  Parameters4/5

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

  Schema coverage is only 50% (merchantId lacks description). The description compensates by telling users exactly where to find merchantId ('Get merchantId from search_transactions or get_top_merchants'), and it restates the window options. It does not add the default window value, but that is already in the schema.

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

  Purpose5/5

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

  The description uses a specific verb-phrase 'Spending profile for one merchant over a window' and enumerates concrete outputs (visits, totals, averages, first/last visit, benchmark), clearly distinguishing it from sibling tools that cover multiple merchants or general spending breakdowns.

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

  Usage Guidelines4/5

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

  It provides clear context that this tool is for a single merchant's spending profile and implies prerequisites by directing users to obtain merchantId from search_transactions or get_top_merchants. However, it does not explicitly contrast with alternative tools like get_spending_breakdown or aggregate_transactions, so it stops short of 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.

• get_net_worth_historyA
  4.3/5.0
  Behavior4/5

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

  With readOnlyHint already provided, the description adds meaningful context: the asset-only scope, the by-group breakdown, and the default period. These details go beyond the annotation and help set expectations about what data is returned and its limitations.

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

  Conciseness5/5

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

  Three tightly packed sentences convey purpose, scope, and default behavior without redundancy. The most important information is front-loaded, and every sentence contributes to understanding.

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

  Completeness5/5

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

  For a read-only, single-optional-parameter tool with no output schema, the description covers the return type (monthly period totals with by-group breakdown), the asset-only limitation, and the default range. This is sufficient for an agent to invoke it correctly.

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

  Parameters3/5

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

  The single parameter 'months' is fully documented in the input schema, including format and default behavior. The tool description adds no additional parameter-level insight, so the schema carries the weight, yielding the baseline score.

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

  Purpose5/5

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

  The description clearly states the tool returns month-end asset totals over time with a by-group breakdown, explicitly distinguishing it from a current net worth snapshot. The verb 'get' plus the resource 'net worth history' and the asset-only caveat make the purpose unambiguous.

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

  Usage Guidelines4/5

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

  It provides contextual guidance: 'for charting how wealth has changed' and notes the default 12-month window. It cautions that liabilities are excluded, which helps the agent decide when this tool is inappropriate, though it does not explicitly name alternative tools.

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

• list_accountsA
  4.3/5.0
  Behavior4/5

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

  The readOnlyHint annotation already declares the safe read nature. The description adds valuable context about pseudo accounts, which is a behavioral aspect of the returned data (distinguishing manual vs live connections). This goes beyond annotation and informs agent expectations.

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

  Conciseness5/5

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

  The description is a single, efficient sentence that conveys the core purpose and a key nuance. Every word contributes value.

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

  Completeness5/5

  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 no output schema, the description is sufficiently complete. It names the resource (accounts), the output (balances), and clarifies an edge case (pseudo accounts).

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

  Parameters4/5

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

  The tool takes no parameters, so the baseline is 4. The description doesn't need to explain parameters, and it correctly focuses on output semantics.

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

  Purpose5/5

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

  The description explicitly states the tool lists connected bank accounts with latest balances, which is a specific verb+resource. It clearly differs from sibling tools like list_holdings or search_transactions, so there's no ambiguity.

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

  Usage Guidelines3/5

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

  Usage is implied: one would use this to get account balances. However, there is no explicit mention of when to use it vs alternatives, nor any exclusion criteria. The pseudo account clarification helps interpret results but not tool selection.

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

• get_net_worthA
  4.4/5.0
  Behavior4/5

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

  Even though readOnlyHint=true already signals a safe read, the description adds meaningful detail by explaining that values are in integer minor units with pre-formatted display strings alongside, plus the breakdown categories. This goes beyond the annotation and gives the agent useful knowledge about output formatting without contradicting the read-only nature.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the main purpose and followed by concise details on breakdowns and value formatting. Every word earns its place, with no redundancy or filler.

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

  Completeness4/5

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

  Despite lacking an output schema, the description provides sufficient detail about what is returned (totals, liquid assets, breakdowns) and how values are represented. It doesn't explicitly describe the top-level structure (e.g., object vs. list), but for a zero-parameter read-only tool, the description covers the essential context.

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

  Parameters4/5

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

  With zero parameters and 100% schema coverage (no properties), the description doesn't need to explain parameters. The baseline of 4 is appropriate because the description focuses on the return payload instead, making the tool's behavior clear without needing parameter explanations.

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

  Purpose5/5

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

  The description clearly states the tool reports the user's current net worth, specifying the exact components (total assets, total liabilities, liquid assets) and breakdown dimensions. It distinguishes itself from sibling tools like get_net_worth_history by emphasizing 'current' net worth, making the scope unmistakable.

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

  Usage Guidelines4/5

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

  The context makes it obvious this is for a current snapshot of net worth, and the straightforward scope implies it should be used when current values are needed rather than historical trends. No explicit exclusions or alternative tool mentions are given, but the purpose is clear enough to guide selection.

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

• get_categorisation_statsA
  4.5/5.0
  Behavior4/5

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

  The readOnlyHint annotation already covers the read-only nature. The description adds meaningful behavioral detail by explaining the output dimensions (counts and minor-unit totals split by direction) and the three categorisation states. No contradictions detected.

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

  Conciseness5/5

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

  The description is a single, well-structured sentence that front-loads the core purpose and includes a practical use case. No wasted words or redundant content.

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

  Completeness5/5

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

  For a no-parameter, read-only tool with no output schema, the description is complete: it explains what is returned (counts and totals by categorisation type and direction) and why it is useful. Nothing essential is missing.

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

  Parameters4/5

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

  The tool has zero parameters, so the schema coverage is vacuously 100%. The description doesn't need to explain parameter semantics, and the baseline of 4 applies.

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

  Purpose5/5

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

  The description clearly states the tool's purpose: to provide categorisation coverage stats (counts and minor-unit totals) for user-categorised, auto-categorised, and uncategorised transactions, split by direction. This is distinct from sibling tools like get_spending_breakdown or list_categories, making the purpose unambiguous.

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

  Usage Guidelines4/5

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

  The description provides a clear use case: 'Useful for judging how complete category-based analysis will be.' It does not explicitly mention when to avoid this tool or point to alternatives, but the use case is specific enough to guide an agent.

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

• search_transactionsA
  4.6/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, so the safe-read nature is covered. The description adds valuable behavioral context: amounts are unsigned minor units, 'type' gives direction (DEBIT = money out), and each item carries its effective category with resolved label. This goes beyond the annotations without contradicting them.

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

  Conciseness5/5

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

  Three sentences, each earning its place: purpose and core features, key data semantics, and an alternative. No repetition of schema details or fluff, making it highly efficient.

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

  Completeness4/5

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

  The tool has 18 parameters and no output schema, so the description must carry a fair burden. It covers the searchable resource, pagination, and key semantic quirks (unsigned amounts, effective category). Minor gaps remain (e.g., default sort/filter behaviors are left to the schema), but the description is sufficient for selecting and invoking the tool.

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

  Parameters4/5

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

  Schema description coverage is high (89%), so the baseline is 3. The description adds meaning by explaining the unsigned minor units convention and the effective category semantics, which map to relevant parameters (minAmountMinor, maxAmountMinor, type, effectiveCategoryIds). This provides a small but useful increment above the schema.

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

  Purpose5/5

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

  The description opens with 'Search the user's bank transactions with filters and pagination', a specific verb and resource that clearly distinguishes this from sibling tools. It also explicitly names aggregate_transactions as the alternative for totals, reinforcing differentiation.

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

  Usage Guidelines5/5

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

  The description explicitly states when to prefer an alternative: 'For totals over many transactions prefer aggregate_transactions.' This provides a clear when-not-to-use and points to the correct sibling, satisfying the highest bar for usage guidance.

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

• aggregate_transactionsA
  4.7/5.0
  Behavior5/5

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

  Beyond the readOnlyHint annotation, the description discloses highly useful behavioral details: it operates server-side, returns per-group counts, distinguishes totalAmountMinor (magnitude) from netAmountMinor (signed credits minus debits), uses minor units, and defaults to the last 3 months if no period filter is provided. This significantly aids the agent in interpreting results and making assumptions.

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

  Conciseness5/5

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

  The description is compact and front-loaded, with the core purpose in the first sentence. Every sentence adds information: operation, grouping, return values, unit convention, default period, and usage examples. No filler or redundancy.

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

  Completeness5/5

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

  Despite having no output schema, the description covers the key return fields (counts, totalAmountMinor, netAmountMinor), the default period, and gives real-world usage examples. With 20 parameters, the description cannot enumerate all filters, but the schema already does so. The description provides sufficient context for an agent to confidently use the tool without surprises.

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

  Parameters4/5

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

  Schema coverage is high (85%), so the baseline is 3. The description adds value by clarifying the groupBy semantics (enumerating keys and the constraint 'at most one of day/month/year') and explaining the meaning of totalAmountMinor vs netAmountMinor, which helps the agent understand output-related parameters like sortBy. It does not duplicate the schema's parameter descriptions.

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

  Purpose5/5

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

  The description clearly states the tool's function: 'Group and total transactions server-side' with specific grouping keys (merchant, category, code, day/month/year). It distinguishes itself from sibling tools by positioning as 'the go-to tool' for spend aggregation questions like 'top categories by spend this quarter' or 'monthly spend at Tesco', which separates it from search_transactions and other stats tools.

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

  Usage Guidelines4/5

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

  The description provides clear context for when to use this tool (aggregation/spend analysis questions) and gives concrete example queries. However, it stops short of explicitly naming alternatives or stating when NOT to use it, so it doesn't fully meet the 5-level standard seen in the get_calls example.

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

• list_categoriesA
  4.9/5.0
  Behavior5/5

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

  With readOnlyHint=true, the description still adds rich behavioral context: taxonomy hierarchy, search coverage (label/description/search terms), and isNetNeutral semantics. No annotation contradiction; it substantially enhances the safety profile already declared.

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

  Conciseness5/5

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

  The description is dense but every sentence serves a purpose. It starts with the main use case, then provides search guidance, examples, hierarchy explanation, and edge cases (isNetNeutral) without redundancy.

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

  Completeness5/5

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

  For a lookup tool without output schema, the description fully accounts for taxonomy size, search behavior, type filtering, hierarchy, and special flags. It equips the agent to correctly select all relevant leaf IDs for a query.

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

  Parameters4/5

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

  Schema coverage is 100%, but the description adds meaningful examples for `query` ('eating out', 'fuel') and clarifies `type` values (DEBIT=spending, CREDIT=income). It goes beyond the schema by explaining hierarchical filtering implications.

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

  Purpose5/5

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

  The description opens with 'Find category ids to filter by', immediately stating the tool's verb and resource. It clearly differentiates from sibling analytics tools by focusing on category discovery and filtering.

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

  Usage Guidelines5/5

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

  Explicitly instructs to pass `query` for searching rather than pulling all 180 entries, and clarifies how to filter by DEBIT/CREDIT type. It also advises checking multiple leaf IDs for ambiguous terms like 'food' and explains the meaning of isNetNeutral, giving practical when-to-use guidance.

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