Osome

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

Beyond the basic safety hints, the description adds crucial operational constraints: it requires the 'company:documents:write' scope and warns that writes are 'rate-limited per user.' It also fully discloses the complex output structure.

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?

While detailed, the structure is highly efficient. Every sentence provides operational value, specifically addressing scoping, limits, and alternative use cases, making it information-dense without being redundant.

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

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

The definition is complete for an advanced write tool. It covers input validation semantics, required permissions, operational limits (rate limits), and expected output behavior and structure, leaving no critical gap for the 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?

Since schema coverage is 100%, the baseline is high. The description adds significant meaning by clarifying the tool's function (starting a conversation vs. continuing one) and detailing the non-obvious behavior of the return set.

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

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

The tool clearly states its purpose: 'Post a comment on a transaction.' It distinguishes itself by specifying that it initiates a conversation if none exists, and it is clearly differentiated from get-transaction-conversation.

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 critical usage advice: the idempotent warning ('don't repeat a call that succeeded') and explicit instruction on the correct sibling tool to use for reading ('Use get-transaction-conversation to read without posting').

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 flag non-readOnly/non-destructive; the description adds the real behavioral payload: the full amount is booked, the transaction is reconciled and enters a reconciledWithCashCoding state awaiting accountant review, failures return a reason such as already reconciled, and it requires company:documents:write with per-user rate limits. This goes well beyond the structured hints.

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

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

Front-loaded with the action and effect, then the return/failure behavior, then sourcing and prerequisites, then scope. Dense but every sentence carries information; the single-paragraph run-on is the only structural weakness.

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

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

No output schema exists, yet the description covers what is returned (overallStatus and outcomes), what failure looks like and why, what state the transaction ends in, and the permissions and rate-limit constraints an agent must anticipate. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds workflow meaning by specifying that accountId must come from list-transaction-cashcoding-recommendations. It says nothing extra about vendorName, vendorContactId, or description, but those are already documented in the schema.

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

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

States a specific verb and resource ('Cashcode one bank transaction to an account') plus the concrete effect: books the full amount to accountId on the transaction date and reconciles it. It also names where accountId comes from and points to the add-transaction-comment alternative, so it is clearly 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?

Explicit routing: take accountId from list-transaction-cashcoding-recommendations, and if no account fits, use add-transaction-comment instead. That is a when-to-use plus a when-not-to-use with a named alternative.

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=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuine workflow context (byte upload must precede this call, metadata plus token must be passed unchanged) but does not address idempotency, behavior on metadata/checksum mismatch, or what is returned.

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

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

Three short sentences, front-loaded with the step position and the gating condition. Every sentence carries distinct information with no filler.

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

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

For a mutation tool with no output schema, the description covers sequencing, token handling, and the resulting artifact type. The only missing element is what the call yields on success (e.g., a document ID), which an agent may want to chain into get-document.

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

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

Schema description coverage is 100%, so baseline is 3, and the description adds meaning beyond it by instructing that the same metadata plus uploadToken must be passed 'unchanged' from prepare-document-upload, tying the required parameters to the prior step rather than restating them.

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

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

States a specific verb and resource ('create the Classic document') and explicitly positions itself as 'Step 3 of document upload'. It clearly distinguishes itself from the sibling prepare-document-upload by naming that tool as the source of the uploadToken.

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

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

Gives an explicit precondition: 'Call only after bytes were uploaded to the presigned POST target from prepare-document-upload.' The alternative/complementary tool is named and the ordering rule is unambiguous.

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

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

Annotations only declare the safe-write profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false); the description goes well beyond them by explaining the two-phase lifecycle (draft now, nothing applied until submit-credit-note), the exact failure precondition, and the required invoice:write scope. This is exactly the context an agent needs before committing a financial reversal.

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?

Six short sentences, front-loaded with the action and scope, then failure mode, then the lifecycle and alternatives. Every sentence adds a distinct operational fact; none is filler.

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

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

Even without an output schema, the description documents the return value ('creditNote with its id, status draft, no number or issue date yet, and an invoice summary') and the required follow-up step. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema coverage is 100% and both params point to their discovery tools (list-companies, list-invoices), so the schema carries the load. The description still adds real semantics by stating the credit note covers 'the whole of' the invoice, telling the agent there is no partial-amount parameter or option.

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

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

States a specific verb and resource ('Create a draft credit note') plus scope ('for the whole of an issued sales invoice, any status except draft'). This immediately separates it from submit-credit-note, get-credit-note, and duplicate-invoice without needing to open any schema.

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

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

Explicitly says when to use it ('It is how an invoice is reversed, since issued invoices can't be deleted'), what blocks it ('Fails if the invoice already has a credit note that isn't cancelled'), and which siblings handle adjacent jobs ('Nothing is applied until submit-credit-note; check it with get-credit-note... copy it with duplicate-invoice').

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=false and destructiveHint=false, so the agent knows this is a non-destructive write. The description adds that each call creates a new customer (duplicate risk) and that it returns the created customer for use in other tools, providing useful behavioral context beyond annotations.

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

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

Three sentences with zero waste: purpose and return are front-loaded, followed by usage of the returned id and a duplicate-creation warning. 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?

Given annotations covering safety and a 100% schema, the description adds necessary context about return value, intended downstream use, and duplicate avoidance. Nothing critical is missing for an agent to call the tool correctly.

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

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

Schema description coverage is 100%, with all parameters and nested fields fully documented in the schema. The description does not add parameter-specific meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

States a specific verb (create) and resource (invoice customer) and distinguishes from list-customers by instructing to check it first for reuse. The return value and intended use are also clarified.

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 when to use (create a new customer) and when not to (check list-customers to reuse an existing one). Names the alternative and the condition that selects it, leaving nothing to inference.

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

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

Annotations cover the safety profile (readOnly=false, destructive=false, openWorld=false), and the description adds genuine behavioral context beyond them: the draft is created empty, it inherits the company's auto-included payment methods, and 'nothing is sent' to the customer. It stops short of mentioning permission/auth requirements, which keeps it from a 5.

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

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

Three sentences, front-loaded with the action and the return value, then the resulting state, then the workflow and alternative. No sentence is redundant; the closing routing sentence earns its place by preventing misuse of this tool for duplication.

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

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

No output schema exists, but the description covers the return value (the draft with its id) and the full lifecycle for the object it creates. With one fully documented parameter and annotations covering the mutation profile, an agent has everything needed to call it correctly.

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

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

