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?

Annotations (readOnlyHint: true, openWorldHint: false) confirm this is a safe read operation. The description adds significant behavioral detail beyond annotations: server-side computation in integer cents, NULL handling for deltaPct when earlier balance is zero, and warning if either sheet does not balance. It loses one point for not explicitly stating that no data is mutated or destroyed, but annotations already cover this.

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 comprehensive but slightly long (10 sentences). It front-loads key information (purpose, date-position contrast) but later sentences could be tighter. Every sentence adds value, but minor streamlining would improve conciseness.

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

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

Given the tool's complexity (three parameters, no output schema), the description is fully complete. It explains the output structure (deltaCents, deltaPct, points, notes), edge cases (NULL deltaPct, unbalanced sheets), and comparative semantics. The output schema is absent, but the description thoroughly documents return values, leaving no significant gaps.

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

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

Schema description coverage is 67% (two of three parameters have descriptions: compare enum and compareAsOf, but asOf lacks a description in schema). The description compensates fully by explaining how compare and compareAsOf work together, including the meaning of comparison names (previous_month_end, previous_year_end, same_date_last_year), the override behavior, and the semantic nuance that comparison is between two dates, not two ranges.

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 specific language ('Your balance sheet as of a date: assets, liabilities and equity, with the balanced check') to clearly state the verb (retrieve/compute) and resource (balance sheet). It distinguishes from siblings like income_statement by emphasizing the position-at-a-date nature, differentiating from period-based reports.

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 this tool vs. alternatives, contrasting with income_statement and warning not to describe the gap as a 'period' figure. It provides clear instructions on how to use comparison parameters, including named options and an explicit date override, with detailed explanations of behavior like delta calculations and NULL deltaPct 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?

Beyond the readOnlyHint annotation, the description discloses the exact semantics of the output: how the GL balance compares to statement closing, the honest 'unknown' when no balance figure exists, the exact status codes, the unreviewed backlog, and the per-statement tie-out arithmetic. It also states the data matches the in-app page, giving the agent a reliable expectation of return content. This goes far beyond what annotations provide.

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

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

The description is dense but well-structured. It leads with the core purpose, then enumerates the specific data points, and closes with an important read-only caveat. Every sentence contributes meaningful information without redundancy. It is concise enough for the complexity it conveys.

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 has no input parameters and no output schema, so the description must carry the full weight of explaining what the tool returns. It does so comprehensively: it defines the comparison, lists all statuses, mentions edge cases (unknown), and describes per-statement details. For a read-only status tool, this is essentially 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?

The input schema has zero parameters, so the baseline for this dimension is 4. The description adds context about what the tool returns rather than parameter semantics, but since there are no parameters to describe, it correctly focuses on output. No additional parameter explanation is needed.

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

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

The description opens with a clear statement of what the tool reports: where each bank account stands on reconciliation, comparing GL cash balance to the latest statement closing balance. It then enumerates specific data elements (status row counts, unreviewed backlog, per-statement tie-out). This clearly differentiates it from siblings like bank_review_queue or cash_position by focusing exclusively on reconciliation status.

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 when to use the tool: when the user wants the bank reconciliation status figures shown in the in-app Bank Reconciliation page. It also explicitly excludes mutation by stating that categorizing, confirming, and posting are human actions in Taokeh, signaling this is a read-only reporting tool. It does not name alternative tools explicitly, but the context and scope are sufficiently clear.

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

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

The description adds substantial behavioral context beyond the readOnlyHint annotation: rows are sorted lowest-confidence first, capped at 200 with a truncation note, and per-confidence bucket counts are provided. It explicitly states that confirming or posting rows is never done by this tool, aligning perfectly with the annotation. This extra detail is valuable for the agent to understand the tool's exact capabilities and limitations.

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 well-structured and front-loaded with the core purpose, but it is quite lengthy, including multiple clauses and historical context that could be condensed. While every sentence adds value, the overall verbosity reduces conciseness; a more streamlined version would be optimal.

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 (review queue with constraints, sorting, truncation, bucket counts) and the absence of an output schema, the description thoroughly explains what the tool returns (rows with live suggestions, confidence scores, reasons) and how the results are structured. It also covers permitted post-return actions (review, explain, propose), making it complete for agent 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?

The single parameter (statementId) has 0% schema description coverage, but the tool description fully compensates by explaining that it is optional and defaults to the latest imported statement. This provides complete semantic meaning 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 clearly states the tool's purpose: returning unposted bank-statement rows awaiting review, either for a specified statement or the latest imported one. It specifies the content (suggested category, contact, confidence score, reason) and distinguishes from siblings by focusing on the review queue rather than actions like classification or confirmation.

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 guidance on when to use the tool (for unposted rows requiring review) and what actions are permitted (review, explain, propose a category) versus prohibited (confirm, post). It also mentions the alternative of the owner using the /go command bar. However, it does not directly name sibling tools for comparison; the guidance is implicit through the detailed prohibitions.

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 the exact composition of the returned data, the separate treatment of the Shareholder Loan as a liability, and the MYR-booked balance convention. This is rich behavioral context that prevents misinterpretation of the output.

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

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

The description is longer than minimal but every sentence adds essential accounting context. It is front-loaded with the main query and then elaborates on inclusions/exclusions and currency treatment. While not as brief as a two-sentence description, it remains efficient and 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?

Without an output schema, the description carries full responsibility for explaining the return value. It thoroughly describes the 'accounts' list, the 'total' composition, the separate 'ownerFunding' field, and currency handling, making the tool's behavior fully understandable.

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

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

The tool has zero parameters, so the schema coverage is trivially 100%. The baseline for 0 params is 4, and the description appropriately focuses on output semantics rather than parameter details, which are absent.

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: answering 'How much cash you have right now' with a breakdown of bank accounts and cash pockets. It distinguishes itself from siblings by focusing on current liquid cash and explicitly separating owner funding, which is a liability, from the cash total.

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 current cash position) and includes a crucial warning about never adding ownerFunding to total. However, it does not explicitly mention alternative tools for related queries, such as cash_forecast for future projections, leaving some inference to the agent.

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

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

The description is exceptionally transparent about behavioral nuances: how returns are handled, how fees are treated differently per channel, and edge cases like credit notes and settlement corrections. This goes beyond typical descriptions and aligns with the readOnlyHint.

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 verbose and repetitive, repeating the same explanations multiple times (e.g., return handling, fee treatment). It lacks clear structure and would benefit from significant trimming to improve readability.

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

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

The description covers a wide range of edge cases (returns, fees, corrections, exclusions) and provides guidance on alternative data sources. While it doesn't describe the output structure, it adequately explains the meaning of each metric, making it fairly complete for the tool's complexity.

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

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

The schema provides only date patterns, but the description adds the required format (YYYY-MM-DD) and implies a date range. It doesn't specify inclusivity, but that's a minor gap. Overall, it compensates well for the lack of schema descriptions.

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

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

