Taokeh MCP server

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

The annotations already declare readOnlyHint=true, and the description complements this by explaining the report's structure (grouped by supplier, with aging/overdue information). No contradiction exists, and the description adds behavioral context about what the report presents beyond the safety 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 a single, memorable sentence with an effective em-dash structure. It is front-loaded with a relatable question and wastes no 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?

The tool is simple: one optional parameter, no output schema, and safety annotations provided. The description explains what the report contains (payables aging by supplier). The only gap is the lack of clarification around the 'asOf' parameter, but for a simple report this is a minor omission.

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 does not mention the only parameter 'asOf' at all. Since schema description coverage is 0%, the description fails to compensate for the lack of parameter explanation. The parameter name and pattern are somewhat self-explanatory, but the description adds no semantic value for how the date affects the aging report.

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 specifies the exact resource ('accounts-payable aging by supplier') and the informational content ('whom you owe money and how overdue it is'). It clearly distinguishes itself from the sibling tool 'ar_aging' by explicitly naming the accounts payable side.

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 clear context for when to use the tool: when you need to understand outstanding payables and their overdue status. It does not explicitly name alternatives, but the 'accounts-payable' phrasing versus the sibling 'ar_aging' implies the differentiation, and no exclusions are 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 already indicate readOnlyHint=true, so the description adds value by explaining the output is bucketed by age and spans all customers. It does not mention return format, but that is not required given the read-only nature and no output schema. 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 two sentences, front-loaded with a clear question and purpose, and includes a direct pointer to an alternative. Every sentence earns its place with no redundancy.

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

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

For a simple read-only report with one optional parameter and no output schema, the description covers the core purpose and when to use it. However, it omits explaining asOf, which is a minor completeness gap. Overall, it is sufficient for tool selection.

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%: the only parameter 'asOf' is not explained in the description. The description never mentions that an optional as-of date can be provided, leaving the agent to infer its meaning from the name and pattern. This is a notable 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 clearly states the tool generates an accounts-receivable aging report across ALL customers, bucketed by age. It uses a specific verb and resource ('accounts-receivable aging') and distinguishes itself from the sibling tool open_invoices, which targets a single customer.

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 provides an alternative: 'For the unpaid invoices of ONE named customer, use open_invoices,' guiding when to use this tool vs. another. It also implies the scope is all customers, making the usage context 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?

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?

Annotations already mark readOnlyHint=true, and the description adds valuable behavioral nuance beyond that: the credit card liability warning, the 'unknown' handling when a statement has no balance, and the explicit note that categorizing/confirming/posting are human actions. This gives an agent important context not encoded in 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?

The description is dense and somewhat long, but each sentence carries meaningful content: position wording, exact fields reported, the credit card liability distinction, parity with the web UI, and the read-only boundary. No fluff, though 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?

With no output schema, the description carries the needed completeness load: it names the report contents, the status categories, the backlog, the per-statement balances, and the warning about credit card figures. An agent has enough understanding to call the tool and interpret a returned snapshot.

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 coverage is 100%, so the schema already exhaustively documents the input contract. Description therefore does not need to compensate for missing parameter documentation. Baseline 4 is appropriate.

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

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

The description clearly identifies a read-only bank reconciliation status report: GL balance versus latest statement closing balance, status counts, and per-statement tie-out. It is specific about the resource and scope, although it does not explicitly differentiate itself from sibling tools like bank_review_queue.

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 clear context: it shows the same figures as the in-app Bank Reconciliation page and is READ-ONLY, implying it is for checking status, not taking action. However, it never explicitly says when to choose this over alternatives or names a sibling like bank_review_queue for the actionable side.

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 readOnlyHint: true, and the description adds substantial behavioral detail beyond that: the 1000-row window ceiling with refusal, the 200-row cap with truncation note, null suggestions on settled rows, possibleDuplicateOf being only a resemblance, and the rule that confirmation/posting always requires human action. There is no contradiction with the read-only annotation; the tool only reads, while proposals are made through another 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 it is front-loaded with the core purpose, uses visual markers like ⛔ and ⚠, and structures the content around defaults, windows, exclusions, suggestions, and settled rows. Some phrases are repetitive or contain asides that could be trimmed, but the length is largely justified by the number of modes and caveats an agent must understand.

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 full burden of explaining return semantics. It covers scope and statement fields, statusCounts, confidence buckets, row-level fields for both unreviewed and settled rows, possibleDuplicateOf, yourProposal, truncation behavior, and the refusal condition for large windows. Combined with the explicit routing to sibling tools, this is enough for an agent to invoke the tool correctly without guessing.

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

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

Schema coverage is 75% and the schema's statementId description is corrupted, so the description must compensate and largely does. It explains the meaning and default of status, the date-window behavior of from/to without statementId, and the role of statementId in scoping and the row cap. The description adds real semantics beyond the schema, though statementId itself is not given a dedicated, direct 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 clearly identifies the tool as the imported bank register/review queue and explains that it returns statement rows in any status, defaulting to unreviewed ones. It differentiates itself from search_documents for hand-recorded settlements and from draft_bank_classification for proposing categories, so an agent can select it correctly among the many sibling 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 gives explicit selection criteria: use the default for the unreviewed queue, pass status for settled history, pass from/to without statementId for a date window, and use search_documents with docType:'payment' for hand-recorded entries. It also states what the tool can and cannot do, naming draft_bank_classification as the separate tool for proposals.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds scope context ('Sales and expenses ONLY', 'so far') which clarifies what data is returned without contradicting the read-only nature. It doesn't exhaustively describe edge cases but does enough for a simple read 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 two sentences with no wasted words. It front-loads the core purpose and then delivers a clear alternative, making every sentence earn its place.

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

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

For a zero-parameter tool with no output schema, the description fully explains what the tool returns and how it relates to sibling tools. There is no missing context for an agent to invoke it correctly.

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

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

The tool has zero parameters, so the baseline is 4 per rubric. The description compensates by explaining exactly what data is included (today's and this-month's sales and expenses), which adds meaning 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?

The description clearly states it provides a one-glance health check of today's and this-month's sales and expenses, which is a specific verb+resource. It also explicitly differentiates from the daily_brief sibling tool by limiting scope to sales and expenses only.

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 names the alternative tool (daily_brief) for a fuller morning read and states that it includes everything this tool provides, effectively giving when-to-use and when-not-to-use guidance. This is exemplary usage differentiation.

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 sparse annotations, disclosing that values are estimates, what happens when channel data is unavailable or the API fails, that estimates are deliberately not counted in the dip, and that amounts are integer cents. It also explains the 'assumptions' list and the treatment of owner advances as liabilities, making the tool's behavior highly transparent.

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 adds necessary domain context: treatment of overdue amounts, channel unsettled pools, payroll components, remittance timing, and units. It is front-loaded with the core purpose and then expands into behavioral specifics. It could be tighter with bulleted structure, but the verbosity is justified by the tool's complexity.

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 without an output schema, the description fully covers return values (week-by-week inflows/outflows/closing balance, dip, assumptions list), units, data sources, and edge cases such as disconnected or lapsed channel access. It is complete enough for an agent to invoke 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?

The input schema is empty, so the baseline for parameter semantics is 4. There are no parameters to document; the description instead explains the forecast's inputs implicitly from the books. No additional parameter-level detail is needed beyond what the empty schema already conveys.

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 this as an 8-week cash-flow forecast built from bookkeeping data, with a specific scope: opening liquid balances, scheduled inflows, and known/estimated outflows. It also distinguishes itself from related reporting tools by emphasizing it is 'not a model' and by explaining what is deliberately excluded or reported separately.

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 context for when to rely on this forecast: it states what is included, what is excluded (owner advances, overdue receivables, unsettled channel money), and how to treat those exclusions as stated upside. It does not explicitly name alternative sibling tools or say 'use this when you need X, not Y', but the inclusion/exclusion logic effectively guides 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?

Beyond the readOnlyHint annotation, the description discloses important behavioral semantics: `total` is strictly liquid cash, owner funding and card balances are separate liabilities, each card has a `direction`, and balances are MYR-booked even for foreign accounts. This is substantial, practical behavior guidance that prevents common misuse and does not contradict 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 main numeric/computational answer and then expands into the important exclusions. It is dense and fairly long, but each rule contributes to correct interpretation of the output. A little tightening would improve it, but for a tool with a nuanced cash distinction structure, the length is 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?

With no output schema at all, the description carries the responsibility of defining the return shape, and it does so effectively: `total`, `accounts`, `ownerFunding`, `cards`, `cardsOwing`, `direction`, and the relevant currency/booking behavior are all explained. There is enough detail for an agent to both invoke the tool and correctly present 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?

