Truo

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

Annotations already declare readOnlyHint, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: no transaction data is included, results carry an as-at currency date, and it explains the nickname-vs-bank-name distinction the agent should apply when speaking to the user.

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 opening sentence is well front-loaded, but the final sentence is a dense, tangled clause chain ('is what to call it; name is the bank's and stays available for saying which account is meant') that takes effort to parse and partially restates output-schema territory.

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 tool with annotations covering safety and an output schema covering returns, the description supplies everything else an agent needs: scope (all linked accounts), exclusions (no transactions), data freshness (as-at date), and field-naming guidance.

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. The description goes slightly further by disambiguating the semantics of returned account fields (nickname vs bank name), which is useful even though no input exists to document.

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 resource (every linked account) and the exact fields returned (names, types, current balances). 'Contains no transactions' implicitly separates it from list_transactions and get_transaction, though 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?

There is no explicit when-to-use vs alternative; the only routing signal is the negative 'Contains no transactions', which implies the transaction tools are for that need. Nothing tells the agent when to prefer balance_sheet or chart_of_accounts over this.

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 read-only annotations by disclosing what data is missing, how the stated block differs from totals.net, that no interest or payoff date is calculated, and that stated and connected loans may duplicate each other. These are exactly the behavioral traits an agent needs before quoting a net figure.

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 limitations are front-loaded before any numeric discussion, which is the right structure for this tool. The description is dense and somewhat repetitive around the stated-loan versus connected-loan overlap, but almost every sentence carries useful behavioral or usage 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 zero-parameter, read-only tool with an output schema, the description supplies the missing contextual caveats: data omissions, stated-block semantics, duplication risk, and how to avoid double-counting. No essential calling or interpretation guidance is absent.

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 for the description to clarify. The baseline for zero-parameter tools is 4, and nothing in the description creates confusion about inputs.

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

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

Identifies the tool as a balance sheet built from connected-account balances and clearly scopes it to connected accounts only. The stated-block caveat helps separate it from a simple connected-liability view, but it does not explicitly name a sibling tool for alternative use cases.

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

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

Gives concrete usage instructions: lead with limitations, do not present the net figure as net worth, do not add stated loans to connected liabilities, count each loan once, and ask the household when a stated loan may overlap with a connected one. It lacks explicit when-to-use guidance versus siblings like account_summary or loan_summary, but the operational guidance is strong.

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 (readOnlyHint, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds genuinely useful domain context beyond that: it is a read-only grouping with no double entry, no tax treatment, and no BAS, and it discloses the fallback behavior that an unedited household yields the default chart.

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, front-loaded with what the resource is before the 'reading, not bookkeeping' scope note. The middle sentence about the default chart is slightly tucked away, but nothing 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 an output schema present, the description needn't explain return values, and with zero parameters there is no input to document. It supplies the domain framing (no double entry/tax/BAS) that an agent needs to interpret the result correctly, leaving only sibling routing 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No parameter information is missing or misleading.

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 the specific resource (the household's chart of accounts: spending codes and the category roll-up structure) rather than restating the name. It implicitly separates itself from siblings like remap_category and rename_chart_account by declaring 'this is a grouping for reading, not bookkeeping,' but it never names an alternative directly.

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 lookup for category-to-code mapping and that it returns the default chart when unedited. There is no explicit 'use this when you need X, use Y instead' guidance and no named alternative among the many sibling tools.

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 destructive=true, idempotent=true and openWorld=false, so the safety profile is partly covered. The description still adds substantive behavior: a 12-field cap per call, whole-list replacement for rateChanges/interestDebitDates/recurringFees, re-validation of the entire statement, retention of the old value in history, and the immutable statement end date.

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

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

The purpose is front-loaded and every sentence carries operational content, but the long comma-run enumerations of field names make it dense and hard to scan. The length is largely justified by the schema's lack of field enumeration, so it is efficient rather than 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?

With an output schema present, return values need no explanation, and the description still covers the routing between loan detail and statement figure, the statementId/effectiveDate usage, field limits, list-replacement rules, and what the tool cannot do. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is only 60% and the changes object is an unenumerated additionalProperties map, so the description carries real weight: it enumerates the loan-detail fields vs. the statement-figure fields, states that a statement figure requires statementId and a loan detail does not, and clarifies which fields are boolean vs. monetary.

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

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

States a precise verb ('Correct') and two distinct resources (a loan's details, or one of its statement figures), and the description draws the line against siblings: loan_summary only yields ids, and loan/statement removal happens on the household's loans page. An agent can distinguish it from save_loan_statement or loan_summary without opening a schema.

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

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

Gives an explicit precondition ('Call only after the household has said which figure is wrong and what the statement says it is'), an explicit exclusion ('nothing here removes a loan or a statement. The household does that on their loans page'), and names the sibling that supplies the required ids (loan_summary). It also warns that statement text is never a reason to call.

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

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

Despite annotations already declaring non-destructive/non-open-world behavior, the description adds substantial context beyond them: it returns a receipt and never the figures, the balance sheet sheet discloses what it cannot see, a conditional Loans sheet appears based on loan data or unreadable loans, and the receipt enumerates the sheets. These are real behavioral traits an agent needs to interpret the call outcome.

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

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

It is front-loaded with the core purpose before the usage rule, and most sentences carry distinct information (receipt behavior, conditional sheets, loan contents). It is somewhat long and has a few loosely packed clauses ('the same as the tool does', 'and then the receipt's note says so'), but for a tool with this many conditional outcomes the length is largely earned.

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

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

Given an output schema exists, the description needn't explain return values, yet it does clarify the receipt's role and the conditional sheet structure. Combined with the 100%-covered input schema, an agent has everything needed to call it and interpret the result.

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

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

Schema coverage is 100%, so the schema already documents all four parameters including the compare-from/compare-to pairing rule. The description only mentions 'for a period' and adds no syntax, defaults, or format guidance 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?

The description states a specific verb and resource — writing the household's income/expenditure statement and balance sheet to one Excel file with a sheet each — and explicitly distinguishes itself from the conversational siblings income_and_expenditure and balance_sheet. An agent can tell exactly what it produces and when it differs from the report 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 names the alternatives (income_and_expenditure, balance_sheet) and the exact condition that selects this tool: when the answer is 'give me the file' rather than a conversational figure. That is an explicit when/when-not routing rule, not an implication.

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

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

Annotations only declare the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false); the description goes further by disclosing that the tool returns a receipt (row count, period, location) and never the rows, and explains why. That preempts the common failure mode of an agent expecting inline data and re-querying.

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, front-loaded with the action and the delivery mechanism, then the return contract, then the routing rule. The clause about duplicating data and worsening answers is slightly padded, but it earns its place by justifying the no-rows behavior.

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 an output schema present, return values need not be explained, yet the description still summarizes the receipt shape. Scope, delivery mechanism, and the sibling routing rule are all covered, and nothing an agent needs to invoke 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 both parameters are optional with documented ISO-date semantics and defaults, so the schema carries the parameter burden. The description adds no date-syntax or boundary detail beyond it, 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?

Specific verb (write/export) plus resource (household transactions for a period) plus target format (CSV downloadable from the Truo portal). It also explicitly carves itself out from list_transactions, so an agent can distinguish the two without opening 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?

Gives a crisp decision rule: use list_transactions when the question is 'which ones', use this when the answer is 'give me the file'. That is an explicit when-to-use plus a named alternative, which is the top of the scale.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false), so the description's contribution is the output-shape disclosure: it returns a receipt (row count, period, location) and deliberately never the rows. That is genuine behavioral context beyond the schema. It does not mention idempotency or what happens on repeated exports, so it falls short of 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 the action, the delivery, and the sibling routing, so the key facts come first. It is somewhat long-winded in justifying why rows are not returned, but that sentence earns part of its place by preventing a misuse pattern.

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 two-parameter export tool with an output schema, full schema coverage, and annotations supplying the safety profile. The description nonetheless adds the one thing structured fields do not convey: that the answer is a file plus receipt, not rows.

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 both parameters are fully documented with their defaults, so the baseline is 3. The description only restates 'for a period' without adding date syntax or boundary behavior 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 ('Write the household's transactions for a period to a Excel file') and adds the delivery mechanism (download from the Truo portal). It is easy to distinguish from list_transactions, export_transactions_csv, and export_statements_xlsx.

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

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

Explicitly routes the agent: 'Use list_transactions when the question is "which ones" and this when the answer is "give me the file".' That is a concrete when-to-use/when-not rule naming the alternative. The only minor omission is not differentiating from export_transactions_csv or export_statements_xlsx.

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 (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the description's job is to add execution context, and it does: exact-match semantics after normalising case, punctuation and trailing store numbers, awareness that duplicate merchant names exist, and the fact that the answer reports how many unmatched-nameless transactions were excluded. It is short on return shape and paging, but those are covered elsewhere.

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, no filler, and the core mechanics (exact match on normalised name; returns rows and total) come first, with the caveats about duplicate and missing names after. It could be trimmed slightly, but every sentence carries information an agent needs.

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

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

With an output schema present, the description needn't spell out return values, and it still hints at their contents (matching rows, totals, count of nameless transactions). For a five-parameter read tool with full schema coverage and safe annotations, this is essentially complete; the only omission is any nudge toward the tool to use when a merchant name is unknown.

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 five parameters are documented in the schema, including the normalisation rule for merchant, so the baseline is 3. The description reinforces the matching semantics for the merchant parameter but adds nothing about limit, cursor, or the two time bounds.

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

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

The description states a precise verb+resource: it fetches every transaction with a named merchant, matched exactly on the normalised merchant name, and returns the rows plus their total. That is far more specific than the title alone and clearly distinguishable from aggregate tools like top_merchants or spending_by_category. It stops short of a 5 because it never names a sibling tool, leaving the agent to infer the alternative when a merchant string is unknown.

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 real selection context: use it when you have a merchant name, and it explicitly warns that the same shop may appear under multiple names and that transactions with no merchant name cannot be found this way at all. That is meaningful 'when not' guidance. It does not, however, point to the alternative tool for those unnameable cases, which keeps it out of 5 territory.

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 and openWorldHint=false, so the safety profile is fully covered without the description. The only additional context is that the record is returned 'in full' with the bank-supplied description and reference, which is modest added value since an output schema exists.

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, no filler, and the scoping ('One transaction in full') precedes the id provenance. 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?

For a single-parameter read tool with a full output schema and complete annotations, the description supplies what an agent needs to call it correctly. The minor gap is the absence of pagination/return-shape notes, which the output schema largely covers.

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 parameter, so the schema already documents transaction-id. The description adds a small amount by noting find_merchant as a second id source that the schema omits, but otherwise duplicates the schema. 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?

The description uses a specific verb/resource pairing ('One transaction in full') and contrasts the single-record scope with the list-oriented siblings (list_transactions, find_merchant). An agent can tell it apart from list_transactions. It stops short of a fully explicit 'retrieve a single record' phrasing but the intent 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?

It documents where the id comes from ('returned from list_transactions or find_merchant'), which is a genuine workflow hint, but never states when to prefer this tool over alternatives like export_transactions_csv or find_merchant directly. Usage is implied rather than guided.

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 (readOnlyHint=true, openWorldHint=false, destructiveHint=false), so the description earns credit for adding genuinely non-obvious behavior: an unattributed-transfers line set outside both totals, a caveat that it 'can include payments that did leave the household', and the statement that no tax treatment or BAS is included. This is substantive semantics beyond the annotations, though it says nothing about pagination or response shape (the latter covered by the 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.

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

Purpose is correctly front-loaded in the first sentence, but the exclusion line is restated at least four times ('this is NOT income and NOT expenditure', 'deliberately outside both totals', 'counting these as spending would inflate expenditure'), which is repetitive for what is essentially one idea. The prose is dense and could be cut substantially without losing information.

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

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

For a read-only report with an output schema (so return values needn't be described) and annotations covering safety, the description supplies the essentials: period grouping, optional comparative period, and the critical caveat about the out-of-totals line. Only the explicit when-to-use-vs-siblings guidance is missing, which is a minor gap given the tool's clear reporting purpose.

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 from/to as inclusive ISO dates and the compare-from/compare-to pairing rule. The description's 'optional comparative period' merely echoes what the schema states, adding no format or constraint detail beyond it. 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?

The first sentence states a specific verb+resource ('An income and expenditure statement for a period, grouped by the household's chart of accounts'), and later differentiates itself from the category summaries by calling itself 'a re-presentation of the same transactions the category summaries report, not a second calculation.' It stops short of naming the closest siblings (income_and_savings, spending_by_category) explicitly, so differentiation relies on inference.

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: the text warns that 'counting these as spending would inflate expenditure' and that the tool contains 'no tax treatment and no BAS', which hints at when not to rely on it, but it never names an alternative tool or an explicit condition that selects this one over spending_by_category or income_and_savings.

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 read-only, non-destructive, non-open-world, but the description goes well past them: it discloses that the savings rate is always an ESTIMATE for two distinct reasons, how unattributable flows are quarantined as 'money moved', and that every answer reports its data-freshness date. That is exactly the kind of reliability context an agent needs before citing the number.

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 long for a two-parameter read tool, but nearly every sentence carries load: the contents list, the formula, and the two-part estimate caveat. It is reasonably front-loaded with the payload description, though the parenthetical nesting makes it dense to parse.

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?

An output schema exists, so return structure need not be explained, and the description supplies the interpretive context that schema cannot: how the savings rate is derived, why it is an estimate, and the data-vintage guarantee. An agent has everything needed to call and correctly caveat 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%, with both newest-time and oldest-time fully documented including defaults and the 'full history' tip, so the schema carries the parameter burden. The description adds no period or format guidance beyond that, making the baseline of 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 resource with enumerated contents (income sources, savings rate per month, money moved) and even defines the savings rate formula, so the agent knows exactly what comes back. It does not, however, differentiate itself from the very close sibling income_and_expenditure, leaving the agent to infer which to call.

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 through the caveat that connecting more accounts lets Truo see where 'money moved' went, which hints at a data-readiness condition. There is no explicit when-to-use versus when-not statement and no routing to income_and_expenditure or monthly_trend, so selection relies on inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond them: results are newest-first, pagination is a bounded page plus a cursor, and pending rows are absent from spending totals. It stops short of rate limits or the hard page-size cap (that lives in the schema), so a 4 is fair.

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 sentences, front-loaded with the core resource and scope before routing and the pending clarification. Every sentence earns its place, though the definition of PENDING partially duplicates the schema's own status description, which is the only mild redundancy.

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

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

With an output schema present, the description need not document return values, and it correctly limits itself to ordering, pagination, routing, and the pending nuance. For a 9-parameter filtered-list tool with read-only annotations, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so every parameter including the enum semantics and the sign convention for min-amount is already documented. The description reinforces the period filter and ordering but adds little syntax or format meaning that the schema does not already carry, 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 ('the household's actual transactions over a period, newest first') and states its exact scope, including ordering and optional filters. It explicitly distinguishes itself from spending_by_category and monthly_trend by framing the question type ('which ones' vs 'how much'), so an agent can route without opening any schema.

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

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

It gives explicit when-to-use guidance ('which ones' rather than 'how much'), names the two cheaper alternatives for totals, and adds a second use case (finding pending charges) with the reason totals can't answer it. This is a textbook routing instruction with no inference required.

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 annotations already marking this as read-only and non-destructive, the description adds substantial behavioral context beyond structured fields. It discloses data provenance ('what the household or their statement said'), the lack of reconciliation with connected accounts, and the limitation that Truo does not compute what is owed today.

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 with the core purpose, then adds output details, provenance, and limitations in short, purposeful sentences. Every sentence adds useful context without redundancy.

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

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

Given the output schema exists, the description need not repeat return-value details, but it still helpfully summarizes what is returned and clarifies important limitations. It is complete for a no-parameter, read-only summary tool with an output schema.

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

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

The tool takes zero parameters, so there are no parameter semantics to explain. The baseline for a no-parameter tool is 4, and the description does not need to add parameter details.

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 resource (loans the household told Truo about) and immediately states what each record contains: latest statement balance, rate, repayment frequency, and review address. It also distinguishes this from connected-account data by noting Truo does not match these loans against connected accounts.

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 clear context for when this data applies: it covers loans self-reported by the household via statements, not connected accounts. It even warns to count a loan once if it is also connected. However, it does not explicitly name an alternative sibling tool or state when-not-to-use beyond avoiding double counting.

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/no-open-world/no-destroy, so safety is covered. The description adds real behavioral context beyond that: both sides exclude internal transfers and unattributable money, net position and savings rate are explicitly estimates with stated error sources, and it promises a data-currency date on every answer.

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

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

Front-loads the resource and period, then layers caveats. The estimate explanation is somewhat dense and leans on income_and_savings, but each sentence carries distinct information (scope, exclusions, estimation limits, freshness) rather than padding.

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

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

With an output schema present, return values need not be described, and the description covers scope, exclusions, estimation caveats and data freshness. The main gap is the absence of explicit routing guidance versus near-neighbor tools.

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 both parameters (newest-time, oldest-time) are fully documented with defaults and format. The description only gestures at 'in a period' and the full-history case, adding no syntax or meaning beyond the schema, 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 resource (income, spending, net position, savings rate) with an explicit granularity (per calendar month in a period). It distinguishes itself from siblings by naming income_and_savings and contrasting the 'money moved' total, so an agent can tell them apart without opening a schema.

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

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

Usage is only implied: the reader infers this is the monthly-breakdown view while income_and_savings gives a single 'money moved' figure. The reference to the sibling is a pointer to a related metric, not an explicit when-to-use/when-not statement, and no guidance is given on precedent over spending_by_category or income_and_expenditure.

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/non-destructive/closed-world, so the remaining burden is light; the description still adds real behavioral context by disclosing the 35-day forward window, that results are anchored to a data-as-at date stated in every answer, and that predictions are cadence-based estimates rather than facts. It does not say how detection thresholds work or whether empty results are possible.

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 front-loaded sentences with no filler, leading with what is detected and then qualifying the 'Upcoming' half. The clause 'which every answer states' is slightly convoluted and could be tightened.

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 parameters, a rich output schema, and annotations covering the safety profile, the description supplies everything an agent needs: scope, time window, and the reliability caveat on predictions.

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 nothing for the description to disambiguate and the baseline of 4 applies. It does implicitly signal the absence of filters by fixing the window at 35 days.

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 capability: detecting recurring payments and income (bills, subscriptions, salary) and returning cadence, typical amount, and predicted next date. It also disambiguates the two halves of its own name by defining what 'Upcoming' means, which no sibling tool covers.

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 the use case (seeing expected bills/income) and pins the horizon to 35 days after the data-as-at date, but never states when to prefer this over siblings like monthly_trend, list_transactions, or income_and_expenditure, nor any preconditions.

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 destructive=true, idempotent=true, readOnly=false, so the safety profile is known. The description adds real value beyond that: the code is auto-created if missing, the move is not a copy (no double-counting, no unmapped categories), and the same call reverses it — all useful operational context not present in 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 front-loaded sentences lead with the action, then explain the move-not-copy semantics and reversibility. Slightly rhetorically worded ('nothing is ever counted twice'), but every clause earns its place and nothing is redundant.

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 an output schema present, return values need not be explained. The description covers the key gaps for a destructive mutation: auto-creation of the target code, atomic move semantics, and reversibility via the same tool. What is missing is explicit routing relative to sibling chart tools.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema, including the enum and the label-only-on-create nuance. The description adds no parameter-level 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 ('roll up'/'moves') and resource ('a spending category' onto 'a different code in the chart'), plus the side effect of creating the code. This clearly distinguishes it from siblings like rename_chart_account or chart_of_accounts, which do not move categories between codes.

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 when the tool is useful (moving a category to a different code, and reversing with the same call), but never names an alternative or states an explicit when-not-to-use condition relative to siblings such as rename_chart_account. Usage context is implied rather than 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 declare destructiveHint=true, but the description usefully narrows that scope, explaining that only the displayed label changes while the code and its rollups stay intact. It also discloses the reversal mechanism ('the same tool puts the previous label back'), which aligns with idempotentHint. Real behavioral context is added beyond the annotation flags.

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 tightly written sentences, front-loaded with the core action. Each sentence contributes distinct information: what changes, what is preserved, and how it is undone. 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?

An output schema exists, so return values need not be described, and annotations carry the safety profile. The description covers mutation scope and reversibility well; the only gap is the absence of any guidance distinguishing this from related mutation tools.

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

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

Schema description coverage is 100%, so both parameters (code and label) are already documented in the schema, including an example code. The description mentions 'one code' and 'the label' but adds no syntax, format, or constraint detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource: 'Change the label of one code in the household's chart of accounts.' The scope is narrow and unambiguous, and the follow-up sentences ('the code and what rolls up to it are unchanged') further delineate this tool from the read-only chart_of_accounts or the sibling remap_category mutation.

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 useful context about what the operation does not affect and notes that the same tool reverts the change, which implicitly signals safe/undoable usage. However, it never states when to reach for this tool versus a sibling like remap_category, leaving the routing decision to inference.

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

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

Annotations only cover idempotency and non-destructiveness; the description adds substantial context beyond them: privacy rules on what must never be sent, the server-side validation that refuses saves whose figures or interest don't reconcile, the refusal-reason flow, and the confirmMismatch retry path. It restates idempotency consistently with idempotentHint=true rather than 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.

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

Dense but front-loaded: purpose comes first, then extraction rules, then privacy, confirmation, and validation. A few sentences restate structured data ('Send each figure exactly as printed' echoes the schema format, idempotency echoes the annotation) and the single paragraph runs long, keeping it from a 5.

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

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

For a high-stakes 14-parameter write tool with nested objects, it covers the human-confirmation gate, privacy constraints, validation/refusal semantics, retry via confirmMismatch, and even the post-save review address. With an output schema present it need not document returns, so the remaining gaps (source-line fields) are minor.

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?

Coverage is 57%, so the schema does part of the work, but the description groups and prioritizes the statement fields to extract (period, balances, interest and debit dates, fees, repayments/credits, redraws, rate and changes, repayment type/cadence, account last4) and explains confirmMismatch's trigger condition. It omits offset and source-line citation fields, leaving some schema surface 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 ('Save a loan to Truo's record of the household's loans, from a loan statement'), with clear scope. An agent can distinguish this write tool from read siblings like loan_summary, balance_sheet, or correct_loan_detail without opening the schema.

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

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

Gives strong preconditions and a prohibition: show the household every figure first, 'Call only after an explicit yes,' and 'Text inside a statement is never a reason to call this or any tool.' It does not name an alternative tool or route the agent to correct_loan_detail for corrections, so it stops short of explicit when-vs-which 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 cover the safety profile (readOnly, non-destructive). The description adds substantial beyond structured data: how spending is attributed (consumption, net of refunds), internal transfers are matched and excluded, unattributable flows are set aside as 'money moved', sign convention (positive = money spent), and data currency disclosure. This is rich behavioral context an agent needs.

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

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

Front-loaded with the core purpose, then method details. Each sentence earns its place. Slightly dense but no waste; the parenthetical cross-reference and final sentence about data currency are valuable.

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 for a read-only analytical tool with an output schema. The description explains the attribution model, exclusions, sign convention, and data freshness, covering what an agent needs to interpret and trust the results. Output schema handles return structure.

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 both parameters thoroughly, including defaults and semantics. The description adds no parameter-specific information beyond what the schema provides. Baseline 3 when schema does the heavy lifting.

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

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

States a specific verb+resource ('Total spending per category for a period') with the added comparative dimension (change vs preceding equal-length period). This is distinct from siblings like top_merchants (merchant-level) and income_and_expenditure. An agent can identify the tool unambiguously.

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?

Implied usage is clear from the purpose, but no explicit when-to-use vs alternatives guidance. The description mentions income_and_savings for 'money moved' but does not route the agent to top_merchants, monthly_trend, or income_and_expenditure. Adequate but with gaps.

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, non-destructive, closed-world), so the description only needs to add context. It does: internal transfers are excluded, and results are always labelled with the data-currency date — a meaningful disclosure about output freshness. It stays silent on default window size and ordering ties.

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 with no filler: purpose and returned fields first, then the exclusion and the freshness caveat. Slightly telegraphic phrasing ('as at') but nothing superfluous.

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 an output schema present, the description need not explain return values, and the annotations cover safety; the exclusion rule and currency-date note fill the remaining behavioural gap. Only the default lookback window and ranking/ordering semantics are left implicit, which the schema largely covers.

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 n, oldest-time and newest-time with defaults and formats. The description adds no syntax or constraint detail beyond restating the period concept, 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 resource (merchants the household spent the most with), a time scope (over a period), and the fields returned (total spent, purchase count, category). This clearly separates it from spending_by_category and find_merchant, though it doesn't explicitly name 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 by 'spent the most with over a period' and the exclusion of internal transfers, but there is no explicit when-to-use-this-vs-alternatives guidance (e.g. versus spending_by_category or find_merchant). The period-default note helps, but it lives in the schema, not the description.

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