The description clearly states that the tool provides sales broken down by channel over a date range, listing specific metrics. It distinguishes from sibling tools by explicitly mentioning channel-based breakdown and exclusions of manual/non-channel sales.

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 instructs to provide dates in YYYY-MM-DD format and clarifies exclusions (manual/non-channel sales) and where to find missing data (e.g., for TikTok fees). While it doesn't explicitly state when to use it versus alternatives, the context of sibling tools makes the intended use 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 detailed behaviors: open vs closed day semantics, when posting happens, rounding rules for cash vs QR, consolidated e-invoice thresholds, and the not_available status for workspaces without the paid add-on. 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 well-structured with clear lead-in, important caveats, and section-like headings (Returns, IMPORTANT, THE ONE EXCEPTION). Some redundancy exists (e.g., Malaysia time, rounding noted twice), but the length 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?

With no output schema, the description must explain all return values and edge cases. It covers receipt/void counts, cash/QR totals, rounding, open/closed status, receipt range, credit sales, consolidated vs individual counts, awaiting buyer count, and accounting interactions. This is complete for tool selection and 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?

The single optional 'date' parameter is fully described in the schema (format YYYY-MM-DD, omit for today). The description repeats 'default today, Malaysia time' but adds no new meaning. With 100% schema coverage, 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 clearly states what the tool does: it returns details of a counter day (receipt count, voided count, cash/QR totals, rounding, status, receipt range, credit sales). It distinguishes this from sibling financial reports by explaining how counter day figures relate to the ledger and other 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 when-to-use and when-not-to-use guidance: while status is 'open', figures are not in the ledger and will not appear in sales_summary, cash_position, or income_statement; credit sales post immediately and appear in those reports. It also warns 'Never add creditSales.total to the cash and QR totals' and notes the paid add-on condition for 'not_available'.

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 critical behavioral traits beyond the annotations: it does not post to books initially, later posts with stock receipt and cost blending, server recomputes quantities/totals authoritatively, attachment rides through to the posted bill, and large files use out-of-band upload. With annotations all false, this full burden is 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 sentence earns its place: it front-loads the core purpose, then constraints, workflow, behavioral caveats, and attachment handling. It is structured logically and avoids redundant fluff, making it dense but efficient.

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 (14 params, no output schema, low schema coverage), the description covers the full context: when to use, prerequisites, the draft-vs-post flow, server authority, attachment lifecycle, and file-size handling. It leaves no major gaps for invocation.

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

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

Schema description coverage is only 43%, so the description compensates by explaining the meaning of needsReview (set for doubts), notes (short reviewer note, not a dump), attachment methods (inline vs token, size limits), and the working field (present your work). It does not cover all line subfields, but it clarifies the most important semantic parameters.

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

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

The description clearly states the verb 'File' and resource 'supplier-bill DRAFT into Taokeh', and explicitly distinguishes from siblings by limiting to inventory-only bills and pointing to create_expense_draft for already-paid services. This leaves no ambiguity about what the 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?

It gives explicit when-to-use and when-not-to-use guidance: only for inventory bills, for services/non-stock use the manual form or create_expense_draft. It also names prerequisite tools (intake_contract, resolve_vendor, resolve_product) and explains the workflow for handling doubtful cases via needsReview and notes.

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

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

Annotations are all false and provide little context, so the description must cover behavioral traits. It discloses side effects (creates a reviewable draft, not an address book entry), the mandatory image requirement and refusal without it, failure behavior on bad files ('NOTHING is filed'), and honesty expectations about unreadable fields. This far exceeds what the annotations 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 long but every sentence carries operational weight for a complex 14-parameter tool. It is front-loaded with the core purpose and then details workflow. However, it's a single dense paragraph; better structuring with bullets or sections would improve scannability, so it loses one point.

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 no output schema and sparse annotations, the description covers the full workflow: reading the card, attachment options, approval flow, edge cases, and reporting back. The only notable gap is that it never describes the response/return value of a successful call, which would be useful given the lack of an output schema.

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

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

Schema coverage is 100%, but the description adds substantial usage meaning: it explains the required image field (though not marked required in schema), mutual exclusivity of attachmentBase64 vs attachmentToken, default partyKind, and how notes should be written. This goes well beyond the baseline schema descriptions.

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

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

The description opens with a specific verb+resource: 'File a pending CONTACT draft from a business card YOU have read.' It also clarifies that the tool does not add anyone to the address book but creates a draft for owner approval, which clearly distinguishes it from sibling create_*_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 explicitly states when to use the tool (after reading a card image) and provides usage alternatives for attachments (inline base64 vs request_attachment_upload), including 'never both.' It also gives practical guidance for blurry images, illegible fields, and two-person cards. It doesn't explicitly contrast with other create_*_draft siblings, but the tool name and focus make that clear.

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

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

Annotations only give generic hints (readOnlyHint=false, etc.). The description adds essential behavioral detail: it creates a pending draft, not a posting; balance/revenue/SST reduction happens only after user approval; stock return is the user's decision; goodsReturned is only a hint. It also explains that positive amounts are required and that over-quantity lines are refused, which goes far beyond structured fields.

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

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

Though long, every sentence adds value. Key warnings are capitalized and front-loaded. The description is structured logically: purpose, workflow, key constraints, and error handling. It is dense but not redundant, and it avoids restating what the schema already shows.

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 13 parameters and no output schema, the description covers the full lifecycle: how to prepare via intake_contract, how to find the original invoice, what happens at approval, how to handle errors, and when to use alternatives. It leaves no critical gap for an agent to make a major mistake.

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

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

Schema coverage is 77%, but description expands meaning substantially: the distinction between kind values, the flow for resolving originalDocId, the 'no negative amounts' rule, the quantity cap relative to invoice sold units, and the advisory nature of goodsReturned. These clarifications are not in the schema and are critical for 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 description opens with a specific verb ('File') and resource ('CREDIT NOTE draft') and immediately clarifies the business purpose ('sales return, short delivery, price correction or allowance'). It distinguishes this draft from other document types by explaining what it does NOT do (does not post to the books) and by referencing sibling tools like revise_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?

Provides explicit when-to-use guidance: 'RESOLVE THE ORIGINAL INVOICE FIRST' and tell users to find it with search_documents. It contrasts 'against_invoice' vs 'allowance' usage, warns against filing a real return as an allowance, and mentions using revise_draft (kind: 'credit_note') for corrections. This is strong alternative/context 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?

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 are all false and thus uninformative, so the description carries the full burden. It discloses that the draft is pending, that attachments ride along and land on the posted entry, that a bad file causes rejection and nothing is filed, and provides specific instructions for amountUncertain, needsReview, and notes. This is rich behavioral transparency beyond any 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 (~200 words) but every sentence earns its place: purpose, non-posting behavior, prerequisites, field semantics, and attachment size guidance. It is front-loaded with the core purpose, and the structure flows logically from what the tool does to how to use it. Given 15 parameters and a complex workflow, this is appropriately sized and not verbose.

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

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

With no output schema and 15 parameters, the description covers all critical aspects: purpose, failure mode, attachment strategy, reviewer note style, what happens on approval, and the prerequisite call flow. An agent can correctly select and invoke this tool with high confidence. It is complete for its complexity.

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 compensates by explaining amountUncertain, needsReview, notes, attachmentBase64 vs attachmentToken, attachmentFilename/MediaType, and the prerequisite relationship to intake_contract/expense_accounts. However, it does not clarify date, amount, currency, inputTax, reference, or account codes—though these are relatively self-explanatory from names. Still, the description provides substantial added meaning for the most nuanced parameters.

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

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

