Taokeh MCP server

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

Annotations only declare readOnlyHint/openWorldHint false; the description goes far beyond, disclosing what a row represents (payable less payments, never gross), how unmatched payments enter as negatives, exclusions (cash bills, owner-paid bills, debit notes), and reconciliation exceptions (manual journals, FX revaluation, unposted bank lines).

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?

Long but deliberately structured with front-loaded purpose and capitalized headers ('WHAT A ROW IS:', 'UNMATCHED PAYMENTS:'). Dense yet nearly every clause carries interpretation value; a few caveats could be trimmed but nothing is 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 no output schema, the description carries the return-value burden and does so thoroughly, explaining total, documentTotals, unmatchedPayments, unmatchedPaymentsTotal and their signs. Complete for a complex financial report.

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 covers the single asOf parameter at 0%, but the description supplies the missing meaning: it is the valuation date ('less what has been paid against it by `asOf`' and aging 'from the date it left'). Format is left to the schema pattern, which is fine.

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?

Opens with a specific verb+resource+scope: 'Whom you owe money and how overdue it is — your accounts-payable aging by supplier, aged from each bill's DUE date.' An agent can immediately tell this is the payables aging report versus ar_aging or search_documents.

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 rich interpretation guidance (quote documentTotals for overdue, compare against search_documents) but never states when to use this tool vs alternatives like ar_aging or the balance sheet. Usage is implied rather than routed.

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 readOnlyHint and openWorldHint, so the description carries the behavioral burden and does so richly: negative rows, unmatched payments, reconciliation discrepancies, back-dated exclusion of post-asOf movement, and deliberate document-universe differences. It stops short of stating return format or any performance limits, but for a read-only report the coverage is well beyond the annotation baseline.

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

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

The core purpose and sibling routing are front-loaded in the first sentence, and the dense remainder is information-bearing rather than filler. It is a single sprawling block, however, and a few asides (e.g. the FX revaluation detail) 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 output schema, the description still enumerates the return structure (unmatchedPayments fields, unmatchedPaymentsTotal, documentTotals, totals) and explains edge cases that would otherwise confuse an agent, leaving nothing essential unstated for a one-parameter report.

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 0% for the single `asOf` parameter, so the description must compensate. It does: 'Movement booked after `asOf` is excluded, so a back-dated aging shows what was owed on that date' tells the agent what the parameter actually controls, though it omits the date format (which the schema pattern supplies).

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 ('accounts-receivable aging across ALL customers, bucketed by age') and immediately distinguishes itself from the sibling open_invoices by scope (ALL customers vs ONE named customer). An agent can pick between the two 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?

Explicitly names the alternative tool and the condition that selects it, tells the agent which figure to quote for which question (documentTotals for overdue, totals for balance), and explains when this report should and shouldn't match the control account.

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

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

Beyond the readOnlyHint annotation, the description discloses important behavior: deltas are computed server-side in integer cents, deltaPct is NULL when earlier balance is zero, percentages use absolute earlier balance, current earnings is not a real account, nothing posts to it, and warnings are included if the sheet does not balance. This is detailed behavioral transparency.

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 quite long and repeats the position-versus-period warning multiple times, but the repetition is purposeful to prevent common misinterpretations. It is well structured with clear sections for comparison semantics, delta behavior, and output notes, so the length is mostly justified.

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?

Even though there is no output schema, the description fully explains output concepts: deltaCents, deltaPct, points, notes, null handling, and warning behavior. It also covers edge cases like zero earlier balances and imbalanced sheets, making it complete for an agent to invoke 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?

The description adds strong semantic value for compare and compareAsOf, including override behavior and the meaning of named comparison points. However, asOf has no schema description and the description does not state what happens when asOf is omitted, even though it is not required in the schema. It mostly compensates for schema gaps but leaves that minor ambiguity.

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?

Description clearly states the tool returns a balance sheet as of a date: assets, liabilities, equity, and the balanced check. It also distinguishes itself from income_statement by emphasizing position vs period, so an agent can tell it apart from key 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?

The description explicitly explains when the comparison mode is appropriate, how to choose named comparison points versus an explicit earlier date, and warns against framing the delta as a period figure. It names income_statement as the contrasting tool and gives clear 'never' instructions, acting as practical usage 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?

The description goes far beyond the annotations, disclosing read-only behavior, the 'never forced to zero' difference, handling of 'Not stated' balances, pagination limits, truncation behavior, and refusal of non-ringgit accounts. It aligns with the readOnlyHint annotation and adds substantial behavioral 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 long but every sentence is purposeful: it front-loads the core purpose, then systematically details return objects, edge cases, defaults, restrictions, and related tools. No fluff or redundancy; the structure aids comprehension.

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

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

With no output schema, the description must explain return values, which it does comprehensively (report, clearStep, hints) including their subfields and special conditions. It also covers pagination, defaults, and restrictions, making the tool fully usable without external reference.

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?

Even though the schema describes all 5 parameters (100% coverage), the description enriches them: explains defaults (first bank account, latest statement), the purpose of balance (only when statement lacks closing balance, never stored), offset's paging (300 rows), and asOf's hand-reconciliation role. This adds significant meaning beyond the schema.

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

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

The description clearly states the tool's purpose: performing an audit bank reconciliation for one bank account, matching the app's behavior. It specifies the resource (bank account) and distinguishes from siblings like bank_reconciliation_status and create_bank_clearing_draft, leaving no ambiguity.

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 explicitly explains when to use this tool (to work the reconciliation with the owner) and names alternative tools for actions (create_bank_clearing_draft for ticking entries, create_payment_match_draft for settling payments). It also details parameter defaults and selection logic, leaving no guesswork.

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, and the description reinforces it with 'READ-ONLY.' Beyond that it adds real behavioral context: it defines what each stored status means, explains pairing semantics, and states the figures match the in-app page. It does not cover auth requirements or performance, so not 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?

The description is a single enormous run-on paragraph packed with parentheticals and nested definitions. It is front-loaded with the main purpose, but the volume and lack of structure make it hard to scan and violates the conciseness bar.

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

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

With no output schema, the description must and does explain return contents in detail (rowCounts, reconcilingItems, drift categories, per-statement tie-outs). It is arguably over-complete rather than under-complete, which is the right side of the tradeoff for a schema-less 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?

There are zero parameters, so the baseline is 4; there is nothing for the description to clarify or compensate for.

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

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