There are zero parameters and the schema has 100% coverage by being empty, so the baseline of 4 applies. The description adds value by explaining the meaning of the conceptual result fields, but there are no parameter-specific semantics needed here.

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 clearly states what the tool reports: current cash across every bank account and cash pocket, with GL balances and a grand total. Even though it uses a question-style phrasing rather than a firm imperative, it identifies the resource and scope precisely and separates it from forecast-type siblings by focusing on the right-now position.

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 establishes when this tool is appropriate: whenever the agent needs the current cash position as booked in the GL. It also instructs how to treat returned values, such as reporting owner funding as a liability and card balances only as debt outside total. It does not, however, explicitly name alternatives like cash_forecast or business_snapshot, so it stops short of giving full when-to-use/when-not-to-use 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?

The description extensively discloses behavioral traits beyond annotations: returns lag sales, gross figures exclude returns, settlement corrections are invisible, TikTok fees are booked later on a different date basis, and manual/non-channel sales are excluded. This goes far beyond the readOnlyHint 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 extremely long and dense. While it is well-structured with paragraphs and front-loaded with the core purpose, it contains many edge-case elaborations that could be condensed. It is not concise, but each sentence adds substantive detail, balancing thoroughness with 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?

Given the tool's complexity (multiple channels, returns, corrections, TikTok timing, and fee handling), the description is remarkably comprehensive. It covers all relevant edge cases, including returns-only channels, settlement corrections, and the TikTok date basis discrepancy, ensuring the agent has complete context.

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

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

The schema already defines from and to as dates with a pattern. The description only adds 'Give from and to as YYYY-MM-DD,' which redundantly repeats the pattern. Since the parameters are simple and fully defined by the schema, the description adds minimal semantic value beyond what is already structured.

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 reports sales broken down by channel with a specific list of metrics (order count, gross goods revenue, discounts, shipping, freight, marketplace fees, netProceeds). It distinctly differentiates from sibling tools like sales_summary by focusing on channel-level breakdown and specific accounting nuances.

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 clear context on when to use it (e.g., for channel breakdowns, date ranges) and important caveats like mentioning the month being read and not calling fees final until settlements. It doesn't explicitly name alternative tools, but the usage context is unambiguous given the sibling list.

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 read-only behavior, but the description adds extensive non-obvious semantics: open versus closed posting, immediate posting of creditSales, cash-only rounding, RM10,000 e-invoice splitting, and the not_available status for non-subscribers. Nothing contradicts the readOnlyHint 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 nearly every clause covers a distinct semantic risk: posting timing, credit-sales exception, rounding behavior, consolidated invoices, and add-on availability. The first sentence front-loads the tool's purpose, though the emphatic formatting and some repeated caveats keep it from being maximally concise.

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

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

Because there is no output schema, the description carries the full burden of explaining return values and field meanings. It covers statuses, saleId, creditSales, cashTotal, qrTotal, consolidation counts, and the paid-add-on not_available case, so an agent has enough context to interpret results and avoid misuse.

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 single optional date parameter with a pattern, timezone, and 'omit for today' instruction, so coverage is 100%. The description adds only 'default today, Malaysia time', which largely repeats the schema, so the baseline score of 3 is appropriate.

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

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

The description opens with a concrete scope: 'The Counter (Kaunter) till's day, for one date' and enumerates the returned metrics. It also distinguishes this tool from ledger-facing siblings by explaining that open-day figures are not yet in sales_summary, cash_position, 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?

It explicitly names sibling tools and gives the conditions under which this tool's figures do or do not align with them. It also tells the agent when the tool is the right source for till-level detail versus ledger reports, and warns against summing creditSales into the cash/QR totals.

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 annotations (readOnly=false, destructive=false), the description clearly states this tool does NOT post to the books and only creates a pending draft that the user reviews and approves. It also reveals side effects: the server recomputes quantities, the bill posts later, and attachments ride through to the posted bill.

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 dense and information-rich, but very long and repetitive in places, with full paragraphs in ALL CAPS and multiple restatements about due dates, attachments, and terms. It would be more concise if the most essential rules were front-loaded and the repeated cautionary detail trimmed, while still keeping the important edge cases.

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

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

Given the tool's complexity and the lack of an output schema, the description covers the full workflow: preparation, line semantics, term handling, review notes, attachment upload paths, size limits, sandbox fallback, and mutual exclusions. An agent has enough context to call the tool correctly and avoid the main failure modes.

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

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

The schema already carries detailed descriptions for many high-complexity parameters like term, dueDate, notes, and the attachment fields, and the description adds operational meaning on top of those. A few parameters such as vendorId, reference, and printedTotal receive no extra clarification beyond the schema, but the critical semantic traps are well covered.

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 verb and object: 'File a supplier-bill DRAFT into Taokeh from a bill you've read.' It immediately distinguishes this tool from create_expense_draft and the manual bill form, so an agent can tell when this is the right sibling to call.

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

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

The description gives explicit when-to-use guidance: inventory-only bills, not services/non-stock/mixed, and not already-paid ones (use create_expense_draft). It also prescribes a preparation pipeline (intake_contract, resolve_vendor, resolve_product), attachment handling, 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?

Annotations only set flags (readOnlyHint=false, etc.), but the description adds a rich behavioral contract: the image is REQUIRED and a draft without it is refused, blurry/two-person cards must set needsReview, bad files are rejected without filing, and the owner reviews before the contact is added. These details are not captured in structured 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 long but each sentence earns its place given the 16-parameter complexity. It is front-loaded with the purpose and required image, then systematically covers workflow, honesty rules, attachment methods, and party handling. It could be structured with bullets for readability, but the density is justified and logically ordered.

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 tool with 16 parameters and no output schema, the description covers all essential aspects: purpose, exclusions, behavioral requirements (image required, refusal, needsReview), parameter semantics (attachment options, defaults), and even post-call expectations (reporting fields back to the user). Nothing critical 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 schema coverage is 100%, the description adds crucial cross-parameter logic absent from the schema: mutual exclusivity of attachmentBase64 and attachmentToken, the role of attachmentBytes in rejecting truncated uploads, the default of partyKind to 'customer', and the purpose of partyName for existing companies. These are operational semantics that materially affect correct invocation.

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 clearly states 'File a pending CONTACT draft from a business card YOU have read,' naming the specific resource (contact draft) and verb (file). It explicitly contrasts with adding to the address book, distinguishing it from sibling draft tools like create_invoice_draft and clearly setting its scope.

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 explains the primary use case (when you have read a business card image) and states what it does NOT do ('This does NOT add anyone to the address book'), providing a clear exclusion. It also routes the agent to request_attachment_upload for large images or PDFs, with an explicit 'never both' rule, giving concrete alternative paths.

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 all-false annotations, the description discloses crucial behavioral traits: the tool does NOT post to the books, it creates a pending draft that a human reviews/approves; only after approval does it reduce balance, reverse revenue/SST, and restock. It reveals that Taokeh stores amounts negative internally so the caller must send positives, that over-quantity lines are refused with a message naming the remaining available quantity, that goodsReturned only pre-ticks a checkbox and never decides stock movement, and that needsReview should be set with a short note. No annotation contradiction exists — readOnlyHint=false is consistent with a draft-creating write operation.

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 carries operational safety value for a financially high-stakes document type. It is front-loaded with the core purpose and the critical 'does NOT post to the books' caveat. It loses one point for being somewhat stream-of-consciousness — the allowance-vs-invoice rules, voiding guidance, and correction guidance could be grouped more tightly — yet the density of irreplaceable information justifies most of its 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?

For a 13-parameter financial tool with no output schema and all-false annotations, the description is exceptionally complete: it covers both kind variants and their constraints, the approval/side-effect model, amount sign conventions, quantity limits, the goodsReturned advisory semantics, reviewer-note expectations, and the full decision tree for when a credit note is the wrong document. The only minor gap is that it never states what the tool returns on success (draft id?), but given the emphasis on downstream human approval and revision paths, this does not materially impair an agent's ability to invoke and follow up 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?

