Osome

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

Annotations already declare the safety profile (mutating but non-destructive, closed-world). The description usefully adds a non-obvious side effect — the conversation is created when absent — which annotations cannot convey. However, it is silent on whether the posted comment is editable, permission requirements, and why a comment-creating tool accepts limit/createdAfter/createdBefore, suggesting it also returns a comment list.

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 short sentences, front-loaded with the primary action, and the side-effect caveat follows immediately. 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?

The description covers the core action and the auto-creation side effect, and annotations carry the safety profile with no output schema needing explanation. The gap is the unexplained read-back parameters, which leave an agent unsure whether the call returns a comment list and how filtering applies.

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 schema fully documents the 6 parameters. The description adds no parameter-level meaning and notably does not explain the presence of read-oriented filters (limit, createdAfter, createdBefore) on a write tool.

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

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

States a specific verb and resource ('Add a text comment to a transaction conversation') plus the AcDocument conversation auto-creation behavior. It implicitly contrasts with the read-only sibling get-transaction-conversation, but never names it, so sibling differentiation is left to inference.

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

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

Usage is implied by the verb: use this to post a comment rather than read one. There is no explicit when-to-use statement, no mention of when to prefer get-transaction-conversation, and no prerequisites or exclusions.

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

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

Annotations only give the generic readOnly=false/destructive=false/openWorld=false profile, so the description must add context and it does: it discloses the auth scope requirement and the underlying Classic reconcile behavior being reused. It stops short of saying what the call mutates on the transaction beyond the account pick, or whether it is idempotent.

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 action and the endpoint it maps to, with the required scope last. Only mild jargon ('Websome', 'Classic') adds friction, but nothing is wasted.

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 the precondition and permission but says nothing about the result of a successful apply (e.g. what is updated on the transaction or what response to expect). Adequate but leaves a real gap.

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

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

Schema description coverage is 100%, so parameters are fully documented in structured fields and the description only reinforces the source of accountId. It adds no syntax or constraint detail beyond what the schema already provides, which is the baseline expectation 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 precise verb+resource: applying a cashcoding account recommendation to a transaction, and names the exact endpoint semantics it mirrors ('Classic cashcoding reconcile endpoint as the Websome transaction page'). This clearly separates it from the read-only sibling list-transaction-cashcoding-recommendations.

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 instructs the agent to pass an accountId obtained from list-transaction-cashcoding-recommendations and states the required permission scope (company:documents:write), which is a real prerequisite. It does not state when not to use it or what happens if the transaction already has an account.

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

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

Annotations already declare this as a non-destructive, closed-world write, so the description is not burdened with the safety profile. It usefully adds behavioral context the annotations lack: it must run after the byte upload and requires the short-lived uploadToken to be passed unchanged.

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 workflow position, then the precondition, then the parameter instruction. 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 write tool with full schema coverage, annotations, and no output schema, the description supplies the crucial sequencing and token-reuse context. Minor gaps around error/expiry handling remain but are not essential to correct invocation.

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

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

Schema coverage is 100%, so parameters are already documented. The description still adds meaning by requiring that the same metadata be passed (cross-step consistency with prepare-document-upload), which is not apparent from the schema alone.

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

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

States a specific action (create the Classic document) tied to a precise workflow position (Step 3 of document upload), and by naming the prepare-document-upload prerequisite it separates itself cleanly from its sibling. An agent can tell what this does and where it sits in the flow.

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

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

Explicitly states the precondition 'Call only after bytes were uploaded to the presigned POST target from prepare-document-upload,' giving a clear trigger. It stops short of naming failure modes or what to do if the upload/token has expired, so it is strong but not exhaustive.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-open-world write operation. The description adds that the result is a draft and that it serves as an alternative to deletion, which is useful context, but it does not disclose permissions, side effects on the original invoice, or what the draft entails.

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

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

A single front-loaded sentence with the verb first and zero wasted words. It is appropriately sized for a simple two-parameter creation tool.

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

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

Given the simple schema, full parameter coverage, and annotations that cover the safety profile, the description supplies the key missing context: it creates a draft for an issued invoice rather than deleting it. It does not explain follow-up steps or the resulting draft's lifecycle, but no output schema exists and the core invocation requirements are covered.

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 both parameters are already documented in the schema. The description mentions the invoice implicitly but adds no format, constraint, or meaning beyond what the schema provides.

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

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

States a specific verb (Create) and resource (draft credit note) scoped to an issued invoice. The word 'draft' distinguishes it from the sibling submit-credit-note, and 'instead of deleting the invoice' differentiates it from a deletion operation.

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

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

Provides clear context for when to use it: to address an issued invoice without deleting it. It names deleting the invoice as the alternative, but does not explicitly name sibling tools like submit-credit-note or get-credit-note, nor does it state 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 already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the write nature is covered. The description adds a genuinely useful return-value contract (the id is the invoice customerId), which matters because there is no output schema, but says nothing about permissions, duplicate handling, or whether existing customers are affected.

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 short sentences, front-loaded with the action and followed by the one piece of chaining information that matters. No filler, though at this level of schema complexity it is terse almost to the point of under-specification.

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?

A mutation tool with nested objects, no output schema, and half its parameters undocumented needs more from the description. The return-id note is valuable, but the required nested fields, the customer type semantics, and any duplicate/permission behavior are left entirely to the schema.

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

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

Schema coverage is 50%: only companyId is described. The description's 'for a company' loosely maps to companyId but adds no format or constraint detail, and it says nothing about the large nested customer object, including the required name/type fields and the individual/company enum. It does not compensate for the coverage gap.

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

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

States a specific verb and resource ('Create an invoice customer') plus the scope modifier 'for a company', which separates it from siblings like create-invoice-draft or create-credit-note. It does not explicitly contrast with list-customers, but the verb+resource make the intent unambiguous.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no named alternative. The second sentence implies a workflow ('Use the returned id as invoice customerId'), which hints at when this tool is called relative to invoice creation, but the agent must infer the rest.

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 mutation profile and closed-world scope are covered by structured data. The description's only added behavioral signal is the word 'draft', which implies a non-finalized record that can later be edited or submitted, but it does not state side effects, whether anything is posted to the ledger, or whether the call is idempotent.

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

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