The description opens with a specific verb+resource: 'File a paid-expense DRAFT into Taokeh from a receipt you've read.' It immediately clarifies this is a draft, not a posted entry, and distinguishes it from sibling tools like create_bill_draft. The scope and outcome are 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 explicitly states when to use this tool (after reading a receipt, for a draft) and what it does NOT do ('does NOT post to the books'). It gives prerequisites ('Shape the fields with intake_contract + expense_accounts first'), and names an alternative (request_attachment_upload) for larger attachments. This is strong usage guidance with clear 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?

With no useful annotations (all false), the description carries the full burden. It discloses key behaviors: not posting to books, server re-computes quantities and totals authoritatively, attachment flows (inline vs token) and its impact on review/approval, and the need for a short reviewer note. This exceeds the structured annotations and gives the agent actionable behavioral knowledge.

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

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

The description is longer than typical but every sentence adds value: it front-loads the core purpose, then covers behavioral traps (server authoritative), reviewer notes, and attachment upload flow. It is well-structured and dense, though slightly verbose. It earns a 4, not 5, because it could be tightened 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 complex tool with 14 parameters, no output schema, and no useful annotations, the description is remarkably complete. It covers the draft vs posted lifecycle, server-side recalculation, attachment instructions, and reviewer note guidance. It does not explicitly explain return values (no output schema anyway) or every edge case (e.g., near-miss customer guard), but it provides enough to invoke the tool correctly.

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

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

Schema description coverage is 43% (6 of 14 params have descriptions). The description compensates significantly by explaining the semantics of lines (server recomputes), notes (short reviewer note, not reasoning), attachment handling (base64 vs token), and needsReview. It does not explicitly cover all remaining params (e.g., saleDate, paymentMethod, reference) but provides higher-level guidance via intake_contract and resolve_customer.

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 sales-invoice DRAFT into Taokeh from a sales note you've read." It clearly distinguishes this tool from siblings by stating it does NOT post to the books and only creates a pending draft for review. This is a clear, differentiated 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 clear context: use it when you've read a sales note and need to file a draft. It gives a workflow prerequisite ('Shape the fields with intake_contract + resolve_customer + resolve_product first') and explains the draft-vs-posted distinction. It does not explicitly name sibling alternatives (e.g., create_bill_draft) but the context is strong enough.

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

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

Despite annotations carrying no positive hints (all false), the description fully discloses behavior: it does NOT post to the books, requires balancing to the sen, refuses unknown account refs, never creates accounts, never edits/deletes posted history, flags control accounts with approval restrictions, and explains attachment handling. This goes far beyond what annotations 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 long but well-structured with clear sections like 'WHAT NOT TO USE THIS FOR,' and front-loaded with the core purpose. Every sentence adds necessary detail for a complex tool, though it could be slightly tighter without losing 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 tool's complexity (11 params, no output schema, no enums), the description covers all key aspects: purpose, usage, constraints, balancing, account matching, control account rules, attachment guidance, error handling, and alternatives (revise_draft). No output schema means return values are not required, and the description fully addresses what the agent needs to invoke 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 82%, so baseline is 3, but the description adds significant meaning: it explains that lines must each carry exactly one side (debit or credit), how accountRef matching works (code best, exact name, ambiguous refused), the mutual exclusivity of attachmentToken vs attachmentBase64, and the purpose of notes/needsReview. This is valuable beyond the schema.

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

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

The description opens with a precise verb and resource: 'File an ADJUSTING JOURNAL ENTRY as a draft in Taokeh' and immediately clarifies it is 'the accountant's entry, not a document.' It enumerates specific use cases (accruals, prepayments, depreciation, corrections, reclassifications, year-end adjustments, reversing entries) and explicitly distinguishes it from sibling document-draft tools.

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

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

Provides explicit when-to-use/when-not-to-use guidance with named alternatives: 'WHAT NOT TO USE THIS FOR' lists create_bill_draft, create_invoice_draft, create_expense_draft, create_receipt_draft. It also instructs to shape fields with intake_contract first and advises when to use reversing entries for posted errors.

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 sparse annotations (all false) to disclose key behaviors: it POSTS NOTHING and MOVES NOTHING, creates no journal entry, saves as draft, issues no emails, carries no SST, and the server recomputes quantities and totals. This provides rich context that annotations alone would not convey, with no contradictions to the schema or annotations.

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

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

The description is long but front-loaded with the core purpose and key non-behaviors. Every sentence adds value (e.g., inventory-only, no SST, server recompute, review guidance). It is structured as a coherent flow from purpose to boundaries to workflow. Slightly verbose with uppercase emphasis, but appropriate for 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?

Given the lack of an output schema, the description explains the tool's effect, limitations, and downstream steps thoroughly. It covers what the tool does not do, prerequisites (intake_contract, resolve_*), and error correction (revise_draft). It does not specify the return value, but for a draft-creation tool, that is less critical and the overall context is comprehensive.

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

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

Schema description coverage is only 45%, but the description compensates by explaining critical parameters in context: `reference` is the buyer's own PO number (not the supplier's quotation number), `notes` is for a brief reviewer note, and `confirmNewVendor` requires explicit user confirmation. It also references intake_contract/resolve_vendor/resolve_product for shaping fields, adding meaning 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: 'File a PURCHASE-ORDER draft into Taokeh.' It clearly distinguishes this from sibling tools by explicitly noting it creates an intent-to-buy document and differentiating from create_bill_draft ('Goods that have ALREADY arrived are not this door'). The scope is unambiguous.

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

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

Usage guidelines are explicit and thorough. It states when to use this tool (intending to place an order with a supplier) and when not to (services/non-stock items should use the manual form; already-arrived goods should use create_bill_draft). It also directs users to revise_draft for corrections, covering both alternatives and exclusions clearly.

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

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

Beyond the sparse annotations (readOnlyHint=false, destructiveHint=false), the description discloses critical behaviors: it does not post to the books or move stock, the server recomputes quantities and totals from the tally, and bad attachments are rejected with nothing filed. This gives the agent a realistic model of side effects and authority.

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

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

The description is longer than average but every sentence earns its place, covering purpose, prerequisites, server behavior, review notes, and attachment handling in a logical flow. It avoids redundancy with schema field descriptions and is better structured than a simple tautology, though slightly dense.

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, minimal annotations), the description is remarkably complete. It covers the full workflow: resolving customer/product, handling no-customer quotes, server recalculation, reviewer notes, attachment upload paths, and the near-miss guard. All critical invocation details are addressed.

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

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

With schema coverage at 53%, the description compensates substantially by adding meaning to parameters: it explains `needsReview` and `notes` (short reviewer note, not lengthy reasoning), clarifies that `customer` can be empty for walk-in estimates, and details the `attachmentBase64` vs `attachmentToken` flow. It also warns that server figures are authoritative for `lines` and totals.

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 from a request you've read or been told.' It clearly distinguishes from siblings like create_invoice_draft by emphasizing that a quote is an estimate that does not post to the books or move stock, making its 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 gives explicit prerequisites ('Shape the fields with resolve_customer + resolve_product first') and clear conditional guidance (e.g., attach original document when reading from a document, use request_attachment_upload for large files, set needsReview for any doubt). It does not explicitly name alternative draft tools for comparison, so it falls just short of a 5.

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

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