At 77% schema coverage, the description still adds substantial meaning beyond the schema: kind is given a decision rule ('when it isn't clear, ask the user which invoice it is against'), originalDocId is tied to a resolution workflow (search_documents), quantity is constrained by what the invoice actually sold net of prior credit notes with an example warning against unit conversion, and goodsReturned/notes semantics are sharpened beyond their schema text. The description compensates for the uncovered parameters and enriches the covered ones.

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 names a specific verb (File), a specific resource (a CREDIT NOTE draft into Taokeh), and the document's financial meaning (sales return, short delivery, price correction, or allowance that reduces what a customer owes). It also distinguishes the tool from its siblings by explaining what it is NOT: not a voided invoice, not an invoice correction (update_invoice_draft), not a re-filing (revise_draft). An agent can tell exactly what this tool does without 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?

The description gives explicit when-to-use guidance: a credit note is right only when something changed AFTER the sale. It names the alternatives with conditions — owner voids the invoice if the sale never happened, update_invoice_draft if the invoice was typed wrong, revise_draft if the draft was filed wrong — and even notes there is 'deliberately no AI lane for voiding'. It also instructs to shape fields with intake_contract and resolve the original invoice with search_documents first, making the invocation workflow 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?

Given the annotations are all false/neutral, the description carries the full burden. It discloses key behaviors: creates a pending draft, not posted to books; requires an original invoice; money-only with no stock/COGS effects; no cap on charge; server validation; and why the review screen shows the original total.

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 highly structured and information-dense. Each sentence serves a purpose, clarifying complex domain rules. Slightly verbose, but appropriate for the complexity of the financial document.

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 the tool's purpose, prerequisites, limitations, review workflow, and parameter nuances comprehensively. However, it does not describe the return value/output, which would be helpful since there is no output schema. Otherwise, it is nearly 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?

Schema coverage is high (73%), but the description adds crucial semantics beyond the schema, such as unitAmount being the 'additional' amount not the new price, quantity defaulting to 1, and originalDocId requirements. This enhances the parameter understanding beyond the schema alone.

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

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

The description clearly states the tool's purpose: filing a SELL-SIDE DEBIT NOTE draft, an additional charge on an existing invoice. It explicitly contrasts this with credit notes, new invoices, and buy-side debit notes, making it easily distinguishable from 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 provides explicit when-to-use and when-not-to-use guidance, including alternatives like create_invoice_draft for extra goods or new invoices, revise_draft for corrections, and clarifies the sell-side vs buy-side distinction. This is exemplary.

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

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

Annotations only say this is a non-read, non-idempotent write; the description enriches that with the exact side-effect shape: it creates a pending review draft that does not hit the ledger until user approval, and the attachment rides through to the posted entry. It also discloses rejection semantics (truncated base64 and bad/oversize files are rejected, nothing filed) and the shoebox-item lifecycle (approval closes the item). 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 every sentence carries a decision-relevant instruction — no filler. It is front-loaded with the core purpose and flows logically from draft lifecycle to field shaping to the attachment decision tree.

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

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

For an 18-parameter tool with no output schema and minimal annotations, this is remarkably complete: it covers prerequisites, the staged approval lifecycle, failure modes, shoebox-item interaction, and all attachment alternatives. The only thing unspecified is the response shape, which is a minor gap given the depth elsewhere.

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%, so the description must compensate, and it does: it defines when amountUncertain should be true, how to write a SHORT reviewer note, and the three-way attachment routing with mutual-exclusion rules. It deliberately delegates account-code semantics to intake_contract, which is a reasonable design choice rather than a gap.

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

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

The first sentence names a specific verb and resource ('File a paid-expense DRAFT into Taokeh from a receipt you've read'), which immediately scopes it away from the many sibling draft creators (create_bill_draft, create_invoice_draft, create_receipt_draft). The draft-vs-posted distinction further pins down what the tool uniquely does.

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

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

The description gives explicit prerequisites ('Shape the fields with intake_contract + expense_accounts first'), precise trigger conditions for amountUncertain and needsReview, and a full decision tree for attachments — small files inline, big files via request_attachment_upload, and a sandbox fallback. It even states the negative rule ('never both'), so the agent knows what to avoid.

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 carry only readOnly=false / idempotent=false, so the burden falls on the description, and it exceeds it: the server re-computes line quantities and the grand total (with SST) and its figures are authoritative; a quantity sent alongside a parseable tally is advisory and shown beside the server's; truncation protection (attachmentBytes rejects a truncated base64); already-booked shoebox items are refused with a reason; confirmNewCustomer skips the near-miss guard; and approval closes the shoebox item and lands the attachment on the posted invoice. No statement contradicts 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 by absolute measure, but each block conveys non-obvious operational truth (failed-upload semantics, reviewer-note length guidance, sandbox fallback, s.82 record-keeping rationale) that an agent cannot infer from the schema. It is front-loaded with the core purpose and no-posting caveat. It is not a single crisp paragraph, so it sacrifices some readability, but the density is earned for a 20-param, compliance-sensitive mutation.

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 20 params, the description covers the success model (pending draft the user reviews and approves, only then posting and moving stock), failure modes (truncated base64 rejected, oversized/bad-type file rejected and nothing filed, shoebox item refused if already booked/set aside), and the complete attachment decision matrix including the allowlist sandbox case. The gaps are modest: the return shape of a successful call is not described, and a few params (printedTotal, working, customer/customerId) remain unexplained.

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 60%, so the description must compensate, and it does for the highest-stakes params: quantity (omit on measurement-profile, advisory vs authoritative), term (verbatim, don't round to familiar terms), dueDate (derivation from preset terms, no deriivation for unknown terms), attachment fields (exclusive, size rules, mutual exclusion), shoeboxItemId semantics, and confirmNewCustomer guard. Gaps remain for working, printedTotal, and customer/customerId, which gain no meaning beyond their bare names in either schema or 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 starts with a specific verb-resource pair: 'File a sales-invoice DRAFT into Taokeh from a sales note you've read', which uniquely identifies the tool versus siblings like create_bill_draft or create_redit_note_draft. It immediately adds the bordering caveat ('This does NOT post to the books') that distinguishes the draft-filing action from a final booking. This is about as distinct a purpose statement as the domain allows.

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 workflow preguisites ('Shape the fields with intake_contract(doc_type:'invoice') + resolve_customer + resolve_product first') and explicit conditional routing for the attachment dimension: inline for small files, request_attachment_upload for real photos/PDFs, sandbyox fallback when the shell cannot reach taokeh.my, and shoeboxItemId instead of any upload. What is missing is an explicit 'use create_redit_note_draft when...'-style exclusion naming sibling draft tools, so this earns 4 rather than 5.

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

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

Annotations only supply shallow signals (readOnlyHint=false, destructiveHint=false, etc.), and the description adds rich behavioral truth far beyond them: the draft does NOT post to the books, an unbalanced entry is refused with the difference named, an unknown account ref is refused, and 'THIS TOOL NEVER CREATES AN ACCOUNT'. It also discloses the deliberate never-edit/never-delete posted history policy and the approval restriction for flagged control accounts - exactly the behavioral context an agent needs and annotations cannot 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 structured into clearly distinct concerns - non-posting behavior, balance rule, account matching, reversing workflow, control accounts, exclusions, attachments - with the core purpose front-loaded in the first sentence. Every paragraph addresses a failure mode or policy constraint an agent would otherwise encounter; only the ledger-integrity philosophy explanation runs slightly long.

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 13-parameter accounting tool with no output schema, the description covers the full decision surface: what it files, what it refuses, how approval works, integration with intake_contract/search_journal/revise_draft/request_attachment_upload, and edge cases (truncated attachments, ambiguous account names, unreachable host). Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 85%, so the baseline is 3 and the schema already documents each parameter thoroughly. The description adds decision heuristics beyond the schema: the attachmentToken-vs-attachmentBase64 choice ('Prefer request_attachment_upload... if your shell cannot reach taokeh.my'), the rule that attachmentBytes must always accompany base64 to reject truncated pastes, and guidance on what `notes` should contain for control lines and doubts.

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

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

States a specific verb and resource: 'File an ADJUSTING JOURNAL ENTRY as a draft', and immediately carves out the core differentiator: 'the accountant's entry, not a document'. It also enumerates the exact use cases (accruals, prepayments, depreciation, corrections, reclassifications, year-end, reversing entries), leaving no ambiguity about what this tool is for.

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 an explicit 'WHAT NOT TO USE THIS FOR' section that names the exact sibling to pick instead: create_bill_draft, create_invoice_draft, create_expense_draft, create_receipt_draft. It also chains the workflow instruction - use intake_contract for the chart of accounts, search_journal to locate a posted error, revise_draft to fix a wrongly filed draft - so the agent knows exactly when this tool is and is not the right call.

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

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

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?

The description goes far beyond the annotations by disclosing concrete side effects and non-effects: no journal entry, no stock movement, no amount owing, no email to the supplier, approval only saves a draft, and the server recomputes quantities authoritatively. It also claries that no SST or tax line exists on the purchase order.

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 well-structured: it opens with the core definition, then states non-effects, exclusions, preparation steps, server authority, and error-recovery routing. Every sentence carries a distinct constraint or decision rule without redundant filler.

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

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

Given 11 parameters, no output schema, and a large sibling set, the description covers what to send, how to prepare the data, what the user must still do, what the server will override, and which alternative tool to use fpr different situations. An agent has enough to call 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?

With schema coverage at only 45%, the description compensates substantially. It explains the reference field as the buyer's own PO number rather than the supplier quotation, dictates the length and purpose of notes, explains needsReview, describes how quantity is either derived from tally or treated as advisory, and tells the agent to omit expectedDate rather than guess.

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 action: 'File a PURCHASE-ORDER draft into Taokeh', and immediately explains what that means — an intent to place with a supplier. It distinguishes this from a bill by explicitly saying it posts nothing and moves nothing, and from create_bill_draft by noting arrived goods belong to that 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?

Gives explicit routing rules: use revise_draft if filed wrong, use create_bill_draft if goods have already arrived, and use the manual purchase-order form for non-stock items. It also directs the agent to prepare fields with intake_contract, resolve_vendor, and resolve_product first.

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 (all hints false), so the description carries the behavioral burden and does so thoroughly. It discloses mutation semantics (creates a pending draft, does not post to books), server-side recomputation of quantities and totals, authoritative server figures, rejection of truncated base64, and the near-miss guard behavior for confirmNewCustomer. No contradiction with annotations exists.

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

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

Although the description is long, it is densely informative and front-loaded with the core purpose. Every major clause covers a distinct operational concern: workflow, authoritative computation, reviewer notes, attachment size paths, and sandbox fallback. The structure flows naturally from definition to process to edge cases, and there is no filler.

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

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

For a 17-parameter mutation tool with no output schema and minimal annotations, the description is exceptionally complete. It covers the full lifecycle, customerless quotes, measurement-profile quantity derivation, reviewer note style, attachment upload alternatives, and failure modes. An agent has enough context to call the tool correctly and to route around exceptional cases.

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 59% schema coverage, the description substantially compensates for the uncovered parameters. It explains the practical meaning of quantity vs tally/thickness/width, the role of needsReview and notes, the attachment token/base64/bytes relationship, and the confirmNewCustomer guard. This goes well beyond the schema by explaining why and how parameters interact.

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 quotation DRAFT into Taokeh'. It clearly distinguishes a quote draft from a posted quotation, invoice, or delivery order by stating it is an estimate and does not post to the books or move stock. This effectively differentiates it from sibling draft tools like 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 workflow direction: resolve_customer and resolve_product first, set needsReview for doubt, and keep reviewer notes short. It also provides concrete alternative routing for attachments—inline base64 for small files vs request_attachment_upload for large ones—and states when to inline despite the sandbox restriction. This is strong when-to-use guidance tied to real conditions.

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?

While annotations only hint at write behavior (readOnlyHint=false), the description discloses critical behavioral traits: it does not post immediately, the server re-derives allocation against live outstanding, attachmentBytes prevents truncated-file acceptance, and attachmentToken vs attachmentBase64 are mutually exclusive. It also states that store of proof rides the draft to settlement. These go well beyond annotation coverage and set accurate 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 intentionally so—given the complexity of 15 parameters and multi-step attachment logic. It is front-loaded with the core purpose and workflow, then methodically covers allocation and attachment rules. Each sentence adds substantive guidance; no filler. The length is justified given the tool's intricacy.

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 15 parameters, no output schema, and complex behaviors (allocation, attachment transport, reviewer notes), the description is thorough. It covers prerequisites (customer resolution, open_invoices), decision points (total vs allocations), exception handling (foreign currency, network limits), and security details (attachmentBytes for truncation). An agent has everything needed to invoke it correctly.

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

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

Schema coverage is only 47%, so the description must compensate—and it does extensively. It explains the semantics and interplay of total vs allocations, needsReview, notes, and all attachment-related parameters (base64, token, bytes, sha256, mediaType, filename). It clarifies when each attachment method is appropriate and the role of attachmentBytes in detecting truncation. This far exceeds 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 states a specific verb ('File') and resource ('customer-payment DRAFT'), and clarifies it does NOT post but creates a pending draft for user review. It explicitly outlines the workflow (resolve customer, see open invoices, then submit total or allocations). This clearly distinguishes it from sibling draft tools (e.g., create_invoice_draft, create_bill_draft) by emphasizing the receipt-settlement 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 provides explicit when-to-use instructions: resolve the customer first, check open invoices, then choose either a lump total or per-invoice allocations. It also names alternatives (request_attachment_upload for large files) and gives routing guidance for foreign-currency invoices (refused, route to Banking → Payments). It even specifies conditions for when to inline vs. out-of-band attachment, including network limitations.

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 non-readOnly and destructive, so the draft-not-created nuance adds real behavioral context beyond the schema, including that the owner's tap is what saves the schedule. The description also reveals that issueMode auto is blocked and that first-issue date is derived and shown on the review page, which is valuable. It stops short of detailing failure modes or rate limits, but for a draft-creation tool the main consequences are well covered.

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 earns its place: it front-loads the draft-only warning, explains the schedule concept, maps the key parameters, lists prohibitions, and closes with an honest-use directive. It is arguably verbose, but the density of operational cautions justifies the length for a high-stakes billing tool.

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

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

With no output schema and annotations that don't clarify side effects, the description carries the burden of explaining what happens after invocation—the draft goes to a human review page—and what the agent must not do. Missing an explicit statement of what a successful response contains, but for a draft-filing tool the workflow and constraints are complete enough to invoke it correctly.

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

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

Schema coverage is 91% and the schema already documents most parameters, but the description adds essential semantics: customer must exist exactly, lines must be real catalogue products, startDate day becomes billing anchor with month-end handling, and paymentMethod books differently. It reinforces the meaning of maxOccurrences and endDate indirectly, but relies on the schema for remaining details, hence not a 5.

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

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

The description opens with a clear, emphatic statement that this tool files a pending draft only and creates nothing until human approval, and it names the resource (recurring invoice draft) with the specific verb 'file'. It further differentiates from siblings like create_invoice_draft and update_recurring_invoice_draft by explaining that this proposes a new billing schedule, so an agent can select it confidently.

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 guidance: use it to propose recurring invoices (with retainer/subscription/rent examples), and it explicitly says what it cannot do (set issueMode auto, set MFRS 15 recognition, set next issue date directly). It also tells the agent to ask rather than guess when paymentMethod or prices/dates are uncertain, effectively defining when not to invoke the 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?

The description claims the tool is a read operation ('single read') and a pure aggregation, while the annotations include `readOnlyHint: false`. This is a direct contradiction: the agent cannot rely on the description's implicit read-only promise and the annotation's mutability signal. Rule scores this 1 because the description contradicts the structured 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, with extensive parentheticals about cash semantics and approval counting. All the details are load-bearing and the main purpose is front-loaded ('Your morning brief in one call'). The sentence structure is somewhat heavy, but it is far from tautological: it earns its 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?

There is no output schema, so the description carries the burden of understanding the response. It does well for the cash fields and approvals (defining `cash.total`, `cash.ownerFunding`, `cash.cards`, and `approvals.total` with careful liability and count semantics). However, some high-level outputs (tax position, low stock, overdue bucket details) are only named, not explained, making it slightly incomplete as an output 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?

There are zero input parameters, so there is no parameter semantics description needed to fill in; the baseline for a parameterless tool is 4. The description correctly spends no space on parameters and focuses instead on what the tool returns.

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

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

The description uses a specific, comprehensible framing: 'Your morning brief in one call' and enumerates exactly what the tool surfaces: sales/expenses, cash position, debtors, approvals, tax and low stock. It also names the sibling tools's individual reads it aggregates, which distinguishes it from business_snapshot, cash_position, ar_aging, tax_position, and 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?

The description clearly establishes the intended use case: a one-call morning brief, contrasted with individual tools via 'Assembles the same figures as the individual tools' and 'brief me is a single read.' It does not explicitly provide a 'when not to use' list or direct the agent to a more specific sibling for deeper drill-down, keeping this at a 4 rather than 5.

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

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

Annotations are bare (all false flags), so the description carries the full burden, and it delivers: every line is a pre-fill suggestion the owner must approve; invalid rows are rejected with named corrective data; stale allocations fill in nothing rather than a stale figure. Safety-relevant behaviors are stated explicitly and repeatedly ('never posts to the ledger', 'the one-tap Accept never applies'), consistent with readOnlyHint=false since it writes suggestions.

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?

Every sentence carries substantive constraint information and the core purpose is front-loaded, but the ~850-word description is one unbroken paragraph with no hierarchy. The 'it never posts / owner decides' point is restated at least four times, and the standing-rule caveat is buried at the end, so an agent must parse a dense wall of text to find critical rules.

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

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

For a tool with six nested fields, intricate category-dependent conditionals, currency rules, and reference-data dependencies, nearly everything an agent needs is stated: ID source, valid category set, contact matching, the CARD_PAYMENT exception, allocation math with tolerance, and failure reporting ('Per-row outcomes are reported — nothing is silently skipped'). The only minor omission is the exact shape of the per-row outcome report, which the no-output-schema setup leaves the agent to infer.

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 there are no per-property descriptions, so the description must supply all semantics — and it does, exhaustively: category must come from the review screen's set; contactName must match an existing contact exactly; accountCode is accepted only for OTHER/INTERNAL_TRANSFER and required for CARD_PAYMENT; allocations are limited to 20 items, only with contactName, in Ringgit, summing to the line within 0.10. It also encodes cross-field invariants the schema cannot express, such as the currency and outstanding-balance rules.

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 — 'Propose a category (and optionally a contact) for up to 50 imported bank rows still waiting for review' — and names bank_review_queue as the ID source. The PROPOSALS ONLY framing ('never confirms, never posts, nothing you send here moves money') cleanly separates this from the create_*_draft siblings that actually create 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?

Gives explicit when-to-use (rows still waiting for review, IDs from bank_review_queue) and when-not (already-decided CONFIRMED/POSTED/IGNORED rows are rejected). It names reference siblings as data sources — expense_accounts for the chart, open_invoices / ap_aging for open documents — and the standing-rule caveat tells the agent how to behave when the owner already has a rule.

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 stating it is READ-ONLY, creates/hires/files nothing, and is ADMIN ONLY. It discloses assumptions, defaults, that every assumption must be repeated to the user, and that the result is an estimate on stated assumptions. This is rich 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 dense and informative, but it is a single wall of text with long parentheticals and a very specific tax-authority reference. The main purpose is front-loaded, yet structure could be improved with clearer separation of purpose, parameters, defaults, and warnings.

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 no output schema, the description clearly indicates what the tool returns and under what assumptions. It covers defaults, key optional parameters, admin/read-only behavior, and the estimate nature. The main missing piece is `epfEmployeeRate`, which prevents full completeness.

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 burden. It explains monthlyWage, residency, citizenship, and ageBand reasonably well, but it does not explain the `epfEmployeeRate` parameter at all—its units, default, or effect. This is a notable gap for an optional parameter that an agent might need to 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 immediately identifies the operation: cost a HYPOTHETICAL hire from a monthly wage, returning real employer cost and employee take-home. It names the specific payroll components and gives concrete example questions, making the tool's purpose unmistakable and distinct from actual payroll or document tools.

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

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

It explicitly says 'Use it for...' with concrete scenarios, and it provides when-not guidance ('never as a quote or as tax advice'). It also clarifies optional inputs like residency and citizenship, including when to set both. This is strong usage direction for an agent.

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

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

Annotations already convey readOnlyHint=true, and the description aligns with that by presenting this as a lookup/selection tool. It adds useful context about the returned data (categories, paid-from accounts, codes) and the company-specific scope, which is valuable given there is no output schema.

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

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

A single sentence that front-loads the core identity ('The expense accounts you can post to in this company') and then elaborates with the precise selection information. Everything present earns its place, with no filler or redundancy.

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

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

For a zero-parameter, no-output-schema tool, this description is complete. It states what the tool returns (company postable expense accounts), what fields are available (category, paid-from, code), and the intended workflow (shaping a paid-expense draft).

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 baseline is 4. The description's mention of picking a category and paid-from account by code refers to the output content rather than input parameters, which is consistent with 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 clearly identifies the resource: a list of expense accounts available for posting in this company. It specifies what can be picked (category and paid-from account) and by what identifier (code), distinguishing it from sibling tools like create_expense_draft or expenses_summary.

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 provides a clear usage context: 'for shaping a paid-expense draft' tells an agent when to use this tool. However, it does not explicitly name alternatives or exclusion conditions, so it does not fully route the agent away from similar expense-related tools.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the read-only nature is known. The description adds useful context by specifying that only paid expenses are included and defining the time periods (today and month-to-date). It does not mention return format or any aggregation behavior, but that is less critical with annotations present.

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

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

A single, front-loaded sentence conveys the purpose without any wasted words. It is appropriately concise for a simple zero-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 simple read-only summary tool with no parameters and no output schema, the description is reasonably complete. It covers the subject (paid expenses) and time range (today and month), though it leaves ambiguous whether the response is one total or two separate figures. This is a minor gap given the tool's simplicity.

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 the schema is an empty object with 100% coverage. Per guidelines, the baseline for 0 params is 4, and the description does not need to add parameter details. It adds meaning by indicating the nature of the summary.

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 reports how much the user has spent, specifically on paid expenses today and this month to date. It distinguishes from siblings like sales_summary and expense_accounts by mentioning 'paid expenses' and time ranges, though it lacks an explicit verb like 'get' or 'list'.

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 when the user wants a quick view of paid expenses for today and this month. It does not explicitly state when to use this tool versus alternatives such as search_expenses or expense_accounts, nor does it mention exclusions or prerequisites.

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?

Annotations already declare readOnlyHint=true, and the description reinforces and extends this: 'It GUIDES to the UI only — it changes nothing: no setting is ever toggled by the connector.' It also discloses a critical failure mode: record-like queries will still rank a page and thus produce a plausible but wrong answer. This is valuable behavioral context beyond the annotations. 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?

The description is front-loaded with the most important distinction and every section adds useful information. However, it is quite long, with some repetition (e.g., 'never the books' and later 'does NOT look up documents'), and the vivid 'wrong answer wearing a right one's clothes' phrasing is stylistic rather than essential. Still, the length is largely justified by the high risk of misuse.

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 thoroughly documents the return shape: ranked feature matches with exact deep-link URLs, one-line descriptions, configHint, and addOn flag. It covers failure behavior, scope limits, alternatives, and the safety guarantee. An agent has everything needed 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 schema already provides 100% coverage for the single `query` parameter with a clear description. The tool description adds extra semantic guidance: it gives concrete examples ('how do I connect Shopee'), reiterates what not to type, and explains how the query is used to rank features. This goes beyond the schema description, though the schema already does substantial work.

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 FEATURE FINDER, NOT A RECORD SEARCH.' It names the exact resource (Taokeh's screens, features, settings), the action (find/guide to UI), and explicitly distinguishes itself from record-search tools. This fully separates it from 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 gives explicit when-to-use guidance (capability questions like 'where do I turn on payment reminders') and when-not-to-use guidance (records, document numbers, customer names). It names direct alternatives: search_documents, search_expenses, search_journal, resolve_customer/vendor/product, and open_invoices. It also provides 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?

Beyond the readOnlyHint annotation, the description discloses the signed URL expiry and sharing properties, that bytes are never inlined (with token-cost rationale), that Taokeh does not OCR or interpret the file, and that the operation has no side effects. It also confirms there is no contradiction with 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 core purpose and usage are front-loaded, and each sentence carries real information. The description is somewhat long for a simple read-only link tool, with a few rhetorical embellishments, but the length is justified by the many owner varieties and edge cases.

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 covers the return contract (signed URL, filename, media type, size, no inline bytes), security posture, owner/draft edge cases, and read-only behavior. An agent has all information 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?

Although schema coverage is 100%, the description adds crucial semantic detail: how to obtain the owner/id values from prior tool results, when attachmentId must be supplied, and when it must be omitted. This goes well beyond the schema's enum and type 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 states the tool gets a short-lived link to the ORIGINAL DOCUMENT filed against an expense or draft, which is a precise verb+resource. It also clarifies what counts as a document in each state, distinguishing the lookup target from other operations like get_document_pdf.

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 it ('CHECK a document is on file, or re-read one you filed earlier'), where to find the required ids (search_expenses and create_*_draft/revise_draft results), and when not to ('An APPROVED draft honestly reports no original... ask for it there instead'). This is clear routing guidance with no reliance on inference.

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

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

The description adds rich behavioral context beyond the readOnlyHint annotation: the returned URL is short-lived (~15 minutes), shared-access means anyone with it can use it, and sharing should be deliberate. It also discloses that multiple matches will be listed for the user to pick, and clarifies that this tool does not send emails. 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 front-loaded with the core purpose, then systematically covers identification, return value, expiry, scope, and non-email behavior. Every sentence adds relevant information, and the structure makes the tool's behavior easy to parse for an agent.

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 carries the full burden of explaining return values, and it does so explicitly: the signed URL, the document number, and expiration time are all mentioned. It also covers document coverage and disambiguation behavior, making the tool's behavior complete for an agent invoking 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?

With 100% schema description coverage, the schema already documents all three parameters clearly. The description reinforces the relationship between docId and docNumber ('give one') but does not add significant new semantics beyond what the schema provides. This meets the baseline but does not exceed it.

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: 'Get a shareable link to the ACTUAL PDF of one invoice, quote or credit note'. It clearly distinguishes the tool from generic document tools by emphasizing the real PDF artifact and explicitly noting it does not email anyone. This makes the purpose unmistakable.

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 clear when-to-use context: when you need to hand the user or their customer the actual document. It explains the two identification paths (docId from search_documents or printed docNumber) and the disambiguation behavior if multiple matches occur. It stops short of explicitly naming alternative tools for when not to use it, but the guidance is still 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?

The description adds substantial behavioral context beyond the annotations: it clarifies that nothing posts to the books, that the server validates opening balance plus rows against closing balance and rejects with the exact delta, that a wrong signConvention can pass arithmetic but fail a directional check, and that the card settlement line is excluded automatically. It also details attachment archiving behavior and idempotent adoption on identical re-import. 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 every substantial section earns its place: overview, credit-card convention warning, and archiving workflow. It is front-loaded with the core behavior, then organized into distinct paragraphs that group related warnings and operational steps. The length is justified by the high-risk failure modes and the number of parameters.

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 and no output schema, the description is remarkably complete: it covers prerequisites, arithmetic validation, sign-convention directional checks, per-line expensing behavior, attachment upload flow, and the re-import adoption path. A return-shape specification would be a nice addition, but the operational context needed to invoke this tool correctly is fully present.

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 schema coverage is 69%, the description adds essential meaning for the most nuanced parameters: signConvention is explained with two concrete interpretations and the refusal rule for bank accounts, attachmentToken and attachmentBase64 are positioned with mutual exclusivity and practical guidance, and rows are defined as signed amounts. This goes well beyond what the schema 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?

The description opens with a specific verb and resource: 'Import a bank statement into Taokeh for reconciliation.' It clearly scopes the tool to statement imports that land in Banking → Review, and explicitly contrasts it with sibling doors: 'Single receipts, invoices or bills go through their own draft doors, not here.' This makes it easy to distinguish from create_bill_draft, create_invoice_draft, and other 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?

The description gives explicit usage prerequisites: 'use intake_contract(doc_type:''statement'') first to see the tenant's bank accounts + the arithmetic law.' It also states when not to use the tool, names alternative doors for other documents, and explains the re-import workflow for adopting an attachment onto an already filed statement. This is concrete, actionable routing guidance.

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

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

Annotations already indicate read-only, but the description adds substantial behavioral context beyond that: it explains that comparison returns deltaCents and deltaPct computed server-side, details about deltaPct being NULL when the earlier figure is zero, how percentages are measured, and the structure of the `windows` and `notes` fields. 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 front-loaded with the core purpose in the first sentence. Every subsequent sentence earns its place by explaining comparison behavior, return fields, and edge cases. Despite being longer, the structure is logical and all content is necessary for correct tool usage.

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 5 parameters (2 required), no output schema, and moderate complexity, the description provides complete coverage. It explains the output structure (deltaCents, deltaPct, windows, notes), handles edge cases (NULL deltaPct, unequal window lengths), and gives usage instructions. No gaps are apparent.

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 60% schema description coverage, the description adds significant meaning to all five parameters. It explains the purpose of `from` and `to` as the primary period, details the `compare` enum options with clear definitions, and explicitly states that `compareFrom`/`compareEnd` must be used together and override `compare`. This fully compensates for schema gaps.

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

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

The description clearly states it provides profit and loss for a period, listing major line items (revenue, COGS, gross profit, expenses, net income). This distinguishes it from sibling tools like balance_sheet or cash_forecast by specifying the exact financial statement. The verb 'your profit and loss' is specific and the resource is well-defined.

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 comparison feature and, crucially, tells the agent NEVER to call the tool twice and subtract manually. It provides clear instructions on setting the `compare` parameter or using explicit `compareFrom`/`compareEnd`. It also warns to read `notes` before quoting a variance and explains how to handle unequal length windows.

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. The description adds behavioral context beyond that: users review everything in Taokeh, employees is admin-only, and settings includes owner-only values the AI may never write. It does not mention output shape or potential size/performance, but for a reference tool this is solid.

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 information-dense and front-loaded with the core purpose. Each section earns its place: required fields, doc_type categories, staging functions, ordering, permissions, and non-posting behavior. It is not redundant, though the long doc_type list could arguably be trimmed for conciseness without losing much value.

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 simple schema (one optional parameter), no output schema, and read-only annotations, the description covers everything needed: what the contract contains, the full set of doc_type values, how each is staged, ordering constraints, permission caveats, and the non-posting guarantee. It is complete for an agent to select and invoke the tool appropriately.

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 burden. It enumerates all valid doc_type values and explains their meaning, including special categories for opening balances and master data, plus the associated staging functions. It does not explicitly state that doc_type is a string, but it fully describes the accepted values and their 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 what intake_contract does: it returns the shape a Taokeh document needs, listing supported doc_type values, the intended source documents, and how the contract maps to staging functions. It distinguishes itself from sibling draft/staging tools by framing this as a reference/contract tool, not an execution 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 explicitly explains when to use this tool: before staging documents, opening balances, or master data. It gives specific doc_type values, instructs to do 'accounts' first, notes the employees contract is admin-only, and says nothing posts on its own. This is strong, actionable guidance that clearly routes the agent to the correct usage.

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 adds substantial behavioral detail beyond that: results are capped but include the true count, the matching rule matches the dashboard chip, and Counter quantities are as at day-close so an open trading day overstates shelf stock. 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 compact yet complete: purpose, row shape, cap behavior, matching rule, and a critical timing caveat are each given in one well-placed sentence. No filler or repetition.

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 return values, and it does: it lists the fields per row, states that results are capped with a true count, and clarifies the reorder rule and Counter timing. This is sufficient for an agent to know what to expect and how to interpret the data.

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 coverage is 100% by virtue of an empty schema, so the baseline is 4. There is no parameter-level information to add, and the description appropriately focuses on outputs and behavior instead.

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

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

The description opens with a precise verb and resource: 'Which products are at or below their reorder point right now' and labels it the 'what do I need to reorder' list. It further specifies the exact filtering rule and output fields, distinguishing it clearly from siblings like stock_level and stock_movements.

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 contextual cues: it is a current reorder snapshot, capped with a true count, and aligned with the dashboard low-stock chip. It explains the Counter day-close timing caveat that affects interpretation. It does not explicitly name alternatives or state when not to use it, but the context is clear enough for an agent to select it appropriately.

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

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

The description explicitly claims "READ-ONLY. It changes nothing," but the annotations set readOnlyHint to false. This is a direct contradiction between the descriptive text and structured metadata. Per the rubric, a contradiction forces a score of 1, despite the description otherwise containing rich behavioral detail.

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 core purpose and uses numbered sections, which is good structure. However, it is verbose and repetitive, repeating the read-only point multiple times ("READ-ONLY", "It changes nothing", "it cannot approve anything", "no tool can approve on the owner's behalf"). It would benefit from tightening.

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 no output schema, the description thoroughly explains what will be returned in each bucket: pending items with reference, party, amount, wait time, next step, and review link; approved items with the resulting posted document reference; rejected items with verbatim reasons and `reasonRecorded` semantics; and staged migration work. It leaves no critical operational 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?

With 0% schema description coverage, the description fully compensates: it specifies `since` as YYYY-MM-DD or ISO with a 7-day default, `kind` as an optional single-lane filter, and `limit` with default 50, max 200, and honest truncation behavior. It adds practical meaning that the sparse schema alone 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?

The description opens with a specific, concrete purpose: "YOUR OWN QUEUE in this company, in one call — what you filed and what happened to it." It enumerates four distinct status questions (PENDING, APPROVED, REJECTED, STAGED), making the tool's role unmistakable and distinguishing it from sibling report/review tools.

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

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

It gives clear context for when to use the tool: the user wants one consolidated view of their own filed items across all lanes, including approvals since a date and migration items. It does not explicitly name alternatives or exclusion conditions (e.g., 'use bank_review_queue instead when...'), 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?

readOnlyHint=true already signals a safe read operation. The description adds that results are unpaid/part-paid, oldest first, and filtered by customer name. It does not describe returned fields, but with annotations covering safety, this is acceptable.

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, front-loaded sentence with no filler. Every phrase adds value: unpaid/part-paid, one customer, oldest first, search by name.

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 simple one-parameter, read-only tool with no output schema, the description sufficiently covers scope, ordering, and search key. It does not enumerate return fields, which might be useful but is not critical for tool selection.

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 zero description coverage for the single 'customer' parameter. The description compensates by explaining it is a customer name, which is essential for correct invocation and adds meaning beyond the raw schema 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?

The description clearly states it returns unpaid/part-paid invoices for a single customer, ordered oldest first, searchable by customer name. This distinguishes it from aggregate tools like 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?

The description implies use when needing open invoices for one customer and specifies search by customer name. It does not explicitly name alternative tools or exclusion scenarios, but the scope is clearly constrained to a single customer, providing adequate context.

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 explains the non-obvious behavioral distinction between LEARNED and OVERRIDE bases, what timesSeen and ruleSetOn mean, and explicitly warns not to report an override as history. This is exactly the kind of subtle behavioral context an agent needs to avoid misreporting 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 long but information-dense, and every clause contributes to understanding a genuinely complex return value. It front-loads the core purpose and then unpacks the LEARNED/OVERRIDE semantics, with the warning placed near the end for emphasis. Slightly verbose, but earned.

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

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

There is no output schema, so the description fully compensates by specifying the grouping fields, aggregates, basis values, timesSeen, ruleSetOn, and the tenant-scoped nature. It also includes the critical caveat about overrides, making the tool safely invokable and interpretable without additional context.

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

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

With 0% schema description coverage, the description carries the parameter burden and delivers: counterparty is defined as a payer or payee named as printed on the statement line. This is more meaningful than the raw schema's minLength constraint, though it could add a bit more on matching or formatting expectations.

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 what the tool returns: historical confirmed/posted bank rows for a counterparty, grouped by category/contact/GL account, plus the live Taokeh suggestion with its basis. This distinguishes it from sibling tools like resolve_vendor or search_document_lines because it centers on precedent for categorization, not entity resolution or document search.

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 states its intended use: it is the tenant-scoped precedent behind a suggestion, so an agent can explain WHY a row is categorized a certain way. It gives clear context, but does not explicitly name alternatives or state when not to use it, so it stops 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?

The readOnlyHint is reinforced and expanded: the tool 'cannot create a run, pay anybody, or file anything.' It also discloses behavioral edge cases: it reads the latest FINALIZED or POSTED run, returns a plain statement if nothing has been run rather than zeros, and enforces an ADMIN ONLY role requirement. These go far 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 adds functional or safety-relevant information, and the most important user-facing behavior is front-loaded. The final ADMIN/READ-ONLY warning is appropriately placed at the end.

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 summary tool with no output schema, the description comprehensively covers return semantics, parameter behavior, permission constraints, and edge cases. The only missing piece is exact response structure, but that is unnecessary given the detailed narrative and the tool's simple boolean/string parameters.

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% because month and perEmployee lack schema descriptions, but the description compensates thoroughly: month format YYYY-MM and behavior when omitted, perEmployee's sensitivity and employeeId detail, and staff's independent-of-run behavior and link to update_employee_draft. Only a small amount of redundancy with the staff schema description remains.

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 month's payroll...') and enumerates exactly what is included: gross, deductions, employer contributions, net pay, and true total cost. It also distinguishes itself from sibling tools by clarifying payroll-specific outputs and pointing to update_employee_draft for employee IDs.

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 tells when to use it ('what does payroll look like this month' and 'who is out next week'), when to set perEmployee and staff, and warns to request per-employee salaries only when genuinely needed. It also contrasts with alternatives like employer_cost_estimate by clarifying this is actual stored payroll, not a recalculation.

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 read-only annotation, the description adds rich behavioral details: deterministic computation, specific period comparison, handling of one-offs, cents units, and behavior for optional month. This goes well beyond what annotations convey, giving the agent a thorough understanding of the tool's 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 but every sentence adds value, covering purpose, methodology, return fields, and parameter semantics. It is front-loaded with the core purpose and structured logically, making it easy to process despite its 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 thoroughly explains all return components, units, and the behavior of the optional month parameter. It is complete for a tool of this complexity, covering all necessary context for an agent to invoke it correctly.

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

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

Schema coverage is 100% for the single optional parameter, but the description adds meaningful behavior beyond the schema: it explains that for a completed past month, the whole month is compared, and for the current month it uses month-to-date. This enriches the parameter's meaning.

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 it is a diagnostic breakdown of why net profit moved, using specific verbs and a defined resource. It also distinguishes itself from sibling tools by emphasizing the deterministic comparison logic and the focus on profit drivers, which is unique among the listed 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 provides clear context for when to use the tool, explaining the comparison methodology and return values. However, it does not explicitly mention when not to use it or point to alternative tools (e.g., income_statement), so the guidance is strong but not fully 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 annotations give little behavioral detail, so the description carries the full burden, and it does so thoroughly. It discloses that the link is single-use, expires quickly, is company-specific, that the server determines MIME type from raw bytes, and that the token can be adopted onto an already-pending draft, including the duplicateAttachment result.

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?

Although long, the description is dense with non-redundant, decision-relevant information: purpose, usage order, repair workflow, and constraints. It is front-loaded with the core purpose and each subsequent sentence addresses a likely agent question or failure mode.

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 compensates by explicitly naming the return values (uploadUrl, attachmentToken) and explaining how they are used. It covers the complete workflow across all sibling create tools, the bank import path, and the re-file repair scenario, leaving no significant gap for 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?

Schema description coverage is 100%, so the schema already fully documents filename and mediaType, including the advisory nature of mediaType. The tool description adds no new parameter-specific meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Get a one-time link to upload' a document, and clarifies the exact use case (large files too costly to inline as attachmentBase64). It clearly distinguishes itself from sibling create/import tools and from get_attachment by focusing on the upload-link step.

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 provides explicit when-to-use guidance ('Use this for anything bigger than a few KB; keep attachmentBase64 for tiny files only') and when-to-call ordering ('CALL THIS FIRST, BEFORE the create/import call'). It names the alternative (inline attachmentBase64) and even includes a detailed repair path if the create call was already made without the token.

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=true and openWorldHint=false; the description adds far richer behavior: the three-status result model, the nearMiss flag with a concrete example ('JJ Dungun' for 'PERNIAGAAN JJ'), what data comes back in the resolved case, and the hard constraint to ask rather than guess. Nothing contradicts the read-only annotation — resolving is consistent with not mutating state.

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

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

Three sentences: purpose, status model, and the nearMiss/ask-user rule. Each adds distinct value and the purpose is front-loaded, but the closing 'Never guess among candidates — ask the user' mildly restates the earlier ask-the-user instruction, so one clause is slightly redundant.

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

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

For a minimal schema (1 param, no output schema) with nuanced behavior, the description is near-complete: it covers every outcome the agent will face, what data comes back in the resolved case (id + A/R balance), how to recognize shorthand matches, and what to do in each branch. The only minor omission is an explicit next-step for the 'none' status, but the confirm-before-creating rule effectively covers 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 0% with only a bare 'name' string field, so the description must compensate. It does: the first sentence establishes that the parameter is a customer name as written on an invoice draft, and the nearMiss discussion clarifies fuzzy and prefix-matching semantics. Only a formal 'name: ...' parameter breakdown is missing, which matters little for a single obvious parameter.

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: 'Resolve a customer name for an invoice draft against this company's real customers.' It enumerates three distinct outcomes (resolved, ambiguous, none) with their payloads, and the customer-specific scope clearly distinguishes it from sibling tools resolve_vendor and resolve_product.

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 decision rules: report nearMiss matches as likely shorthand and ask the user, only file as new on explicit confirmation, and never guess among candidates. It does not explicitly name alternatives (e.g., use resolve_vendor for vendors), but the customer-scoped framing and the detailed handling rules make when-to-use clear. An explicit when-not-to-use note would fully close the gap.

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 discloses return fields (id, sku, name, unit, default sell price), statuses (resolved/ambiguous/none), and the critical rule 'never guess among candidates.' This goes well beyond the readOnlyHint annotation by explaining how ambiguity is handled.

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 three sentences with no fluff: purpose, return values, and behavior. It is front-loaded with the core action and immediately useful details.

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 simple lookup tool with one parameter and no output schema, the description is complete. It specifies input semantics, output fields, statuses, and a safety rule against guessing, making the tool's behavior fully transparent.

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

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

With 0% schema description coverage, the description fully compensates by explaining that 'query' accepts a product name or SKU, and that plain forms work best. This gives the agent the semantic meaning needed to invoke the tool correctly.

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 'Resolve a product by name or SKU for an invoice line,' using a specific verb and resource. It distinguishes from sibling tools like resolve_customer and resolve_vendor by explicitly targeting products.

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 phrase 'for an invoice line' provides clear usage context, and 'Plain names or SKUs work best' offers practical input guidance. However, it does not explicitly name alternatives or state 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?

Beyond the readOnlyHint annotation, the description discloses matching behavior (exact/prefix vs nearMiss) and the required user-confirmation workflow ('only file as new if they confirm', 'ask the user'). This prevents an agent from auto-resolving or auto-creating records. It does not contradict the read-only annotation because 'file as new' is framed as a downstream decision, not a write performed by this 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?

Three sentences: first sets purpose and possible statuses, second details the nearMiss rule including the confirmation requirement, third is a clear imperative ('Never guess among candidates'). Information is front-loaded and no sentence is filler.

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

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

For a one-parameter, no-output-schema tool with readOnlyHint=true, the description covers the call's purpose, parameter, returned status categories (resolved/ambiguous/none with id/candidates), and disambiguation behavior. The only minor gap is an explicit action for the 'none' status, but the overall guidance is sufficient 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?

With 0% schema coverage, the description compensates by identifying the sole parameter as a 'supplier / vendor name' for a bill draft and clarifying how it is matched (exact/prefix, nearMiss). It adds semantic context beyond the raw string field. It doesn't specify formatting or case rules, but for a single string this is sufficient.

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

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

States 'Resolve a supplier / vendor name for a bill draft against this company's real vendors' – a specific verb, object, and target dataset. It also lists the three outcome statuses, making the operation's scope concrete. It doesn't explicitly contrast with resolve_customer/resolve_product, but the vendor-specific wording is enough to identify the intended 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?

Gives clear context: the tool is for bill-draft vendor names matched against real vendors, and instructs to 'ask the user' whenever candidates are ambiguous or nearMiss. It explicitly says 'Never guess among candidates,' which is a strong usage rule. It doesn't name alternative sibling tools for exclusion, so no direct when-not-to-use statement.

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 details side effects: it updates in place, re-validates, appends a note to the approval card, and does not approve the draft. It also clarifies that the reviewer is told about the change and that the original document/image is not patchable. This goes well beyond the minimal 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 main purpose and then provides detailed behavioral notes. It is somewhat verbose with repetitive emphasis (e.g., 'Fields you do not send...' and 'REVISING DOES NOT APPROVE ANYTHING'), but the structure is logical and information is well-organized.

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 thoroughly covers behavior, constraints, and side effects, but does not mention what the tool returns or the expected response format. Since there is no output schema, this is a notable absence. It also doesn't address errors or edge cases beyond refusing foreign keys, but that may be acceptable.

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 provides 100% description coverage for every parameter, so the baseline is 3. The tool description adds some high-level guidance, such as 'patch of just the fields that were wrong' and 'every key must belong to this draft kind', but these largely restate schema details. No significant new parameter meaning is added.

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 'Correct a draft you already filed, instead of filing it again', clearly stating the action and target. It distinguishes from create_*_draft by explaining why re-calling create is refused, but it does not mention the update_*_draft sibling tools, leaving some ambiguity about tool selection.

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 says 'Use this whenever you realise a filed draft is wrong' and explains 'instead of filing it again', giving a clear condition. It also states that only a PENDING draft can be revised, which is an important constraint. However, it does not discuss the update_*_draft alternatives, so guidance is not fully exhaustive.

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 behavioral context beyond the readOnlyHint annotation by explaining how the absence or presence of date parameters changes the output, and by specifying the grouping dimensions. It does not describe return structure, but it provides meaningful behavioral detail.

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 concise, front-loaded sentences. The first states the purpose, the second explains parameter behavior and output breakdown. Every word earns its place with no redundancy.

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

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

Given the tool has no output schema and only two optional parameters, the description covers the essential behavior: what is returned and how date ranges affect it. It could specify whether the breakdown is separate or combined, but for a summary tool this is sufficiently 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?

Schema coverage is 0% (no descriptions for 'from' and 'to'), so the description must compensate. It does so by explaining the effect of date ranges vs. no dates. It implicitly maps the parameters to the range, giving them semantic meaning beyond the schema's basic format.

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 'How much you have sold' and specifies it covers invoiced sales, distinguishing it from other financial reports. It also mentions the breakdown dimensions (month, customer, product), making its purpose specific and 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 clear guidance on usage: with no dates it shows today and this month, with a date range it shows the period's sales. It does not explicitly mention alternatives or when not to use, but the context is sufficient for selecting the 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 only provide readOnlyHint and openWorldHint; the description adds substantially more behavior: the 200-row cap with `total`/`shown`/`more` and the slicing strategy, row ordering ('newest document first, then in the document's own line order'), the verbatim-never-re-derived guarantee, `unitCost` as cost-at-posting-time, unit fallback behavior, and 'Nothing is written, and no draft is created.' These claims align with the annotations rather than contradicting them.

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

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