The opening clause ('Where each bank account stands on reconciliation: GL balance vs the latest statement's closing') states a specific verb/resource/scope clearly. It does not, however, explicitly differentiate itself from siblings like bank_reconciliation_report or bank_review_queue, so an agent must infer the boundary.

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 statement and no named alternatives, even though several siblings (bank_reconciliation_report, bank_review_queue, bank_reconciliation_status) clearly overlap. The agent gets a rich payload description but no routing guidance.

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

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

Annotations only give readOnlyHint/openWorldHint, and the description massively exceeds them: the 1000-row refusal on unreviewed windows, the 200-row cap with truncation note, NULL suggestion fields on settled rows, `notPostable` on every foreign-currency row, the loan/OWNER_WITHDRAWAL fence, the sole-proprietor carve-out, and the hard limit that it can never confirm or post. These are exactly the non-obvious behaviours an agent would otherwise get wrong.

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 correctly — what the tool is comes first — but it is many times longer than needed, with repeated material (the 2400/loan parenthetical is stated twice, and the 'only a resemblance, say so' caveat recurs for possibleDuplicateOf, possibleTwin and its three kinds). Deeply nested asides about loan fences and business types bury the operational facts 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 no output schema, the description carries the full return-shape burden and does so: suggested fields on unreviewed rows, decided fields on settled rows (`category`, `glAccount`, `contact`, `journalEntryId`, `splits`, `allocations`), `yourProposal`, `statusCounts`, `currency`/`currencies`, and sorting/truncation behaviour. Nothing material is missing for correct invocation.

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

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

Schema coverage is 75% and the schema already lists the `status` values and the from/to window behaviour, so the description largely repeats structured data there. It does add real meaning the schema lacks — statementId defaults to 'the latest imported statement if you don't name one', and that a window payload reports `scope:'window'` with `statement` null. Useful but not fully additive over the schema.

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

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

The opening line names the exact resource and its scope: 'The IMPORTED BANK REGISTER — the rows that came in on a bank or card statement, in ANY status, defaulting to the ones still awaiting review.' It also explicitly separates itself from the neighbouring concept (hand-recorded settlements), naming search_documents with docType:'payment' as the sibling for those. An agent can distinguish this from search_documents, shoebox_items and draft_bank_classification 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?

When-to-use is spelled out per branch: omit `status` for the review queue, pass `status` for settled history, pass `from`/`to` without statementId for a cross-statement date window, and use create_bank_clearing_draft instead of a category when `possibleTwin.kind` is 'bookEntry'. When-NOT-to-use is equally explicit ('Never ask the owner to post, match or refund' a foreign-currency row; 'never propose a category' for a paired or cardBill row).

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 carry the safety profile (readOnlyHint=true, openWorldHint=false), and the description adds meaningful behavioral context beyond them: the temporal framing ('so far', today's and this-month's), the hard exclusion scope ('Sales and expenses ONLY'), and the point-in-time nature of a snapshot. It stops short of a 5 only because it doesn't describe the return format or whether figures are aggregates.

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

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

Two sentences with zero wasted words: the core purpose is front-loaded ('one-glance health check'), the scope is stated precisely with 'ONLY', and the alternative routing follows immediately. The em-dash separation and caps signal emphasis without bloat.

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 parameterless, read-only snapshot tool with no output schema, the description fully covers what an agent needs: what data is returned (sales and expenses, today and this month), what is excluded, and what to call instead for broader coverage. Nothing required for correct invocation is missing.

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

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

The input schema is empty and the parameter count is 0, so the baseline of 4 applies — there are no parameters whose semantics need clarification. Schema description coverage is trivially 100% for an empty schema, and the description correctly communicates that this tool requires no arguments.

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: a 'one-glance health check' of 'today's and this-month's sales and expenses'. It sharply delineates scope with 'Sales and expenses ONLY' and explicitly differentiates itself from daily_brief, so an agent can distinguish it from the 58 siblings 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?

The description gives an explicit when-to-use-this vs. when-to-use-that rule: call daily_brief instead when wanting the fuller morning read (cash position, receivables, approvals, tax, low stock), noting daily_brief 'includes everything here'. This is a direct alternative with a named sibling and a specific selection condition.

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

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

The description goes far beyond the annotations (`readOnlyHint: false`, `openWorldHint: true`) by disclosing exact accounting treatment: owner advances excluded, overdue AR not assumed collected, channel unsettled money deliberately excluded from balances, and every outflow category with its timing. It also explains how absent channel data affects the forecast, which is rich behavioral 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 purpose is front-loaded in the first sentence, and most subsequent sentences carry accounting rules rather than filler. It is long and occasionally repetitive in emphasizing 'honest' and 'stated upside,' but the length is justified by the complexity of the forecast.

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

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

With no output schema, the description carries the full burden of explaining return values and does so thoroughly: weekly inflows/outflows/closing balance, the `dip`, `assumptions`, `overdueArCents`, and `channelUnsettled`. Nothing essential for interpreting or safely using the forecast 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?

There are zero input parameters, so the baseline is 4. The description does not need to document parameter syntax, and it correctly focuses on output semantics instead.

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 and resource: a forward 8-week cash-flow forecast. It distinguishes itself from siblings like cash_position and working_capital by scoping the output to projected weeks, a `dip`, and `assumptions`, and by explicitly saying it is 'honest arithmetic from your books, not a model.'

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

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

The description explains the forecast's scope and when certain fields appear (channel connected vs. not), but it does not explicitly compare itself to alternatives such as cash_position or working_capital. Usage is implied by the purpose rather than guided by named when-to-use/when-not rules.

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 the read-only, closed-world safety profile, so the description carries the real burden — and it delivers: what is inside `total` vs excluded, how ownerFunding and cards are surfaced separately, business-type caveats (sole proprietor/partnership, `fromBeforeBusinessType` flag), card `direction` semantics, and MYR booking of foreign balances. This is far beyond what the annotations provide.

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

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

Purpose and total definition are front-loaded, then edge cases follow in a logical order. The single dense paragraph with heavy emphasis ('never', '⚠') is long, but nearly every sentence carries distinct accounting semantics rather than 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?

With no output schema, the description assumes full responsibility for explaining return values, and it does so comprehensively — total composition, ownerFunding, cards/cardsOwing, direction, and currency booking. Nothing essential for correct reporting 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?

There are zero parameters and 100% schema coverage, so the baseline is 4. The description adds no parameter meaning because none exist; the field-level explanation it does give concerns outputs, not 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?

Opens with a specific verb+resource statement — 'How much cash you have right now' — and immediately enumerates the returned shape (every bank account and cash pocket with its current GL balance, plus a grand total). An agent can tell this apart from forward-looking siblings like cash_forecast or aggregate reports like balance_sheet. Purpose is unambiguous.

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

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

The description is rich on how to interpret and relay results, but it never states when to choose this tool over alternatives such as cash_forecast or balance_sheet, nor any prerequisites. Usage is implied by the resource rather than routed explicitly, so 3 is appropriate.

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 give only readOnlyHint/openWorldHint, so the description carries the behavioral load and does it thoroughly: returns matching rules, reversal date basis, gross-vs-net semantics, settlement lag, delayed TikTok fees, and the fact that marketplace figures are not final at import. This is far beyond what the annotations disclose.

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, but the body is a very long, dense run-on that restates the same point twice (the six figures are GROSS of returns) and re-explains the dual date basis for both reversals and TikTok settlements. Much is earned given no output schema, but it is not tight.

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

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

With no output schema, the description carries the full burden of explaining return-value semantics and does so completely: what counts in returns, what stays gross, why saleCount-0 rows appear, exclusions, and how figures may move after import. An agent has everything needed to read the result correctly.

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

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

With 0% schema description coverage, the description must define the params, and it does: from/to are a date range and must be given as YYYY-MM-DD. This confirms format and meaning for both parameters, though it adds no guidance on inclusive bounds or timezone.

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 gives a precise verb+resource+scope: sales broken down by CHANNEL for a date range, followed by an enumeration of the per-channel figures returned. It is clearly distinguishable from a flat sales summary, but it never names a sibling (e.g. sales_summary) to route against.

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 channel dimension — nothing states when to prefer this over sales_summary or expenses_summary. The directive 'Say which month you are reading' is a caveat about interpreting output, not guidance on tool selection.

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

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

The description goes far beyond the readOnlyHint annotation, explaining critical behavioral nuances: an open day is not in the ledger, stock/COGS only move at close, closed days post as one consolidated sale via saleId, creditSales post immediately as credit invoices, cash is rounded but QR is not, and large receipts are handled individually. This prevents serious misinterpretation of the returned figures.

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 long, but almost every sentence addresses a distinct misinterpretation risk or clarifies an important return value, which is justified given there is no output schema. It is front-loaded with the return summary before the caveats, though tighter phrasing could reduce its overall length.

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

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

With no output schema, the description carries full responsibility for explaining return semantics, and it does so thoroughly: open/closed behavior, saleId, creditSales, rounding rules, consolidated vs individual receipts, and the not_available state for companies without the paid add-on. An agent has enough information to call and interpret this tool correctly.

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

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

The only parameter is 'date', and the schema already covers 100% of its meaning with 'YYYY-MM-DD in Malaysia time. Omit for today.' The description repeats this but does not add meaningful parameter-level detail beyond what the schema provides.

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

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

The description clearly defines the resource ('Counter till's day'), scope (one date, default today, Malaysia time), and the specific outputs returned (receipt count, voided count, cash/QR totals, open/closed status, receipt ranges, credit sales). It also distinguishes this tool from ledger-level sibling reports by explicitly stating that an open counter day has not posted to sales_summary, cash_position, income_statement, etc.

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

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

The description provides strong context for when this tool is relevant: use it to inspect till-level day figures before they reach the ledger, and it explains how those figures relate to sales_summary, cash_position, income_statement, open_invoices, and ar_aging. It does not explicitly state 'use this instead of X', but the ledger-vs-till distinction gives clear practical 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 give only the generic readOnly=false/destructive=false/idempotent=false profile; the description adds substantial context beyond them: the draft-then-human-approval lifecycle, that a tick posts nothing to the books and is reversible ('the owner can un-tick it'), the exact refusal reasons at both filing and approval, and the invalidation rule ('If anything it was filed against changes before approval ... approval refuses and nothing is ticked'). This is far richer than the annotations.

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

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

The critical constraint is front-loaded in caps, which is exactly right, and each sentence carries information. However, the prose is dense and run-on, packing the entire refusal taxonomy into a single sprawling sentence with nested parentheticals, which costs some scannability.

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

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

For a 10-parameter, no-output-schema mutation tool, the description covers the full lifecycle: id sourcing, item construction, size limits, cancellation handling, refusal conditions, post-filing invalidation, and the owner note. Nothing an agent needs to file 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 100%, so the baseline is 3, but the description adds real meaning: entryId must come from clearStep.uncleared, statementLineId from clearStep.candidateLines, clearedDate defaults to the reconciliation date like the page, and statementId vs asOf are alternatives. It also clarifies that the decoy keys (notes, ticks, bankId, entries) are not filters and points to the correct parameter names.

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 'FILES A PENDING DRAFT' proposing ticks for Banking → Clear transactions, and immediately scopes the effect ('NOTHING CHANGES UNTIL A HUMAN REVIEWS AND APPROVES IT'). It distinguishes itself from siblings by directing the agent to bank_reconciliation_report for ids and from update/revise tools by framing the output as a reviewable draft.

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 explicitly says to 'Read bank_reconciliation_report first and take every id from it' and specifies exactly which ids come from which sub-fields. It states when to use statementLineId versus clearedDate, the 300-item cap, and how cancelling pairs are filed. The refusal list names the conditions under which the tool will not accept a filing.

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 it is a non-readOnly, non-destructive, non-idempotent write; the description adds substantial context beyond that — it does NOT post to the books, it creates a pending draft the user approves, approval triggers stock receipt/moving-average blending/SST booking, and the server recomputes quantities rather than trusting the agent's figures. It also discloses the strict line-key rejection behavior and the legacy silent-drop change, which no annotation conveys.

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

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

The critical constraints (INVENTORY-ONLY, does not post) are front-loaded, but the body runs long and re-explains attachment mechanics that the schema parameter descriptions already cover in detail, plus repeats the strict-line-key rule in an extended narrative. Much earns its place, but the length is bloated relative to a 19-param 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?

With no output schema and 19 parameters, the description supplies the missing context: the drafting→approval lifecycle, prerequisite tools, alternates for excluded bill types, attachment paths with mutual-exclusivity rules, and term-vs-dueDate fallback behavior. Nothing an agent needs to invoke this correctly 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 schema already carries rich per-parameter text (58% coverage), but the description adds real meaning the schema lacks: why `term` matters (payables aging buckets, OVERDUE badge, 8-week forecast) and the attachment decision tree (inline vs request_attachment_upload vs shoeboxItemId, and the allowlisted-shell exception). It does not spell out untagged params like vendorId/reference/printedTotal.

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 and resource ('File a supplier-bill DRAFT into Taokeh') and immediately narrows scope with 'INVENTORY-ONLY'. It actively distinguishes itself from siblings by naming the manual bill form and create_expense_draft as the routes for adjacent 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?

Explicit when-not conditions ('for services / non-stock / mixed bills use the manual bill form, or create_expense_draft if already paid') plus a required prerequisite pipeline (intake_contract → resolve_vendor → resolve_product). An agent can route correctly without opening any other schema.

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 (readOnly=false, destructive=false). The description adds the review/approval flow, that the draft is refused without the image, how truncation and MIME mismatches are rejected, mutual exclusivity of the two attachment paths, and the owner-verification step — substantial context beyond the annotations.

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

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

Front-loads the two hard requirements (image required, no address-book write) and is well ordered, but it is a very dense block that repeats some schema guidance (never guess a phone/email, leave empty and flag) rather than purely adding new 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 16-parameter, no-output-schema write tool, the description supplies everything an agent needs: the required input, both attachment routes, the refusal conditions, the honesty/notes policy, and the downstream review consequence. Nothing material is missing.

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

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

Schema coverage is 100% and the schema already documents most fields, so the baseline is 3; the description earns extra credit by explaining cross-parameter flow the schema cannot (attachmentBytes guards against truncated base64, attachmentToken must be used after the PUT, never both, partyName overrides printed company).

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 ('File a pending CONTACT draft from a business card') and explicitly distinguishes itself from the address-book mutation it is not ('This does NOT add anyone to the address book'), which separates it from update_contact_draft and the other create_*_draft 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?

Gives explicit when-to-use conditions (agent has read the card, image mandatory), the two mutually exclusive attach paths (inline base64 vs request_attachment_upload → PUT → attachmentToken), defaulting rules for partyKind, and when to leave fields empty. 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.

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

Annotations declare a non-read-only, non-destructive write. The description adds rich behavioral context: it does not post to books, creates a pending draft, user approves before balance/SST/stock changes, over-quantity lines are refused, mismatched totals refuse one-tap approval, already-reversed invoices are refused, and strict line keys are enforced. This goes well beyond 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?

Front-loaded with the core purpose, and most sentences carry necessary distinctions for a complex 13-parameter tool. However, it is a dense wall of text that could be better structured for readability, so not a perfect 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?

No output schema exists, but the description covers usage conditions, edge cases, refusals, alternatives, and behavioral details. An agent has enough information to invoke the tool correctly without needing additional context.

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

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

Schema coverage is 77%, so the schema already documents many parameters. The description adds cross-parameter semantics: how kind interacts with originalDocId/customer, positive amounts, discount handling, line key strictness, goodsReturned as a hint only, and notes. This adds meaningful guidance beyond the schema descriptions.

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 (file), resource (credit note draft), and scope (reduces what a customer owes), and distinguishes from sibling tools like update_invoice_draft, update_credit_note_draft, revise_draft, and voiding. An agent can immediately tell what this tool does and what it does not.

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

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

Explicit when/when-not guidance: only when something changed after the sale; if the sale never happened, void the invoice; if the invoice was typed wrong, use update_invoice_draft; if a posted credit note is wrong, use update_credit_note_draft. Also instructs to resolve the original invoice first and ask the user when the invoice is unclear.

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 the safety profile (non-readonly, non-destructive, non-idempotent), and the description goes well beyond them: it discloses that nothing posts to the books until a human approves, that one-tap approval is refused if the computed total drifted, that reversed orders from Shopee/TikTok/Shopify pages are refused at file and approval, and that strict line-key validation now rejects unknown keys by name. Missing are rate limits or auth/permission specifics, but the behavioral picture is unusually rich.

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

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

The purpose and the invoice requirement are front-loaded, which is good, but the text is long, heavily used with caps, em-dash asides and an emoji warning, and several rules (money-only, no restock, charge-the-shortfall) are restated in more than one place. Every rule is real, yet the same information could be delivered in materially fewer sentences.

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

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

For a nested-line, 11-parameter mutation tool with no output schema, the description covers everything an agent needs: prerequisites (intake_contract, search_documents), the approval/return semantics of the pending draft, failure modes (reversed invoice, unknown line keys, mismatched customer, total drift), and correction paths. Nothing material is left to inference.

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 73%, so the schema already carries most per-field meaning, but the description adds non-obvious semantics: originalDocId is effectively required (verified to exist, be an invoice, and belong to the right party), unitAmount is the ADDITIONAL per-unit shortfall rather than the corrected price, quantity defaults to 1, and productRef must resolve to a product already on that invoice. It stops short of documenting dnDate's format or the customer/customerId refusal interaction in any 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?

States a specific verb and resource ('File a SELL-SIDE DEBIT NOTE draft'), defines what the document economically is (an additional charge on an already-issued invoice, not a stock or goods event), and explicitly distinguishes it from siblings: credit note, new invoice, and the buy-side /debit-notes flow. An agent can route correctly 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 explicit when-to-use and when-NOT-to-use with named alternatives: shape with intake_contract first, find the invoice with search_documents, use create_invoice_draft when there is nothing to correct upward, revise_draft on a misfile, update_supplier_debit_note_draft for an already-posted buy-side note. Exclusions are stated, not implied.

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

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

Annotations already declare non-read-only, non-destructive, non-idempotent, closed-world, but the description goes well beyond: it describes the draft→approval→posted lifecycle, that the attachment 'lands on the posted entry automatically on approval', refusal behavior (truncated base64, mismatched MIME type, shoebox item already booked or carrying a pending draft), and mutual-exclusivity rules ('never both'). This is real behavioral context an agent cannot get from the structured fields.

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 correctly — purpose and the critical non-posting caveat come first, with operating instructions after. It is long, and the final sentence stacking the token flow, the sandbox-allowlist exception and 'never both' is dense, but nearly every sentence carries distinct operational content rather than 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 an 18-param mutation tool with no output schema, the description covers the genuinely hard parts — attachment ingestion, review flags, shoebox state constraints, and validation failure modes. The residual gaps are the plain fields (date, currency, inputTax, reference, account codes) that an agent would still be guessing at.

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 44% across 18 params, so the description must compensate. It does explain amountUncertain, needsReview, notes intent, and the three attachment-parameter paths in useful detail, but date, memo, currency, inputTax, reference, debitAccountCode, and creditAccountCode remain undocumented in both places (account codes are only indirectly pointed at via expense_accounts). Partial compensation for a sizeable gap.

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 and resource ('File a paid-expense DRAFT into Taokeh from a receipt you've read') and immediately clarifies the non-effect ('does NOT post to the books'). It cleanly separates itself from posting/ledger tools, though it never names a create_*_draft sibling (e.g. create_receipt_draft or create_bill_draft) as an alternative, so same-family disambiguation is left to 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?

Strong operational guidance: 'Shape the fields with intake_contract + expense_accounts first', explicit conditions for amountUncertain and needsReview, and a decision path for attachments (inline base64 for small files vs request_attachment_upload → attachmentToken for real photos/PDFs). It stops short of saying when to choose this tool over create_bill_draft/create_receipt_draft for a given document, so it is clear context without full alternative routing.

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

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

With annotations only carrying the read/write/idempotency flags, the description adds substantial behavioral context: the server re-computes every line quantity and grand total (figures authoritative), attachment lifecycle (draft → posted invoice, no re-upload), the strict line-key rejection with named refusal, and the near-miss/confirmNewCustomer guard implied elsewhere. It also states what happens on truncation ('rejected instead of filed') and that unknown keys previously failed silently.

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 purpose, then ordered by workflow (prereqs → recompute → reviewer note → attachment → strict keys), and the ⛔ key warning is signposted. It is long and the attachment paragraph partially restates the schema's own attachmentBase64/attachmentToken/attachmentBytes descriptions, which is 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?

For a 20-parameter mutation with no output schema and only flag-level annotations, the description is close to complete on workflow and side effects. It never says what the call returns (e.g. a draft id or review link), which would help an agent chain to revise_draft or get_document_pdf, and a few params rely solely on their schema entries.

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 60%, and the description meaningfully compensates for the uncovered area: it explains the two attachment paths (inline vs request_attachment_upload → PUT → attachmentToken), attachmentBytes as a truncation check, mutual exclusivity, the shoebox path, and the needsReview/notes contract. It stops short of explaining several undocumented params (reference, customer/customerId, printedTotal).

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

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

Specific verb+resource ('File a sales-invoice DRAFT into Taokeh from a sales note you've read') and immediately differentiates from the posting path and from update_invoice_draft by stating it creates a pending draft the user approves. An agent can tell this apart from create_receipt_draft / create_quote_draft / create_recurring_invoice_draft 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 explicit prerequisites (shape fields with intake_contract(doc_type:'invoice') + resolve_customer + resolve_product first) and when-to-use context (only after the user approves does it post and move stock). It also routes to the alternative request_attachment_upload for large files and to the inline path when the sandbox blocks the host. No explicit exclusion against sibling draft creators, but the workflow guidance 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 declare a non-destructive write, but the description carries far more: it never posts to the ledger, only approval writes it, unbalanced entries are refused with the difference named, unknown account refs are refused and ambiguous ones report candidates, accounts are never auto-created, and control-account lines are flagged and require full in-app review. It also explains the no-edit/no-delete policy as deliberate, which is exactly the kind of context annotations cannot convey.

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 and the negative scoping are front-loaded, and nearly every sentence carries operational content. It is long and heavy on all-caps emphasis, but for a 13-parameter tool with several hard failure modes the density is largely justified 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 13 parameters, no output schema, and a non-trivial balancing and attachment workflow, the description covers everything an agent needs to call it correctly: the intake_contract prerequisite, the balance rule, the one-side-per-line rule, control-account review escalation, attachment transport fallbacks, and the correction path.

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 85%, so the baseline is 3; the description still adds real meaning by specifying that accountRef must come from the chart returned by intake_contract, that codes beat exact names, and that ambiguous names produce candidates. It also spells out the attachment exclusivity rule (token XOR base64, with attachmentBytes as a truncation check) beyond what the schema states.

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?

Opens with a specific verb+resource ('File an ADJUSTING JOURNAL ENTRY as a draft') and immediately scopes it to accountant's entries (accruals, depreciation, reclassifications, reversals). It explicitly distinguishes itself from the document-based siblings by naming create_bill_draft, create_invoice_draft, create_expense_draft and create_receipt_draft as the correct tools for anything with a real document.

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 explicit when-to-use (accruals, prepayments, corrections), explicit when-NOT-to-use with the four alternative tools named, and a full alternative workflow for correcting posted entries (search_journal → reversing entry → correct entry). It also routes misfiled drafts to revise_draft rather than a duplicate file.

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 that nothing posts until approval, that the server re-derives allocations at both create and approval, that credit cards and foreign-currency bills are refused by name, and that a matching imported line triggers a refusal. Attachment flow (inline vs token, byte-size guard, mutual exclusivity) is fully explained.

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 crucial 'draft only, nothing changes' constraint, but the body is a dense wall of ALL-CAPS clauses and long parentheticals that is hard to parse. Much of the content earns its place given the tool's complexity, but the formatting and length 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 15 parameters, no output schema, and intricate business rules, the description still covers every material branch: allocation strategy, debit-note netting, currency and account restrictions, duplicate-filing avoidance, and the full attachment path. An agent has everything needed 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?

Schema coverage is high (87%), so the baseline is 3, but the description adds real meaning: amounts are ringgit not sen, `total` auto-allocates oldest-first into net-of-debit-note figures, explicit allocations may go up to the pre-debit-note open amount, and purchaseId should be preferred over reference. It reinforces rather than merely repeats 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 precise verb+resource (files a supplier-payment DRAFT) and immediately scopes it as pending-only pending human approval. It clearly separates itself from siblings like create_payment_match_draft and draft_bank_classification by defining exactly what kind of payment event this is.

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

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

Explicit when-to-use and when-NOT-to-use: routes to draft_bank_classification when the payment already sits on an imported line, to import_bank_statement for card spend, to Banking→Match for foreign currency, and to revise_draft instead of refiling. Prerequisite steps (resolve_vendor, ap_aging, search_documents) are 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 only say readOnlyHint=false, destructiveHint=false, idempotentHint=false; the description adds far more — nothing mutates until a human approves, at most 50 documents, refusals by name at filing and re-checked at approval, and staleness refusal if the line or a document changes. The only gap is the absence of any statement about what a successful response contains, though the refusal payload (documents the line can take, with ids) is described.

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

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

The critical constraint (pending draft, nothing changes until approval) is front-loaded in caps, and most sentences carry load given the number of refusal modes. It is nevertheless long, with some repetition around the refusal list and the re-check at approval that 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?

For a mutation-tool with 8 parameters, no output schema, and non-trivial eligibility rules, the description covers preconditions, scope of allowed documents, refusal modes, and cardinality limits. No output schema exists, and the one return-ish detail (refusals list eligible documents with ids) is supplied.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: bankTransactionId must be a POSTED line from bank_review_queue, allocations must use saleId for money in and purchaseId for money out, must be in ringgit, and must sum to the WHOLE line to the sen (no ±0.10 rounding allowance). It also clarifies the decoy parameters (lines/notes/bankLineId/transactionId are not filters on this tool).

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

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

States a specific verb and resource ('Propose how ONE bank line ... settles open invoices or bills') and immediately frames it as a pending draft that a human approves. It distinguishes itself from the other draft-creation siblings by naming the exact in-app equivalent (Banking → Match → Save) and the money-in vs money-out branches.

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

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

Explicit about when to use it, what qualifies as a valid input line, and what to do when it does not (unpost the line in Banking, set the right customer, repost, then file). It also enumerates when the tool refuses and why, which is precisely the when/when-not guidance an agent needs.

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 non-read-only, non-destructive, non-idempotent. The description adds genuinely load-bearing behaviour: nothing is POSTed or moved, no journal/stock/amount owing is created, the order is saved as a DRAFT and Taokeh emails nobody, SST is not applied by this tool, quantities are recomputed server-side and the agent's figures are advisory only, and unknown line keys are now refused by name rather than silently dropped.

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 no-posting guarantee, which are the highest-value facts. The remaining bulk is largely earned by the domain's real complexity, though the parenthetical SST sentence and the layered tally/quantity caveats are dense enough to slow an agent down.

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

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

No output schema exists, so the description must carry the full return-side story, and it does: it tells the agent the draft is filed, no books move, and the conversion to a bill happens later on Taokeh. Combined with the strict-key warning and the cross-tool routing, an agent has everything needed to call this correctly for an 11-parameter mutation.

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

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

Schema description coverage is only 45%, but the description compensates for the important gaps: it explains what `notes` should contain (one-to-two-sentence reviewer flag), instructs setting `needsReview`, clarifies that `reference` is the buyer's own PO number and not the supplier's, and that `confirmNewVendor` bypasses the near-miss guard only after explicit user confirmation. It does not add much for `vendor`/`vendorId`/`printedTotal`, keeping it short of a 5.

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

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

States a specific verb and resource ('File a PURCHASE-ORDER draft'), then defines the semantic boundary precisely: an order you intend to place, read off a quotation. It explicitly distinguishes itself from create_bill_draft ('goods that have ALREADY arrived') and from update_purchase_order_draft/revise_draft, so an agent can route correctly 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?

Gives when-to-use (intent to buy, not yet received), when-not (goods already arrived → create_bill_draft; service/non-stock → manual form), prerequisite sequence (intake_contract, resolve_vendor, resolve_product), and the correction path (revise_draft kind:'purchase_order' rather than filing a second one). Nothing material 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?

Annotations declare write/non-destructive/non-idempotent, and the description adds substantial context beyond them: the tool creates a pending draft that only posts on human approval, the server re-computes quantities and grand total so server figures are authoritative, review-time document visibility (s.82), and strict line-key rejection with named errors. This is precisely the extra behavioral detail annotations cannot carry.

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 purpose and draft semantics before mechanics, and nearly every sentence carries operational information (attachment rules, key strictness, server authority). It is dense and long, with a few heavily nested sentences, but little is 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 17-parameter mutation tool with no output schema, the description covers the core call path, the attachment strategy, and the failure modes an agent must avoid. It stops short of explaining a handful of remaining fields, so it is strong but not exhaustive.

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 59%, so the description is expected to compensate. It does add meaning for notes, needsReview, and the attachment precedence rules, but several parameters (taxCode, working, discount, printedTotal, reference, customerId, term) are neither described in the schema nor mentioned in the description, leaving real gaps.

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 ('File a quotation DRAFT into Taokeh') and immediately scopes it: an estimate that does NOT post to the books or move stock, creating a pending draft the user approves. This cleanly separates it from create_invoice_draft and the other create_*_draft 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?

Explicit workflow ordering ('Shape the fields with resolve_customer + resolve_product first'), when to set needsReview and write a note, when a customer may be omitted, and a clear attachment decision tree (inline vs request_attachment_upload vs the sandboxed-shell exception). Alternatives and their selecting conditions are named.

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 (not read-only, not destructive, not idempotent); the description adds material behavior beyond that — it does NOT post, a human must approve before a real bank receipt is written and invoices settle, the server re-derives allocation against live outstanding, and attachments ride the draft onto the settlement entry. It also spells out the attachment path (inline vs request_attachment_upload), size/truncation rejection, and mutual exclusivity.

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 core purpose and the non-posting constraint, then flows into prerequisites, currency constraint, then attachments. It is dense and somewhat long, with attachment landing-on-settlement stated twice, but almost every clause carries operational weight for a 15-parameter tool.

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

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

For a money-moving, attachment-carrying, review-gated tool with no output schema, the description covers the lifecycle (draft → review → approval → bank receipt), the prerequisite chain, the currency restriction, and the full attachment decision tree including the sandboxed-client fallback. An agent has what it needs to call this correctly.

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

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

With only 47% schema coverage, the description carries real weight: it explains the total-vs-allocations choice and oldest-first auto-allocation, the needsReview/notes contract, and the attachment field relationships (attachmentBase64 + attachmentMediaType + attachmentBytes vs attachmentToken). It leaves required receiptDate, printedTotal, bankAccountId, attachmentFilename, and attachmentSha256 undocumented, so it does not fully compensate for the coverage gap.

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 ("File a customer-payment DRAFT") and immediately scopes it as non-posting, distinguishing it from siblings like create_payment_draft and create_bank_clearing_draft. An agent can tell exactly what this does before 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 explicit prerequisites and workflow: resolve the customer via resolve_customer, check obligations via open_invoices, then choose EITHER a lump total OR per-invoice allocations. It also states a hard exclusion (MYR only; foreign-currency is refused and routes to Banking → Payments), leaving nothing 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 declare the generic mutation profile (readOnly=false, destructive=false, idempotent=false). The description adds substantial context beyond that: nothing is created until a human approves in Taokeh, it cannot enable issueMode auto or MFRS 15 recognition, the next issue date is derived, and unlisted line keys are refused by name.

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 most important fact (draft-only, human-approved) is front-loaded and capitalized, and each section earns its place for a complex mutation tool. It is nonetheless dense and long, with some redundancy between the opening sentence and the WHAT IT CANNOT DO block, which keeps 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 an 11-parameter, non-idempotent mutation with no output schema, the description covers the approval workflow, hard prohibitions, line-product constraints, date anchoring, and payment semantics. An agent has everything needed to call it correctly without opening the 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?

Schema coverage is 91% so the schema already documents most parameters. The description still adds real meaning: startDate's day-of-month becomes the billing anchor (with 31st shortening to 28/29/30), past dates do not backfill, and CASH vs CREDIT book differently. It doesn't add much for the remaining params like needsReview or notes, keeping it below a 5.

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

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

States a specific verb and resource ('Propose a NEW recurring invoice — a billing schedule that issues the same invoice to the same customer every month, quarter or year') and front-loads the crucial draft-only nature in caps. It distinguishes itself from create_invoice_draft by routing per-foot/per-piece lines there, and from update_recurring_invoice_draft by scoping to new schedules.

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 when-to-use examples (retainer, subscription, maintenance contract, rent) and an explicit when-not-and-use-alternative rule for lines carrying a per-foot note. It also tells the agent to ask rather than guess on paymentMethod and contracted price/start date.

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 carry readOnlyHint=false and openWorldHint=true, so the description must do the heavy lifting, and it does: it discloses that cards/cardsOwing are liabilities never to be netted against cash, that ownerFunding is never money the business owes the owner, that unmatchedPayments is already netted inside receivables.total, and that fenced rows cannot be entered until the accounting start date moves. What is missing is the tool's own operational profile (side effects, permissions, whether the brief is computed live), so 4 not 5. Note: readOnlyHint=false is merely the absence of a read-only assertion and is not directly contradicted by the description's 'single read' framing.

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 ('Your morning brief in one call:') and nearly every clause carries real information, but everything after the colon is a single sentence with parentheses nested two and three levels deep, which makes the caveats hard to parse. Sized large but mostly justified given there is no output schema to hold the field semantics.

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 no-param, no-output-schema aggregation tool, the description supplies the semantic contract for the hard parts: cash composition and its liability exclusions, receivables netting, the decision-vs-row counting rule for approvals, and the rows/flagged/fenced meaning of staged sets. It does not document the top-level envelope (the actual keys for sales, expenses, tax position, low stock), which leaves a small 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?

Zero parameters, so per the rubric the baseline is 4; there is no parameter syntax for the description to add or omit. Schema coverage is effectively 100% of an empty object.

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?

Opens with a specific verb+resource+scope ('Your morning brief in one call') and enumerates exactly what it covers: today's/this-month's sales & expenses, cash, receivables, approvals, tax, low stock. It explicitly names the siblings it duplicates (business_snapshot, cash_position, ar_aging, tax_position, low_stock) and differentiates itself as the aggregate read, so an agent can pick it over those five 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?

Clearly signals when to use it ('brief me' is a single read) and points at the alternative set it subsumes ('Assembles the same figures as the individual tools ... plus your pending-approval queue'), implying you should call it instead of five separate reads. It stops short of an explicit when-not (e.g. when you need line-level detail from one of those tools), so 4 rather than 5.

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 mark this as a non-read-only, non-destructive write; the description goes well beyond them by disclosing that proposals never post or confirm, are surfaced as an 'AI suggestion' badge, are batch-acceptable only for category/contact, and never move money. It also enumerates per-row rejection reasons, possibleTwin/cardLinePosted warnings, pre-selection behavior, and refusal of stale allocations.

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 first sentence is well front-loaded, but the remainder is one enormous unstructured paragraph mixing every edge case, with heavy repetition and no formatting to aid scanning. Nearly all content is substantive given zero schema coverage, so it is dense rather than padded, but the structure makes it hard for an agent to extract the operative rules.

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-complexity, single-parameter batch tool with no output schema and no schema descriptions, the definition supplies the category/account/contact/allocation rules and the per-row outcome semantics an agent needs. Nothing material appears 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 0%, so the description carries the full parameter burden and does so: category constraints, contactName applicability per category and exact-match requirement, accountCode restrictions per category, allocations shape ({docNumber, amount}, RINGGIT, ≤20, must sum to the line within 0.10), and note length/audience are all spelled out.

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

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

The opening sentence states a precise verb (propose), resource (category/contact for bank review rows), and scope (up to 50 rows, imported and hand-typed UNCATEGORIZED lines). It is immediately distinguishable from siblings like create_bank_clearing_draft and bank_review_queue, which it explicitly names as sources/alternatives.

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

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

Gives explicit when-to-use and when-not: only SUGGESTED/UNCATEGORIZED rows accept proposals, CONFIRMED/POSTED/IGNORED and paired statement lines are rejected, and it routes specific cases to alternatives (create_bank_clearing_draft for bookEntry twins, LOAN_PAYMENT vs OTHER for owner withdrawals). It is unusually thorough about alternatives and 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description reinforces and extends this: 'READ-ONLY — it creates nothing, hires nobody and files nothing.' It adds context the annotations cannot carry — default assumptions (RESIDENT, single, no children, no TP1 reliefs), the regulatory basis of the PCB calculation, and an explicit instruction to restate assumptions and never present as a quote.

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 and usage are front-loaded in the first sentence, and most sentences do carry parameter or behavioral meaning that the empty schema otherwise loses. However it is an unusually long single block, and some content (statutory part citations, the 13 August 2026 letter reference) adds bulk without helping an agent decide or call correctly.

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

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

With no output schema and 6 params at 0% coverage, the description carries the burden and largely does — it enumerates the returned components (wage, employer EPF/SOCSO/EIS/HRD levy; net after employee EPF/SOCSO/EIS/SKBBK/PCB) and all defaults. It stops short of describing the reply's structure or the assumption block's shape, which an agent presenting results would benefit from.

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 0%, so the description must carry the full burden and does: it explains each optional field's effect (residency flat 30% for NON_RESIDENT; citizenship driving EPF Part F rates against the RM1,700 floor and SKBBK; permanentResident applying citizen EPF rates plus EIS; ageBand reducing EPF and moving to SOCSO Category 2; epfEmployeeRate election rules). It even clarifies interactions between fields, e.g. citizenship does not change tax residency so residency must also be set.

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: 'Cost a HYPOTHETICAL hire' and spells out exactly what it returns (employer cost = wage + EPF/SOCSO/EIS/HRD levy; take-home after employee contributions and PCB). The word 'HYPOTHETICAL' cleanly separates it from any payroll-actuals sibling, so an agent can place it 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 concrete when-to-use examples ('if I hire someone at RM4,000, what does it really cost me?') and states the posture clearly: present as an estimate on stated assumptions, never a quote or tax advice, and repeat assumptions to the user. It also states access restrictions (ADMIN AND BOOKKEEPER + PAYROLL ONLY), but never names or compares to an alternative tool such as payroll_summary for actuals.

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), so the description only needs added context, and it delivers a lot: what the curated list excludes and why, the category-code validation rule, the separate paid-from rule, the refusal semantics for ownerPocketCode=null, and the ringgit-only constraint. This goes well beyond what the annotations state.

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, but the body is a dense ~230-word essay with heavy parenthetical nesting and repeated restatements of the exclusion rules (control/contra accounts, engine accounts, A/R and A/P controls appear more than once). For a zero-parameter read tool some of this detail could be trimmed or tabulated.

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

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

With no output schema, the description carries the burden of explaining what comes back, and it names the relevant returned fields and the rules governing each. It stops short of describing the actual return shape or ordering, but an agent has enough 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?

The tool takes zero input parameters, so the baseline is 4. The description references output-side field names (expenseCategories, paidFromAccounts, ownerPocketCode, ownerPaidRefusal), which compensates somewhat for the missing output schema, though it does not define their types or structure.

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

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

The opening clause identifies the resource ('The expense accounts you can post to in this company') and the use context ('for shaping a paid-expense draft'), so an agent can infer it returns account-code lists. However, there is no explicit verb like 'list'/'get', and nothing distinguishes it from adjacent lookups such as resolve_vendor, resolve_product, or stage_master_data, so selection 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?

The description ties the tool to shaping a paid-expense draft and gives domain conditions (owner-paid vs. company-paid, which paid-from code applies), which implies when the data is needed. But it never states when to call this tool versus the create_expense_draft/update_expense_draft siblings, nor any exclusions or prerequisites for the call itself.

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

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

Annotations already indicate readOnlyHint=true, and the description adds useful scope information: only paid expenses are counted, and the time window is today and month-to-date. However, it does not describe the return format, whether the result is a single total or separate numbers, or behavior when there are no expenses.

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

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

The description is a single sentence, front-loaded with the core question 'How much you have spent', and contains no filler or redundant wording. Every word contributes to meaning.

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 summary tool, the description provides sufficient detail to understand the tool's purpose and invoke it correctly. The lack of an output schema means the description could ideally clarify the return shape (e.g., two totals vs. one), but this is a minor gap for such a simple 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?

The tool has zero parameters and schema description coverage is 100%, so there is no parameter burden for the description to carry. The baseline of 4 applies because the schema fully covers an empty parameter set.

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

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

The description clearly identifies the tool as a summary of paid expenses, with a specific scope (today and this month so far). It uses a clear 'have spent' action on the 'expenses' resource and is distinguishable from siblings like create_expense_draft or search_expenses, though it does not explicitly name alternatives.

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

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

The description implies usage for checking how much has been spent today and this month so far, but it does not state when to use this tool versus alternatives, nor does it provide any exclusion criteria. The context is clear enough but not explicit.

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

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

The description is exceptionally transparent: it explains partial months with `partial: true` and `through`, absent months and the cutover rule, the equal-basis engine behind the figures, the netCashMovement vs cashClose discrepancy, the time-budget refusal behavior, and the fact that it returns figures only with no interpretation. The readOnlyHint annotation is consistent with this being a read-only computation 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?

The description is long, but the length is justified by the tool's many edge cases. It is well-organized into labeled sections (THREE THINGS YOU MUST READ, EQUAL BASIS, TIME BUDGET, FIGURES ONLY), which helps an agent parse the critical caveats. A few phrases could be tightened, but nothing is 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?

Despite having no output schema, the description names every field returned, explains how each is computed, clarifies partial/absent/cutover behavior, states currency, and documents failure modes. An agent has everything needed to interpret the response correctly and avoid common misinterpretations.

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 33%, so the description carries the burden for `from`/`to` and it does: YYYY-MM format, inclusive, 36-month cap, and MYR currency. For `metrics`, it adds that leaving a metric out omits those fields entirely and never zeroes them, going beyond the schema's basic enum description.

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 clear, specific statement: a month-by-month series of company figures across a user-named window. It also differentiates itself from income_statement by explicitly saying to request this once instead of stitching 36 months together, making the tool's role unambiguous.

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

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

The description gives direct when-to-use guidance: use this for analyzing a year or three years of trading, and never call income_statement 36 times. It also advises asking for narrower windows or fewer metrics when the time budget is exceeded, covering the main alternative and constraint behavior.

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

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

Beyond the readOnlyHint=true annotation, the description discloses the tool's failure mode (it will rank some page even for record-like input and return a wrong answer), its output shape (deep-link URLs, one-line page description, configHint, addOn flag), and guarantees that no setting is ever toggled. This is exactly the contextual behavior an agent needs to trust 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?

The description is front-loaded with the core distinction and each sentence carries substantive guidance, but it is long and repeats the 'not a record' warning more than once. The density and warning are justified by the tool's deceptive failure mode, though it could be tightened slightly without loss.

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

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

With no output schema present, the description fully compensates by enumerating the return elements (page URLs, descriptions, configHint, addOn flag), covers edge behavior (nothing matches), and provides alternative routing. Nothing an agent needs to use 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?

The schema already documents the query parameter at 100% coverage, giving the baseline 3. The description adds value by clarifying it must be a natural-language CAPABILITY query, providing concrete examples, and reinforcing what it must NOT be (document/customer/amount), so the parameter semantics are further strengthened.

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 precise verb phrase ('A FEATURE FINDER, NOT A RECORD SEARCH') and names its exact scope: Taokeh's screens, features, and settings. It explicitly distinguishes itself from record-search siblings by stating what it is not, so an agent can immediately tell find_in_taokeh apart from search_documents, search_expenses, etc.

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 ('tell the user WHERE in Taokeh to do something or change a setting') and equally explicit when-not-to-use with a detailed list of alternative tools for records, including what each alternative covers. It even instructs the fallback behavior when nothing matches.

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?

It discloses that the returned link is short-lived (about 15 minutes) and that anyone holding it can access the document, adding a security caution beyond the readOnlyHint annotation. It also identifies the return items (signed URL and filename). No contradiction with the read-only annotation.

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 verbose and ends with a nonsensical repeated phrase 'the filename, the filename, ...' which wastes tokens and confuses the return-value statement. While the main content is ordered logically, the malformed tail and excessive examples hurt conciseness.

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

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

The description covers purpose, prerequisites, parameter sourcing, and a security caveat, which is fairly complete for a read-only retrieval tool. However, the corrupted tail leaves the exact return payload unclear (only 'the filename' is restated), and error behavior (e.g., no original on file) is not addressed.

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

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

The schema already describes all three parameters at 100% coverage, and the description adds cross-tool guidance on where to find the correct ids (expenseId from search_expenses, draftId from drafts, attachmentId from attachments list). This enriches the schema beyond generic field descriptions.

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

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

The opening sentence explicitly states the tool's action: 'Get a short-lived link to the ORIGINAL DOCUMENT filed against something in the books.' It also distinguishes between posted expenses and pending drafts, making the target resource unambiguous. Even with the malformed tail, the central purpose is clear.

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

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

The description tells the agent when to invoke it ('to CHECK a document is on file, or to re-read one you filed earlier') and how to prepare inputs using search_expenses and create_*_draft results. It lacks an explicit 'when not to use' clause or named alternatives, but the usage context 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 only declare readOnlyHint and openWorldHint; the description adds substantial behavior the agent could not otherwise know: the URL is signed, short-lived (~15 min), and shareable by anyone holding it. It discloses that voided documents still produce stamped PDFs (diagonal VOID, 'Status VOID' header, 'Total credited/charged' labels, an explicit sentence in the PDF), that voided invoices have no link at all, and that printed language follows a company setting. This far exceeds the annotation bar.

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 and no section is entirely off-topic, but the mass is disproportionate: the voided-document behavior is restated across several long clauses, there is a dangling dated parenthetical ('2026-09-14') and a doubled em-dash typo. The same facts could be conveyed in roughly a third of the words.

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

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

No output schema exists, and the description compensates by naming the return payload (signed URL, document number, expiry) and covers the real edge cases: ambiguous numbers, voided invoices being unfindable, voided credit notes still resolving, and the language setting. Nothing needed to call this 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 100%, so the baseline is 3. The description matches and slightly extends the schema: docId comes 'from search_documents', docNumber is the printed number, and it adds the ambiguity behavior — 'if a number matches several documents I'll list them so you can pick the id' — which the schema does not state. DocType is implicit in the description's enumeration of invoice/quote/credit note.

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?

Opens with a specific verb+resource+scope: 'Get a shareable link to the ACTUAL PDF of one invoice, quote or credit note.' It distinguishes itself from search_documents (the identifier source) and states exactly what it does not do ('This does not email anyone — it hands YOU a link'). An agent can pick it apart from siblings immediately.

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 clear context for use — hand the real document to a user or their customer — and two explicit identification paths (docId from search_documents or docNumber). It also routes the agent to search_documents to read a document's VOID status before describing it. It does not contrast against other link/attachment siblings (get_attachment, request_attachment_upload), so it stops short of full alternatives coverage.

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 are only coarse defaults (readOnlyHint=false, destructiveHint=false, openWorldHint=false, idempotentHint=false), so the description carries the real behavioral burden and does: nothing posts, the server validates opening+rows against closing and rejects with the exact delta, foreign-currency accounts are refused for posting/matching, the card directional check runs separately because negating every figure still ties out, the card 'payment received' line is auto-excluded, and confirmOverlap/confirmSignConvention are guards not to be used to force a pass. The only nuance is the claim that an identical reading stages nothing twice, which reads as content-level dedup rather than the blanket idempotentHint flag — a soft tension, not a contradiction.

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 well (purpose and 'nothing posts' come first) and every paragraph is on-topic, but it is a very long single block with heavy parentheticals and no structural breaks. Substantial content duplicates the schema almost verbatim, notably the signConvention PRINTED_CARD/STORED explanation and the confirmOverlap/attachmentToken guidance, which the rubric says earns no credit.

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 15-parameter, non-read-only import with no output schema, the description covers the full lifecycle: intake_contract prerequisite, required reading of the statement, the arithmetic tie-out, credit-card convention traps, foreign-currency refusal, the archiving workflow, overlap handling, and re-call adoption. 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 coverage is 73% and the per-parameter descriptions are already rich (signConvention, confirmOverlap, statementDate, beginningBalanceDate, and the whole attachment family are documented in the schema), so the baseline is high. The description does add meaning the schema lacks: rows are 'signed amount: + money in, − money out', the balances are the printed opening/closing figures, and the validity constraint that opening + rows must tie to closing. Those additions are real but incremental relative to the schema's own text.

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

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

The description names a specific verb and resource (import a bank statement) and states the destination and the key consequence up front: 'This does NOT post to the books — every row lands in Banking → Review.' It also distinguishes itself from siblings by explicitly excluding them: 'Single receipts, invoices or bills go through their own draft doors, not here.' An agent can tell this apart from create_expense_draft, stage_document, or draft_bank_classification without opening another 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 spelled out with prerequisites and named alternatives: call intake_contract(doc_type:'statement') first, call request_attachment_upload first when archiving, and use signConvention='PRINTED_CARD' vs 'STORED' depending on how the figures were read. It gives explicit when-not cases (single receipts/invoices/bills go elsewhere; foreign-currency accounts must be flagged rather than told to post) and describes the re-call/adoption path for already-filed statements.

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 declare readOnlyHint=true and openWorldHint=false, the description adds rich behavioral context beyond safety: it details server-side delta computation in integer cents, the null handling of deltaPct when the earlier figure is zero, sign behavior when moving out of a loss, the presence of `windows` and `notes` fields, and periodic-stock edge-case warnings. These go well beyond what annotations provide.

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

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

The description front-loads the core purpose then moves to comparison guidance and edge cases. It is dense and information-rich, with every sentence serving a purpose, but the long periodic-stock paragraph and nested warnings make it slightly sprawling for an at-a-glance read.

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 no output schema, the description fully compensates by explaining the structure of returned fields (`deltaCents`, `deltaPct`, `windows`, `notes`) and how to interpret them. It also covers edge cases like zero-base percentages and periodic stock, making it complete for correct invocation and reporting.

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 60%, so the description compensates by explaining the semantics of `compare` (with definitions of 'previous_period' and 'same_period_last_year') and how `compareFrom`/`compareEnd` form an explicit earlier window. It adds meaningful interpretation of comparison parameters, though `from`/`to` are not described beyond the schema patterns.

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+resource: 'Your profit and loss for a period' and then enumerates the exact line items returned (revenue, COGS, gross profit, expenses, net income). This clearly distinguishes it from siblings like balance_sheet or cash_forecast, which cover different financial statements.

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 explicit when-to-use guidance for comparisons — 'to answer "how does this month compare with last?" ask for it here — NEVER call this tool twice and subtract the figures yourself.' It also prescribes how to set comparison parameters and warns to read `notes` before quoting a variance.

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 the description reinforces this with 'Nothing posts on its own.' It adds extra behavioral context: admin-only for employees, owner-only settings the AI may never write, and the review flow. These go beyond the annotations, though not exhaustively.

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 long but front-loaded with the core purpose. It is dense with essential information and avoids filler. While a more structured format (e.g., bullets) could improve readability, every sentence earns its place given the tool's role as a contract reference.

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 tool that defines contracts across many document types, the description covers all necessary context: purpose, doc_type variants, staging relationships, precedence, and permission constraints. There is no output schema, but the tool's output (the contract) is sufficiently implied.

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

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

The schema provides only a bare string for doc_type with no enum, and schema coverage is 0%. The description fully compensates by listing every valid doc_type value and explaining its meaning and usage, making the parameter self-documenting.

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 explicitly states the tool's purpose: defining the shape a Taokeh document needs for various transaction types, and enumerates all doc_type values. It clearly distinguishes itself from siblings by positioning itself as a reference contract rather than a creation or staging tool.

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

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

The description gives explicit usage guidance: it explains when to use this tool (to understand the document shape) and when to use alternatives like stage_document, stage_opening_balances, and stage_master_data for specific doc types. It also prioritizes 'accounts' first and notes admin-only restrictions, leaving no ambiguity.

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, yet the description adds substantial context beyond them: results are capped with a true count, services ('Service — no stock') are excluded, the rule matches the dashboard chip, and Counter-use companies see day-close figures with a clear explanation of the open-trading-day skew. This is exactly the behavioral detail that prevents misreading the numbers.

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 purpose, then the row shape, capping, exclusions, the rule, and the Counter caveat. Nearly every sentence earns its place, though the density is high and the Counter sentence is long enough to be a slight drag on scanability.

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

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

With no output schema and no parameters, the description carries the full burden and discharges it: it enumerates the returned columns (sku, name, on-hand, reorder point, unit), discloses capping plus true count, and explains the accounting-timing caveat. An agent has everything needed to call and interpret 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?

Zero input parameters, so the baseline is 4; there is nothing to document and the description does not need to compensate. It correctly spends its words on output shape instead.

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+resource outcome: the products at or below their reorder point, framed as 'the what do I need to reorder list'. It gives the exact inclusion rule, which is enough to distinguish it from stock_level and stock_movements 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?

The framing ('what do I need to reorder') makes the use case explicit and the disclosed rule (reorder point set AND on-hand ≤ reorder point) tells the agent exactly which products qualify. It does not explicitly name a sibling alternative or a when-not condition, so it stops short of a 5.

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

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

The description emphatically declares 'READ-ONLY. It changes nothing', yet the annotations set readOnlyHint=false, which asserts the tool is not read-only. This is a direct contradiction on the safety-relevant dimension an agent weighs most before calling. Other useful disclosures (truncation reporting, null reason semantics) cannot offset a conflicting safety claim.

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

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

The four numbered buckets give it real structure and the purpose is front-loaded, but it is a single ~250-word paragraph with rhetorical asides ('that one is now invoice INV-0042', 'READ IT and fix precisely'). Several lines serve post-call behavior rather than invocation, making it heavier than needed.

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

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

With no output schema and no schema descriptions, the description carries the return-shape burden well: it names per-item fields (reference, party, amount, days waited, next step, review link, shownOnReviewAs, reason/reasonRecorded) and the STAGED/APPROVED semantics. Coverage is strong, though the kind enum and the limit maximum discrepancy leave small 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?

With 0% schema description coverage, the description must compensate and largely does: it gives `since` as YYYY-MM-DD or ISO with a 7-day default, `kind` as a single-lane filter, and `limit` default 50 with honest truncation reporting. It omits that `limit`'s stated max of 200 conflicts with the schema's far larger maximum, and it never lists the `kind` enum values, so it is not fully self-sufficient.

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 the specific resource ('YOUR OWN QUEUE in this company') and enumerates exactly what it returns across four buckets (PENDING, APPROVED, REJECTED, STAGED), which distinguishes it from siblings like search_documents, open_invoices, or bank_review_queue. An agent can tell what this tool uniquely provides 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?

Usage is clearly framed as a personal queue read that answers four concrete questions, and it explicitly rules out approval/money-movement actions ('no tool can approve... every pending item is one human tap'). It does not, however, name a sibling alternative or state when a different tool would be preferable.

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 openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: results are ordered oldest-first, invoices fully covered by credit notes are excluded from the list, and outstandingBalance is a net customer figure that can be lower than the listed invoices sum. It does not mention pagination, result limits, or match semantics.

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 and ordering are front-loaded in the first clause, and each subsequent sentence explains a distinct figure (outstanding, grossOutstanding, outstandingBalance). It is nonetheless a dense block of prose for a one-parameter read tool, and the payment-allocation aside in the middle is longer than needed to support correct invocation.

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

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

With no output schema, the description carries the burden of explaining the returned figures and does so thoroughly, including the relationship between outstanding, grossOutstanding, and outstandingBalance, and the balanceNote caveat. Remaining gaps are match semantics and pagination/result limits.

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

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

The single required parameter is undocumented in the schema (0% coverage). The description clarifies that it is a customer name to search by rather than an ID, which is genuinely useful, but it does not say whether matching is exact, partial, or fuzzy, nor what happens on ambiguity (resolve_customer exists as a sibling, suggesting ambiguity is possible).

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+resource+scope: 'The unpaid (or part-paid) invoices for one customer, oldest first', which an agent can distinguish from balance-level siblings like ar_aging or ap_aging. It stops short of naming an alternative tool or stating what this is NOT, so sibling differentiation is implied rather than explicit.

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?

'search by customer name' implies the intended invocation, and 'for one customer' implies the scope versus a portfolio-level aging report. However, there is no explicit when-to-use versus when-not guidance and no alternative named (e.g. ar_aging for all customers), so usage is only implied.

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

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

Annotations declare readOnlyHint=true and openWorldHint=false, and the description goes well beyond them: it defines what 'teaches' the tally (a confirmed-but-unposted row or an undone post teaches nothing), explains that OVERRIDE beats the tally, that timesSeen is 0 for rules, and that ruleSetOn is the date set. This is exactly the kind of semantic disclosure annotations cannot carry.

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 almost every sentence carries needed semantics (basis meanings, override precedence). It is dense and runs long for a one-parameter tool, with heavy emphasis capitalization (CONFIRMED, POSTED, LEARNED, OVERRIDE, BEATS) that borders on noise, keeping it off 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?

There is no output schema, so the description carries the return-value burden itself, and it does: it enumerates the returned fields (count, date range, total amount, grouping keys) and the suggestion's basis/timesSeen/ruleSetOn. An agent has enough to call it and to interpret the result correctly.

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

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

Schema description coverage is 0% for the single counterparty parameter, so the description must compensate. It does so partially by clarifying the value is 'named as printed on the statement line', which tells the agent to pass the raw statement text, but it gives no detail on matching, casing, or unmatched names. Adequate but leaves a real gap.

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: it returns the historical, human-confirmed bank rows for a named bank counterparty, grouped by category/contact/GL account, plus the live suggestion. This is clearly distinguishable from sibling resolvers (resolve_vendor, resolve_customer) and from draft_bank_classification, which draft rather than report precedent.

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

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

It gives a clear context for use ('the tenant-scoped PRECEDENT behind a suggestion, so you can explain WHY a row is being categorized a certain way') and a usage directive ('Never report an override as history'). It stops short of naming alternatives or stating when NOT to call it, so it does not reach a 5.

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 readOnlyHint already covering safety, the description adds substantial behavior: role gating (ADMIN AND BOOKKEEPER + PAYROLL ONLY, refuses otherwise), the read-only boundary (cannot create a run or file with LHDN/KWSP/PERKESO), DRAFT `needsRecompute` semantics, and the crucial fact that figures are stored payslip sums, never recalculations. This is far beyond what annotations provide.

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

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

Front-loaded with the core output and use cases, then layered with draft and role caveats in a logical order. It is long and occasionally dense, with some overlap between the `staff` sentence and its schema description, but nearly every sentence carries essential context.

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

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

No output schema exists, so the description fully describes return contents (gross components, deductions, employer contributions, net, true cost, leave list, roster). Combined with draft semantics and role gating, an agent has everything needed 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?

Schema coverage is only 33% (only `staff` documented), so the description carries the rest: `month` format is given as YYYY-MM, `perEmployee` behavior and its sensitivity are explained, and `staff` is contextualized as the id source. It adds real meaning for the two schema-undocumented parameters.

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 ('a month's payroll from gross to net, as it was actually run') and enumerates the exact figures returned, so an agent knows precisely what it produces. It differentiates from siblings like employer_cost_estimate by emphasizing stored payslip sums rather than estimates. No ambiguity about what the tool is.

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 says what happens with no `month` (latest FINALIZED or POSTED run) versus a given `month` (YYYY-MM), names when to set `staff` and `perEmployee`, and cautions about when not to request per-person data. It also routes to `update_employee_draft` for the employeeId source. Clear when/when-not guidance.

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

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

Annotations only cover read-only/open-world, so the description carries the behavioral load and does so richly: exact comparison windows, the drivers bridge structure, oneOffs handling of disposal/FX so a lumpy asset sale isn't read as a trend, integer-cents units, `direction` semantics relative to profit, and the periodic-stock COGS caveat that warns against misreading a missing COGS as margin gain.

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

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

It is a long single paragraph but front-loads the core diagnostic purpose and then layers needed detail. Given there is no output schema, enumerating the return shape earns its place, though the prose is dense enough to be slightly heavy for a one-parameter tool.

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

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

With no output schema, the description fully enumerates the return shape (both net-profit windows, delta, drivers bridge, oneOffs, priorMonthFull, assumptions, notes), and covers edge cases and units, leaving nothing an agent needs in order to call and interpret 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% and there is only one optional param, so the schema already documents `month`'s format. The description adds genuine semantic value beyond it by clarifying that a completed past month compares its whole length while the default is current month-to-date against the same day-span.

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 ('diagnostic breakdown of WHY net profit moved') and explicitly frames it as deterministic decomposition rather than a generative model, which distinguishes it from siblings like income_statement or financial_timeseries that report rather than explain movement.

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 clear conditional guidance on the one parameter (omit `month` for current month-to-date; supply it to analyse a completed past month), and explains the comparison baseline. It does not, however, explicitly name an alternative sibling tool or say when to prefer this over income_statement, so it falls short of full 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?

Beyond the sparse annotations, the description discloses many behavioral traits: the link is single-use, expires quickly, is company-scoped, accepts only raw bytes, and requires the token in place of base64. It also explains the duplicateAttachment adoption behavior and media-type handling, giving strong transparency for a non-idempotent, write-oriented 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?

The description is long and dense, but nearly every sentence carries operational value: upfront purpose, workflow ordering, repair scenario, lifecycle constraints. It is front-loaded well, though the repair paragraph could be tighter without losing critical guidance.

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

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

Despite having no output schema, the description names the return values (uploadUrl, attachmentToken), explains how to use them, covers alternatives, and even handles the edge case of repairing a previously filed draft. This is complete enough for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description itself adds no parameter-specific meaning beyond what the schema already documents; it focuses on the returned uploadUrl and attachmentToken rather than filename/mediaType 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?

Description opens with a specific, actionable goal: obtain a one-time link to upload a large file instead of inlining base64. It clearly distinguishes this tool from siblings by naming the create/import tools that consume the attachmentToken and contrasting it with attachmentBase64.

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

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

The description explicitly states when to use this tool ('anything bigger than a few KB'), when not to ('keep attachmentBase64 for tiny files only'), and the ordering requirement ('CALL THIS FIRST, BEFORE the create/import call'). It even gives a repair path for cases where the agent already filed bare.

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 readOnlyHint and openWorldHint=false, but the description goes well beyond that: it enumerates the three possible statuses, defines outstandingBalance as NET (open invoices less unmatched payments, can be zero or negative when paid ahead), and warns against calling a negative balance a debt. That is precisely the extra context an agent needs before speaking a number to a 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?

Front-loaded with the core purpose and each subsequent clause carries distinct operational detail, but the dense nesting of parentheticals (the credit-check-in-chat aside, the balance arithmetic) makes it heavier than it needs to be. Nothing is wasted, though.

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

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

There is no output schema, so the description must describe returns — and it does, covering all three statuses and the fields returned for each (id, outstandingBalance, candidates, nearMiss). Nothing needed to call or interpret it 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 0% for the single param, so the description must carry the load. It conveys that the input is a customer name as written/abbreviated and that prefix and near-miss matching are attempted, which adds real meaning beyond the bare string type.

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 (Resolve) and resource (a customer name for an invoice draft) plus the scope (against this company's real customers). An agent can distinguish it from resolve_vendor/resolve_product by the resource alone 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?

Explicit routing guidance for each outcome: ask the user which candidate when ambiguous, treat nearMiss as likely shorthand, only file as new on user confirmation, and never guess. This is genuine when/when-not guidance, not 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 the safety profile (readOnlyHint, openWorldHint=false); the description adds the return payload (id, sku, name, unit, default sell price, isService), the meaning of isService for stock/costing, and the three outcome statuses. That is substantial behavior beyond what the annotations declare.

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 scope, matching rules, return fields, and status semantics. Every sentence is useful, though the isService parenthetical is slightly wordy.

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

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

With no output schema and minimal annotations, the description supplies the return fields, matching constraints, and status outcomes an agent needs to call and interpret this tool correctly.

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

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

Schema description coverage is 0% and the single 'query' param is undocumented in the schema, so the description carries the burden and does so by specifying acceptable inputs (name, SKU, exact barcode) and their matching strictness.

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 (resolve) plus resource (product) and the accepted identifiers, scoped to an invoice line. It is clearly distinguishable from resolve_customer and resolve_vendor among the 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?

Gives practical selection guidance: plain names/SKUs work best, a barcode must match exactly, and it warns to never guess among ambiguous candidates. It stops short of naming alternative tools or stating when not to use it.

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

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

Discloses important behaviors beyond the readOnlyHint annotation: return statuses (resolved, ambiguous, none), the nearMiss flag, and the rule to ask the user rather than guess among candidates. The phrase 'only file as new if they confirm' could sound like a write operation, but readOnlyHint is not contradicted because it is guidance for downstream action, not a claim that this tool mutates data.

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

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

The description is front-loaded with its purpose and uses four sentences, each carrying useful information. There is slight redundancy between 'ask the user which one' and 'Never guess among candidates — ask the user,' but it reinforces a critical safety rule without becoming bloated.

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?

Covers the main resolution paths: resolved, ambiguous, and nearMiss, along with explicit user-confirmation requirements. The main gap is the lack of explicit guidance for the status 'none' when no close vendors exist, although the nearMiss rule implies the general principle. Since there is no output schema, the status descriptions are essential and mostly sufficient.

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 0%, but the description compensates by explaining the single 'name' parameter is a supplier/vendor name from a bill draft that should be matched against the company's real vendors. This gives the parameter meaningful context that the bare schema does not provide.

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: 'Resolve a supplier / vendor name for a bill draft against this company's real vendors.' It clearly distinguishes from sibling tools like resolve_customer and resolve_product by being vendor-specific. The statuses it mentions further clarify its role as a resolution rather than a creation 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?

Provides clear context: use this when reading a vendor name from a bill draft and needing to match it to existing vendors. It gives strong behavioral guidance for ambiguous and nearMiss cases, including 'ask the user' and 'never guess.' It does not explicitly name alternatives or state 'do not use for customers/products,' but the vendor-specific wording makes that implicit.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, but the description goes well beyond them: it explains that the server re-validates the patch 'exactly as it did at filing' (same account/date/line/total rules), that unsent fields are preserved, that nothing is approved or posted, that the approval link still works and shows revised figures, and that a 'revised by your AI' line is appended to the reviewer's note. This is the behavioral context an agent needs and cannot get from annotations.

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

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

Front-loads the purpose, then the alternative, then the state constraint, then the approval semantics — a sensible ordering. It is long and leans on ALL-CAPS emphasis in several places, but nearly every sentence carries distinct operational information 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?

For a mutation tool with four parameters, a large patch object, and no output schema, the description covers the lifecycle an agent must reason about: re-validation, partial updates, pending-only eligibility, non-approval, and the human-facing note change. Nothing required 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 the schema already documents kind/draftId/patch, so the baseline is 3. The description adds genuine semantics on top: patch contains 'just the fields that were wrong', fields you do not send are left exactly as filed, and note is appended rather than overwriting — behavior not visible from the schema alone.

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+resource: 'Correct a draft you already filed, instead of filing it again', and immediately differentiates from the filing tools it sits beside. The header sentence alone lets an agent tell revise_draft apart from create_expense_draft or update_invoice_draft.

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 explicit when-to-use ('use this whenever you realise a filed draft is wrong'), the concrete failure mode of the alternatives ('re-calling create_expense_draft ... is refused as a duplicate', 'a second create files a CONFUSING SECOND DRAFT'), and a when-not with the required fallback ('ONLY a PENDING draft can be revised ... file a fresh draft in that case'). No inference is left to the agent.

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 only readOnlyHint and openWorldHint, and the description adds substantial behavioral context beyond them: currency is MYR with foreign invoices converted at the invoice-frozen rate, credit notes are excluded so returns are not netted, and the two tax bases are disclosed with exactly which payload fields are tax-inclusive vs. ex-tax. This is precisely the kind of trap-avoiding detail an agent needs and cannot get from the 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?

Front-loaded with the core meaning, then layered detail in decreasing priority. Every sentence carries real information (currency basis, credit-note exclusion, tax bases), though the closing imperative about quoting one basis is advisory framing rather than tool semantics and could be trimmed without loss.

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

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

There is no output schema, so the description must describe the return shape — and it does, naming byMonth, byCustomer, byProduct and the total/exTax fields and their differing tax bases. Combined with the mode explanation and exclusion rules, an agent has everything needed to invoke and interpret the result correctly.

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

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

Schema description coverage is 0% for `from` and `to`, so the description carries the semantic burden — and it does explain that omitting them yields today/month-to-date while supplying a range yields that period's invoiced sales. It does not restate the YYYY-MM-DD pattern, but that is already in the schema, so the gap is minor.

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?

Opens with a specific verb+resource ('How much you have sold') and immediately defines the two operating modes — no dates yields today plus month-to-date, a date range yields invoiced sales for that period. It further specifies the breakdown dimensions (month, customer, product), so an agent knows exactly what this returns and how it differs from sibling summaries like expenses_summary or income_statement.

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

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

The description clearly states the two usage contexts (no dates vs. with a date range), which effectively tells the agent when each behavior fires. What it does not do is name an alternative sibling (e.g. income_statement or financial_timeseries) or state when NOT to use this tool, so it stops short of the explicit routing found in the best definitions.

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 readOnlyHint/openWorldHint; the description adds a large amount of behavioral disclosure beyond them: 'Nothing is written, and no draft is created,' currency of each money column vs. converted siblings, fxRate semantics, margin formula, isMeasureDrift meaning and reliability windows, unit vs unitStamped fallback, and newest-first ordering with a 200-row cap and more/total/shown.

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 correctly — the one-line purpose and the sibling contrast come first — but the body is extremely long and repetitive: isMeasureDrift is defined, then re-explained with per-table date windows, margin rules are re-derived at length, and there is a forward reference ('see MARGIN below'). Most content is useful, but it is not economical.

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 23-param, no-output-schema tool, the description covers the return shape (explicit row field list), ordering, pagination and next-step guidance, plus edge cases (measure-drift rows, unit-stamp backfill windows, quote/DO/PO not being sales/purchases). Nothing an agent needs to call or interpret this correctly appears 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%, so baseline is 3, but the description adds real semantics the schema lacks: it spells out each docType value's business meaning (including the sell-side vs buy-side debit note distinction), the productText match against both product name and line description, and that number also matches the customer's own Ref No on invoices.

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 ('Read the LINE ITEMS of documents IN BULK') with an explicit scope contrast against the sibling: 'search_documents answers WHICH documents; this answers WHAT WAS ON THEM.' An agent can distinguish this from search_documents, search_expenses and search_journal 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?

Gives explicit when-to-use conditions (any question needing detail behind totals), names alternatives and their domains (header-only: search_documents; paid expenses: search_expenses; ledger: search_journal), and even prescribes a required precondition — read lines here before calling update_quote_draft / update_delivery_order_draft / update_purchase_order_draft / update_bill_draft because they take full replacement line sets.

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