The description discloses the draft lifecycle (pending review/approval before posting), server-side re-derivation of allocations, currency restriction, and attachment carry-through behavior, all beyond the neutral annotations. It also notes failure behavior for bad/oversize attachments ('rejected and NOTHING is filed').

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 dense paragraph but every sentence carries operational value, front-loading the critical 'does NOT post' caveat. It is longer than the simplest examples, but the complexity of the tool justifies the length.

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

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

Given 13 parameters, no output schema, and neutral annotations, the description covers the core workflow, prerequisites, constraints, and failure modes. It omits only the response shape and a few self-evident parameter semantics, but overall a strong, operational spec.

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 assigns meaning to key parameters: total = auto-allocated oldest-first, allocations = explicit per-invoice, needsReview = set for doubt, attachmentBase64/Token = small vs large file paths. However, some parameters (customerId, printedTotal, bankAccountId) remain undescribed in both schema and description, though the workflow implies their purpose.

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

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

The description opens with a specific verb+resource: 'File a customer-payment DRAFT into Taokeh' and immediately clarifies it does NOT post, distinguishing it from real receipt posting. It also differentiates from sibling create_*_draft tools by scoping to customer payments.

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 prerequisite tools (resolve_customer, open_invoices) and alternative upload path (request_attachment_upload), and says a foreign-currency invoice is refused and routes to Banking → Payments. It also explains when to set needsReview and how to structure notes.

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

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

The description repeatedly frames the tool as a read operation, ending with "so 'brief me' is a single read." However, annotations set readOnlyHint to false, which indicates the tool is not marked as read-only. This is a direct annotation contradiction, so the description cannot be trusted for behavioral transparency despite its useful cash.total nuance.

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 "Your morning brief in one call" and packs the important contents into a structured list. The parenthetical cash.total clarification is valuable, though the second sentence partially repeats the first sentence's component list while adding tool names.

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 aggregator with no output schema, the description covers many output categories and even explains cash.total semantics. However, the readOnlyHint contradiction leaves the actual side-effect profile unclear, and the return structure is not described beyond field names.

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 there are no parameter semantics to clarify. The 0-parameter baseline of 4 applies; the description appropriately spends its words on output semantics instead of parameters.

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

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

The description clearly states that this is an aggregated morning brief covering sales, expenses, cash, receivables, approvals, tax, and stock. It distinguishes itself from siblings by explicitly naming the individual tools whose figures it assembles and noting the added pending-approval 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 gives clear context: use this when the user says "brief me" and wants a single aggregated read. It names the individual alternatives (business_snapshot, cash_position, ar_aging, tax_position, low_stock), though it does not explicitly state when NOT to use it in favor of those individual 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?

The annotations only indicate false flags (not read-only, not idempotent, not destructive). The description enriches this by clarifying the actual write behavior: 'writes a suggestion the owner sees... never confirms, never posts... nothing you send here moves money'. It also discloses per-row error handling ('unresolvable name rejects that row'), output reporting ('Per-row outcomes are reported'), and the owner's batch-acceptance workflow, adding valuable context beyond 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 but each sentence adds critical operational detail, laid out in a front-loaded, logical flow: action, sourcing, limitations, parameter semantics, UI context, and error handling. It is appropriately sized for a tool that proposes financial categorizations with many user-facing constraints.

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

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

With no output schema, the description covers input sources, eligibility, contact validation, note expectations, the owner's review workflow, batch acceptance, and outcome reporting. It is self-sufficient for an agent to select, invoke, and understand the consequences of this tool, leaving no major operational gaps.

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

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

Schema description coverage is 0%, so the description must carry the parameter semantics. It explains category must be from the review screen's set, contactName only for CUSTOMER_PAYMENT/SUPPLIER_PAYMENT and must match an existing contact exactly, note is limited to 300 chars and serves as the owner-facing reason, and transactionId comes from bank_review_queue. This fully compensates for the absent schema descriptions.

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

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

The description opens with a specific verb 'Propose' and a precise resource: 'bank rows still waiting for review' with a scope cap of 50. It further distinguishes itself from siblings by noting it is proposal-only and by referencing bank_review_queue for IDs, differentiating from create_* draft tools and read-only reporting siblings.

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

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

Explicitly states when to use: 'PROPOSALS ONLY' and 'Only SUGGESTED/UNCATEGORIZED rows accept a proposal', and gives alternatives/conditions: 'get their ids from bank_review_queue', 'create the contact first, or omit it'. Also excludes when not to use: 'never confirms... the owner reviews and posts every line in /banking'.

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 beyond the annotations (readOnlyHint: true, openWorldHint: false) by explicitly stating 'READ-ONLY — it creates nothing, hires nobody and files nothing.' It also clarifies that the estimate is based on Taokeh's implementation of LHDN's official method and that defaults are used. However, it does not cover potential rate limits or system constraints.

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 well-structured and front-loaded with the core purpose, but it is slightly lengthy due to detailed explanations of defaults and assumptions. Every sentence adds value, though some details could be condensed without losing clarity.

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 5 parameters, no output schema, and no nested objects, the description provides comprehensive information: defaults, optional parameter effects, calculation source, and usage context. It explains the output format (estimate with stated assumptions) and the tool's limitations (not tax advice, not a quote), making the description fully adequate.

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 description coverage at 0%, the description fully compensates by explaining each optional parameter's meaning and effect (e.g., residency, citizenship, ageBand, epfEmployeeRate). It describes their interplay, such as how citizenship drives HRD Corp levy and makes SKBBK mandatory but does not change EPF/SOCSO/EIS rates.

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: 'Cost a HYPOTHETICAL hire: give a monthly wage and get back what that employee would really cost the employer.' It uses specific verbs ('Cost', 'give', 'get back') and distinguishes itself from sibling tools like 'open_invoices' or 'payroll_summary' by focusing on hypothetical hiring cost estimates.

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 guidance on when to use this tool (e.g., 'if I hire someone at RM4,000, what does it really cost me?') and what assumptions are made (e.g., defaults for residency, citizenship, age band, etc.). It also explains optional parameters and their effects, such as ‘NON_RESIDENT’ tax treatment and HRD Corp levy for foreigners.

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

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

The readOnlyHint annotation already flags the tool as safe; the description adds functional detail by explaining that it provides a list of categories and paid-from accounts to pick from, identified by code. This goes beyond the annotation without contradicting it, offering enough context about what the tool returns and how it is used.

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

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

The description is a single sentence that front-loads the core identity ('The expense accounts you can post to in this workspace') and then elaborates with usage context. It is appropriately concise for a reference tool, though the dash-and-parenthetical construction could be marginally clearer.

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 covers the essential purpose and usage context: what the tool provides (expense accounts), how to select them (category and paid-from account by code), and when to use it (shaping a paid-expense draft). It does not discuss pagination or response format, but these are not critical for such a simple lookup tool.

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

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

The tool has zero parameters, so there is nothing to define beyond the schema's empty object. The description's mention of 'by code' hints at how the list is structured (accounts are referenced by code), which is useful context for an agent handling the tool's output.

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

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

The description clearly identifies the tool as a reference for expense accounts in the workspace, specifying that it covers categories (what the money was for) and paid-from accounts (where it came from), and that selection is by code. This distinguishes it from siblings like expenses_summary (a report) and create_expense_draft (the actual creation tool).

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

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

