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=true and openWorldHint=false, and 'READ-ONLY' merely restates that. However, the description adds substantive behavioral context the annotations cannot: the meaning of each status bucket, that NOT_EXPLAINED is an 'honest remainder', that STATEMENTS_DONT_JOIN signals a missing/duplicated statement, and crucially the CREDIT CARD liability sign convention (negative = money owed). That domain semantics is genuinely valuable beyond 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?

The description is an extremely dense single block, essentially one sprawling sentence with only a final 'READ-ONLY.' tacked on. The core purpose is front-loaded in the opening clause, but the intervening enumeration of every status, bucket, and edge case is hard to scan and much of it could be structured or trimmed. Length is not justified by what it helps an agent decide.

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 of describing the return shape, and it does so thoroughly: balances and differences per account, rowCounts by status, backlog with pairedInBooks, reconcilingItems with signed effects, notOnStatementNotInBooks, and per-statement tie-out. An agent can anticipate the response structure. What it lacks is any pointer on when this tool is the right choice relative to sibling reconciliation tools.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There is no parameter syntax for the description to document and it adds nothing spurious.

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

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

The description clearly identifies the resource (per-bank-account reconciliation status) and enumerates what the status comprises: GL vs statement balance, rowCounts by status, backlog, reconcilingItems, and per-statement tie-out. It is specific about the returned content, but it never distinguishes itself from the sibling bank_reconciliation_report or bank_review_queue, both of which sound like overlapping reconciliation views.

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 statement of when to call this versus bank_reconciliation_report, bank_review_queue, or the in-app page it references. The only guidance is the implicit framing 'Where each bank account stands on reconciliation', which conveys context but no selection criteria or 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 only declare readOnlyHint/openWorldHint, so the description carries the real behavioral load and does so richly: the 1000-row ceiling on unreviewed windows (with the refusal behavior), the 200-row cap with truncation, lowest-confidence sort, per-bucket counts, the standing-rule override, and the hard limit that it can never confirm or post. It also documents how decided rows come back with NULL suggestions versus decided fields — 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?

The critical scoping constraint and default behavior are front-loaded, which is good. However the body is extremely long and packs many edge cases (three possibleTwin kinds, duplicate semantics, rule explanations, /go command bar history) into one block, which is more than an agent needs to invoke the tool and risks burying the actionable instructions.

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

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

For a read-only, no-output-schema tool of high domain complexity, the description is complete: it explains returned fields, suggestion provenance, duplicate/twin signals, and the boundary of what can and cannot be done. Nothing an agent needs to interpret the payload or act on a row 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 75%, but the description adds meaning the schema alone doesn't: the interactive effect of `from`/`to` *without* a `statementId` widening scope across all statements (payload `scope:'window'`), the ceiling that only applies to unreviewed windows, and the exact `status` vocabulary interpretation. This goes beyond restating 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 states a specific resource ('the IMPORTED BANK REGISTER — the rows that came in on a bank or card statement') and its default scope ('defaulting to the ones still awaiting review'). It explicitly distinguishes itself from the sibling that covers hand-recorded settlements (search_documents with docType:'payment'), so an agent can route without opening either schema.

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

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

It gives explicit when/when-not rules: omit `status` for the unreviewed queue, pass `status` for settled history, pass `from`/`to` without `statementId` for a date window across statements. It also names the alternative tool for the excluded case (hand-recorded settlements via search_documents), 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 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 minimal annotations. It discloses that overdue receivables are not assumed collected, channel unsettled balances are deliberately excluded from the dip, missing channel data leaves the field absent, and all amounts are integer cents. These behavioral caveats are exactly what an agent needs to interpret results correctly.

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 each sentence carries decision-relevant detail: what is included, what is excluded, how estimates are surfaced, and how edge cases are handled. It is front-loaded with the core purpose and then systematically covers inflows, outflows, outputs, and units.

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, and it does: week-by-week inflows/outflows/closing balance, the dip, assumptions, overdueArCents, channelUnsettled, and units. It also covers failure modes such as missing channel connections or unreachable APIs.

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 an empty input schema, so the baseline is 4. The description cannot add parameter-level meaning, but it compensates by explaining the internal semantics of the computed fields and assumptions.

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

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

The description opens with a specific verb and resource: 'A forward 8-week cash-flow forecast — honest arithmetic from your books, not a model.' It clearly defines what the tool computes and distinguishes it from a current-position snapshot tool like cash_position by emphasizing the forward-looking 8-week window.

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

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

The description gives clear context for use: it is a forward-looking forecast built from books, inflows, outflows, and projected low points. It does not explicitly name sibling alternatives or state 'use this when...' versus other cash tools, but the 8-week forecast scope makes the selection context unambiguous.

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 well beyond the readOnlyHint annotation by explaining key behavioral details: ownerFunding is a liability excluded from total, credit cards are returned separately as card debt, each card has a direction, and balances are MYR-booked. This is rich contextual transparency for an agent.

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 longer than average but almost every sentence adds an important semantic distinction. It is front-loaded with the core answer and then explains exclusions. Minor redundancy exists around 'accounts' and total components, but the structure is still effective.

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 of explaining the response shape and semantics. It covers the total, account breakdown, shareholder loan, credit cards, direction fields, and currency treatment—making the tool fully understandable to an agent.

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

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