The description is long (~450 words) but deliberately structured: purpose first, then usage motivating examples, then gotchas with visual markers (⚠, ⛔). Some redundancy exists — the 'dimensions and specifications are text' caveat is restated several times, and the 180-PDF round-trip motivation is optional — but each major section carries unique information an agent needs.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does: it enumerates every row field (docId, docNumber, docDate, party, lineNo, product {sku, name}, description, quantity, unit, unitPrice, unitCost, discount, lineTotal, taxCode), states ordering, documents the 200-cap with `total`/`shown`/`more`, and pre-empts semantic traps (units not pieces, buy-side unitPrice=unitCost, dimensions as free text). For a 23-parameter tool this is 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?

Schema coverage is 100%, but the description adds meaning well beyond the field comments: docType is called out as REQUIRED with the buy-side vs sell-side debit-note distinction, `number` is clarified as also matching the customer's Ref No/DO/PO, and `productText` is explained as matching BOTH product name and line description with concrete examples ('chengal', '2x4'). It explains the domain reason behind the matching behavior — Taokeh stores no dimension column — which the schema alone does not convey.

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

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

The opening sentence states a precise verb+resource: 'Read the LINE ITEMS of posted documents IN BULK — what was actually sold or bought, line by line, across many documents in one call.' It explicitly differentiates from the closest sibling: 'search_documents answers WHICH documents; this answers WHAT WAS ON THEM.' There is no ambiguity about what this tool does.

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

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