The description states the intended use: 'for shaping a paid-expense draft,' which tells the agent when to invoke this tool. It does not explicitly name alternatives or exclusions, but the context is clear enough that an agent could differentiate it from create_expense_draft or expenses_summary.

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 goes well beyond the readOnlyHint annotation by explicitly stating 'it changes nothing' and 'no setting is ever toggled', and adds behavioral details such as ranking matches, returning deep-link URLs, configHint, addOn flag, and honest no-match behavior. It also notes the live catalogue grounding to prevent hallucinated navigation.

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

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

The description is longer than a simple two-liner but every sentence adds necessary information about behavior, output, and constraints. It is front-loaded with the core purpose and the extra details are all relevant, though slightly verbose.

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

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

Despite no output schema, the description fully explains the return format (ranked matches, page URLs, descriptions, configHint, addOn flag) and the tool's safety and failure modes. It is complete for a 1-parameter lookup tool with plenty of context.

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

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

Schema coverage for the one string parameter is 0%, so the description carries the full burden. It defines the query as a natural-language request and gives three concrete examples, giving the agent clear guidance on what to pass.

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

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

The description clearly states the tool returns exact Taokeh pages for a user's intended action, with a specific verb ('tell the user WHERE') and a well-defined resource (Taokeh's live feature catalogue). It is clearly distinguished from sibling tools, which are financial reports and draft-creation actions.

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 ('to tell the user WHERE in Taokeh to do something or change a setting'), provides natural-language query examples, and gives exclusions ('it changes nothing' and 'never make up a path'). It also instructs what to do on no match: browse sidebar or contact support.

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 reveals the signed URL is short-lived (~15 minutes), works for anyone holding it, and that bytes are never inlined. It also states 'Read-only; it changes nothing, emails nobody, and no link it hands out can reach another workspace'—adding network-scope and side-effect guarantees. This significantly exceeds the annotation's minimal signal.

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 distinct value—purpose, usage, parameter guidance, return behavior, security caveats, and lifecycle nuance. It front-loads the core purpose in the first clause. Slightly dense but justified given 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?

With no output schema, the description compensates by fully specifying the return shape (URL, filename, media type, size) and behavior. It also covers edge cases like approved drafts having no original, making it a self-sufficient 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?

Schema coverage is 100%, but the description enriches the meaning: it explains the relationship between owner and id, when to use expenseId vs draftId, and when to omit attachmentId. This adds operational context the schema alone lacks.

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 'Get a short-lived link to the ORIGINAL DOCUMENT...' which precisely identifies the verb (get), object (original document link), and scope (filed against expenses/drafts). It also differentiates itself from siblings like get_document_pdf by emphasizing it returns a link, not inlined bytes.

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 states 'Use it to CHECK a document is on file, or to re-read one you filed earlier.' It also provides a clear path to finding what to ask for ('search_expenses reports hasAttachment and attachments...'). However, it doesn't name an alternative tool for when you need the actual file content, so no explicit exclusions.

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

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

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?

Despite no annotations providing behavioral cues (readOnlyHint=false, etc.), the description fully discloses behavior: the server checks balances, rejects with exact delta, never invent rows. It explains the archiving mechanism, the consequence of no token (no source document), and idempotent retry behavior. No contradictions with annotations found.

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 relatively long but each sentence is meaningful. It front-loads the core purpose and non-posting behavior, then details constraints and attachment workflow. Minor redundancy around 'never invent or omit rows' is justified by criticality. Could trim 'never invent or omit rows to force it to balance' slightly, but overall well-structured.

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 9 parameters, no output schema, and complex workflow (pre-requisite intake_contract, optional attachment via two methods, idempotent retry, overlap guard), the description covers all aspects: prerequisites, error handling, archiving, user confirmation for overlaps, and parameter relationships. Nothing significant is missing.

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

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

Schema description coverage is 56% (5 of 9 params have descriptions). For undocumented params (bankAccountId, openingBalance, closingBalance, rows), the description compensates richly: it explains the account id comes from intake_contract, opening/closing balances are printed balances, rows must include signed amounts. For documented params, the description adds workflow context (mutual exclusion, size constraints for base64).

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 imports a bank statement for reconciliation, distinguishes it from posting to books, and contrasts with single-receipt/invoice/bill tools. The verb 'import' plus 'bank_statement' and the explicit 'does NOT post to the books' make 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 explicit when-to-use guidance: use intake_contract first to discover bank accounts and the arithmetic law. It states when NOT to use it (single receipts, invoices, bills go through draft doors). It instructs on attachment upload process, and even explains how to retroactively add an attachment without duplicating rows. No ambiguity.

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

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

Annotations already 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 the description reinforces this by stating 'Nothing posts on its own'. It adds context about workspace grounding and the content of each contract variant, though it does not cover error conditions or prerequisites. 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 front-loaded with purpose and then systematically maps doc_types to actions. It is somewhat verbose but every sentence adds value given the tool's complexity; slight trim could improve readability 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?

Given no output schema, the description covers the contract contents (required fields, totals, SST, worked example) and special cases like settings allowlists. It is complete for operational use, though it does not define the exact JSON structure of the returned contract.

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 sole parameter doc_type has no schema enum or description, but the text exhaustively lists valid values with explanations and defaults, fully compensating for the 0% schema coverage and adding concrete 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 it provides 'the shape a Taokeh document needs' for various documents, distinguishing it from sibling create_*_draft tools by focusing on the contract/schema rather than submission.

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 details which doc_type values correspond to which business scenarios, maps each to a specific draft creation tool (e.g., create_expense_draft), and emphasizes that nothing posts automatically, giving the agent clear when-to-use and when-not-to-use guidance.

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

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

The description goes well beyond the readOnlyHint annotation by disclosing that the response is capped but includes a true count to indicate additional records exist. It also reveals the behavioral impact of Counter mode, where sales are only posted at day-close, thus affecting the accuracy of on-hand quantities during the trading day. This is valuable, non-obvious context that annotations alone do not provide.

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

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

The description is three sentences, each earning its place. The first sentence states the purpose, the second explains the rule and capping, and the third covers the Counter nuance. It is front-loaded, concise, and free of redundant phrasing.

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?

Considering the lack of an output schema and the tool's moderate complexity, the description is remarkably complete. It explains the exact low-stock rule, the output fields, the capping behavior with a true count, and the counter day-close caveat. Together these cover the important behavioral aspects without needing additional documentation.

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 zero parameters and 100% schema coverage, there is no parameter ambiguity. The description adds value by detailing the output row fields (sku, name, on-hand quantity, reorder point, unit), which clarifies the return data. This aligns with the baseline of 4 for no-parameter tools, as the description enriches understanding 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 the tool's purpose: identifying products at or below their reorder point, framed as the 'what do I need to reorder' list. It specifies the resource (products) and the exact condition, making it a specific and distinguishable query. Although it doesn't explicitly contrast with sibling tools like stock_level, the focused reorder-point scope provides strong differentiation.

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

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

The description gives clear context for when to use the tool, such as reordering decisions, and aligns its rule with the dashboard's low-stock chip. It also explains the Counter mode caveat, which informs the user about data freshness. However, it does not explicitly state when not to use it or name alternative tools, so it falls short of a perfect 5.

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

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