There is a single parameter with 100% schema coverage, so the schema already documents companyId (including the numeric pattern). The description's 'for a company' only implies the resource scope and adds no format or constraint detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('Create an empty draft invoice for a company') plus the return value ('return it with its id'). It draws a clear boundary against siblings by describing the draft's initial state (no customer, no line items) and explicitly naming update-invoice-draft, submit-invoice and duplicate-invoice as the follow-on 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 an explicit step-by-step workflow: create draft here, then set customer/items/dates/currency with update-invoice-draft, then finalize with submit-invoice. It also names the alternative path (duplicate-invoice) for copying an existing invoice, so an agent knows both when to use and when not to use this tool.

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

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

Annotations declare the safety profile (readOnlyHint=false, destructiveHint=false), and the description adds substantial context beyond that: exactly what is copied (customer, line items, currency, notes, payment methods, tax-inclusive setting), what is reset (no dates or invoice number), that the original is unchanged, and that nothing is sent.

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

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

Front-loaded with the core action and result, followed by copy semantics and workflow routing. Three sentences, all of which earn their place with no filler.

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

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

No output schema exists, and the description still states what is returned (the draft with its id). For a two-parameter duplication tool, the description covers action, side effects, non-effects, and next steps 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 coverage is 100%, so both id and companyId are already documented. The description reinforces company scoping ('the copy is always created in that company') and the 'any status' property of the source invoice, but adds little beyond the schema's own parameter descriptions.

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

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

States a specific verb (copy/duplicate) and resource (sales invoice) with precise scope: creates a new draft in the same company and returns its id. It explicitly distinguishes itself from create-invoice-draft, so an agent can differentiate without opening either schema.

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

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

Names the alternative (create-invoice-draft for an empty draft) and the follow-on tools (update-invoice-draft to set dates, submit-invoice to finalize), giving explicit when-to-use routing and workflow sequencing.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, but the description adds substantial context beyond them: no PDF rendering, links may remain empty until Classic finishes, 'sent' status does not imply customer email delivery, and submission can queue InvoiceNow/PEPPOL delivery and IRAS reporting. These are real behavioral and side-effect disclosures an agent needs before invoking a destructive, externally-visible operation.

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

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

The description is front-loaded with the core action and return value, then layers in behavioral caveats and the alternative path. It is on the longer side and some caveats (Classic generation timing, email delivery semantics) stack up, but each sentence carries distinct information and 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?

For a destructive, open-world tool with a nested-object parameter and no output schema, the description covers return value (document links, possibly empty), side effects (external delivery/reporting), and intent confirmation. It is close to complete; only minor gaps remain around any permission/auth prerequisites for submission.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters, including the invoice object and its nested fields. The description reinforces that the invoice object is only needed for drafts and that line items/recipient come from the stored draft, but this largely duplicates the schema's own invoice description, so 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 states a specific action ('Return an invoice's document links' plus submitting a draft 'exactly like submit-invoice') and explicitly distinguishes itself from siblings submit-invoice, get-invoice-document-links, and preview-invoice. The only friction is the name itself: 'generate-invoice-pdf' implies PDF rendering while the description says 'It does not render a PDF itself,' creating a small mismatch between name and 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?

It gives explicit when-to-use guidance ('Confirm the user intends to submit, including any configured external delivery and reporting') and names alternatives for the non-submitting case ('Use preview-invoice or get-invoice-document-links to read an invoice without submitting it'). Nothing is left to inference about when this tool is the right choice.

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 the safe read-only profile, but the description goes further by disclosing the return shape: grouping by supplier, one line per document, the exact aging buckets (Current, < 1 Month, 1/2/3 Months, Older at 30-day steps), and that totals are in the company's base currency. The one remaining gap is pagination/size behavior, which is unaddressed.

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

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

Purpose and scope are front-loaded in the first clause, and the routing sentence comes last where it is most useful. It is dense and long, but nearly every clause carries information an agent needs; minor trimming would still be possible.

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

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

With no output schema, the description carries the burden of describing the return value, and it does so thoroughly: grouping, line contents, aging buckets, and currency of totals. Combined with 100% parameter coverage, nothing material is missing for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the as-of semantics of dateTo ('as of dateTo') but adds no syntax or format details beyond what the schema already documents for id, dateTo, and the unused dateFrom.

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

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

States a specific verb and resource ('Get the aged payables report for a company') and immediately defines the scope: supplier obligations from approved, still-unpaid purchase documents as of dateTo. It is unmistakably distinct from get-aged-receivables, which it names directly.

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 routes the agent: 'Use get-aged-receivables for what customers owe, or get-invoice-pending-summary with movement out for payables totals only.' Both the alternative tool and the condition selecting it are given, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds meaningful context beyond that: the report is built only from documents still unpaid at dateTo, and it returns only the report (no exchange rates). It stops short of describing pagination or bucket definitions, but this is solid supplemental disclosure.

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

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

Two sentences with zero padding; the primary purpose is front-loaded and the sibling routing follows. Every clause carries information, including the useful 'returns only report' distinction.

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 takes on the job of describing the return shape, and it does so ('grouped by contact into aging buckets', 'returns only report'). Combined with full schema coverage and supporting annotations, an agent has enough to call it correctly; only finer details of bucket composition are left implicit.

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

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

Schema coverage is 100%, so all three parameters are already documented in the schema, including the note that dateFrom is unused. The description reinforces the dateTo as-of semantics but adds no format or syntax detail beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb (Get) and resource (aged receivables report), and immediately defines the semantics: outstanding amounts owed as of dateTo, grouped by contact into aging buckets. It explicitly distinguishes itself from get-aged-receivables-v2 and get-overdue-invoices, so an agent can tell them apart without opening any schema.

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

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

Provides explicit routing rules: use get-aged-receivables-v2 for the ledger-based report that also returns exchange rates, or get-overdue-invoices for past-due buckets only. This names both alternatives and the conditions that select each, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds genuinely new behavioral context beyond the annotations: the data provenance (unreconciled balances on the AR ledger account), that it returns report and exchangeRates, and the required invoice:read scope.

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

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

Front-loaded with the core purpose, then provenance, then sibling routing, then the auth requirement. Each sentence carries distinct information and none is redundant.

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

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