It is a single sentence with no filler and the verb-resource pair is front-loaded, which is appropriate for a one-parameter tool. The brevity tips into under-specification, but no sentence is wasted.

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

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

For a simple one-required-parameter create with full schema coverage and no output schema, minimal prose is defensible. Missing context is the shape of the created draft (line items, dates, amounts, defaults), whether it is immediately editable, and how it relates to submit-invoice, all of which the agent would need to know to proceed after the call.

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 companyId parameter, so the schema already carries the parameter documentation and the baseline of 3 applies. The description adds nothing about the parameter, leaving any format or lookup requirements entirely to 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 names a specific verb and resource ('Create a draft invoice') and scopes it to a company, so an agent knows what it produces. It does not, however, distinguish itself from close siblings such as submit-invoice, update-invoice-draft, duplicate-invoice, or create-credit-note, so the 'draft' vs 'submitted' boundary is left implicit.

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

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

There is no explicit when-to-use guidance, no mention of prerequisites (companyId must reference an existing company), and no routing to alternatives. The natural workflow (create draft, then update-invoice-draft, then submit-invoice) is never stated, so the agent must infer it from sibling names.

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 write, non-destructive, closed-world behavior, lowering the burden. The description adds a useful detail: the result is a new draft (not submitted, original untouched), aligning with destructiveHint=false. It does not state what fields carry over or whether permissions beyond the ids are needed.

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

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

A single front-loaded sentence with no waste. It is efficient, though arguably a touch terse given the mutation it performs.

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

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

For a simple two-param tool with annotations covering the safety profile and full schema coverage, the essentials are present. It omits what gets copied into the draft and the resulting state, which would have added value.

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 both id and companyId are documented in the schema. The description adds no format or syntax detail beyond that, so the baseline of 3 is appropriate.

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

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

The description states a specific verb (duplicate) and resource (invoice) and clarifies the output is a new draft. That distinguishes it somewhat from create-invoice-draft, but it does not explicitly name or contrast with the siblings it could be confused with.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as create-invoice-draft or preview-invoice. The agent must infer the use case entirely from the tool name.

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: submitted status does not imply email delivery, submission mutates invoice state, requires lineItems/details pre-set via update-invoice-draft, and may queue PEPPOL/IRAS external delivery and reporting.

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?

Five dense sentences, all front-loaded and each carrying a distinct warning (delivery semantics, state change, prerequisites, external side effects, alternatives). Slightly long but no sentence is wasted.

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 write with no output schema, the description covers the state change, delivery caveats, prerequisites, external reporting, and return content (document links), leaving nothing essential unstated.

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

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

Schema description coverage is 67%, so the schema carries most parameter meaning. The description adds the prerequisite relationship (invoice details and lineItems already set via update-invoice-draft) but does not clarify the nested invoice object or ID formats.

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+resource ('Submit a draft invoice and return its document links, or return existing links for a non-draft invoice') and explicitly differentiates the dual behavior. An agent can distinguish this from preview-invoice and get-invoice-document-links 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 names both alternatives and the conditions that select them: 'Use preview-invoice to inspect a draft without submission, or get-invoice-document-links to retrieve links without submission.' It also states a hard gate: 'Confirm the user intends to submit.'

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 only the optional date-scoping behavior; it says nothing about permission requirements, default period when no dates are given, or the report's structure. With annotations doing the heavy lifting, this is minimum-viable rather than rich.

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

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

A single front-loaded sentence with no filler; the only mild redundancy is repeating 'aged payables' as 'accounts payable aging' in parentheses. Efficient and easy to parse at a glance.

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

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

For a simple read-only reporting call with fully described parameters, the description is sufficient to invoke correctly. However, with no output schema present, it gives no indication of the report's return shape or what happens when the optional date range is omitted, leaving a modest gap.

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

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

Schema description coverage is 100%, so 'id', 'dateTo' and 'dateFrom' are all documented with types and YYYY-MM-DD format in the schema. The description's mention of date-range filtering mirrors that, adding no syntax or semantics beyond the schema; 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 (Generate) and resource (aged payables / accounts payable aging report), with the parenthetical resolving the domain term. It is distinguishable from the sibling get-aged-receivables by name, but the description never explicitly contrasts itself with that near-twin tool.

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

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

The phrase 'optionally filtered by date range' implies the tool's reporting use case and that the date filter is discretionary, but there is no when-to-use/when-not guidance and no reference to the receivables counterpart or other reporting 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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that this is a generated (computed) report with optional scoping, but says nothing about aging bucket conventions (30/60/90+), point-in-time vs live data, or timezone handling of as-of dates.

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

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

A single well-formed sentence with the action and object front-loaded and the optional filter appended. No waste, though it is terse enough that it omits routing information it arguably has room for.

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

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

There is no output schema, so the description carries some burden for explaining what the report contains, yet it never mentions the aging buckets or report shape. Combined with the 100%-covered input schema and read-only annotations, it is minimally viable but leaves the v1/v2 routing question unresolved.

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, dateFrom, dateTo all documented with formats), so the schema already does the heavy lifting. The description only restates the date-range filter concept without adding format, default, or inclusive/exclusive semantics — 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 (Generate) and resource (aged receivables / AR aging report) scoped to a company. It is separable from get-aged-payables by resource name, but it never distinguishes itself from the sibling get-aged-receivables-v2, leaving ambiguity about which version an agent should call.

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

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