The description claims 'READ-ONLY' and 'It changes nothing,' but the annotations declare readOnlyHint=false, which implies the tool may modify state. This is a direct contradiction between the description and structured metadata, severely undermining trust. Despite rich behavioral detail otherwise, the contradiction forces a score of 1 per scoring rules.

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 lengthy but front-loaded with purpose and structured by the four questions. Every sentence adds value for an agent, though some repetition (e.g., 'READ-ONLY' stated multiple times) could be trimmed. For the complexity of the tool, it strikes a reasonable balance.

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

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

No output schema is provided, so the description must convey return structure. It does so thoroughly: pending items include reference, party, amount, days waited, next step, and review link; approved items include what they became; rejected items include verbatim reason and reasonRecorded flag; staged items cover migration work. Pagination and truncation are also documented.

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

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

Schema description coverage is 0%, so the description must fully compensate. It explains all three parameters: `since` (optional, YYYY-MM-DD or ISO), `kind` (optional single-lane filter), and `limit` (default 50, max 200, with truncation honesty). It also adds context about what `kind` values correspond to the four buckets. This exceeds the baseline and provides actionable guidance.

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 returning the user's own queue in a workspace, answering four specific questions (pending, approved, rejected, staged). It distinguishes itself from 40+ sibling tools by being the personal queue aggregator for all document types.

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

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

The description explicitly states when to use this tool (to see your own queue) and what it does not do: 'READ-ONLY. It changes nothing, it cannot approve anything, no tool can approve on the owner's behalf, and no tool of any kind moves money.' It also explains that every pending item requires human action, guiding the agent not to attempt approvals.

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?

The description explicitly declares READ-ONLY and explains it returns grouped historical data plus a learned suggestion, adding context beyond the annotations. It also clarifies the owner's confirmation role, which is useful behavioral context.

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

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

The description is concise, well-structured, and front-loaded with the core purpose. Every sentence contributes specific value without redundancy.

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

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

Despite lacking an output schema, the description details the response structure (grouped by category, contact, GL account, with counts, date range, and totals) and the intended use case, making it self-contained 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?

With 0% schema description coverage, the description compensates by defining 'counterparty' as a payer or payee named as printed on the statement line, giving clear meaning to the single 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 clearly states the tool shows historical bank rows for a given counterparty, including grouping by category/contact/GL account and a live suggestion. It distinguishes itself by explaining it provides tenant-scoped precedent behind a suggestion.

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 conveys a clear use case: explaining why a row is being categorized a certain way based on historical precedent. While it implies when to use it, it does not explicitly name alternatives or exclusion criteria.

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 substantial behavioral context: the tool returns stored payslip figures never recalculated, refuses on non-admin connections, and plainly says if nothing has been run. It also clarifies it cannot create runs, pay anyone, or file with government agencies, exceeding what annotations provide.

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

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

The description is informative and front-loaded, starting with the core payroll purpose. It is moderately lengthy but every sentence adds value. Minor redundancy: the 'READ-ONLY' near the end repeats the annotation, but still useful for emphasis. Could be slightly more concise without losing meaning.

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

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

Given the tool has high complexity (payroll with many components, different runs, per-employee data), and no output schema, the description thoroughly explains what is returned (gross components, deductions, employer costs, leave data) and behavior (stored figures, admin only, read-only). It covers edge cases (empty month defaults, nothing-run message) completely.

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

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

Schema description coverage is 0%, so the description must compensate fully. It does so by explaining `month` is an optional YYYY-MM string, and `perEmployee` is a boolean for per-person breakdowns. It adds semantics by noting the default behavior for `month` and the privacy/prudence warning for `perEmployee`. The description makes both parameters clear despite no schema descriptions.

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

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

The description clearly states the tool provides a month's payroll from gross to net, including specific components and employer costs. It distinguishes itself by also listing who is on approved leave in the next 14 days, making it clear this tool covers both 'what does payroll look like this month' and 'who is out next week' in one 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 provides explicit when-to-use guidance: without `month` it reads the latest FINALIZED or POSTED run; with `month` as YYYY-MM it fetches a specific month. It warns to use `perEmployee: true` only when the user actually wants per-person breakdowns. It also states it is READ-ONLY and ADMIN ONLY, clarifying when not to use it versus create or admin 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?

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 description transparently discloses behavioral traits: the link is single-use, expires quickly, workspace-specific, and the server determines the real MIME type from file bytes despite a provided hint. It explains how the attachmentToken works with various draft creation tools and what happens on approval. Annotations (readOnlyHint=false, etc.) are consistent, and the description adds significant context beyond 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 front-loaded with the primary purpose and use case, but it becomes quite verbose with detailed workflow instructions, alternative scenarios, and repair logic. While all information is valuable, a more structured format (e.g., sections or bullet points) could improve readability. It is not wasteful, but could be more 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?

Given the tool's complexity (0 required parameters, no output schema, multiple downstream integrations, and a non-trivial workflow), the description is remarkably complete. It covers the return values (uploadUrl, attachmentToken), the exact usage sequence, error recovery, and constraints. Everything an agent needs to use the tool correctly is 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?

Schema coverage is 100%, and the schema already provides clear descriptions for both 'filename' and 'mediaType'. The description adds minor reinforcement (e.g., filename shows on review card, mediaType is advisory) but does not substantially increase understanding beyond what the schema already communicates. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: obtaining a one-time upload link for large files (receipts, bills, etc.) that are too costly to inline as base64. It distinguishes this from the alternative inline approach and explicitly lists the downstream tools that accept the returned token, making its role unambiguous among 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 explicit when-to-use guidance (for files larger than a few KB) and when-not-to-use (keep base64 for tiny files). It prescribes the invocation order (call this first, before the create/import call) and warns against filing bare. It also explains the repair path if the order is violated, giving agents concrete instructions.

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 and openWorldHint annotations, the description details important behaviors: statuses returned, the 'credit-check-in-chat' moment (A/R balance), nearMiss detection, and the instruction to always ask the user rather than guessing among candidates. This fully discloses the tool's decision logic.

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 appropriately sized and well-structured, starting with a clear purpose, then detailing statuses and edge-case handling. Every sentence adds value, including the nearMiss example and the imperative 'Never guess among candidates — ask the user.'

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

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

For a single-parameter tool with no output schema, the description is complete: it explains the resolution statuses, the nearMiss behavior, and what action to take (ask user) vs. what not to do (guess). The agent has enough information to invoke and interpret the tool correctly.

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

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

With 0% schema description coverage, the description compensates by contextualizing the single 'name' parameter as the customer name to resolve, including an example of a shorthand variant. It adds practical meaning beyond the bare schema field, though it doesn't provide exhaustive format 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?

The description states a specific verb ('Resolve') and resource ('customer name for an invoice draft'), clearly distinguishing it from sibling tools like resolve_product and resolve_vendor. It also outlines the statuses (resolved, ambiguous, none), making the tool's function 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?