Gives concrete when-to-use scenarios ('average price per item across a year, how a price moved between two customers, which sizes or grades actually shift'), names the exact alternatives ('Header-only search: search_documents. Paid expenses: search_expenses. The ledger postings behind a document: search_journal'), and states explicit exclusions ('quotes, delivery orders and purchase orders are not here'). Nothing is left to inference.

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

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

Despite readOnlyHint=true already covering safety, the description adds extensive behavioral context: payment docId is a bank transaction id (not a document id), refNo is not the invoice number, null dueDate means cash not missing data, einvoice status is 'as recorded in Taokeh' (not portal truth), source is derived not stored, and contras are intentionally absent. This goes far beyond what annotations could convey.

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

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

The description is front-loaded with the core purpose and results, and every sentence carries real semantic weight. However, it is a very long single block with some repetition (the customer Ref No / DO-PO concept is restated multiple times in the description and schema), so it sacrifices scanability for completeness.

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 specifies return-row semantics: which fields appear on which doc types, field omissions vs nulls, payment allocations grain, capped results with more flag, and special id warnings. An agent has everything needed to call correctly and interpret results without guessing.

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 76%, but the description substantially enriches parameter meaning: number searches both document number and customer Ref No, dueFrom/dueTo are due-date (not document-date) filters restricted to invoice/bill, docType disambiguates sales_debit_note vs debit_note, and multiple 'NOT a filter' params are correctly routed to canonical parameters. It more than compensates for the remaining undocumented params.

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 ('Find') and enumerates exact document types and filter combinations, immediately distinguishing it from line-level, journal, and expense searches. The return row description clarifies what a search_documents hit looks like, and the payments section further scopes the tool to document-grain and bank-line search.

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 alternatives: search_journal for contras/text, search_expenses for text, get_attachment/get_document_pdf for fetching artifacts, and states payments are opt-in by name. It also gives when-not-to-use cases (dueDate filters only with invoice/bill; contras excluded) and reasons for the 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?