'Optionally filtered by date range' hints at a use case but gives no explicit when-to-use, when-not-to-use, or alternative selection guidance. Critically, the existence of get-aged-receivables-v2 is never acknowledged, so the agent has no basis for choosing between the two.

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), so the safety profile is covered. The description adds essentially nothing beyond that: no mention of date-range defaults, whether the range is inclusive, or what the report contains. Minimal added behavioral context.

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

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

A single clear sentence that is front-loaded and wastes no words. It is appropriately short, though brevity comes at the cost of missing necessary routing and behavioral detail.

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-generation tool in a crowded accounting toolset with a closely named sibling, the description omits the when-to-use context, the v2 distinction, and any behavioral notes. It is under-specified for the complexity present.

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

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

Schema description coverage is 100%, so each parameter (companyId, dateFrom, dateTo) is already documented with types and formats. The description adds no additional parameter meaning, 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 (Generate) and resource (aged receivables v2 report). However, it does not distinguish from its near-identical sibling get-aged-receivables despite the v2 suffix, leaving the agent unable to tell why v2 exists or differs.

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?

No when-to-use guidance, no prerequisites, and no mention of the sibling get-aged-receivables that appears to do the same thing. The agent is left to guess which of the two to call.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is clear. The description adds the YTD defaulting behavior, which is genuinely useful context, but says nothing about report contents or formatting.

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 short sentences with zero waste, front-loading the core purpose before the defaulting behavior. Nothing could be removed without losing information.

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

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

For a low-complexity read-only report with complete parameter docs and full annotations, the essential calling information is present. However, with no output schema, the description does not characterize what the balance sheet report returns, leaving that to the agent's assumptions.

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, and the description adds the fallback behavior for dateFrom/dateTo (defaults to YTD when no range is supplied), which is real semantic value beyond the schema's plain type/format entries.

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

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

States a specific verb (Generate) and resource (balance sheet report) with scope (for a company). It is clearly distinguishable from the financial-statement siblings like get-profit-and-loss and get-cash-flow-statement by name, though it does not explicitly call out the distinction.

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 default-to-YTD note gives some context for how to call it, but there is no explicit when-to-use guidance or routing versus the other report tools (trial balance, P&L, cash flow). Usage is only implied by the report type.

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 fully covered by structured data. The description adds nothing beyond that — no return shape, pagination, sorting, or whether inactive/closed accounts are included — and there is no output schema to compensate.

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

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

A single seven-word sentence with the resource and scope front-loaded and zero filler. Nothing is redundant or padded.

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 lookup with full schema coverage and safety annotations, the description is minimally sufficient. It is thin on return content (no output schema exists) and on how the company ID should be obtained, leaving small but real gaps.

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

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

Schema description coverage is 100%, with the single 'id' parameter documented as 'Company ID'. The description adds no syntax, format, or sourcing guidance beyond that, 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 ('bank accounts') scoped to 'a company', which is clear enough to distinguish from most siblings like get-invoice-pending-summary or list-documents. However, it offers no differentiation from adjacent accounting lookups such as get-chart-of-accounts, with which bank accounts could plausibly be confused.

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

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

There is no when-to-use guidance, no mention of prerequisites (e.g., needing a valid company ID from list-companies), and no named alternative for related lookups. The agent must infer usage entirely from the name and schema.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds essentially nothing behavioral beyond that — no mention of whether figures are live/preliminary, authorization needs, or comparison behavior.

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

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

Two short sentences with the purpose front-loaded and the constraint following. No wasted words, though the brevity is close to under-specification rather than optimal conciseness.

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

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

