nz-openbank-mcp

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

readOnlyHint=true already establishes the safety profile, so the description's main addition is the field-level return shape and the fact that formatted_account is masked. That is useful context, but because a full output schema exists, restating the fields is largely redundant and no error/not-found behavior is disclosed.

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

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

Two short, front-loaded sentences with the purpose first and the return shape second; nothing is padded. The field enumeration verges on duplicating the output schema, costing a little weight.

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 annotations and an output schema, the definition covers what an agent needs to invoke it. It is thin on routing versus the balance and pending-transaction siblings, which is the main remaining gap.

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

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

Schema coverage is 100% and the account_id description already gives the Akahu format with an example. The description adds only 'by id', which is the baseline expectation rather than new meaning, so the standard 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 ('Fetch a single account by id'), which cleanly separates it from acct_list_accounts by cardinality. It does not explicitly name the sibling it displaces, but the singular-vs-list distinction is clear enough from the wording.

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

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

Usage is only implied by the 'single account by id' phrasing; there is no explicit guidance on when to prefer acct_get_account_balance (balance-only) or acct_get_pending_transactions, nor any note on what happens with an unknown id. The agent must infer the routing from sibling names alone.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description adds genuine value by disclosing the exact response keys and the null edge cases (all three None when no balance block, available alone None when unreported). It does not mention auth requirements or rate limits, but for a read-only balance lookup that is a minor gap.

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

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

Front-loaded with the purpose and the sibling comparison in the first sentence, then a compact return-shape paragraph. Slight redundancy with the existing output schema, 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?

For a one-parameter read tool with an output schema and readOnlyHint, the definition covers selection rationale and the non-obvious null semantics. Only authentication context is absent, which is not critical here.

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

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

Schema coverage is 100% and the single account_id parameter is already documented as an Akahu account id. The description adds no format, sourcing, or validity 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?

States a specific verb and resource ('Return just the balance for an account') and immediately contrasts scope with the sibling acct_get_account. An agent can distinguish this from acct_get_account without opening either schema.

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

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

'Cheaper than get_account' gives a concrete cost-based selection signal for choosing this over the richer sibling. It stops short of explicit when-not guidance (e.g. use get_account when you also need account metadata), but the routing intent is clear.

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

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

Annotations already establish readOnlyHint, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: pending entries can change or vanish before settling, and pending entries carry no id — both are non-obvious traits that affect how an agent should handle results.

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 front-loaded in the first sentence, followed by the volatility caveat, then the return shape. Every sentence is informative and there's 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?

Because an output schema exists, the detailed field-by-field return description is largely redundant, though it clarifies semantics the schema can't (e.g., negative amounts, currency may be None). Missing is explicit positioning relative to txn_get_pending_transactions; otherwise an agent has enough to call it correctly.

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

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

Only one parameter, account_id, and schema description coverage is 100%, so the schema already carries the semantics. The description implies single-account scoping but adds no format, source, or validation guidance for the Akahu account id. Baseline 3 applies.

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

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

States a specific verb and resource: list pending, not-yet-settled transactions scoped to one account. It's clear what the tool does, but it never distinguishes itself from the near-identically named sibling txn_get_pending_transactions, so an agent can't tell from the description which is account-scoped and which is global.

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

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

Usage is only implied by the parenthetical '(not-yet-settled)' and the note that pending entries affect available balance. There is no explicit 'use this when...' or 'for all-account pending use X instead', and the closest alternative is a sibling with an almost identical name.

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

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

With readOnlyHint already declaring a safe read operation, the description adds useful behavioral context beyond annotations: masked account numbers, formatted balances, field semantics, and the condition under which balance and currency are None. It does not cover ordering or pagination, but those appear irrelevant for a zero-parameter list.

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 efficiently documents the return shape. Every sentence contributes directly to selecting or using the tool, with no redundant filler.

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

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

For a zero-parameter read-only list tool, the description gives enough detail about scope, returned fields, masking, formatting, and null behavior. An output schema exists, but the added field notes further help an agent understand the result without being redundant.

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 no parameters, so there is no parameter semantics to explain. A baseline of 4 is appropriate because the schema is empty and the description does not need to compensate for missing parameter documentation.

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: “List every connected account,” and specifies the scope and output contents. This clearly distinguishes it from siblings like acct_get_account or acct_get_account_balance, which handle single accounts or balances.

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 tool is used to retrieve all connected accounts, but it does not explicitly state when to use it instead of alternatives such as acct_get_account or acct_get_account_balance. There are no exclusions or routing guidance.

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

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