The description adds substantial behavioral detail beyond the readOnlyHint annotation: returns are capped with a 'more' flag, rows are newest first, attachment semantics are clarified ('an empty list means genuinely no receipt is attached, not "unknown"'), and it explains how to read an attachment via get_attachment. This is rich context an agent cannot infer from the schema alone.

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

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

The description is dense but every sentence earns its place: scoping, filter semantics, return shape, attachment behavior, linking to get_attachment, and usage guidance are all present. It is front-loaded with the core purpose, though the single-paragraph format makes it slightly less scannable than it could be.

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 16 parameters, sparse annotations, and no output schema, the description does a strong job of covering return rows, attachment semantics, the recurrence of the double-booking risk, and the relationship to get_attachment. Minor gaps remain: it discloses that results are 'capped' with a 'more' flag but does not explain how the agent would retrieve the next page, and it leaves pagination behavior partially 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 communicates the intended filter combination: 'by any combination of: reference (partial), text in the memo/description (partial), date range, amount range, and category account.' It also, through the many 'NOT a filter' schema descriptions and the phrase 'Pass memo text as text', actively steers the agent away from plausible but wrong parameters. It does not enumerate every accepted parameter, but the schema already documents most of them well.

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: 'Search PAID EXPENSES already posted to the books' and goes on to list the exact filter dimensions. It also differentiates itself from sibling tools by noting that 'search_documents does NOT cover paid expenses — this tool is the only way to see them.'

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: 'ALWAYS check here BEFORE filing an expense draft (create_expense_draft): if the same receipt is already booked, filing again would double-book it.' It also names the alternative it is not and states this tool is the only way to see paid expenses.

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 aligns with annotations (readOnlyHint=true, 'Read-only — it changes nothing') and adds substantial behavioral detail beyond them: it explains the return format (lines with account code/name, debit, credit, description), that it returns newest first with a cap and a `more` flag, and that it never returns the whole ledger without filters. This fully discloses the key behaviors.

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 detailed but every sentence earns its place: it opens with the purpose, then the return value, then filters, then the filter requirement, then order/cap/more, then the pairing, then read-only. It is well-structured, front-loaded, and avoids redundancy with the schema (e.g., it does not repeat the source enum list).

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

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

Given the tool's complexity (15 parameters, no output schema), the description covers all essential aspects: what it searches, what it returns, how to filter, the caution against dumping the whole ledger, ordering, pagination via `more`, and its relationship to sibling tools. It also leverages the schema's 'NOT a filter' hints to prevent misuse. Nothing critical 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 87%, so the schema already documents most parameters. The description adds a summary of filter categories (date, text, accountCode, source, amount) and clarifies that `text` matches memo AND line descriptions—but the schema already states this. It confirms how amount range is measured (total debits), but again that is in the schema. The description does not significantly augment the schema beyond an organizational overview, so a baseline of 3 is appropriate.

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

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

The description states a specific verb ('Search') and a precise resource ('the general ledger's JOURNAL ENTRIES') and clearly distinguishes it from siblings by contrasting with search_expenses and search_documents. It also explains the return of balanced lines, so an agent can tell exactly what this tool does relative to others.

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 states when to use ('Pairs with search_expenses for reconciling') and when not to ('This never dumps the whole ledger' implies filters required). It also lists concrete filter combinations and provides alternatives via 'NOT a filter' parameter hints, which guide the agent to `text` or `accountCode` instead. This gives clear context but could have stated explicit exclusions more directly.

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