Although there is no output schema, the description names the returned artifacts (report and exchangeRates) and the data source, so an agent knows what to expect. Combined with full schema coverage and rich annotations, nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description echoes dateTo ('as of dateTo') and the company scoping but adds no syntax, format, or defaulting detail beyond what the schema already documents.

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

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

States a specific verb and resource ('Get the aged receivables v2 report') and defines the output precisely: outstanding customer amounts as of dateTo, grouped by contact into aging buckets. It is immediately distinguishable from siblings like get-overdue-invoices and get-aged-receivables.

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 routes the agent: get-overdue-invoices for past-due buckets only, get-invoice-pending-summary for totals, and get-aged-receivables for the original report. The when-to-use-this vs alternatives decision is fully resolved.

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 destructiveHint=false, and the description adds value beyond that by disclosing the returned column structure, the base-currency reporting, the treatment of Equity (Retained Earnings, Current Year Earnings), and the final Total Liabilities & Equity line. It does not discuss pagination or edge cases, but for a read-only report tool this is strong.

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

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

Three dense sentences, front-loaded with the core action and the as-of constraint before the report contents and the sibling alternatives. Every sentence earns its place, though the account-type enumeration is slightly heavy.

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

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

With no output schema, the description carries the burden of explaining the return value, and it does so thoroughly (column layout, currency, equity composition, final total line). Combined with the sibling routing, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so all three parameters (id, dateTo, dateFrom) are already documented. The description reinforces the key semantics (dateTo default/UTC, dateFrom ignored), but this largely restates what the schema already says rather than adding new format or validation detail, so baseline 3 applies.

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

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

States a specific verb and resource ('Get a company's balance sheet'), the as-of semantics, and what the report contains (Assets, Liabilities, Equity by account type and account, with totals). It also distinguishes itself from related report tools by naming them explicitly.

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

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

Explicitly routes the agent: use get-trial-balance for account movements over a period, get-profit-and-loss for income/expenses, get-cash-flow-statement for cash flows. It also clarifies that dateFrom is ignored and dateTo defaults to today, removing the main point of confusion.

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

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

Annotations already establish the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), yet the description adds real behavioral detail: the result ordering puts open accounts first and closed last, and the returned shape is limited to id, name and type. That is useful context beyond the structured fields.

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

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

Three tight sentences, front-loaded with the resource and scope, then the return shape, then the routing note. Nothing redundant and no filler.

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

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

With no output schema, the description compensates by enumerating the returned fields (bankAccounts with id, name, type) and explicitly noting balances are absent. Combined with annotations covering safety and a fully documented single parameter, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the single 'id' parameter (Company ID) is already fully documented in the schema. The description adds no further syntax or scoping detail about the ID, so the baseline 3 for a fully-covered schema applies.

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

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