Goes well beyond the annotations: discloses the bank-side rate limit, refines idempotency as "within rate-limit windows" (consistent with idempotentHint=true, not contradicting it), and flags the write-consent requirement plus the AKAHU_AUTOMATION_BYPASS escape hatch. Also states the response shape, which is exactly the operational context an agent needs before calling a non-readOnly tool.

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

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

Front-loaded with the action, then constraints (rate limit, idempotency, consent), then the return shape. Every sentence carries a distinct, useful fact with no filler.

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

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

An output schema exists, yet the description still previews the return fields and covers the two things that most often break this call in practice: bank rate limiting and the consent/bypass requirement. Nothing material is missing for a one-parameter mutation tool.

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

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

Schema coverage is 100% for the single account_id parameter, so the baseline is 3. The description only restates "one specific account" and adds no format, prefix, or ID-source detail beyond what the schema already documents.

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 ("trigger Akahu to fetch fresh data") plus a scoped resource ("one specific account"), which implicitly separates it from the sibling acct_refresh_all_accounts. An agent can tell exactly what the call does 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?

"Use when you only need to refresh one account (e.g. checking before a payday lookup)" gives a concrete selection condition, and the single-account scoping effectively steers agents away from the bulk-refresh sibling. It stops short of naming that sibling explicitly, so it is clear context rather than full when/when-not guidance.

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

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

Goes well beyond the annotations by disclosing that it is rate-limited by the bank, that idempotency holds only within rate-limit windows, that write consent is required unless AKAHU_AUTOMATION_BYPASS=true, and the return shape. These are non-obvious operational facts an agent cannot get from readOnlyHint/idempotentHint alone.

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

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

Front-loaded with the action, then constraints, then the return shape — every sentence carries signal. The explicit return signature is slightly redundant since an output schema exists, but it is brief enough not to be waste.

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 mutation-ish trigger, the description covers the action, timing guidance, rate-limit behavior, auth/consent requirement, and failure surface. Nothing an agent needs in order to call it correctly and interpret the result 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?

There are zero parameters, so the baseline is 4. Nothing in the description needs to explain inputs, and it correctly spends no words doing so.

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 ('Trigger Akahu to fetch fresh data') and an explicit scope ('every connected account'), which cleanly separates it from the sibling acct_refresh_account that targets a single account. No schema inspection needed to know what it does.

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

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

'Use before a query that needs the freshest balance or transaction data' gives a clear triggering condition. What's missing is an explicit when-not or a named alternative (e.g. use acct_refresh_account for one account), though the 'every connected account' scope makes the split inferable.

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

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

The readOnlyHint annotation already establishes that this is a safe read operation. The description adds useful detail about the returned identity fields and how name is assembled, but it does not cover auth requirements, error behavior, or other operational context.

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

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

The description is two short sentences with the core action front-loaded and no wasted text. The return-value detail is compact and useful.

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 empty input schema, existing output schema, and read-only annotation, the description is nearly complete for this simple tool. The main remaining gap is the lack of explicit sibling differentiation from id_verify_name.

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 no parameters, so there is no parameter semantics for the description to document. The baseline for zero-parameter tools 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: return identity/profile data for the connected Akahu user. It is clear what the tool does, but it does not explicitly differentiate itself from the sibling id_verify_name tool.

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

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

Usage is implied by the phrase 'for the connected Akahu user,' but the description gives no explicit when-to-use guidance or comparison with alternatives such as id_verify_name. It is adequate for a simple no-parameter identity lookup but leaves routing 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?

Adds substantial behavioral context beyond the annotations: the required Personal-App scope grant, the 403 Forbidden failure mode, possible per-call bank charges, and mandatory user confirmation that cannot be bypassed. These are exactly the operational risks an agent needs before invoking a verification call.

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

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