The tool has zero parameters, so the schema imposes no burden. The description instead focuses on output meaning, which is appropriate. No parameter-level explanation is needed.

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 tool as reporting current cash across bank accounts and cash pockets, including a grand total. It is specific about what the tool computes, but it does not explicitly differentiate itself from sibling tools like cash_forecast.

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 establishes a clear context: the tool answers 'How much cash you have right now.' It also provides strong exclusions about what should never be treated as cash, but it does not explicitly state when to choose this tool over alternatives such as cash_forecast.

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 mark this as read-only, and the description adds substantial behavioral detail: returns are matched to credit notes, settlement corrections do not move invoice-side figures, TikTok fees are booked later and folded in, and reported figures may not be final until payouts settle. This goes far beyond the structured annotations and clarifies real-world accounting behavior.

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 it is well-structured with labeled sections (RETURNS, NOTE, TIKTOK) and front-loads the core channel breakdown before going into exceptions. Some repetition and parenthetical detail could be trimmed, but the complexity of the accounting semantics justifies much of the 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 fully documents the returned fields, row presence behavior, returns treatment, settlement corrections, channel exceptions, and the warning that past-range figures can move. For a complex reporting tool, this is exceptionally complete and leaves little ambiguity about what the agent will receive.

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 burden for parameter meaning. It explains that from and to define a date range, gives the YYYY-MM-DD format, and—crucially—documents that sale-date and settlement-date matching differ for TikTok. It does not explicitly clarify inclusivity or timezone handling, but it compensates well for the empty 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 opens with a specific verb and resource: 'Your sales broken down by CHANNEL' for a date range, and it names the relevant channels. This clearly differentiates it from generic sales tools like sales_summary by establishing the channel dimension as the core purpose.

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 strong usage context: it explains the date range requirement, excludes manual/non-channel sales, and warns that settlement-based fees and returns can make a channel appear differently depending on the month read. It does not explicitly name sibling alternatives or say when to prefer another tool, but the context is otherwise 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?

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?

The description goes well beyond annotations: it prominently states 'FILES A PENDING DRAFT ONLY — NOTHING CHANGES UNTIL A HUMAN REVIEWS AND APPROVES IT IN TAOKEH', explains that 'a tick posts nothing', details refusal conditions by name, notes re-approval failure if underlying data changes, and clarifies defaults such as clearedDate. This is rich behavioral context that no structured field provides.

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 carries essential information for a safety-sensitive, multi-parameter operation. It is front-loaded with the most critical warning. It could be improved with bullet points or shorter paragraph breaks, but the density is justified by the complexity of the 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 tool with 10 parameters, intricate refusal logic, and an implicit human approval workflow, the description covers all operational aspects: required inputs and their sources, pairing rules, defaults, limitations, failure conditions, and post-submission behavior. Nothing essential is left to inference, making it highly complete.

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?

Despite 100% schema description coverage, the description adds critical semantic value: source of each id (bank_reconciliation_report, clearStep.uncleared, clearStep.candidateLines), exclusive usage of statementId vs asOf, default behavior of clearedDate, the 300-item limit, handling of cancelling pairs, and explicit warnings about unknown keys. This is far more than the schema descriptions offer.

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 ('file a pending draft'), a concrete resource ('bank clearing draft'), and the exact domain ('Banking → Clear transactions'). It clearly differentiates itself from the other create_*_draft siblings by focusing on bank clearing ticks and emphasizing that nothing changes until human approval.

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 strong workflow guidance: 'Read bank_reconciliation_report first and take every id from it' and 'read the report again and file afresh' if something changes. It does not explicitly list alternative tools or when not to use it, but the prerequisite and the detailed steps sufficiently orient an agent. One small gap is not naming a sibling to avoid (e.g., bank_reconciliation_status), so a 4 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?

With no helpful annotations (all hints false), the description carries the full burden and does so thoroughly. It discloses that the draft does NOT post to the books until approved, explains the posting consequences (stock, moving-average cost, input SST), details the strict line-key rejection behavior, and describes attachment handling edge cases (truncated base64, sandbox restrictions). This level of transparency exceeds what annotations would 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 is long but every section contributes essential operational detail. It is front-loaded with the most critical constraints (inventory-only, non-posting, line-key strictness) and branches into attachment handling and term semantics. While not concise in absolute terms, it is efficiently structured for a tool with 19 parameters and stringent rules; the density is justified, though a tighter organization could improve 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?

Given the complexity (19 params, strict validation, attachment workflows, server-side recomputation), the description covers nearly every scenario an agent might encounter: when to use which attachment method, how to handle measurement-profile companies, the need for reviewer notes, the handling of unknown terms, and even the sandboxed-client fallback. Nothing essential 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 only 58%, but the description compensates richly. It explains the meaning of `term` (credit period driving payables aging), the derivation of quantity from thickness/width/tally on measurement-profile companies, the strict line-key rule, attachment token vs base64 trade-offs, and the `confirmNewVendor` guard. These insights go far beyond the schema's field descriptions, giving the agent deep understanding of each parameter's purpose and interactions.

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

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

The description opens with a specific verb and resource: 'File a supplier-bill DRAFT into Taokeh from a bill you've read.' It clearly identifies the tool's purpose and immediately distinguishes it from siblings by stating 'INVENTORY-ONLY' and pointing to alternatives (manual bill form, create_expense_draft). This leaves no ambiguity about what the tool does or how it differs from related tools.

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

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

The description explicitly states when to use this tool (inventory-only bills) and when not to (services/non-stock/mixed bills use manual form or create_expense_draft). It also prescribes the prerequisite workflow: 'Shape the fields with intake_contract(doc_type:'bill') + resolve_vendor + resolve_product first.' This provides clear, actionable guidance on selection and sequencing.

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 all false, so the description carries the full burden. It discloses that the image is REQUIRED or the draft is refused, that approval is by the owner, that truncated base64 is rejected via attachmentBytes, that bad type/oversize files are rejected with nothing filed, and that attachmentToken and attachmentBase64 are mutually exclusive. No contradiction with annotations.

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

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

The description is long but front-loaded with the core purpose and workflow. Some redundancy (e.g., honesty warning appears in both description and schema) slightly bloats it, but the density of operational guidance justifies the length for a 16-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 16-param write tool with no output schema and minimal annotations, the description covers the full invocation workflow: reading the card, field extraction, honesty rules, attachment paths, partyKind/partyName, and post-call reporting. Nothing essential for correct invocation appears to be 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?

Even with 100% schema coverage, the description adds critical meaning: the image is required despite not being in the schema's 'required' list, the token/base64 exclusivity, and why attachmentBytes should accompany base64. It also clarifies partyName and needsReview semantics beyond their schema entries.

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 ('File a pending CONTACT draft') and resource ('from a business card YOU have read'), and explicitly distinguishes itself from adding to the address book. It names the draft role and the sibling domain (create_*_draft, update_contact_draft) implicitly via the workflow, making its purpose 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?