States a specific verb and resource ('List the bank accounts recorded in a company's accounting ledger') and immediately distinguishes itself from search-transactions, which handles the transactions themselves. An agent can separate it from siblings like get-chart-of-accounts or list-customers without opening the schema.

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

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

Explicitly routes the agent to search-transactions when the bank transactions (rather than the accounts) are wanted, and notes that balances are excluded, which pre-empts a common wrong expectation. It stops short of stating full when/when-not conditions (e.g. whether balances live in another tool), but the alternative is named 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?

Annotations already declare the safe read-only profile, and the description adds substantial context beyond them: the report's shape (one column, operating/investing/financing lines with totals, net change, opening and closing cash), base currency, rounding to whole units, and the no-consolidation scope. With no output schema, this disclosure carries real weight.

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

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

Front-loaded with the core identity and period before the return detail and the sibling routing. Dense but every clause is informative; the only minor cost is the long run-on return-shape sentence.

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

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

For a read-only reporting tool with no output schema, the description supplies the period requirement, the return contents, the currency/rounding assumptions, and the consolidation scope – everything an agent needs to call and interpret 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 description coverage is 100%, so all three parameters (id, dateFrom, dateTo) are already documented in the schema. The description restates the period concept but adds no syntax or format detail beyond what the schema provides, matching the baseline for full-coverage schemas.

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

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

States a specific verb and resource (cash flow statement) plus the preparation method (indirect) and the required period, so an agent can distinguish it from other financial statements at a glance. It also explicitly names the sibling tools it is not.

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

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

Explicitly routes to alternatives: get-profit-and-loss for income/expenses and get-balance-sheet for the position on a date. Clear context, but there is no explicit statement of when this tool itself is the wrong choice or any prerequisites (e.g., which companies are eligible).

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 destructiveHint=false, so safety is covered; the description adds genuinely useful behavior: the list is identical for every company in the jurisdiction and carries no balances. It stops short of disclosing auth requirements or volume/pagination characteristics, so it is strong but not exhaustive.

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

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

Three sentences, front-loaded with the core purpose, then the return shape, then the disambiguation. No filler; every sentence carries information the agent needs.

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

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

With no output schema, the description compensates by naming the return fields (code, name, type, accountClass) and the scoping semantics. Combined with the single fully documented parameter and read-only annotations, nothing essential is missing.

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

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

Schema coverage is 100% and the single 'branch' parameter is fully documented in the schema, including the allowed jurisdiction codes. The description only reinforces the link between 'one jurisdiction' and the parameter without adding syntax or format detail, so the baseline 3 applies.

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

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

Specific verb+resource ('standard chart of accounts') with explicit scope ('for one jurisdiction, sorted by account code') and the returned fields enumerated. An agent can distinguish this from get-trial-balance or search-accounting-transactions purely from the description.

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 routes to alternatives with the selecting condition: 'Use get-trial-balance for a company's account balances, or search-accounting-transactions for the entries in an account.' Both the when-to-use and the when-not-to-use are stated.

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

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

Annotations already establish readOnly/non-destructive/closed-world, so safety is covered. The description adds real behavioral value by disclosing that the response is deliberately trimmed to only id, name and nextFiscalYearEnd — important since there is no output schema to reveal 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?

Two sentences, no filler: the first gives purpose plus return shape, the second gives the prerequisite and the sibling routing. Purpose is front-loaded.

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

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

For a single-parameter read tool with no output schema, the description covers what it does, how to obtain the ID, what comes back, and where to go for adjacent data. Only minor gaps (e.g., behavior when the ID is inaccessible or invalid) remain, which is acceptable for this scope.

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

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

Schema coverage is 100% and the single parameter is fully documented in the schema. The description reinforces 'by ID' and points to list-companies as the ID source, matching but not exceeding the schema's own note. Baseline 3 applies.

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

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

States a specific verb and resource ('Get one company by ID') and immediately delimits the scope with the exact fields returned. It is cleanly distinguishable from sibling list/get tools without opening any schema.

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

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

Gives an explicit prerequisite ('Use list-companies first to find the IDs of companies the user can access') and names two alternatives (get-directors-shareholders, get-corporate-subsidiaries) with the condition that routes to them (ownership and structure). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered; the description adds genuinely useful return-shape information ('each with its name', 'empty list when none are recorded') that no annotation or output schema provides. It omits any note on permissions or scoping of the corporate secretary profile, keeping it out of the top tier.

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

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

Three sentences, zero filler: what it returns, the empty-case behavior, and the sibling routing are each front-loaded and distinct. Nothing redundant with the name or title.

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

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

For a single-parameter read tool with annotations covering safety and no output schema, the description supplies everything needed to invoke it correctly: scope, return shape including the empty case, and where to go for adjacent company data.

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

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

There is a single parameter ('id' as Company ID) and schema description coverage is 100%, so the schema already carries the semantics. The description adds no format, source, or lookup detail (e.g. where to obtain the ID) beyond the schema, which is the expected baseline at full coverage.

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

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

States a specific verb and resource ('List the subsidiaries recorded in a company's corporate secretary profile') and immediately names the adjacent siblings (get-directors-shareholders, get-company), so the agent can tell it apart without opening another schema. No ambiguity about 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?

Explicitly routes the agent to the two closest alternatives for related data (directors/shareholders, company itself), which is strong sibling differentiation. It stops short of stating a when-not condition or prerequisites for using this tool, so it falls just under the top tier.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine context beyond that: it discloses the exact scope of returned data and, notably, that the linked invoice portion is deliberately limited ('IDs, number, status and document links only'), which prevents an agent from expecting a full invoice. It stops short of noting any paging or missing-record behavior, so not a 5.

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

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

Two sentences, zero padding, and the highest-value information (what is returned, and the linked-invoice scope limit) is front-loaded before the sibling routing. Every clause 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?

There is no output schema, so the description must explain return values — and it does so in detail, including the enum of possible statuses and the deliberate truncation of linked-invoice data. Combined with the annotations covering the read-only profile, an agent has everything needed to call this correctly.

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

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

One parameter with 100% schema description coverage ('Credit note ID' plus a digits-only pattern), so the schema already carries the semantics. The description's 'by ID' adds nothing beyond it. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Get one credit note by ID') and enumerates exactly what comes back: status with its enum values, number, issue date, reason, lifecycle timestamps, document links, plus a bounded linked-invoice summary. An agent can distinguish this from every sibling get-*/list-* tool without opening the schema.

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

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

Names three alternatives with the condition that selects each: preview-invoice for the full invoice, create-credit-note to draft, submit-credit-note to apply. It also implicitly rules out preview-invoice for a compact view. This is explicit when/when-not/alternative guidance.

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

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

Annotations already establish readOnly, non-destructive, closed-world behavior. The description adds genuine value beyond them by delimiting the return content (companyUsers with name and role, pending positions marked) and stating what is NOT returned (share counts, IDs, contact details). It omits any note on permissions or completeness of records, keeping it short of a 5.

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

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

Front-loaded with the core purpose, then return shape, then exclusions, then sibling routing. Every sentence carries distinct information with no filler.

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

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

No output schema exists, so the description must describe return values, which it does precisely (companyUsers, name and role fields, Pending marker, omitted fields). It also covers the single input and alternative tools, leaving nothing an agent needs 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?

Only one parameter, already documented at 100% schema coverage (id: Company ID, as returned by list-companies). The description adds no additional semantics about the id beyond what the schema provides, so baseline 3 applies.

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

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

Specific verb plus a precisely scoped resource: people on corporate secretary records holding acting or pending Director, Shareholder, Beneficial Owner, Controller or Agent positions. It is immediately distinguishable from sibling list tools like list-companies or list-customers.

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 routes the agent: use get-corporate-subsidiaries for owned companies and get-company for the company record. This is a clear when-to-use-this vs when-to-use-alternatives statement.

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

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

Annotations already declare a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false), and the description adds substantive context on top: the response is limited to id and name only, explicitly excluding file contents, links, status and extracted details, and it discloses two failure conditions (document missing or not visible to the user). That is real behavioral value beyond the structured fields.

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

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

Four short sentences, each carrying distinct information: purpose, ID source, return shape limits, failure modes, and ID-type disambiguation. Front-loaded with the core action and zero filler.

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

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

With no output schema, the description compensates by enumerating exactly which fields are returned and which are not, plus the error behavior. For a single-parameter read tool this is fully sufficient 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 100% and the single param is self-documenting, so the baseline is 3. The description goes further by defining what the ID is (Core document ID from list-documents) and, critically, what it is NOT (acDocumentId), preventing a common mis-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?

States a specific verb+resource (get one document) and immediately scopes it by the Core document ID that list-documents returns. It also disambiguates from transaction tools by noting Core IDs are not acDocumentId values, so an agent can distinguish it from siblings like get-invoice-document-links or search-accounting-transactions without opening schemas.

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

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

Gives clear context: the ID must come from list-documents, and explicitly warns that acDocumentId values (used by transaction tools) will not work here. It does not spell out a when-not/alternative beyond that ID-source rule, but the routing condition is unambiguous.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), so the description's 'without changing the invoice' is confirmatory. It adds genuinely new behavior context: the exact response shape and the state dependency that both links are null until the invoice is submitted and the document generated — a non-obvious empty-result condition.

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

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

Three sentences, front-loaded with the core action and constraint, then the return shape, then the sibling routing. No filler; every sentence carries information an agent needs.

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

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

There is no output schema, but the description compensates by listing the returned fields and explaining the null-link state, so an agent knows exactly what to expect. Combined with the sibling routing and the 100%-covered id parameter, nothing needed to call this tool correctly is missing.

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

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

Schema description coverage is 100% for the single id parameter ('Invoice ID, as returned by list-invoices'), so the schema does the heavy lifting. The description adds no extra parameter syntax or edge cases (e.g., what happens with an unrecognized id), so the baseline 3 applies.

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

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