No output schema exists, so the description could have explained the return shape (a cash flow statement's structure). It covers inputs adequately via the schema but leaves the output side entirely to inference for a financial-report tool.

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

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

Schema coverage is 100%, so all three parameters are documented in the schema itself. The description only restates the date-range requirement and adds no syntax or format detail 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?

States a specific verb+resource: 'Generate a cash flow statement for a company.' The resource (cash flow statement) is distinct from siblings like get-balance-sheet or get-profit-and-loss, so an agent can tell them apart. It does not explicitly name alternatives, which keeps it at 4 rather than 5.

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

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

'Requires a date range' gives a precondition, implying usage for period-based financial reporting. However, it offers no when-to-use vs alternatives (e.g., balance sheet or P&L) and no exclusions, leaving usage 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, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds only branch-scoping context, and says nothing about the shape, breadth, or currency of the returned account list.

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?

One short sentence, front-loaded with the verb and resource, containing zero filler. Nothing could be removed without losing information.

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

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

For a simple single-parameter read tool whose annotations already cover the safety profile and whose param is fully documented, the description is close to sufficient, though with no output schema it could say a little about what the chart of accounts contains.

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 the single branch parameter is documented with the same 'e.g. SG, HK, UK' examples repeated verbatim in the description, so no meaning is added beyond the schema. Baseline 3 applies for a fully documented parameter.

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

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

States a specific verb and resource ('Get the chart of accounts') with an explicit scope qualifier ('for a branch'). It is clearly distinguishable from sibling reads such as get-trial-balance or get-journal-entries, though it never names an alternative to contrast with.

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?

No when-to-use or when-not-to-use guidance, no mention of prerequisites or alternatives among the many sibling get-* reporting tools. The '(e.g. SG, HK, UK)' example is the only contextual hint, and it describes parameter format rather than usage.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that surface: no note on behavior for an unknown ID, no auth/permission context, and no indication of what 'details' comprise.

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

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

A single tight sentence with the verb and resource front-loaded and zero filler. Appropriate length for a one-parameter lookup tool.

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

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

For a simple single-param read tool with safety annotations already present and no output schema, this is minimally adequate. It never says what fields 'details' returns or how it behaves on a missing/invalid ID, leaving some gaps 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?

Schema description coverage is 100% for the single parameter ('Company ID'), so the schema already documents it. The description adds no format, syntax, or sourcing detail beyond restating 'by ID', warranting the baseline 3.

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 ('company') scoped to a single entity via 'by ID', which implicitly separates it from the sibling list-companies. It does not, however, explicitly name or distinguish itself from that sibling.

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?

No guidance on when to use this versus list-companies or any other retrieval tool, and no prerequisites mentioned. Usage must be inferred entirely from the name and the 'by ID' phrasing.

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, destructiveHint=false, and openWorldHint=false, covering the safety profile. The description adds no behavioral context beyond that—no details on return scope (direct vs. indirect subsidiaries), pagination, or error conditions.

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

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

The description is a single, front-loaded sentence with no wasted words. It is appropriately concise, though its brevity borders on under-specification for a tool that lacks an output schema.

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

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

There is no output schema, so the description should ideally explain what the tool returns (e.g., a list of subsidiary objects and their fields). It also omits any usage context or return format, leaving significant gaps for an agent invoking 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%, with the single 'id' parameter documented as 'Company ID'. The description's phrase 'for a company' adds only marginal meaning and provides no syntax or format details beyond what the schema already gives.

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 ('Get') and resource ('subsidiaries for a company'), making the core operation clear. However, it does not distinguish this tool from related siblings like get-company or get-directors-shareholders, leaving an agent to infer the difference.

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

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

There is no guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions stated. The description only says what it does, not when it should be chosen.

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 nothing beyond that; 'safe invoice summary' is undefined and could be read as a behavioral claim, but it is never explained.

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

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

A single short sentence with the verb front-loaded and no padding. It is efficient, though the trailing 'safe invoice summary' clause is unexplained enough to be slightly wasteful.

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 single-parameter lookup with no output schema, the description partially covers the return ('credit note and safe invoice summary') but leaves 'safe' undefined. An agent can call it correctly, but the meaning of what comes back is only vaguely conveyed.

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 a single required 'id' parameter fully documented in the schema, so the description does not need to compensate. It adds no extra meaning about the ID format or constraints, 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 (credit note), which is clear on its own, but the appended 'and safe invoice summary' is ambiguous jargon that never gets explained. Nothing in the description distinguishes it from siblings like create-credit-note or submit-credit-note beyond the verb.

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

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

There is no indication of when to call this tool versus create-credit-note, submit-credit-note, or get-document. No prerequisites, no context about what a 'safe' summary means or when it is appropriate.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond the word 'Get' — no note on whether data is current or cached, no mention that the company must exist, and no hint about the shape of 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?

A single front-loaded sentence with zero filler; the resource is stated immediately. It is efficient, though its brevity edges toward under-specification rather than exemplary conciseness.

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

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

For a one-parameter, read-only lookup with no output schema, the description is minimally adequate. It does not describe the returned directors/shareholders structure, but the low complexity and full annotation coverage keep this from being a serious gap.

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

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

Schema description coverage is 100%; the single 'id' parameter is fully documented as 'Company ID'. The phrase 'for a company' merely restates that, adding no format, sourcing, 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?

The description names a specific verb ('Get') and a specific resource ('directors and shareholders'), scoped to a company, so an agent can distinguish it from get-company, get-corporate-subsidiaries, and other get-* siblings. It stops short of explicitly contrasting with those siblings, so it is clear but not fully differentiated.

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

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

There is no guidance on when to use this tool versus alternatives such as get-company or get-corporate-subsidiaries, and no stated prerequisites beyond the implied need for a company ID. The agent must infer usage from the name alone.

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 no further behavioral context such as error handling, permissions, return shape, or lookup failure behavior, leaving it with very little beyond the annotations.

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

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

The description is a single, front-loaded sentence with no filler. Every word contributes to identifying the operation and its lookup key.

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

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

For a simple one-parameter read tool with full schema coverage and read-only annotations, the description covers the essential purpose. However, without an output schema, it does not describe what the retrieved document contains or what happens if the ID is invalid, leaving minor contextual gaps.

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

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

Schema description coverage is 100%, and the single 'id' parameter is already documented as 'Document ID' in the schema. The description adds only the phrase 'Core document ID,' which does not meaningfully extend the schema's semantics; baseline 3 is appropriate when the schema carries parameter documentation.

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-resource pair ('Get a specific document') and scopes it to a Core document ID, which distinguishes it from list-documents by implying a single-record lookup. It does not explicitly name or differentiate itself from sibling tools like list-documents or get-credit-note, so it falls short of a 5.

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

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

The description offers no guidance on when to use this tool versus alternatives such as list-documents. Usage is only implicitly inferable from 'by Core document ID,' with no when-not conditions or prerequisites mentioned.

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 fully covered by structured data. The description adds the useful detail that two URL kinds are returned (preview and original), but says nothing about what happens when no document exists yet, or whether URLs are signed/expiring. With no output schema this is a modest but real contribution.

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

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

A single short sentence that front-loads the verb and resource with zero filler. Nothing is redundant or buried.

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

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

The tool is simple (one fully-documented param, clear read-only annotations), so little is required. Still, with no output schema the description should more fully characterize the return value — e.g. the shape of the link object, when values are absent, or URL expiry — and should distinguish this from preview-invoice, which it does not.

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 and schema description coverage is 100% ('Invoice ID' with a numeric pattern), so the schema already fully documents the input. The description adds no syntax, format, or source guidance beyond that, which is the expected baseline for a one-param tool with 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 (get) and a well-defined resource (invoice document links: preview and original URLs), which is more specific than a bare 'get invoice'. However, it does not differentiate itself from close siblings like preview-invoice, generate-invoice-pdf, or get-document, so there is some residual ambiguity about which retrieval tool to pick.

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

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

The description gives no when-to-use guidance, no preconditions (e.g. that the invoice must already have a generated document), and no mention of alternatives such as preview-invoice or generate-invoice-pdf. The agent must infer the routing from the name alone.

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 safe-read profile is covered. The description adds that results are bucketed into awaiting/future/overdue, but omits scope, aggregation basis, or any auth/company-context requirements.

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

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

A single front-loaded sentence with no filler, appropriately sized. It is terse to the point of under-specification, but nothing is wasted.

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, three parameters at 33% coverage, and only safety annotations, the description should carry more. It never defines what the three buckets mean or how 'movement' and 'acDocumentIds' affect the result, leaving the agent under-equipped.

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

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

Schema coverage is only 33%: companyId's 'Company ID' description is essentially a restatement, while 'movement' and 'acDocumentIds' are completely undocumented. The description does not compensate by explaining what these parameters filter, leaving two of three params opaque.

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 ... invoice pending totals') and enumerates the three categories it aggregates (awaiting, future, overdue). This separates it from get-overdue-invoices, which covers only the overdue bucket, though the description never names that sibling 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as get-overdue-invoices or get-aged-payables. The agent must infer usage purely from the tool name and the category list.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that baseline: no mention of return volume, pagination, date-range filtering, or whether journal entries include line detail. With annotations carrying the entire behavioral load, the description's near-zero contribution warrants a low score.

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

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

A single short sentence with no filler, and the resource is front-loaded after the verb. It is efficient, though arguably too sparse to be considered well-structured for a data-retrieval tool.

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

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

For a list-returning read tool with no output schema, the description omits essential context: what a journal entry record contains, whether results are paginated, and whether any filtering beyond company ID is possible. An agent can call it, but cannot predict the shape or size of the response.

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

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

The single parameter 'id' is fully documented in the schema as 'Company ID' (100% coverage), so the schema does the heavy lifting. The description adds no further parameter meaning, which is the expected baseline when schema coverage is complete.

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 ('Get') and resource ('journal entries'), so the agent knows what the tool retrieves. However, it offers no differentiation from siblings such as get-trial-balance, get-chart-of-accounts, or search-accounting-transactions, leaving the boundary between these read tools implicit.

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

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

There is no guidance on when to use this tool versus the many other 'get-*' accounting read tools, nor any stated prerequisites or exclusions. The agent must infer usage entirely from the tool name.

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 the safety profile is covered. The description adds only the derivation lineage ('from aged receivables v2'), which is genuinely useful context, but says nothing about what constitutes 'overdue', the date semantics, or return shape.

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

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

A single efficient sentence that is front-loaded with the action and resource. It is not bloated, though it is terse enough that the missing 'when/how' information is a coverage gap rather than a conciseness win.

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 is thin: it omits what 'overdue' means, whether the result is a list or summary, and how it differs from the aged-receivables tools it references. Annotations cover safety, but the data semantics are left to inference.

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

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

Schema description coverage is 100%, so dateFrom, dateTo, and companyId are already documented in the schema with types and formats. The description adds no parameter meaning beyond this, 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 clear verb ('Get') and resource ('overdue receivables'), which is more specific than the bare name suggests. It also flags the data source ('derived from aged receivables v2'), giving partial differentiation, but it never clarifies how this differs from the sibling get-aged-receivables-v2 or why the name says 'invoices' while the description says '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?

No when-to-use guidance and no explicit alternatives. The phrase 'derived from aged receivables v2' implies a relationship to that sibling but doesn't tell the agent which one to pick or under what conditions, leaving the choice ambiguous among get-aged-receivables, get-aged-receivables-v2, and get-invoice-pending-summary.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, which fully covers the safety profile, so the description's job here is to add context beyond that. It adds nothing: no note on whether the report is computed live or cached, no permission/scope requirements, no default accounting basis, and no indication of report size or pagination. The 'Requires a date range' sentence duplicates the schema rather than revealing behavior.

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

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

Two short sentences, front-loaded with the verb and output artifact, with no filler or repetition. Nothing in the description could be deleted without losing information, since every clause does work.

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 should ideally say what the report contains (period, revenue/expense line items, net result) or how it is structured, but it stops at naming the artifact. Combined with the unaddressed v2 sibling, the definition is minimally adequate but leaves the agent to guess at result shape and version choice.

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, dateFrom, dateTo each documented, with date format YYYY-MM-DD), so the schema carries the parameter burden and a baseline 3 applies. The description's mention of a date range is redundant with the required fields and adds no format, timezone, or inclusive/exclusive-boundary detail.

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

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