The description is front-loaded with the core action and scoping rule, followed by auth, cost, confirmation, and return details. It is efficient overall, though the explicit return-shape explanation is somewhat redundant given that an output schema exists.

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 verification tool with real-world cost and auth requirements, the description covers what it does, how scoping works, permission requirements, failure behavior, confirmation requirements, and return structure. An agent has enough information to invoke it correctly or recognize when it cannot.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters, including account_id's optional scoping behavior. The description reinforces how account_id changes the endpoint used, but does not add much parameter-level meaning beyond the schema.

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

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

States a specific verb and resource: verify a name against the account holder via Akahu's identity check. This clearly distinguishes it from all sibling tools, which handle accounts, transactions, or the user's own identity profile rather than name verification.

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?

Explains the key scoping decision: if account_id is provided, the check is limited to that account; otherwise Akahu checks every connected identity source. It also notes the required portal scope grant. It stops short of explicitly comparing against sibling tools such as id_get_me, but there is no direct alternative for name verification.

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?

Although annotations already declare readOnlyHint=true, the description adds substantial behavioral context beyond that: pending entries affect available balance immediately, can change or vanish, are not returned by get_transactions until settlement, and lack an id. It also describes the response shape and key field semantics, which is valuable given the dynamic nature of pending transactions.

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 and stays reasonably concise. It does enumerate return fields even though an output schema exists, which is somewhat redundant, but the added notes about pending behavior and missing id are useful rather than wasteful.

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 zero-parameter schema, readOnly annotation, and existing output schema, the description is complete enough for an agent to call the tool correctly. It covers the key behavioral caveats around pending transactions and return semantics without leaving material gaps.

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

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

The tool takes no parameters, so there are no parameter semantics to explain; this matches the baseline of 4 for zero-parameter tools. The schema is empty with additionalProperties false, and the description does not need to add parameter detail.

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: list all pending, not-yet-settled transactions across the user's accounts. It also distinguishes this tool from get_transactions by explaining that pending entries do not appear there until settlement, and the 'across the user's accounts' phrasing implicitly contrasts with the account-scoped sibling. An agent can identify the tool's role 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?

The description gives clear usage context: pending transactions affect available balance immediately but are absent from get_transactions until they settle, and may change or disappear. However, it does not explicitly name acct_get_pending_transactions as the per-account alternative or state when not to use this tool.

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

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

readOnlyHint=true already declares the safe-read profile, and the output schema covers the return value, so the remaining burden is light. The description does add meaningful context: it says the lookup is restricted to settled transactions, implying pending ones are excluded, but it does not say what happens for an unknown id or whether pending ids error out.

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

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

Two short sentences, zero filler, with the identifying scope ('one settled transaction by id') front-loaded. The second sentence carries non-redundant information linking the return shape to a sibling tool.

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

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

For a single-record read with an output schema and one fully documented parameter, the description covers what to expect from the response shape. Minor gaps remain around not-found behavior and the settled/pending boundary, but nothing critical to a correct call 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 100% and the single parameter already documents the Akahu transaction id format with an example. The description adds no syntax, format, or edge-case meaning beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('Fetch one settled transaction by id'), and the singular plus 'settled' qualifier distinguishes it from the plural list and pending siblings. It stops short of naming those siblings explicitly, so an agent must infer the contrast.

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

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

Usage is only implied by 'by id' and 'one' – the agent can infer this is the single-record lookup when an id is already known. No alternative is named (txn_get_transactions_by_ids, txn_search_transactions), and no when-not guidance is given.

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 only readOnlyHint=true in annotations, the description carries the behavioral load and does it well: exact return envelope, per-field semantics, the 20-page scan cap, and what truncated=true means plus the remedy. This is exactly the operational detail annotations cannot supply.

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 in one line, then the return contract is packed into a single tight block. It is dense but nearly every clause conveys a distinct fact about format or edge cases; only the field enumeration borders on redundancy given an output schema exists.

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 7-parameter read-only listing tool, an agent has everything needed to call it and interpret the result, including truncation handling. The per-field restatement is partly duplicative since an output schema is present, but the truncation and currency-unknown cases justify it.

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

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

Schema coverage is 100%, so baseline is 3; the description earns above that by clarifying signed-amount semantics (negative = debit), the account-currency formatting variants, and the NZ-calendar-day convention that underpins the date filters.

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

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