States a specific verb (get) and resource (invoice's generated document links) and immediately scopes it ('without changing the invoice'). It even enumerates the exact return fields, so an agent can distinguish it from preview-invoice and generate-invoice-pdf without opening any schema.

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

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

Explicitly routes alternatives: 'Use preview-invoice for the full invoice details, or generate-invoice-pdf to submit a draft and get its links.' It also states the precondition under which the tool is useful (links are null until the invoice is submitted and Classic has generated its document).

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

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

Annotations already establish the safe read-only, closed-world, non-destructive profile. The description adds meaningful behavior beyond that: it defines every returned amount field (awaitingAmount, futurePaymentsAmount, overdueAmount), notes the base currency, and declares the required invoice:read scope.

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

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

Dense and front-loaded: purpose, return shape, scope default, alternative tools, and auth scope in a few tight sentences. 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?

Given no output schema, the description supplies the return fields and their meanings; annotations cover safety; schema covers parameters. An agent has everything needed to choose and call this tool correctly.

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

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

Schema description coverage is 100%, so all three parameters are already documented. The description largely restates movement behavior that the schema already explains and adds no syntax beyond it. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Get unpaid invoice totals for a company') and immediately distinguishes itself from siblings by naming the alternatives for related-but-different goals. An agent can tell this is a summary tool, not a list or an aging report.

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 routes the agent to get-overdue-invoices or get-aged-receivables-v2 for amounts by customer/age and to list-invoices for individual invoices. It also states the scope constraint ('Covers sales invoices unless movement is out') and the required permission, leaving little inference.

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

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

Annotations already declare readOnly, non-destructive, non-open-world. The description goes further and discloses behavior an agent needs that annotations do not: the result is bounded to the first page of up to 100 entries, ordering is by line item, and each record carries only id and amount with no date, accounts, or description. With no output schema present, this is the only place such return-shape limits are communicated.

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

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

Three tight sentences, front-loaded with the core behavior, then the constraint on parameters, then the alternative routing. No sentence is filler; every clause carries selection-relevant 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 single-parameter read tool with no output schema, the description supplies the missing return-value information (page size cap, ordering, field subset) and the sibling routing. Nothing an agent needs to invoke it correctly is absent.

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

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

Schema coverage is 100%, so the single id parameter is fully documented as the company ID. The description reinforces the limited parameter surface by noting there are no date or paging parameters, but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

Specific verb (get) plus resource (journal entries) with explicit scope: first page, up to 100, ordered by line item, only id and amount. It also names the sibling tools it is meant to be distinguished from, so an agent can tell it apart from search-accounting-transactions and get-trial-balance without opening schemas.

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

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

Explicitly routes the agent: use search-accounting-transactions for ledger activity in a date range and get-trial-balance for account balances. It also states what this tool cannot do (no date or paging parameters), which is exactly the when-not guidance that prevents wrong selection.

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

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

Annotations already declare a safe read, but the description adds substantial context beyond them: base-currency conversion at the dateTo rate, negative past-due credit notes meaning a Total can be zero or less, totals collapsing to the overdue Total, and a fallback where an unrecognised layout returns the whole report including Current. It also states the required invoice:read scope, which is auth context an agent needs.

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

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

Front-loaded with the core purpose and output shape before caveats, and nearly every sentence carries non-obvious information (currency handling, negative credit notes, unrecognised-layout fallback). It is dense and run-on in places, and the routing sentence could have come earlier, but there is little waste.

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

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

There is no output schema, yet the description tells the agent what comes back ('Returns report and exchangeRates') and describes the line/column structure and totals, so return-value burden is fully covered. Combined with the auth scope, exclusion of not-yet-due amounts, and fallback behaviour, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, and the description goes beyond it by establishing that dateTo is the as-of date and the exchange rate date ('as of dateTo ... at the dateTo rate'). dateFrom is never mentioned in the description, leaving one parameter to the schema alone, which keeps it from a 5.

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

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

States a specific verb and resource (get the overdue portion of a company's aged receivables v2 report as of dateTo) and defines the exact shape returned: one group per customer with past-due lines. It explicitly distinguishes itself from get-aged-receivables-v2 and get-invoice-pending-summary, so an agent can choose without opening schemas.

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

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

Names both alternatives and the condition that selects each ('use get-aged-receivables-v2 for the full aging or get-invoice-pending-summary for the overdue total only'). It also tells the agent when NOT to expect useful output ('amounts not yet due are left out, so an empty groups list means nothing is overdue').

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, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds real behavioral context: the date range is mandatory and the response is scoped to the report only (no unreconciled-data or multicurrency flags), which is beyond what the annotations say. It stops short of describing result shape or size.

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?

Four short sentences, front-loaded with what the tool does before the routing rules. No filler; each sentence either defines the output scope or routes to a specific alternative.

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 3-param, read-only report tool with no output schema and full annotation coverage, this is nearly complete: caller gets scope, prerequisites (required dates), and alternatives. The only thin spot is the return payload — 'Returns only report' doesn't indicate structure — but that is a minor gap for a report endpoint.

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

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

Schema description coverage is 100% (id = Company ID, dateFrom/dateTo = YYYY-MM-DD), so the schema carries parameter meaning; the description only reinforces that the range is required versus v2's optional range. Baseline 3 is appropriate given the schema does the heavy lifting.

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

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

States a specific verb (Get) plus resource (original profit and loss / income statement) for a company over a required date range. It also names the exact sibling it differs from (get-profit-and-loss-v2) and two adjacent report tools, so the agent can disambiguate without opening any schema.

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

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

Explicit routing: use this one when the date range is required and you only need the report; use get-profit-and-loss-v2 when the range is optional (defaults to YTD) or extra flags (containsUnreconciledData, hasMulticurrency) are needed; use get-balance-sheet / get-trial-balance for other financial statements. Covers when, when-not, and alternatives.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds the invoice:read scope requirement and discloses that the return includes containsUnreconciledData and hasMulticurrency flags, useful behavioral context 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?

Four sentences, front-loaded with the purpose, then defaults, returns, alternatives, and scope. Every sentence carries distinct information 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 report tool with no output schema and annotations covering safety, the description supplies purpose, defaults, return flags, alternatives, and required scope. Nothing critical for correct invocation appears missing.

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

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

Schema description coverage is 100%, so all three parameters (companyId, dateFrom, dateTo) are fully documented in the schema. The description only notes that dates are optional and default to year to date, adding marginal value beyond the schema's default explanations.

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

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

States a specific verb and resource ('Get the profit and loss v2 report for a company') and explicitly names sibling reports it is not, so an agent can distinguish it from get-profit-and-loss, get-revenue-summary, and get-balance-sheet without opening schemas.

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

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

Provides explicit routing: use get-profit-and-loss for the original report over a required range, get-revenue-summary for this report defaulting to the current quarter, and get-balance-sheet for assets and liabilities. Also states date defaults (year to date), covering when and how to use it.

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

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

Beyond the readOnly/non-destructive/closed-world annotations, the description discloses the authorization prerequisite ('Requires the invoice:read scope') and warns that the payload is the entire report rather than a scalar summary, which is exactly the kind of expectation-setting the annotations cannot convey. These are concrete operational details an agent needs before calling.

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

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

Three tight sentences, front-loaded with the purpose and default behavior, then the sibling comparison, then the scope requirement. 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?

With no output schema, the description compensates by stating what is returned (the full P&L v2 report with the same fields as its sibling) and the required scope. Combined with 100% parameter coverage in the schema, an agent has everything needed to select and 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 description coverage is 100% and every parameter (companyId, dateFrom, dateTo, period) is documented in the schema, so the baseline is 3. The description only restates the default window ('current quarter to date'), which largely duplicates the period/dateTo defaults already described in the schema, adding little new parameter 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?

Names a specific verb and resource ('Get the profit and loss v2 report') and immediately frames it against its closest sibling by stating it calls the same endpoint and returns the same fields as get-profit-and-loss-v2, with only the default dates differing. It also corrects the likely misreading of the name by clarifying it returns the full report, not a single revenue figure.

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

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

Gives a clear use context ('for revenue questions', defaulting to current quarter to date) and names the alternative (get-profit-and-loss-v2) with the exact distinction between them. It stops short of an explicit routing rule such as 'use this when the user gives no date range; otherwise use get-profit-and-loss-v2', so the agent must infer which to pick when dates are supplied.

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

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

Annotations cover only the read-only/non-destructive safety profile, and the description adds substantive behavior the agent cannot get elsewhere: the return shape (conversation plus messages with text, createdAt, sender), the default page of 50, the paging mechanism, and the null-conversation edge case for transactions without comments.

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?

Four dense sentences with no filler: what it reads, what it returns, how paging works, and where the sibling tools fit. The core action is front-loaded in the first clause.

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

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

No output schema exists, yet the description describes the returned payload and its edge case (null conversation) precisely, and it covers the paging workflow for a 5-parameter tool. Nothing an agent needs to call it correctly is absent.

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

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

Schema coverage is 100% and already documents limit, createdBefore and createdAfter, so the baseline is 3; the description goes slightly further by framing createdBefore as the paging cursor ('pass the oldest createdAt you have'), but the 50 default and ISO format notes largely restate the schema.

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

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

States a specific verb and resource ('Read the comments on one transaction') plus ordering ('oldest first') and explicitly names add-transaction-comment and search-transactions as the tools for related tasks, so it is distinguishable from every sibling without opening a schema.

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

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

Gives explicit routing advice: use add-transaction-comment to post, search-transactions to obtain the transactionId, and pass the oldest createdAt as createdBefore for paging. When-to-use and which-alternative conditions are both stated.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered and the description correctly does not restate it. The description still adds genuine behavioral value by disclosing the filtering rule ('leaving out accounts with no entries') and the exact shape of the returned report. It does not mention pagination or result-size behaviour, which is the only remaining gap.

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

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

Three sentences, zero filler, and front-loaded with the core action before the return shape and the disambiguation list. Every clause carries information the agent needs to select and call the tool correctly.

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

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

With no output schema, the description compensates by fully describing the return payload (one line per ledger account plus the per-line fields). Combined with 100% schema coverage on all three required parameters and annotations covering the safety profile, nothing material is missing.

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

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

Schema description coverage is 100%, so id, dateFrom and dateTo are already documented, including the YYYY-MM-DD format and inclusive endpoints. The description only reiterates that the period is required and that both days are included, which adds no syntax or meaning beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Get a company's trial balance') scoped to a required period, then enumerates exactly what each line contains (account code, name, type, debits, credits, net movement, opening/closing balances). This is precise enough that an agent can distinguish it from get-balance-sheet or get-journal-entries without opening any schema.

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

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

Explicitly routes the agent: 'Use it for account-level balances and movements; use get-balance-sheet or get-profit-and-loss for the summarised statements, get-chart-of-accounts for the account list without balances, or search-accounting-transactions for the entries behind a balance.' This names four alternatives and the condition that selects each, which is the strongest form of usage guidance.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), and the description goes well beyond them: a hard cap of 25 results, no paging and no search, and the concrete consequence that a user with more companies silently sees only the 25 most recently created. That truncation warning is exactly the kind of behavior an agent cannot infer from annotations or an empty schema.

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

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