The description states a specific verb and resource ('Generate a profit and loss (income statement) report') and even translates the acronym, so the agent knows exactly what is produced. It does not, however, distinguish itself from the present sibling get-profit-and-loss-v2 or from adjacent reports like get-balance-sheet and get-cash-flow-statement, which is a real ambiguity for a reporting API that clearly versions this endpoint.

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 only usage information is the precondition 'Requires a date range,' which merely restates the required schema fields. There is no guidance on when to pick this tool over get-profit-and-loss-v2, or when a P&L is appropriate versus the other financial statement tools in the sibling list, and no exclusions or edge cases are mentioned.

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 contributes the default date-range behavior, but says nothing about what the report returns (no output schema exists), so the agent still lacks return-content context.

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

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

Two short sentences: purpose first, key default behavior second. Every sentence earns its place and nothing is front-loaded poorly.

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

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

For a simple read-only report with fully documented params and annotation-covered safety, the essentials are present. But with no output schema and a near-identical v1 sibling, the description should say what the v2 report contains and how it differs from get-profit-and-loss.

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 dateFrom, dateTo (YYYY-MM-DD) and companyId all documented in the schema, so the baseline is 3. The description only adds the default date-window behavior, not additional 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?

The description gives a specific verb and resource ('Generate a profit and loss v2 report for a company'), so the agent knows exactly what it produces. However, it never distinguishes this tool from the sibling 'get-profit-and-loss' (the v1 variant), leaving the agent unable to tell which version to pick from the description alone.

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 states a useful default ('year-to-date if no date range provided'), which implies a usage context, but there is no explicit when-to-use guidance and no mention of when to prefer the v1 sibling. Usage is only inferable rather than 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 without description help. The description adds one useful behavioral fact — that the output is a derived/aggregated view built from the P&L v2 report rather than raw ledger data — but says nothing about latency, computation caveats, or what the summary includes.

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

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