Provides explicit when-to-use ('after reading a card image yourself'), what not to do ('does NOT add anyone to the address book'), and alternative routing for large photos/PDFs via request_attachment_upload → PUT → attachmentToken instead of inline base64. Also instructs to report fields back to the user so misreads are caught before approval.

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 minimal (readOnlyHint false, etc.), so the description carries full burden. It discloses many behaviors: non-posting nature ('creates a pending draft the user reviews and approves'), refusal behaviors ('over-quantity line is refused naming what is left'), strict line-key enforcement ('a key this schema does not list is REFUSED BY NAME'), and the advisory nature of goodsReturned. No contradictions with annotations.

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

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

The description is very long but well-structured with clear sections (purpose, alternatives, line keys, parameter guidance). Every sentence carries operational significance; however, some redundancy exists (e.g., repeated emphasis on money-only vs stock return). Given the tool's complexity (13 params, many edge cases), the length is justified, but a bit of trimming would improve 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?

With 13 parameters, 77% schema coverage, and no output schema, the description is exceptionally complete. It covers all parameter semantics, error scenarios, alternative tool routing, and approval flow details. Nothing essential for an agent to call this tool 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 77%, so description must add value. It does: explains positive amounts ('Send all amounts POSITIVE'), advises leaving taxCode out to inherit original invoice code, clarifies clientAmount is 'never used to compute anything', defines description as 'TEXT, not a field', and distinguishes originalDocId vs originalDocNumber with refusal conditions. Adds substantial meaning beyond 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 explicitly states the tool's purpose: 'File a CREDIT NOTE draft into Taokeh — a sales return, short delivery, price correction or allowance that reduces what a customer owes.' It clearly distinguishes from siblings by naming alternatives like update_credit_note_draft, revise_draft, and update_invoice_draft, and explains what it does NOT do ('does NOT post to the books').

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

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

Provides explicit when-to-use/when-not-to-use guidance: 'IS A CREDIT NOTE EVEN THE RIGHT DOCUMENT? Only when something CHANGED AFTER the sale...' and then lists alternatives for voiding (no AI lane), corrections (update_invoice_draft), and fixing posted errors (update_credit_note_draft). Also instructs to use revise_draft for mistakes. This is comprehensive and unambiguous.

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 provide basic hints (readOnly=false, etc.), so the description carries the full burden. It discloses that this does NOT post to the books, requires an original invoice, has no stock/COGS impact, no cap on charge, strict line-key rejection, and money-only semantics. No contradiction with annotations; it adds substantial behavioral context beyond the structured hints.

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 earns its place, covering purpose, usage, pitfalls, and parameter nuances. It is front-loaded with the core action and critical requirements, then layers alternatives and warnings. No fluff or repetition; the density is justified by the complexity of the 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?

Given the complexity (11 params, no output schema, multiple sibling tools), the description is remarkably complete. It covers all prerequisites, required fields, error conditions, alternatives, and the exact behavioral flow. An agent could call this tool correctly with no additional information.

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?

Despite 73% schema coverage, the description adds critical semantic meaning: unitAmount is the additional shortfall, not the full price; quantity defaults to 1; taxCode inherits from the original invoice; productRef must appear on the invoice; customer is a cross-check. This goes far beyond the schema's own descriptions and prevents misuse.

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 ('File') and resource ('SELL-SIDE DEBIT NOTE draft'), and precisely defines what it does: an ADDITIONAL CHARGE on an already-issued invoice. It distinguishes from credit notes and new invoices, making the purpose unmistakable and differentiating it from sibling draft tools.

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

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