Two sentences, front-loaded with what is returned and in what order, then the routing guidance. Every clause carries information: limit, absence of paging/search, truncation consequence, and the ID-discovery 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?

There is no output schema, and the description compensates by specifying the return shape ('only its id and name') and the ordering. Combined with the truncation warning and the cross-tool routing, an agent has everything needed to call this correctly on the first attempt.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing further for the description to disambiguate. The description does not waste words inventing parameter detail, which is appropriate 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?

States a specific verb and resource ('List the companies the signed-in user can access'), plus scope (accessible to signed-in user), ordering (newest first), and returned fields (id and name only). It is clearly distinguishable from the sibling get-company and from the other list-* 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?

Explicitly says to 'Call it first to find the company ID that other tools take as id or companyId', giving a concrete ordering prerequisite relative to siblings. It also names the alternative for a different need: 'use get-company for a company's next fiscal year end.'

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, openWorldHint=false, and destructiveHint=false, so safety is covered. The description adds useful behavioral context by mentioning pagination fields, totalCount, and how returned ids feed into update-invoice-draft, which goes beyond the annotation set.

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 compact sentences, front-loaded with the list operation and followed by workflow guidance. There is no redundant or filler language.

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

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

For a read-only list tool with full schema coverage and safety annotations, this gives enough context: what is listed, that results page, and how to use the returned id downstream. No output schema exists, so return-value details are not required, and the description still covers key pagination response fields.

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

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