A single front-loaded sentence with zero filler — the verb and resource lead immediately. It is efficient, though its brevity is partly achieved by omitting information rather than by tight editing of necessary content.

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

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

There is no output schema, so the description carries the full burden of explaining what the returned 'revenue summary' contains — and it does not. For a read-only reporting tool whose entire value is the shape of its output, leaving the return contents and the period/date-range interaction undocumented is a significant gap.

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

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

Schema description coverage is 75% and the schema already documents dateFrom, dateTo, and the period enum clearly. The description contributes no parameter meaning at all, adding nothing about how period interacts with the explicit date range, which is the one ambiguity an agent might hit.

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 (revenue summary) and grounds it in an underlying report, 'the profit and loss v2 report,' which loosely distinguishes it from the sibling get-profit-and-loss-v2. However, 'founder-friendly' is vague marketing framing that does not say what the summary actually contains or how it differs in scope from the raw P&L.

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?

No when-to-use, when-not, or alternative guidance is given. The mention of the P&L v2 report hints this is a simplified alternative to get-profit-and-loss-v2, but nothing tells the agent which tool to pick or under what conditions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and a closed-world scope, so the safety profile is covered. The description adds little beyond that: it does not mention ordering, default page size, or what happens when no comments exist. With annotations carrying the safety burden, this is adequate but thin.

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

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

A single, tight sentence with the key constraint (which ID to use) front-loaded. No filler or redundant phrasing.

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

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

For a read-only list tool with no output schema and full annotation coverage, the description is nearly sufficient; return values need not be explained. The only gap is the absence of any note on result ordering or pagination behavior given the limit/date filters.

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 five parameters (limit, companyId, createdAfter, createdBefore, transactionId) are already documented in the schema. The description merely restates the transactionId provenance ("numeric AcDocument ID from Websome/Roberto transaction.acDocument.id"), which duplicates the schema's own wording.

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 pairs a specific verb ("Read") with a specific resource ("the comments conversation for a transaction"), so an agent immediately knows this retrieves comment threads. It implicitly distinguishes itself from the sibling add-transaction-comment, though it never names that sibling 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?

Usage is only implied: an agent infers it should call this when it wants to read a transaction's comments. There is no explicit when-to-use/when-not-to-use guidance and no mention of alternatives such as search-transactions for broader lookups.

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 only the date-range requirement, which is already in the schema, and says nothing about output format, pagination, or size limits for what could be a large report.

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 short sentences with zero filler, and the purpose is front-loaded ahead of the requirement. Nothing could be trimmed without losing information.

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

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

With no output schema, the description carries the burden of describing what comes back, and it only names the report type without indicating the columns, grouping, or format of a trial balance response. For a financial report tool this is adequate but thin.

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 three parameters documented (Company ID, Start date, End date). The description restates that a date range is required but adds no format or semantics beyond the schema, 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 ('Generate a trial balance report'), which is a distinct accounting artifact from sibling reports like get-balance-sheet, get-profit-and-loss, and get-cash-flow-statement. It is clear but never explicitly differentiates itself from those siblings, so it lands just short of a 5.

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

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

'Requires a date range' gives a prerequisite, which is more than most definitions at this level, but it offers no when-to-use/when-not guidance and never names alternatives such as get-balance-sheet. Usage is only implied by the reporting context.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description usefully adds that results are scoped to the authenticated user's access (no cross-tenant leakage), but says nothing about pagination, ordering, or result 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?

A single front-loaded sentence with the verb, resource, and scoping constraint; zero filler and nothing to trim.

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

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

For a zero-parameter, read-only list tool with no output schema, the description covers who is affected and what is returned well enough to call it correctly. The only gap is the shape/pagination of the returned list, which is minor for such a simple operation.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the 4 baseline applies. No parameter-level detail is possible or needed here.

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

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

States a specific verb (list) and resource (companies) plus a scope qualifier ('the authenticated user has access to'), so an agent immediately knows it returns a collection rather than a single company. It does not explicitly name the singular sibling get-company as the alternative, so sibling differentiation is implied rather than stated.

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

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

Usage is implied by the scope wording: an agent can infer this is the enumeration tool to call when it needs every accessible company rather than one. However, it never says when to prefer this over get-company or how it relates to the other list-* tools, and offers no exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds the workflow intent (feeding a customerId into invoice drafts) but says nothing extra about pagination, ordering, or result limits beyond what annotations provide.

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

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

A single front-loaded sentence with zero filler; the scope (a company) and the purpose come before anything else. Every word 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 simple read-only list tool with no output schema, the definition is adequate but thin: it never explains pagination behavior, result ordering, or what a caller receives, and it leaves three of four parameters semantically undefined. It is minimally viable rather than complete.

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

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

Schema description coverage is only 25% – only companyId carries a description ('Company ID'). The page, search, and perPage parameters are undocumented in both the schema and the description, and the description does not compensate with any filtering or pagination semantics. It fails to fill the coverage gap for a 4-parameter tool.

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

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

States a specific verb and resource ('List invoice customers') scoped to 'a company', and even motivates the purpose (assigning a customerId to invoice drafts). The verb clearly separates it from the sibling create-customer, though it does not name any sibling 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?

The clause 'so invoice drafts can be assigned a customerId' implies the workflow context in which this tool is used, which is useful direction. However, there is no explicit when-to-use vs when-not-to-use guidance and no named alternative, so usage remains implied rather than 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. The description adds a meaningful behavioral fact beyond the annotations: the payload is "Core document IDs" only, which tells the agent a follow-up call (e.g., get-document) is needed for details. It omits ordering, total counts, and pagination limits, 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?

Two short sentences, front-loaded with the verb and resource, and the return-content note follows immediately. Nothing is wasted and no filler is present.

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

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