Provides explicit when-to-use and when-not-to-use guidance: names alternatives like create_invoice_draft for new charges, revise_draft for corrections, and update_supplier_debit_note_draft for the buy side. It also states the prerequisite (original invoice required) and the condition for refusing the tool (no upward correction needed).

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 minimal annotations, the description discloses key side effects and constraints: no ledger posting until approval, automatic attachment propagation, shoebox item refusal if already booked/pending, and rejection of truncated or bad-type uploads. It also explains the sandboxed network fallback for inline uploads.

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 information is front-loaded with purpose and primary behavior, then flows from field shaping to flags to attachment modes. It is dense and occasionally repeats the 'lands on the posted entry' benefit, but every major decision rule earns its place for an 18-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 complex create tool with no output schema and sparse annotations, the description covers the full life cycle: draft creation, review flags, shoebox linkage, attachment handling, and network fallback. An agent has enough context to select it and invoke the correct attachment path without further tool exploration.

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%, but the description compensates for the tricky parameters: amountUncertain, needsReview/notes, attachmentBase64/attachmentBytes/attachmentToken, and shoeboxItemId mutual exclusivity. A few required fields (date, amount, account codes) are left to the referenced intake_contract/expense_accounts workflow rather than explained inline, so it is strong but not exhaustive.

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 names a specific verb ('File'), target (Taokeh), scope (a paid-expense DRAFT), and source ('from a receipt you've read'). It immediately distinguishes the tool from posting to the books by explaining it creates a pending user-reviewed draft, which differentiates it from ledger-posting and other 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 directions: use intake_contract + expense_accounts first, set amountUncertain only when digits are uncertain, set needsReview for other doubts, and choose attachments by size/network conditions ('Small files... inline', 'Anything bigger: request_attachment_upload'). The shoeboxItemId branch and 'never both' exclusion also state exactly when not to send an image.

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 indicate readOnly=false, openWorld=false, idempotent=false, destructive=false—no behavioral detail. The description carries the full burden and delivers: server re-computes quantities and totals, strict line key refusal (by name), attachment truncation rejection, mutual exclusivity of attachment methods, and the shoebox workflow. No contradictions with annotations.

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

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

The description is long but densely packed with critical information. It front-loads the core concept and then organizes warnings and nuances in a logical order. Every sentence earns its place, though the length could intimidate an agent. It is not redundant, but slightly overlong for the platform's typical expectations.

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 20 parameters, 3 required, no output schema, and high complexity, the description covers prerequisites, server behavior, attachment handling, strict validation, and the review workflow. It tells the agent exactly what to expect (a pending draft for user review) and how to handle edge cases (truncated base64, sandboxed network). Nothing essential 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 60%, but the description adds substantial meaning beyond the schema: it explains how quantity is derived from tally on measurement-profile companies, clarifies that unitPrice is required per line, describes the strict line keys, and elaborates on attachment fields (attachmentBytes prevents truncation, attachmentSha256 as optional check). It also clarifies refNo vs reference. This goes well beyond the baseline.

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?

Clearly states the action ('File a sales-invoice DRAFT') and the resource (into Taokeh), and immediately differentiates from posting to the books. Explicitly distinguishes from siblings by naming prerequisite tools (intake_contract, resolve_customer, resolve_product) and the attachment upload alternative (request_attachment_upload).

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

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

Provides explicit sequencing: shape fields with intake_contract + resolve_customer + resolve_product first. Gives conditional instructions for attachments (inline for small, request_attachment_upload for large, never both). Also tells when to omit quantity and how to handle strict line keys, leaving no ambiguity about when to use this tool.

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

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

Annotations are sparse (all false), so the description carries the full burden — and it delivers richly. It discloses that the tool does NOT post to the books, that drafts must balance to the sen or be refused, that accounts are matched by code/exact name, that unknown refs are refused, that ambiguous names are reported rather than picked, that the tool never creates an account, and that posted history is never edited or deleted by design. This goes far beyond what annotations express.

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 it is organized into clearly scoped sections and every sentence carries operational meaning for a complex, high-stakes financial action. The core semantics are front-loaded in the first sentence, and the rest is structured around balancing rules, control accounts, exclusions, attachment handling, and correction workflow. It is dense rather than padded, though a slightly tighter organization would improve 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 tool with 13 parameters, no output schema, and zero clue-giving annotations, the description is unusually complete. It covers entry behavior, balancing constraints, account matching rules, control-account approval consequences, attachment handling with fallbacks, revision via revise_draft, and explicit alternatives. An agent has enough context to invoke the tool correctly in both normal and edge-case scenarios.

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 at 85%, but the description adds significant meaning beyond the schema: accountRef should be a chart-of-accounts code or exact name, never a guess; lines must carry exactly one side and at least two lines are required; attachmentToken and attachmentBase64 paths are mutually exclusive with conditions on reachability of taokeh.my; attachmentBytes should be the decoded on-disk size to reject truncated uploads; notes should be a short reviewer note, not lengthy reasoning. This is exactly the kind of parameter-level context an agent needs.

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

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

The description opens with a specific verb and resource: 'File an ADJUSTING JOURNAL ENTRY as a draft in Taokeh — the accountant's entry, not a document.' It immediately distinguishes the tool from document-based entry tools and lists the exact use cases (accruals, prepayments, depreciation, corrections, reclassifications, year-end adjustments, reversing entries). An agent cannot mistake this for create_bill_draft or create_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?

The description gives explicit when-to-use guidance and names sibling alternatives with conditions: 'WHAT NOT TO USE THIS FOR: anything that has a real document. A supplier bill is create_bill_draft, a sale is create_invoice_draft...' It also prescribes the reversing-entry workflow with search_journal, and tells the agent to say plainly what it is doing rather than reporting it 'cannot' fix an entry.

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 by explaining that the draft does NOT post until the owner approves, that the server re-derives allocations at create and approval time, that duplicate imported-line filings are refused, and that truncated attachments are rejected. These are critical behavioral details that the sparse annotations do not convey, and there is no contradiction with the annotations.

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

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

The description is front-loaded with the most important safety constraint and nearly every sentence carries functional value. However, it is a dense wall of text with heavy all-caps and long parenthetical asides, which makes parsing harder than necessary; it could be tightened or structured without losing information.

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

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

For a 15-parameter mutation tool with no output schema, the description is remarkably complete. It covers prerequisites, allocation rules, currency constraints, credit-card exclusions, the imported-statement duplicate risk, attachment mechanics, review notes, error handling, and what happens at approval. Nothing essential for selecting or invoking the tool 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?

Although schema coverage is already high at 87%, the description adds substantial meaning to parameters: purchaseId should be preferred over reference because supplier bill numbers are not unique, total and allocations are mutually exclusive, attachmentBytes detects truncated base64, and notes should carry only a short reviewer flag. This materially improves correct invocation beyond the raw 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 opens with a specific verb and resource: 'FILES A PENDING DRAFT ONLY' and 'File a SUPPLIER-PAYMENT draft'. It clearly distinguishes this tool from the many create_* siblings and from draft_bank_classification by stating exactly what kind of draft it files and that human approval is required before anything posts.

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 guidance is explicit and thorough. It names concrete alternatives and their trigger conditions: use draft_bank_classification if the payment is already on an imported bank line, use revise_draft if filed wrong, and route foreign-currency or credit-card cases elsewhere. It also prescribes prerequisites like resolve_vendor, ap_aging, and search_documents before 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?

With annotations all false, the description carries the full burden and does so thoroughly. It discloses that nothing changes until human approval, that approval allocates exactly like Banking → Match → Save, that refusals occur both at filing and approval, and that any change to the line or document before approval causes refusal. This is rich behavioral 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?

The description is long but every sentence earns its place. It is front-loaded with the most critical behavioral caveat, then logically proceeds through purpose, parameters, eligible documents, refusal conditions, and the note. The structure is clear and the density is justified by the complex matching 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?

The description comprehensively covers input requirements, eligibility, refusal conditions, and the approval workflow. However, it does not explicitly state what a successful response looks like (e.g., a draft identifier or confirmation), which is a minor gap given there is no output schema. The failure response is partially described (refusal lists documents), but success return is left implicit.

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 substantial meaning beyond the schema: it specifies that bankTransactionId must be a POSTED line from bank_review_queue with status 'posted', explains the allocations format with saleId vs purchaseId and the requirement to sum to the whole line, and explicitly warns that 'lines', 'notes', 'bankLineId', and 'transactionId' are NOT filters and should be passed under the correct parameter names. This is far 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?

The description opens with a clear, emphatic statement of what the tool does: 'FILES A PENDING DRAFT ONLY' and then specifies the exact operation: proposing how one posted bank line settles open invoices or bills. It distinguishes itself from sibling create_*_draft tools by emphasizing the human-approval step and the Banking → Match → Save equivalence.

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 the tool (for a posted bank line from bank_review_queue), enumerates refusal conditions (not posted, already matched, foreign-currency, etc.), and provides a concrete alternative workflow (unpost, set the right customer, repost). This is explicit when/when-not guidance with alternatives.

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

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

Annotations are all false and generic, so the description carries the full burden — and meets it richly. It states that the tool 'POSTS NOTHING and MOVES NOTHING' (no journal entry, stock movement, or amount owing), that approval saves a DRAFT and emails nobody, that no SST is carried, and that the server recomputes authoritative quantities/totals. The strict line-key refusal behavior is also disclosed. No contradiction with annotations; filing a draft is a write, consistent with readOnlyHint=false.

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

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

The description is long, but nearly every passage earns its place given the domain complexity: tax treatment, measurement-profile quantity derivation, workflow ordering, and error recovery. It is front-loaded with the core purpose and behavioral guarantees before the constraints. The heavy use of ALL-CAPS emphasis is stylistically loud but flags genuinely critical constraints.

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 tool with no output schema, the description covers the critical operational facts: result semantics ('saves the order as a DRAFT', 'the server's figures are authoritative'), failure behavior ('NOTHING is filed' on bad keys), prerequisites, alternatives, and the review workflow. Nothing an agent needs in order to call this tool 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 45% (below the 50% threshold), so the description needed to compensate — and it does. It adds workflow meaning around several parameters: the quantity/tally/thickness/width derivation rule, the SHORT reviewer note requirement for `notes`, the strict line-key behavior applying to `lines`, and the confirmNewVendor guard context. A few parameters (printedTotal, unit, working, vendorId) remain lightly documented, but the description compensates for coverage gaps better than the schema alone does.

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 ('PURCHASE-ORDER draft'), and system ('Taokeh'), with the intent ('intend to PLACE with a supplier, typically read off their quotation'). It distinguishes itself from close siblings by name ('use create_bill_draft' for arrived goods, 'use revise_draft' for corrections), so an agent can tell them apart without opening schemas.

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

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

Gives explicit when-not conditions and alternatives: 'Goods that have ALREADY arrived are not this door — use create_bill_draft', 'Filed it wrong? Use revise_draft (kind: \'purchase_order\') rather than filing a second one', and the inventory-only exclusion that routes services to the manual form. It also names the prerequisite shaping tools (intake_contract, resolve_vendor, resolve_product) and when to set needsReview.

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?

Very explicit about side effects: a draft does NOT post to books or move stock; the server recomputes quantities and totals (authoritative); strict field validation refuses unknown keys and files nothing; truncated base64 is rejected via attachmentBytes. This is beyond the annotations (readOnlyHint=false, destructiveHint=false) and adds critical expectations.

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

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

Dense but organized: starts with the core action, then field-shaping, then behavior, then attachment workflow. Some sentences are long, but the information is high-value and the order is logical.

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 17 params with no output schema, it covers the main judgment areas: request extraction, reviewer notes, measurement profiles, attachment handling, and strictness. It doesn't describe the response payload or failure modes, but the behavioral notes suggest the server will reject with errors.

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 has 17 params, description clarifies the tricky ones: attachmentBytes' purpose (truncation check), needsReview guidance with example note length, measurement-profile handling of quantity vs tally/width/thickness, and attachmentBase64 vs attachmentToken mutual exclusivity. That's substantial added meaning 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 description opens with a concrete verb ('File') and a clear resource ('a quotation DRAFT') and immediately distinguishes it from posting a real quotation ('does NOT post to the books or move stock'). It also names the downstream flow (review → approval → conversion to invoice/delivery order), so an agent knows exactly what this tool is for and what it is 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?

It gives practical guidance: resolve customer/product before shaping fields, attach original documents, set needsReview for doubts, inline small files vs use attachmentToken for real PDFs. It doesn't explicitly name sibling alternatives (e.g., 'use update_quote_draft when editing'), but the draft-vs-posted contrast and the attachment alternatives cover the main 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?

Annotations are all false hints, so the description carries the full burden — and it delivers: it discloses that no posting or settlement happens until human approval, that the server re-derives allocations against live outstanding and its figures are authoritative, and that truncated base64 or bad-type files are rejected rather than filed. It also discloses the network-dependent behavior (inline anyway when taokeh.my is unreachable) and the 'never both' mutual exclusion. Nothing contradicts the annotations; creating a pending draft is consistent with readOnlyHint=false and destructiveHint=false.

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

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

The description is long (~350 words) but nearly every sentence maps to a distinct operational decision an agent must make, and it front-loads the core draft-not-post semantic before each concern. Minor tightening is possible — the 's.82 record-keeping' parenthetical and some attachment-outcome phrasing are repeated in the schema — but the density is warranted for a 15-parameter tool with two attachment paths and a fallback rule.

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 very complex tool with uninformative annotations and no output schema, the description covers the full call workflow: prerequisites, currency exclusion, allocation modes, review obligations, both attachment routes, and the downstream record-keeping outcome. The remaining gaps are the unstated return value (e.g., whether a draft ID comes back for use with revise_draft) and the two undocumented parameters noted above — minor against the otherwise thorough coverage.

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

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

With only 47% schema coverage, the description compensates for the decision-critical parameters: the EITHER lump `total` (auto-allocated oldest-first) OR explicit `allocations` mutual exclusion, the paired `needsReview`+`notes` workflow with quality guidance, and the attachmentBase64/attachmentToken either/or with `attachmentBytes` as a truncation guard. However, `bankAccountId` and `printedTotal` receive no meaning from either the schema or the 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?

Opens with a specific verb phrase — 'File a customer-payment DRAFT into Taokeh ("customer paid X")' — that names the exact resource and the direction of money movement, cleanly separating it from create_bill_draft and create_invoice_draft. The explicit 'This does NOT post' adds the crucial draft-vs-post distinction that the title alone cannot convey.

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 preconditions and sequencing: resolve the customer via resolve_customer and check open_invoices first. States hard exclusions (MYR only; foreign-currency invoices are refused and route to Banking → Payments) and names the alternative tool for large attachments (request_attachment_upload), plus a concrete network-fallback rule for sandboxed shells.

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?

Extremely transparent. States this files a draft only, that nothing is posted until a human reviews, that it never buys itself auto-issue, that a customer must already existarked, that no customer will be created. It also flags that wrong guesses should be avoided and user should be asked. That's exactly what an agent needs to know about side effects and prerequisites.

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 dense. The leading ALL-CAPS warning is an excellent front-loaded structure that prevents misuse. A few redundancies (e.g. repeating that nothing is created until human approval) could be trimmed, but everything present carries operational weight. Not quite a 5 because it 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?

Covers what the tool does, prerequisites (existing customer, real products), constraints (cannot auto-issue, no revenue spreading), field semantics, and behavioral guardrails. Sibling context is implied through repeated contrast with single-invoice drafts. 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?

While the schema already describes each parameter, the description adds critical context: `customer` must be an existing resolved customer, lines may be productId or sku, prices bill every cycle, day-of-month anchoring for recurring dates, paymentMethod semantics (CREDIT vs CASH), and behavior guards (never guess). This is far beyond the schema's field-level 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 precise action (file a recurring invoice draft), a specific resource (recurring schedule), and its key distinguishing constraint — nothing is created until a human approves in Taokeh. This is clearly differentiated from create_invoice_draft and other draft tools by the 'recurring' focus and the explicit workflow.

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 when to use it (propose a recurring invoice schedule) and when not to — it explicitly states it cannot set issueMode to auto or set revenue recognition, and warns against guessing prices/dates. It also says to ask rather than guess for paymentMethod. It doesn't explicitly name sibling tools like create_invoice_draft as alternatives, hence 4 not 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 repeatedly calls this a 'single read' and presents it as a read-only aggregation, but annotations set readOnlyHint=false, contradicting that safety profile. Although it adds rich domain semantics about cash, approvals, and staged rows, the annotation contradiction mandates a score of 1.

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 front-loads the summary, but the rest is a single dense, run-on paragraph with numerous parenthetical caveats. The field-level semantics are valuable for a no-output-schema tool, though the structure is not scannable and the prose is overly verbose.

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 a complex aggregate return, the description explains the key output fields and their boundaries in detail: cash.total is liquid only, owner funding and cards are separate liabilities, receivables.unmatchedPayments are already netted, approvals count decisions rather than rows, and staged/fenced rows have special semantics. This is enough for correct interpretation.

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

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

The tool takes no parameters, so there are no parameter semantics to clarify; baseline 4 applies. The description correctly does not attempt to add parameter detail beyond the empty schema.

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

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

States a specific verb and resource set: it is the one-call morning brief covering sales, expenses, cash, receivables, approvals, tax, and stock. It distinguishes itself from siblings by naming the individual tools it assembles (business_snapshot, cash_position, ar_aging, tax_position, low_stock).

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 positions the tool for 'brief me' as a single read that replaces aggregating the individual figures, and names those alternatives. It does not explicitly state when not to use it, such as when only one metric is needed.

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-readOnly/non-destructive/non-idempotent; the description goes far beyond, disclosing that these are proposals only, never posted, never move money, that accountCode arrives pre-selected but doesn't decide, that allocations pre-fill the Match pane and settle nothing, and that batch acceptance sets category/contact only. This is exactly the behavioral context 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 the PROPOSALS ONLY safety statement, which is good, but the body is an extremely dense run-on wall of prose mixing categories, accounts, twins, allocations and rules with no headings or list structure. Much of it earns its place given the tool's complexity, but the layout makes it hard to scan.

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

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

For a complex, nested, high-stakes proposal tool with no output schema, the description covers rejection cases, per-row outcome reporting, possibleTwin handling, contact/account/allocation rules, and owner-facing side effects. Nothing an agent needs to call it 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?

With 0% schema coverage, the description fully compensates: category constraints, contactName matching rules and which categories accept it, accountCode allowed categories and refusals, allocations format ({docNumber, amount}, up to 20, RINGGIT, must sum within 0.10 of the whole line), and note (≤300 chars, shown to owner). Far exceeds the bare schema.

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

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

States a specific verb+resource+scope: 'Propose a category (and optionally a contact) for up to 50 bank rows still waiting for review.' It names the exact row states handled (SUGGESTED/UNCATEGORIZED) and distinguishes itself from siblings by pointing to bank_review_queue for ids and create_bank_clearing_draft for the twin case.

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 throughout: which rows accept a proposal, which are rejected (CONFIRMED/POSTED/IGNORED, Clear-transaction pairs), when to route to create_bank_clearing_draft instead, when the owner should exclude a card line, and the rule that CARD_PAYMENT requires accountCode while other categories reject it.

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

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

Beyond the readOnlyHint annotation, the description adds substantial behavioral context: it is READ-ONLY and 'creates nothing, hires nobody and files nothing.' It discloses the calculation source (LHDN's official MTD method, with a written confirmation reference), spells out all default assumptions, mandates repeating assumptions to the user, and positions the result as an estimate rather than a quote or tax advice. This is exemplary 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 long but every sentence earns its place: use case, parameter semantics, tax computation provenance, default assumptions, compliance guardrails, and access restrictions. It is front-loaded with the core purpose and then moves systematically through parameter details. There is no filler or tautology.

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 there is no output schema, the description clearly states what the tool returns: employer cost and employee take-home. It fully covers the five parameters, the applicable tax method, the default assumptions, and the mandatory communication requirement to repeat assumptions to the user. This is more than enough for an agent to select, invoke, and interpret 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 0%, so the description carries the full burden, and it delivers. It explains monthlyWage through the RM4,000 example, residency via RESIDENT/NON_RESIDENT and the flat 30% tax rate, citizenship via HRD Corp levy and SKBBK effects, ageBand via reduced EPF and SOCSO Category 2, and epfEmployeeRate via the employee's elected reduced EPF rate. Every parameter receives meaning beyond its raw schema definition.

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

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

The description opens with a specific verb and resource: 'Cost a HYPOTHETICAL hire' and concretely defines the outputs: employer cost (wage plus EPF, SOCSO, EIS, HRD Corp levy) and employee take-home pay. It gives a representative question ('if I hire someone at RM4,000...') that makes the tool's scope unmistakable and distinguishes it from generic payroll or reporting 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?

It gives explicit when-to-use framing with example questions and explains the default assumptions users should expect. It also provides role restrictions ('ADMIN AND BOOKKEEPER + PAYROLL ONLY'). However, it does not name any alternative sibling tool or explicitly state when NOT to use this tool, so the guidance stops short of a full when-versus-alternatives treatment.

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 goes far beyond that, explaining that expenseCategories is a CURATED subset, listing exactly what is excluded (cash/bank, A/R and Inventory controls, contra accounts, engine-only accounts), and detailing the distinct validation rule for category vs. paid-from codes. This is rich operational context an agent needs to avoid picking a rejected code.

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 content is substantive, but it is delivered as one dense run-on paragraph with nested asides that make the core point hard to extract. It front-loads the resource name but buries the practical routing guidance mid-sentence, hurting 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?

With no output schema and no parameters, the description carries the semantic burden and mostly does: it explains what the list contains, what it excludes, and the filing-time validation for each code type. It stops short of describing the return shape (e.g. code-plus-name entries) or ordering, which would fully close the gap.

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

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

The tool takes zero parameters, so there is no parameter semantics to document; baseline for a param-less schema is 4. The description instead explains the meaning of the values the tool returns, which is a reasonable substitute.

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

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

States a specific resource — the expense accounts postable in this company, split into category and paid-from codes. It even ties the purpose to a workflow ("for shaping a paid-expense draft"), which is clearer than a bare name restatement. It does not explicitly distinguish itself from sibling lookups like search_expenses or find_in_taokeh, so it falls short of a 5.

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

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

Gives clear context: use it to pick a category and paid-from code when building a paid-expense draft, plus the acceptance rule at filing time for each code type. It effectively tells the agent what codes are valid where, but never names a sibling alternative or states when NOT to call it.

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

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

Annotations already 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 all neutral false values (readOnlyHint, idempotentHint, destructiveHint, openWorldHint), so the description carries the full disclosure burden and discharges it thoroughly: the non-posting review-queue landing, the server's balance check that 'rejects with the exact delta,' the card directional check, automatic exclusion of the payment-settlement line, and the archiving/adoption behavior of repeated calls. It even discloses consequences ('declaring the wrong one books the whole month backwards') and what happens without a token ('nothing is archived').

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 front-loaded: the first sentence states the purpose and the second the non-posting guarantee, with subsequent paragraphs organized topically (core rules, credit cards, archiving, re-calls) and no filler. Some repetition with the schema's own parameter descriptions (e.g., signConvention) exists, but the density is justified by the tool's complexity and hazard profile.

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, 4-required import tool with no output schema, the description covers prerequisites, sequencing, edge cases (cards, overlap), failure modes (balance delta, directional refusal), and idempotent re-call behavior. The only notable gap is that it never describes the response/return value, which matters more given the absence of an output schema.

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

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

Schema description coverage is 73%, above the high bar, so the baseline is 3; the description still adds meaning the schema lacks: the signed-amount convention (+ money in, − money out), the invariant that opening + rows must tie to closing, and the effect of signConvention on the directional check. It also explains that attachmentToken must come from request_attachment_upload and that identical re-calls adopt the file, enriching several parameters at once.

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 — 'Import a bank statement into Taokeh for reconciliation' — and immediately scopes what it is not: 'This does NOT post to the books — every row lands in Banking → Review.' It differentiates from siblings by routing single receipts/invoices/bills to 'their own draft doors,' and the title's '(nothing posts)' qualifier is reinforced throughout.

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 sequential prerequisites: 'use intake_contract(doc_type:'statement') first' to see the tenant's bank accounts and the arithmetic law, and 'call request_attachment_upload FIRST' before archiving. It names exclusions with alternatives ('Single receipts, invoices or bills go through their own draft doors, not here') and specifies exact re-call conditions where identical parameters adopt a file without double-staging.

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?

Annotation Contradiction: annotations set readOnlyHint=false while the description claims 'READ-ONLY. It changes nothing, it cannot approve anything, no tool can approve on the owner's behalf, and no tool of any kind moves money.' This is a direct contradiction with the structured annotation and undermines an agent's ability to trust side-effect expectations.

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

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

The description is long but well-structured: it uses numbered questions, separates the four result buckets, and clearly labels parameter semantics. There is some redundancy in the repeated safety statements, but the length is largely justified by the tool's complexity and the lack of output schema.

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 sparse annotations, the description carries the full burden of explaining return behavior. It details what each bucket contains, the `reason`/`reasonRecorded` semantics, defaults, truncation behavior, and the read-only guarantee. An agent has enough information to call the tool and interpret results 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 0%, and the description fully compensates: it defines `since` as YYYY-MM-DD or ISO with a 7-day default, `kind` as an optional single-lane filter, and `limit` as default 50/max 200 with honest truncation reporting. It also enumerates the lane categories, mapping directly to the schema's enum values.

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, identifiable purpose: it returns the caller's own queue of submitted items across PENDING, APPROVED, REJECTED, and STAGED buckets, and names the lanes and fields included. This clearly distinguishes it from sibling reporting and draft-creation tools.

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

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

The description clearly frames when to use the tool: to answer four questions about the user's own submitted items and their statuses. It also gives parameter-level guidance for `since`, `kind`, and `limit`. It does not explicitly name alternatives or state when not to use it, but the scope is clear enough for 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?

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?

Beyond the readOnlyHint annotation, the description discloses that it is read-only and cannot create runs or file with authorities, that it reads from stored payslips (never recalculation), that it returns leave data, and that it states plainly when no run exists instead of returning zeros. It also notes the tool refuses non-payroll connections. These are substantial behavioral disclosures that enrich the annotation.

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

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

The description is long but densely packed with essential information, and it is well-structured: it opens with the core output, then covers parameters, data source, and permissions. Every sentence adds value; however, it could be trimmed slightly without losing critical detail, making it a 4 rather than a 5.

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

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

For a tool with three optional parameters, no output schema, and a read-only annotation, the description is remarkably complete. It covers what the output includes, how to handle month, the purpose and sensitivity of perEmployee, how to obtain employee IDs for update_employee_draft, the data source (stored payslips), edge cases (no run), and role-based access. 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 only 33% (staff has a description; month and perEmployee do not). The description compensates fully: month is explained with format and default behavior, perEmployee is explained as sensitive and carrying real employee IDs, and staff is elaborated with its purpose for obtaining employee IDs. This goes well beyond the schema to clarify each parameter's semantics.

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 returns a full payroll summary from gross to net, including contributions, net pay, employer cost, and also lists upcoming approved leave. It distinguishes itself from other financial tools by specifying the exact components and the one-call capability for two distinct queries, and it explicitly references the sibling update_employee_draft for employee ID sourcing.

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 when to use the tool ('what does payroll look like this month' and 'who is out next week'), how the month parameter behaves (latest run if omitted, YYYY-MM for specific), and when to set perEmployee and staff flags, including a warning that perEmployee returns sensitive individual salaries. It also specifies role restrictions (ADMIN AND BOOKKEEPER + PAYROLL ONLY) and that it refuses other connections, providing clear guidance on appropriate invocation.

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 already mark this read-only and closed-world, but the description adds substantial behavior: the exact return fields, the three possible statuses (resolved/ambiguous/none), the explicit ambiguity directive, and the isService semantics ("selling it never counts stock or posts a cost"). With no output schema, this disclosure is genuinely valuable.

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, then adds return fields and status behavior. Dense but each clause carries information; the parenthetical isService explanation is long but earns its space by clarifying a non-obvious flag.

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

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

For a one-parameter resolver with no output schema, the description covers purpose, input expectations, return shape, and the ambiguity-handling contract. An agent has everything needed to call it correctly and interpret the result.

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

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

Schema coverage is 0%, so the description must carry the load. It does: the single `query` param is characterized as a product name or SKU, with "plain names or SKUs work best" implying the preferred input form. It doesn't specify matching rules or format edge cases, so not a full 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 (Resolve) and resource (product) plus the concrete context (for an invoice line). It is cleanly distinguishable from the sibling resolve_customer and resolve_vendor by resource, and from update_product_draft by the resolve/read semantics.

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?

"for an invoice line" and "Plain names or SKUs work best" give clear usage context and input guidance, and the status handling ("never guess among candidates") steers behavior. It stops short of naming alternatives or stating when NOT to use this tool, so it falls 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?

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 are all false hints (readOnly, openWorld, idempotent, destructive), so the description carries the full burden. It discloses that the draft updates in place, stays pending, nothing posts, the reviewer is told via an appended note line, fields not sent are left untouched, the card image is not patchable, and invalid keys are refused. This is rich behavioral context far beyond the sparse annotations, with no 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?

Though long, every sentence earns its place. It fronts the purpose, then routes usage, then constraints, then side effects for the reviewer. No filler or repetition of schema details; each clause adds a distinct fact needed to invoke the tool 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?

For a tool with a nested `patch` object, 23+ kinds, no output schema, and weak annotations, the description is remarkably complete. It covers failure modes (refused with status, duplicate refusal, invalid keys), lifecycle guarantees (stays pending, no posting), side effects on the reviewer (appended note), and excludes patchable evidence. Nothing an agent needs to decide whether to call it and how 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%, which sets a baseline of 3. The description adds global patch semantics beyond the schema: patch may only contain fields belonging to the draft kind, foreign/misspelled keys are refused, and the evidence image is deliberately not patchable. It also explains that `note` should be in the reviewer's language and is appended, not overwriting. This adds meaningful context on top of an already detailed 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 first sentence states a specific verb ('Correct'), resource ('a draft you already filed'), and the core action ('instead of filing it again'). It explicitly distinguishes itself from sibling create/update tools by naming the duplicate-refusal behavior and the confusing-second-draft risk, so an agent can tell revise_draft apart without opening sibling 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?

Provides explicit 'when to use' ('whenever you realise a filed draft is wrong'), explicit 'when not to use' ('ONLY a PENDING draft can be revised; approved/rejected/expired drafts are refused — file a fresh draft'), and names the alternative actions (re-calling create_expense_draft is refused, a second create files a confusing second draft). No room for inference left.

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?

The description adds substantial behavioral context beyond the readOnlyHint and openWorldHint annotations: fixed 200-row cap with total/shown/more, ordering rules, currency conversion guidance, margin formula, docStatus semantics, isMeasureDrift caveats, unit fallback behavior, and historical cost-basis explanation. It ends with 'Nothing is written, and no draft is created,' reinforcing the read-only annotation without 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?

The description is very long, but appropriately so for a high-stakes tool with many edge cases around currency, margin, measure drift, and document types. It front-loads the core purpose and use cases before diving into caveats, and uses bold labels and clear sectioning to make the length navigable, though a tighter edit would improve readability.

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 carries the full burden of explaining return rows, ordering, pagination, currency behavior, margin calculation, and per-document-type semantics — and it does so comprehensively. It covers buy-side vs sell-side differences, voided/converted document statuses, and data-reliability cutoffs, leaving no critical gap for an agent deciding whether and how to call this 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?

Though schema coverage is 100%, the description adds meaning the schema alone cannot convey: docType is REQUIRED despite the schema not enforcing it, number also matches the customer's Ref No on invoices, productText matches both product name and line description, and many schema parameters (ref, sku, item, size, docId, limit, etc.) are explicitly marked as NOT filters with instructions on what to use instead. This is far beyond the baseline.

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

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

The description opens with a specific verb and resource: 'Read the LINE ITEMS of documents IN BULK' and immediately contrasts with search_documents ('answers WHICH documents; this answers WHAT WAS ON THEM'). This makes the tool's scope unmistakable and distinguishes it from closely named 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?

It explicitly says when to use the tool ('any question that needs the detail behind the totals'), what it replaces (opening one PDF per document), and names concrete alternatives: search_documents for header-only, search_expenses for paid expenses, search_journal for ledger postings. It even warns to read lines here before calling draft-update tools that 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.