Schema description coverage is 100%, so page, perPage, search, and companyId are already documented in the schema. The description mentions paging but adds no syntax or meaning beyond the schema, making the baseline 3 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?

States a specific verb and resource, 'List a company's invoice customers', and scopes it to invoice customers of a given company. It also names the sibling tools update-invoice-draft and create-customer, helping distinguish this lookup from create/update 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 tells the agent to use a returned customer id as customerId in update-invoice-draft and to use create-customer when the customer does not exist yet. This gives clear downstream usage and an alternative for the missing-customer case, though it does not spell out when not to call this list 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 already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: ordering (oldest first), the absence of a total count, and the exact pagination termination rule (stop when a page returns fewer than perPage items). It stops short of noting permissions/rate limits, but the pagination disclosure is substantive.

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

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

Two sentences, front-loaded with what the tool returns and how it pages, then the sibling routing. Every clause carries information; nothing is filler.

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

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

With no output schema, the description carries the burden of explaining returns and does so (only Core document id and name, no total count) plus the pagination loop needed to enumerate fully. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so page/perPage defaults and the company id are already documented, setting the baseline at 3. The description adds value by tying perPage to the pagination stop condition, giving the parameter behavioral meaning beyond its schema definition.

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

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

States a specific verb and resource ('List the documents stored for a company') with scope qualifiers ('that the user can see', ordered oldest first, paged). It is immediately distinguishable from get-document, list-invoices, and prepare-document-upload, which it names explicitly.

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

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

Explicitly routes the agent: use get-document for a single lookup by ID, list-invoices for sales invoice details, prepare-document-upload to add a file. The when-to-use-this-tool case is implied by the scoping statement, and the alternatives are all named with their 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?

The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: results are 'newest first' and include status, recipient, dates, line items, totals, document links, plus page and perPage. It does not mention auth needs, rate limits, or pagination edge cases, but its added value over the annotations is solid.

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

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

Two sentences with no waste. The primary purpose, return content, and sorting rule are front-loaded, and the alternative-tool routing follows immediately. 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 no output schema, the description appropriately explains the return shape: invoices with status, recipient, dates, line items, totals, document links, plus page and perPage. Combined with the 100% schema coverage and complete annotations, an agent has enough information to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters in detail, including the important search caveat. The description adds no parameter-specific meaning beyond what the schema provides. Baseline 3 applies when the schema carries the parameter burden.

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 and resource: 'List a company's sales invoices from Osome invoicing, newest first.' It also distinguishes this tool from siblings by naming what it is not for: 'get-overdue-invoices or get-invoice-pending-summary for receivables from the accounting ledger.' An agent can tell it apart from those tools without opening a schema.

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

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

It explicitly routes the agent to alternatives: 'Use get-overdue-invoices or get-invoice-pending-summary for receivables from the accounting ledger, and preview-invoice to read one invoice.' This gives both when-to-use and when-not-to-use guidance with named siblings.

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

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

Annotations already establish that this is a read-only, non-destructive, non-open-world operation, and the description adds useful behavior: suggestions are returned best first, each includes accountId, name, source, and accuracy confidence, and the list can be empty. This covers the return variability and output shape that matter for an agent deciding how to act. No annotation contradiction is 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?

The description is front-loaded with the core action, followed by ranking inputs, return shape, and downstream alternatives. Every sentence contributes useful information, and there is no redundant restatement of the tool name or annotations.

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

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

There is no output schema, but the description explains the return structure and that the list may be empty. Annotations cover the safety profile, and the 100%-covered input schema documents all six parameters. The definition gives an agent everything needed to invoke and interpret the 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 description coverage is 100%, so the baseline is 3 even without extra parameter detail in the description. The description reinforces that description and vendorName are ranking inputs, but the schema already documents those same roles and additionally covers topK constraints and the vendorContactId caveat. The description adds little semantic value 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 a specific verb and resource: asking Osome's model which account to cashcode a bank transaction to, and returning ranked account recommendations. It distinguishes the operation from downstream siblings by naming apply-transaction-cashcoding-recommendation and add-transaction-comment. An agent can tell what this tool does without opening the schema.

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

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

The description explicitly says to apply a recommendation with apply-transaction-cashcoding-recommendation and to use add-transaction-comment when none fits. It also clarifies that the optional description and vendorName can be passed to influence ranking. The when-to-use and alternative paths are stated rather than inferred.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), and the description adds substantial behavior beyond them: the return shape (presigned target, form fields, uploadToken) and the prohibition on sending bytes/headers/contentBase64 to MCP. It stops short of disclosing token expiry, auth requirements, or re-call behavior, so a 4 rather than a 5.

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

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

Three tight sentences, front-loaded with 'Step 1', and every sentence carries a distinct directive (precondition, return shape, upload mechanics, next call, prohibitions). No filler.

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

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

With no output schema, the description correctly explains the return value (presigned POST target, form fields, uploadToken) and the full two-step flow, which is exactly what an agent needs to invoke this correctly within the upload pipeline.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning by tying the checksum parameter to the upload step ('include Content-MD5/checksum fields exactly when present') and explaining how the returned form fields must be submitted. That mapping is not evident from the schema's '32-character MD5 hex digest' 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?

It states a specific verb+resource ('Step 1 of document upload') and precisely what it produces: a presigned POST target with form fields and an uploadToken. It clearly distinguishes itself from the sibling complete-document-upload, which it names as the next step.

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

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

Explicit sequencing: 'Call before uploading bytes' and 'then call complete-document-upload' name the alternative and the condition that selects it. It also gives exclusions ('Never send contentBase64, arbitrary upload headers, or file bytes to MCP'), so nothing is left to inference.

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

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

Annotations already declare readOnlyHint, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds behavioral context beyond annotations: it works for any invoice status including drafts, and document links appear only 'once generated,' which helps the agent interpret return state.

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

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

Front-loads the core action and return scope, then adds status coverage and routing guidance in two efficient sentences. No filler; every sentence adds needed 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 one-parameter read-only tool with no output schema and safety annotations already in place, the description supplies purpose, when-to-use, alternatives, return contents, and status behavior. Nothing essential is missing.

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

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