The description opens with a specific verb and resource ("List settled transactions") plus scope ("optional filters"). The word "settled" quietly distinguishes it from the pending-transaction siblings, though it never names them explicitly.

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

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

Usage is implied rather than stated: "settled" excludes pending, and "narrow the dates and call again" gives recovery guidance for truncation. However, it never tells an agent when to prefer txn_search_transactions or txn_get_transactions_by_ids over this tool, so sibling routing is left to inference.

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

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

readOnlyHint=true already covers the safety profile, and the description adds real value on top: it discloses the batch semantics, the "settled" filter, and the return envelope shape with a cross-reference to get_transactions so per-entry shape is inferable. It omits behavior for unknown/nonexistent ids and any batch-size cap, which would be the remaining behavioral gaps.

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

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

Three short sentences, with the core action front-loaded and the usage hint immediately after. The return-shape sentence is partially redundant with the output schema, which is the only mild inefficiency.

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 one-parameter read tool with an output schema and a readOnly annotation, the description covers what it does, when to use it, and what comes back. Only limits (max ids, unknown-id handling, result ordering) are absent, which is a modest but real gap for a batch API.

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

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

Schema coverage is 100% and the single `ids` array is documented as "List of Akahu transaction ids," so the schema does the heavy lifting. The description only restates the list-of-ids idea and adds no detail on ordering, duplicates, or a maximum batch length — baseline 3 applies.

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

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

States a specific verb and resource ("batch-fetch settled transactions by their ids") with the scoping qualifier "settled" and "in one request," which distinguishes it from txn_get_transaction (single), txn_get_transactions (list/filter), and txn_get_pending_transactions. An agent can route to it without opening any schema.

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

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

"Useful when you have a list of transaction ids (e.g. from a prior query) and want to inspect them together" gives a concrete triggering condition and a common source of the ids. It stops short of naming the alternatives it supersedes (e.g. looping txn_get_transaction vs. txn_search_transactions), so it is clear context without explicit exclusions.

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?

Adds substantial behavioral detail beyond annotations: it always elicits user confirmation, is not bypass-eligible, shows every ticket value including the comment, and collects missing required values before the confirmation prompt. It also discloses the return shape, while annotations already cover readOnly=false and destructive=false.

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

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

The description is front-loaded and appropriately sized for a tool with conditional validation and confirmation behavior. There is minor redundancy between 'Submit a support ticket about a transaction to Akahu staff' and 'Sends a ticket to a human at Akahu support.'

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

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

Given the tool's mutation/support complexity, rich annotations, complete schema coverage, and output schema, the description is complete. It covers confirmation behavior, conditional issue_type validation, elicitation of missing values, and return shape.

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 parameter meanings and conditional requirements. The description reinforces the issue_type-to-required-field mapping, but mostly repeats what the schema already states rather than adding new syntax or format 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?

States a specific verb and resource: submitting a support ticket about a transaction to Akahu staff. It clearly distinguishes this from sibling transaction retrieval tools, which only fetch transaction data.

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 context makes clear when to use it: reporting a transaction issue to human support. It does not explicitly name when not to use it or compare against alternatives, but sibling tools are all retrieval/account operations rather than support-reporting alternatives.

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?

readOnlyHint already covers the safety profile, so the description earns credit for adding substantive behavior: only settled transactions are searched (pending ones excluded despite sibling pending tools), matching stops once `limit` is reached, and the default window is 90 NZ days ending today. It stops short of covering performance or ordering of results, so it is not exhaustive.

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 matching semantics, then the date-window behavior, then the usage routing and return shape. Every sentence carries information an agent needs; 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, yet the description still names the return shape and its equivalence to get_transactions, which is useful for chaining. Combined with the settled-only constraint and window defaults, an agent can call this correctly without further reading.

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 all four parameters are already documented, including the 90-day default and the 1-500 range on limit. The description restates the default window rather than adding new syntax or format detail, so baseline 3 applies.

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

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

States a specific verb and resource: case-insensitive substring search across description and merchant name, restricted to settled transactions. The scope plus the explicit contrast with get_transactions lets an agent tell the two apart without opening either schema.

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

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

"Use for free-text lookups; prefer get_transactions when filtering by account or amount" gives both the when-to-use and the named alternative with the condition that selects it. Nothing is left to inference.

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