It gives clear context for use — resolving customer names during invoice drafting — and provides explicit decision rules for handling near misses (ask the user, don't guess). It doesn't explicitly name alternative tools, but the context and examples offer sufficient guidance.

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

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

The description 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, but the description goes beyond by detailing the three possible statuses (resolved, ambiguous, none), the nearMiss flag, and the explicit instruction to ask the user rather than guess. This adds significant behavioral context beyond what annotations provide, without 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 four sentences, all dense with useful information: purpose, statuses, nearMiss handling, and a clear rule against guessing. No filler or redundancy; every sentence earns its place.

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

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

With only one parameter, no output schema, and annotations present, the description fully explains the tool's behavior: statuses returned, nearMiss semantics, how to proceed when close matches exist, and the instruction to ask the user. This is complete for the tool's purpose and complexity.

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 has one required string parameter 'name' with no description (0% coverage). The description does explain that 'name' is the supplier/vendor name to resolve, providing basic semantics. However, it does not add details like matching behavior (exact/prefix), case sensitivity, or formatting. For a simple single parameter, this is adequate but not rich.

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 precisely states the action: 'Resolve a supplier / vendor name for a bill draft against this workspace's real vendors.' This clearly identifies the verb, resource, and scope, and distinguishes it from sibling tools like resolve_customer and resolve_product by focusing on vendors.

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 (for a bill draft) and detailed conditional guidance: ask the user on nearMiss, only file as new after confirmation, and never guess among candidates. It does not explicitly name alternatives or state when not to use, but the vendor-specific scope and decision rules give strong usage direction.

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

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

With no meaningful annotations (all hints false), the description carries the full burden and delivers rich behavior: 'updates the draft in place', 'Fields you do not send are left exactly as filed', 'REVISING DOES NOT APPROVE ANYTHING... stays pending', and the reviewer is told it changed via an appended note. This goes far beyond 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 a single dense paragraph but every sentence adds necessary information: purpose, duplicate pitfalls, status restriction, no-approval behavior, and reviewer notification. It is long but not bloated; a lightly structured layout would improve scannability, but the content is efficient.

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

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

Given the complexity of the patch object and the lack of an output schema, the description is remarkably complete. It covers the re-validation rules, unsent-field behavior, approval status constraints, and the note mechanism. The agent can safely select and invoke this tool without asking for clarifications.

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

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

Schema coverage is 100%, so baseline is 3. The description adds important semantics beyond bare schema: patch keys must belong to the draft kind ('a misspelled or foreign key is refused rather than silently ignored'), the card image is not patchable, and the note is appended, not overwriting. This elevates it above the schema-only baseline.

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

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

The description opens with 'Correct a draft you already filed, instead of filing it again' and later 'updates the draft in place'. The verb 'revise' is specific to the resource (pending draft) and the description explicitly contrasts with calling create_*_draft again, distinguishing it from 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 explicitly states when to use: 'Use this whenever you realise a filed draft is wrong', and gives alternatives: 're-calling create_expense_draft ... is refused as a duplicate' and 'a second create files a CONFUSING SECOND DRAFT'. It also specifies when not to use: 'ONLY a PENDING draft can be revised ... file a fresh draft in that case'.

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 declare readOnlyHint=true and openWorldHint=false. The description adds a wealth of behavioral detail: capping with `more` flag, field omission rules per doc type, e-invoice status semantics, and the critical MyInvois visibility limitation. All of this is consistent with the annotations—the capping is presented as self-aware via `more`, preserving completeness semantics.

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

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

The description is long, but every sentence carries useful information for a multifaceted search tool. It is front-loaded with the search purpose, then organized into result rows, attachments, and e-invoice semantics. Slightly verbose, but the complexity justifies the length.

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

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

With 7 parameters and no output schema, the description covers nearly everything an agent needs: return format, ordering, cap behavior, attachment availability by doc type, e-invoice state details, and how to chain to get_attachment/get_document_pdf. It even includes a caveat about Taokeh's inability to see MyInvois. This is exceptionally 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 only 43% (party, number, docType have descriptions; to, from, minAmount, maxAmount do not). The description compensates fully by explicitly identifying to/from as a date range, min/maxAmount as an amount range, and by adding partial/case-insensitive semantics for party and number. It also clarifies docType values and distinguishes the two debit notes.

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 'Find invoices, credit notes, ...' naming eight distinct document types and all filter dimensions, making it unmistakably clear what the tool does. It also lists the exact return fields (docId, type, number, date, party, total, status), which helps distinguish it from sibling search tools like search_expenses or 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?

The description gives strong usage context: which doc types exist, how filters combine, the meaning of the `more` flag, and explicit pointers to get_attachment/get_document_pdf for follow-up. It also warns against saying 'never submitted to LHDN' because Taokeh cannot see the portal. However, it does not explicitly contrast with sibling search tools such as find_in_taokeh or search_expenses, so it lacks 'when not to use' 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?

Despite readOnlyHint and openWorldHint annotations, the description adds rich behavioral detail: newest-first ordering, capping with a 'more' flag, the exact meaning of hasAttachment/attachments (empty list means genuinely no receipt, not unknown), and the ledger context. This goes well beyond annotations without contradiction.

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

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

The description is long but every sentence adds value: filters, return format, attachment flag semantics, usage guidance, and sibling differentiation. No filler or repetition; it is dense yet structured.

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 7 parameters and no output schema, the description explains return rows, fields, ordering, flags, attachment behavior, and the critical workflow check. It is fully self-sufficient for an agent to invoke the tool correctly.

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

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

Schema coverage is only 43%, and although schema provides descriptions for text, reference, and accountCode, it lacks descriptions for date/amount range parameters. The description compensates by explicitly listing all filter dimensions (reference, text, date range, amount range, category account) and adds semantics like partial matching and exact account code. It doesn't name each parameter but conceptually covers all.

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 specifies a precise verb ('Search') and resource ('PAID EXPENSES already posted to the books'), lists exact filter dimensions, and distinguishes itself from search_documents and expense drafts. Unambiguous and specific.

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 this tool: 'ALWAYS check here BEFORE filing an expense draft' to avoid double-booking, and clarifies search_documents does NOT cover paid expenses, making this the only way. Clear alternatives and exclusion.

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

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

Annotations declare readOnlyHint=true, and the description adds substantial behavioral context: it returns entries with balanced lines, is capped with a 'more' flag, orders newest first, and explicitly states it changes nothing. This goes 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 serves a purpose: purpose, return format, filter options, usage constraints, ordering, sibling differentiation, and read-only assurance. It is well-structured and front-loaded with the core purpose.

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, the description fully discloses return values (balanced lines, more flag). It covers all major aspects: filters, behavior, limits, and relationship to siblings, making it highly complete for a complex tool.

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

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

Schema coverage is 71%, and the description fills gaps for date range, case-insensitive text matching, accountCode semantics, source concept, and amount range on total debits. It adds meaning beyond the schema, especially for 'from' and 'to' which lack 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 clearly states the tool searches the general ledger's journal entries, with a precise verb and resource. It distinguishes itself from siblings, especially search_expenses, by emphasizing that it returns balanced lines and covers all entry sources.

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

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

It explicitly explains when to use search_journal vs search_expenses for reconciling, and states the requirement to provide at least one filter to avoid dumping the entire ledger. This gives clear context and exclusions.

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

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

The description discloses many behavioral traits: idempotency on sourceDocId, server recalculation of totals, flagging of unresolved items, and historical posting. However, annotations state idempotentHint=false, directly contradicting the description's claim that 'IDEMPOTENCY IS ON sourceDocId.' Per the rubric, a contradiction yields a score of 1.

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

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

The description is lengthy but well-structured, with clear signposts like 'IDEMPOTENCY IS ON' and 'THE CUTOVER' to separate concerns. It front-loads the purpose and distinguishes from siblings early. Still, there is some redundancy (e.g., 're-running your whole export is always safe' restates idempotency), preventing a perfect score.

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 migration tool with 11 parameters and no output schema, the description covers preconditions, exclusions, ordering, idempotency, error handling, and the fate of staged documents (flagged vs. approved). It gives the agent enough context to use the tool correctly without needing to read other documentation.

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

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

Schema coverage is 91%, so the baseline is 3. The description adds some context (e.g., sourceTotal is advisory, sourceDocId is the dedupe key), but these points are already present in the schema's parameter descriptions. No significant new parameter-level meaning is introduced.

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 action: 'Bring ONE already-issued historical document... across from the system this workspace is migrating FROM.' It explicitly distinguishes itself from siblings like create_invoice_draft and create_bill_draft, labeling itself as the bulk migration door. This leaves no ambiguity about 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 provides explicit when-to-use and when-not-to-use guidance: 'Use it ONLY for documents that were genuinely issued in the old system... a NEW document belongs in create_invoice_draft / create_bill_draft.' It also covers preconditions (lane open), cutover date filtering, ordering of bills before invoices, and error refusal 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?

Annotations are minimal (readOnlyHint false, destructiveHint false). The description goes far beyond annotations: it explains that staging is idempotent per kind (sending again replaces the set), that opening stock posts a real journal entry, that chart accounts are never deleted/deactivated, that rename is always allowed but change of type/normal balance is refused on posted accounts, and that setting a blank value is refused. It also warns about presentation fields not migrating and bill-of-materials links being separate. Contradiction false.

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

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

The description is extremely comprehensive but verbose—over 1000 words. While it front-loads key points (call intake_contract first, writes nothing, unit is the whole list), the density of detail makes it hard to scan. Some sections repeat concepts (e.g., 'never infer TIN' appears for both contacts and settings). It earns its place with high value content but could be more structured with bullet points or sections.

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 (4 distinct kinds, 4 parameters, one array of up to 5000 rows with 30+ fields), no output schema, and rich sibling set including stage_opening_balances, the description is remarkably complete. It covers sequencing prerequisites, behavioral side effects, per-field constraints, error cases (refused type changes, deduplication rules, AI-prohibited settings), and actionable guidance for the agent (tell the owner about presentation fields, fix rows Taokeh names back). There are no gaps that would leave the agent uncertain.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value beyond the schema: it explains the semantics of the 'kind' enum in detail (accounts sent first, settings last), clarifies that 'rows' replaces the entire staged set, and adds context about openingQty only seeding new SKUs, avgCost being the valuation basis, and settingKey being from an allowlist of fifteen. A minor deduction for not explaining every field in the description (e.g., barcode uniqueness is in schema description already).

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 brings workspace master data across from the old system, specifying four distinct kinds (chart of accounts, product catalogue, contact book, workspace setup). It distinguishes each kind's purpose and differentiates from sibling stage_opening_balances by noting there is no 'already imported' refusal for master data.

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

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

Explicitly says to call intake_contract FIRST for each doc_type to get fields, rules, and current counts. Also states that accounts should be sent first because the trial balance matches against it, and settings is the last mile. Notes what NOT to do: never infer TIN/registration numbers, never send presentation fields, and never write settings that are on the strict allowlist of AI-prohibited keys.

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 key behavior beyond annotations: it posts nothing, only stages rows for review; calling again replaces the entire set; and it refuses when books are locked or already posted. It also explains how totals are re-derived and compared, and the handling of credit rows. Annotations only state readOnlyHint=false, etc., so this adds substantial context.

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

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

The description is long but every sentence contributes essential operational detail. It is front-loaded with a clear purpose, then follows a logical flow: prerequisites, staging behavior, whole-set semantics, mistake correction, cutover context, refusal conditions, and special-case handling. 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?

Given the tool's complexity (5 parameters, no output schema, nested row objects), the description covers all necessary context: return/landing behavior (review screens), error conditions (locked, already posted), exclusions (credit rows), and the unique no-fence treatment for opening documents. This is complete enough for an agent to invoke 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 already covers 100% of parameters with detailed descriptions, which sets a baseline of 3. The description goes further by emphasizing critical usage: send the printed total in sourceTotal, never adjust rows to force a tie, and leave out credit-balance rows from aged lists. This adds semantic depth beyond the schema.

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

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

The description states exactly what the tool does: brings opening balances (trial balance, aged receivables, aged payables) from a prior accounting system. It uses a specific verb ('bring ... across') and names the resource and scope, and distinguishes itself from the sibling stage_document by noting the 'no too old fence' difference.

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

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

Provides explicit when-to-use guidance: call intake_contract first, then use this tool for cutover data. It also gives when-not-to-use context: credit balances on aged lists should be excluded and handled manually, and notes permanent refusal cases (locked books or already-posted balances). The alternative stage_document is explicitly contrasted.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is known. The description adds valuable behavioral context beyond annotations: the Counter day-close timing and how stock moves (per day, not per scan). This helps the agent interpret data freshness and avoid misleading users. 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 two sentences with the core action in the first and a relevant caveat in the second. Every word earns its place; no fluff 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?

For a one-parameter tool with no output schema, the description covers purpose, usage, parameter semantics, and a key data-freshness caveat. It is appropriately complete for 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?

Schema coverage is 0%, so the description carries the full burden for parameter understanding. It explicitly explains that the 'query' parameter accepts a product name or SKU, which significantly enhances the bare string field. This is sufficient for the single required 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 uses a specific verb ('how many units') and resource ('of a product you have on hand'), directly answering 'what does this do'. It distinguishes from siblings like low_stock (which likely lists products below threshold) and resolve_product (which maps identifiers) by focusing on quantity lookup.

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 clearly states the search mechanism ('search by product name or SKU') and provides an important timing caveat about Counter day-close, which clarifies when to trust the figure. It doesn't explicitly name alternative tools, but the context is sufficiently clear for most use cases.

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 value by detailing the specific data sources (SST-02 return figures, consolidated-e-invoice register) and explaining edge cases like registration 'none' meaning no remittance. It does not contradict the annotations and provides meaningful behavioral context beyond safety.

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 well-structured with a colon and numbered items, front-loading the core purpose. It is a single long sentence but each clause carries essential information, and there is no redundant filler. Minor complexity from nested clauses prevents a perfect score.

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

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

With no output schema, the description must serve as the primary documentation of return values. It covers both major sections (SST status and e-invoice consolidation) and their key fields, including dates and validation status. It omits minor formatting details but is adequate for a read-only status check.

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

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

The tool has zero parameters, so the schema provides complete coverage (100%). The description focuses on the output rather than parameters, which is appropriate. It explains the meaning of the returned data, which is the relevant semantic content 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 description clearly identifies a specific resource (tax position) and a specific read action ('one read'), and enumerates the exact components (SST payable and e-invoice consolidation) it returns. This distinguishes it from sibling financial reports like cash_position or business_snapshot, which cover different domains.

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 does not provide any guidance on when to use this tool versus alternatives, nor does it mention related tools or conditions that would make it the appropriate choice. The phrase 'in one read' implies a quick lookup, but no explicit context, exclusions, or alternatives are given.

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