Schema description coverage is 100%, so the single 'id' parameter is fully documented as 'Invoice ID' with a pattern. The description adds no syntax or format meaning beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb ('Get') and resource ('one invoice by ID') and enumerates the full stored details returned. Distinguishes itself from siblings like get-invoice-document-links by scoping to the complete invoice record rather than just links.

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 when to use it: 'to check a draft before submit-invoice' and when not to use it: 'get-invoice-document-links when you only need the links.' It also clarifies it works for any status, including drafts, removing ambiguity.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds genuinely new behavioral context: the output is report-style data grouped by account rather than a flat transaction list, and there is an implicit 90-day lookback window. It does not mention pagination behavior beyond the schema's limit default.

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?

Four short sentences, each earning its place: purpose, output shape, default window, and alternative routing. The most decision-relevant information (what it returns, the default range) is front-loaded.

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

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

There is no output schema, but the description compensates by stating the return shape ('report-style data grouped by account'). Combined with the default date window and the sibling routing rule, an agent has everything needed to call this tool correctly.

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

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

Schema coverage is 100%, so all four parameters are already documented, which sets the baseline at 3. The description goes beyond the schema by specifying the 90-day default date window, which the schema does not state for dateFrom/dateTo, adding real parameter-level value.

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

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

States a specific verb and resource ('Search accounting ledger transactions') plus the grouping scope ('for a company'). It explicitly names the sibling it is not (search-transactions), so an agent can disambiguate the two without opening either schema.

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

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

Gives an explicit routing rule: use search-transactions instead when transaction IDs are needed for commenting. It also states the default behavior (last 90 days) that applies when no date range is supplied, which is the main decision an agent must make when calling this tool.

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

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

Annotations already cover the safety profile (read-only, closed-world, non-destructive), and the description adds behavior the annotations cannot: newest-first sort, paging model, totalCount, inclusive date bounds, and the meaning of the documentRequired status. That is exactly the extra context the annotations leave out.

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

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

Three dense sentences, each earning its place: what it returns first, then the field list (needed because there is no output schema), then cross-tool routing and the exclusion. No filler and the key scope is front-loaded.

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 enumerating returned fields and the status semantics, and it covers ordering, paging, and date-bound inclusivity. An agent has everything required to call it and interpret the result correctly.

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

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

Schema coverage is 100%, so the schema already documents all five parameters and the baseline would be 3. The description adds genuine semantics not in the schema, notably that dateFrom and dateTo are inclusive bounds, which affects how an agent constructs 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?

States a specific verb and resource ('List a company's bank statement transactions') plus scope details: newest-first ordering, pagination, and totalCount. It explicitly separates itself from search-accounting-transactions, so an agent can pick the right tool without opening the schema.

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

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

Names the alternative ('For ledger entries in every account, use search-accounting-transactions') and states when it does not apply ('It has no text search'). It also routes the returned acDocumentId to three named downstream tools, giving concrete follow-up guidance.

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

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

Annotations declare destructiveHint=true and openWorldHint=true, and the description meaningfully enriches them: it discloses the resulting state (becomes applied), that the invoice is cancelled unless already paid, and that external PEPPOL delivery and IRAS reporting may be queued. This tells the agent exactly what side effects and external consequences to expect.

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

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

Three front-loaded sentences with no filler: state change and effect first, external workflow second, confirmation requirement last. Slightly longer than strictly necessary but each 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?

For a destructive, open-world submission tool with no output schema, the description covers the resulting state, the side effects on the linked invoice, external delivery/reporting, and the required user confirmation. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters (id, companyId, issueDate, reason, creditNoteNumber) including defaults and patterns. The description adds no additional parameter-level semantics, so the 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?

States a specific verb (Submit) and resource (draft credit note), ties it to its origin (from create-credit-note), and precisely distinguishes this submission step from the creation step in the sibling list. An agent can tell it apart from create-credit-note and get-credit-note without opening a schema.

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

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

The 'from create-credit-note' phrasing establishes the prerequisite workflow, and the description conditions when effects apply ('unless already paid'). It also instructs on confirmation, but does not explicitly name alternatives or when-not-to-use beyond the 'already paid' caveat.

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 side effects well beyond the annotations: it warns that "sent" does not mean an email was delivered, and that submission may queue InvoiceNow delivery via PEPPOL and IRAS reporting depending on stored settings. For a destructiveHint=true, openWorldHint=true action this external-effect disclosure is exactly what the agent needs.

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?

Four sentences, front-loaded with the core action and its state semantics, then prerequisite, then side effects. Every sentence carries information, though the delivery/reporting sentence could be tightened slightly.

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 only terse annotations, the description covers the action, its state meaning, prerequisites, external side effects, and a confirmation step. It is nearly complete for this destructive, open-world operation, leaving only return-value behavior unaddressed, which is not required.

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 67% and the schema already documents id, companyId, and the invoice fields. The description adds only the lineItems prerequisite, which concerns a different tool, and does not clarify the three actual parameters. 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?

States a specific verb+resource ("Finalize a draft invoice and mark it as sent") and immediately clarifies the semantics of the resulting state. It differentiates itself from siblings like create-invoice-draft, preview-invoice, and update-invoice-draft by naming the draft workflow it completes.

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

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

It gives a concrete prerequisite ("Requires lineItems to already be set via update-invoice-draft") and an explicit confirmation instruction, which is clear when-to-use context. It stops short of an explicit alternative/exclusion map beyond the prerequisite relationship.

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

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

Beyond the annotations, the description explains overwrite semantics, array replacement versus null preservation for lineItems and paymentMethods, recalculation and customer refresh behavior, draft-only scope, and the invoice:write requirement. These details are highly relevant for a destructive update 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 front-loaded with the core action and then covers overwrite behavior, alternatives, and authorization in compact sentences. Every sentence adds useful operational context without 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 nested destructive update tool with no output schema, it provides enough context to call correctly: draft constraint, replacement semantics, recalculation behavior, dependency on submit-invoice, alternative for issued invoices, and required scope.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds important meaning: fields omitted keep stored values, arrays replace whole lists, and null preserves stored lists. It also notes that lineItems must be set here before submit-invoice can finalize.

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

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

The description states a specific verb and resource — changing fields on a draft invoice and returning the updated invoice. It also distinguishes the operation from submit-invoice and create-credit-note, so an agent can select it confidently 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?

It explicitly limits use to drafts, says it does not submit or email, and names the correct alternatives: submit-invoice for finalization and create-credit-note for issued invoices. The required scope is also stated.

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