For a simple, read-only list tool with full schema coverage, the description covers purpose, scope, pagination, and the shape of the return (IDs). The lack of an output schema is compensated by the note about Core document IDs, though ordering and empty-result behavior remain unstated.

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 three parameters (id, page, perPage) self-documented including defaults and max. The description's "with pagination" merely restates what the schema already specifies and adds no 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?

The description gives a specific verb and resource ("List documents") plus a scope qualifier ("for a company") and notes pagination. It is distinguishable from get-document (single retrieval) and list-invoices, though it never explicitly contrasts itself with those 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 states what the tool does but offers no when-to-use guidance, no prerequisites, and no mention of alternatives such as get-document for full document details. Usage is only implied by the name and description.

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 this a safe, read-only, non-destructive operation, so the safety profile is covered. The description adds that pagination is supported via page/perPage and that filters are optional, which is useful context, but it discloses nothing about return shape, ordering, or defaults beyond what annotations give.

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

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

A single front-loaded sentence with no filler, listing purpose, scope, filters, and pagination efficiently. It is appropriately sized, though slightly dense in its clause list.

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

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

For a read-only list endpoint whose annotations already carry the safety profile and with no output schema required, the description is adequate but thin. With five parameters and low schema coverage, more detail on filter behavior and pagination would round it out.

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

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

Schema coverage is only 20% (only companyId is documented), so the description must compensate, and it does name the filter and pagination parameters (status, search, page, perPage). However it omits the status enum values, default page size, and the semantics of 'search', so it only partially fills the gap.

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

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

States a specific verb and resource ('List invoices') scoped to a company, which is clear and unambiguous. It implicitly distinguishes from siblings like get-overdue-invoices or create-invoice-draft, but never names them, so it falls short of explicit differentiation.

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

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

No guidance on when to use this tool versus alternatives such as get-overdue-invoices, get-invoice-pending-summary, or search-transactions. The existence of filters is mentioned but not when they should be preferred.

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 the safety profile is covered. The description adds real context beyond that: it discloses the tool's place in a two-step workflow and that it emits an accountId intended for the apply tool. It doesn't mention pagination, ranking behavior, or failure modes, but those are minor for a capped read 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?

Two sentences, zero waste. The 'what it does' statement comes first and the input-source plus follow-up-tool routing comes second, so the most decision-relevant information 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, so the description carries some return-value burden; it explains that results are account recommendations yielding an accountId for the apply tool, which is the essential contract. It omits the shape of the returned list (ranking, number returned relative to topK), a modest gap for a 6-parameter 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 all six parameters are already documented, including topK, vendorName, and description. The description restates the transactionId source but adds nothing about parameters the schema doesn't already cover. Baseline 3 is correct 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 ('List account recommendations for cashcoding a transaction') that distinguishes it from all siblings, and names the paired tool apply-transaction-cashcoding-recommendation. An agent can tell this is the lookup half of a two-step cashcoding flow without opening the schema.

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

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

Gives clear when-to-use context: it identifies the exact input source (the numeric AcDocument ID from Websome/Roberto transaction.acDocument.id) and states what to do with the output (pass a returned accountId to apply-transaction-cashcoding-recommendation). It does not state when NOT to use it or how it differs from search-accounting-transactions, so it falls short of explicit exclusions.

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

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

Annotations only declare a non-read-only, non-destructive, closed-world mutation. The description goes well beyond that: it discloses the return shape (presigned POST target with fields and uploadToken), the exact submission mechanics (include Content-MD5/checksum fields when present, append the file last), and forbidden inputs. This is rich behavioral context the annotations do not carry.

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

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

Front-loaded with the workflow role, then the return value, then the mechanics, then the prohibitions. Every clause carries actionable content with no filler, despite covering a multi-step flow.

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 explaining what the call returns (presigned target, form fields, uploadToken) and how to use it before the complete step. For a two-phase upload protocol, 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%, with checksum pattern, sizeBytes maximum, and per-field descriptions already documented, so the baseline is 3. The description mentions checksum/Content-MD5 handling but for the form submission rather than adding meaning to the input parameters themselves.

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 within a named workflow ('Step 1 of document upload') and precisely what it produces ('a presigned POST target with form fields and uploadToken'). It also distinguishes itself from the sibling complete-document-upload by positioning itself as the prerequisite 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?

Gives explicit when-to-call ('Call before uploading bytes'), the follow-up action ('then call complete-document-upload'), and clear negative guidance ('Never send contentBase64, arbitrary upload headers, or file bytes to MCP'). An agent knows exactly where this sits in the sequence and what not to do.

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 "without mutating it" largely restates what the structured data provides. It adds no new behavioral context such as return format, whether it works on drafts versus submitted invoices, or any scoping constraints.

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

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

A single short sentence that is front-loaded with the verb and resource; nothing is padded. It is slightly terse given the ambiguity around "preview," but structurally efficient.

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

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

For a simple one-parameter read tool this is minimally adequate, but there is no output schema, and the description does not clarify what a "preview" actually returns or how it relates to the draft/submit workflow. An agent calling it correctly has just enough, but with clear gaps.

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

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

Schema coverage is 100% and the single required id parameter is fully documented in the schema ("Invoice ID" with a numeric pattern). The description adds nothing 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 (invoice data) with a clear qualifier ("for preview"). However, it does not differentiate itself from the many sibling read tools such as list-invoices, get-invoice-pending-summary, or get-invoice-document-links, so the agent cannot tell why it would pick this over another read tool.

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

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

Usage is only implied by "for preview" and "without mutating it" – there is no explicit when-to-use, when-not-to-use, or named alternative. An agent must infer that this is the non-destructive read path versus submit-invoice or update-invoice-draft.

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 genuine behavioral context beyond that: the return shape ('report-style data grouped by account') and the default date window ('last 90 days if no date range provided'). It stops short of pagination/volume caveats, but the additions are real.

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 tight sentences with no filler, front-loaded with purpose, then return shape, then default behavior, then the disambiguation hint. 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?

For a read-only search tool with no output schema, the description covers purpose, return grouping, default date semantics, and sibling disambiguation, while annotations carry the safety profile. Nothing required to call it correctly is missing.

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

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

Schema coverage is 100%, so parameter documentation already lives in the schema (baseline 3). The description adds the implicit defaulting behavior for dateFrom/dateTo that the schema does not state, which is meaningful semantics beyond the structured fields.

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 ('Search accounting ledger transactions for a company') and immediately differentiates itself from the closely-named sibling 'search-transactions'. An agent can distinguish 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?

Explicitly names the alternative ('Use search-transactions instead when you need transaction IDs for commenting'), giving a concrete condition that selects between the two near-identical tools. This is exactly the when-to-use-this-vs-alternative guidance the dimension asks for.

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 by structured data. The description adds real context beyond that: results are paginated and each carries an acDocumentId usable with add-transaction-comment, which tells the agent how the output is consumed. It omits ordering, result caps and empty-result behavior.

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

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

Two short sentences, zero padding, and the core action plus its key output contract are front-loaded. 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?

With no output schema, the description usefully states that returns include acDocumentId, and the schema covers all input details including pagination defaults. It is nearly complete; a note on result ordering or the total result set would close the remaining gap.

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

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

Schema description coverage is 100%, so page, perPage, dateFrom, dateTo and companyId are already fully documented in the schema. The description only adds 'with pagination', which is redundant with the schema's page/perPage entries, 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?

The description gives a specific verb+resource ('Search transactions for a company') and adds the pagination scope, which is more than the bare name. However, it does not distinguish this tool from the sibling search-accounting-transactions, so an agent must infer the difference.

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

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

There is a useful downstream hint that the returned acDocumentId feeds add-transaction-comment, which implies a chaining workflow. But there is no explicit when-to-use vs. when-to-use-an-alternative guidance, and the near-identical sibling search-accounting-transactions is never addressed.

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 real value beyond them: it discloses that submission can queue external PEPPOL delivery and IRAS reporting for linked invoices, which explains the open-world side effects, plus a user-confirmation requirement. It stops short of describing failure behavior or reversibility.

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 effect, then the conditional external workflow and the confirmation requirement. Little waste, though the final sentence is slightly wordy.

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

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

For a destructive, open-world mutation with no output schema, the description covers the important external side effects (PEPPOL/IRAS) and the confirmation requirement. It is missing only edge-case behavior such as what happens on failure or whether the submission is reversible, which is a minor gap given annotation coverage.

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

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

Schema coverage is 60%: id, companyId, and issueDate are documented in the schema, but reason and creditNoteNumber have no descriptions in either schema or description. The description adds no parameter meaning at all, so it fails to compensate for the coverage gap.

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

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

States a specific verb (submit) and resource (credit note) and names the effect: applying it to the invoice. It implicitly distinguishes itself from create-credit-note by emphasizing application/submission, but it never names the sibling explicitly, so an agent must infer the boundary.

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

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

The description implies usage ('submit ... and apply it to the invoice') and adds a confirmation prerequisite, but gives no explicit when-to-use vs create-credit-note, get-credit-note, or submit-invoice, and no preconditions beyond the user-intent check.

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

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

Goes well beyond the annotations: clarifies that the 'sent' status does not imply actual email delivery, and discloses open-world side effects (InvoiceNow delivery via PEPPOL, IRAS reporting) that depend on stored settings. This is exactly the kind of external-effect context annotations cannot convey.

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

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

Front-loads the core action and each subsequent sentence earns its place (sent semantics, prerequisite, external effects, confirmation). Dense but purposeful; 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 destructive/open-world mutation with no output schema, the description covers the key prerequisites, state semantics, and external side effects an agent needs. It omits return/pagination details, but no output schema exists and the safety profile is already carried by annotations.

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 constrained nested object is well documented by the schema itself. The description adds the prerequisite relationship for lineItems (not a param here) but does not clarify the roles of id, companyId, or the invoice fields beyond what the schema states, 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?

States a specific verb and state transition ('Finalize a draft invoice and mark it as sent') plus an important semantic clarification of what 'sent' means. This clearly distinguishes it from siblings like create-invoice-draft, update-invoice-draft, and preview-invoice 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 a concrete prerequisite ('Requires lineItems to already be set via update-invoice-draft') and an explicit usage instruction ('Confirm the user intends to submit'). It routes the agent to the correct upstream sibling, though it doesn't explicitly state when-not to use this versus alternatives in a conditional sense.

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 the description reinforces this by saying values are 'overwritten' rather than merged, plus discloses the customerId side effect that auto-populates recipient data. It does not cover auth/permission requirements, but the destructive semantics and the 'does not submit' boundary add real context beyond the annotations.

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

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

Three tight sentences, front-loaded with the core action; the 'Does not submit' line at the end is a useful disambiguator rather than filler. Minor redundancy with the schema on the customerId behavior keeps it from a 5.

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

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

For a mutation tool with no output schema, the description covers the essentials: overwrite behavior, draft-only scope, and the key side effect. It stops short of stating whether unmentioned fields are preserved and what permissions are needed, which would round it out.

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 the customerId auto-population ('Recipient data is auto-populated from the customer'), so that note is largely redundant. The description gestures at 'dates, currency, and notes' but adds no syntax or format detail, and several fields (invoiceNumber, paymentMethods, includeTaxIntoPrice, supply dates) are unmentioned. 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 ('Update existing fields on a draft invoice') and a scope boundary ('Does not submit the invoice') that cleanly separates it from submit-invoice. The overwrite semantics and draft-only scope let an agent distinguish it from create-invoice-draft and duplicate-invoice 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 positions the tool in the workflow: 'Set lineItems, dates, currency, and notes here before submitting,' which tells the agent this is the pre-submission editing step. It rules out submission but does not explicitly name submit-invoice as the alternative or state prerequisites (e.g., that the invoice must already be a draft).

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