Read KashFlow invoices, customers, suppliers, banking and reports; add customers, notes.
The last two health checks of this connector failed. If this server requires authentication, missing or expired test credentials may be the cause. A test profile lets Glama authenticate for health checks and discover tools; it is separate from your personal connections.
If you are the author, claim ownership, then add or update a test profile under Admin → Test Profile.
Scored across 38 tools
Most tools target clearly distinct resources and actions, with explicit distinctions between lookup-by-code, by-ID, and by-email. However, the numerous invoice-listing tools (recent, overdue, unpaid, by customer, by date range) and the customer lookup variants could still invite misselection without careful reading.
All tool names follow a consistent kashflow_ prefix + snake_case verb_noun pattern, using predictable verbs such as add, create, find, get, and list. The convention is stable throughout the 38-tool set.
The accounting domain is broad enough to justify many tools, and most have distinct purposes. Still, 38 tools is heavy for an agent-facing surface and could likely be consolidated (for example, grouping report tools or invoice list variants).
Reporting and read coverage is extensive, but write coverage is thin: there is no create invoice, record payment, create purchase invoice/receipt, update, or delete operation. These are core accounting lifecycle gaps that will block common workflows.
WRITE: add a note to a sales invoice, by its InvoiceDBID (the numeric id in invoice replies). Existing notes and the invoice are not changed. SOAP InsertInvoiceNote.
| Name | Required | Description | Default |
|---|---|---|---|
| note | Yes | The note text. | |
| note_date | No | Note date, yyyy-mm-dd or yyyy-mm-ddThh:mm:ss (default: now, UTC). | |
| invoice_id | Yes | The invoice's InvoiceDBID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false; the description adds real context beyond them by explicitly stating the invoice and existing notes are unchanged, and by naming the underlying call (SOAP InsertInvoiceNote). It stops short of addressing duplicate behavior, which matters given idempotentHint=false — calling twice presumably yields two notes, and that is not said.
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, no filler, and the most decision-relevant token ('WRITE') is front-loaded. Every clause carries information: mutation type, target, ID provenance, and non-destructive scope.
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 three-parameter write tool with annotations and no output schema, the description covers purpose, safety profile, ID provenance, and the underlying API. The remaining omission — no statement about what (if anything) is returned, such as a note ID, and no warning about duplicate notes on retry — is minor but real.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, but the description adds value by telling the agent that invoice_id is the numeric InvoiceDBID found in invoice replies — a provenance hint the schema does not give. The optional note_date parameter is not mentioned in the description, leaving that gap 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?
States a specific verb and resource (add a note to a sales invoice) and pins the target key (InvoiceDBID), which cleanly separates it from the read-side sibling kashflow_get_invoice_notes. An agent can identify the operation without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'WRITE:' prefix and 'Existing notes and the invoice are not changed' establish the conditions under which this is appropriate (an additive annotation on an existing invoice), and the parenthetical explains where the required ID comes from in invoice replies. It does not name or exclude the read counterpart kashflow_get_invoice_notes, so routing guidance is clear but incomplete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE: create a new customer. The code must be unique (KashFlow refuses a code that exists) and nothing existing is changed. Returns the new CustomerID. SOAP InsertCustomer.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | A unique customer code, e.g. ACME01. | |
| name | Yes | The customer / company name. | |
| No | |||
| notes | No | ||
| mobile | No | ||
| contact | No | Contact person. | |
| website | No | ||
| address1 | No | ||
| address2 | No | ||
| address3 | No | ||
| address4 | No | ||
| postcode | No | ||
| telephone | No | ||
| tax_region | No | VAT classification of the customer: uk (default, domestic), eu (EC customer) or outside_eu. Set it for customers outside the UK. | |
| vat_number | No | ||
| country_code | No | Two-letter ISO country code, e.g. GB. | |
| country_name | No | Country name, e.g. United Kingdom. | |
| payment_terms_days | No | Payment terms in days. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, so the safety profile is covered; the description adds real value beyond that by stating the code-uniqueness failure mode, that nothing existing is changed, and that a new CustomerID is returned. It omits auth/rate-limit or partial-failure behavior, so it stops 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?
Three compact sentences, front-loaded with the operation type and mutation nature, with the critical uniqueness constraint early. The trailing 'SOAP InsertCustomer.' is marginal for an agent but cheap enough not to hurt much.
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?
It helpfully discloses the return value (new CustomerID), which matters because no output schema exists, and it covers the destructive/uniqueness behavior. But for an 18-parameter creation tool with sparse schema coverage, it leaves too many optional fields unexplained for full completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 18 parameters and only 39% schema description coverage, the description must compensate for undocumented fields, but it only elaborates on `code` (uniqueness) and says nothing about `name` being required or how `tax_region`/`payment_terms_days` should be set. Fields like email, notes, addresses, vat_number and telephone get no meaning from either source.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('create a new customer') and leads with 'WRITE:', so the agent immediately knows this is a mutation rather than a lookup like kashflow_get_customer or kashflow_find_customer_by_email. It does not explicitly name a sibling, but 'customer' inherently separates it from kashflow_create_supplier.
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 uniqueness rule ('KashFlow refuses a code that exists') implies the agent should look the customer up first rather than blindly retrying, which is useful implied routing. However, no explicit 'use X instead when...' guidance or preconditions (e.g., required permissions) are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE: create a new supplier. The code must be unique (KashFlow refuses a code that exists) and nothing existing is changed. Returns the new SupplierID. SOAP InsertSupplier.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | A unique supplier code, e.g. OFFICE01. | |
| name | Yes | The supplier / company name. | |
| No | |||
| notes | No | ||
| mobile | No | ||
| contact | No | Contact person. | |
| website | No | ||
| address1 | No | ||
| address2 | No | ||
| address3 | No | ||
| address4 | No | ||
| postcode | No | ||
| telephone | No | ||
| vat_number | No | ||
| eu_supplier | No | True for a supplier in another EU country (EC supplier). Default false (UK). | |
| payment_terms_days | No | Payment terms in days. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly=false, destructive=false, idempotent=false and openWorld=true, yet the description still adds real value: the uniqueness failure mode ('KashFlow refuses a code that exists'), the reassurance that nothing existing is changed, and the return value ('Returns the new SupplierID') which matters because there is no output schema. Auth requirements and rate limits are not covered, 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?
Three short sentences, front-loaded with the WRITE marker and the core action, with the uniqueness constraint and return value following in priority order. 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 is complete on behavior and return value despite the absence of an output schema, which is genuinely helpful for a 16-parameter mutation tool. The gap is parameter coverage: with only 31% schema description coverage, an agent gets no guidance on the meaning or formatting of the optional address, VAT, and payment-term fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 16 parameters and only 31% schema description coverage, the description needs to carry the load but instead mentions only 'code', and its uniqueness note merely restates what the schema already says. The 14 optional fields (email, notes, mobile, contact, address1-4, postcode, telephone, vat_number, payment_terms_days, eu_supplier) get no treatment at all from the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('WRITE: create a new supplier'), and the WRITE prefix immediately separates it from the read-oriented siblings like kashflow_get_supplier and kashflow_list_suppliers. The resource (supplier) also distinguishes it from kashflow_create_customer 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?
Usage is implied by 'create a new supplier' plus the note that KashFlow refuses a duplicate code, which hints the caller should check existing codes first. However, it never explicitly names an alternative (e.g. kashflow_list_suppliers to verify a code, or the update path for existing suppliers), so the when-not guidance is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The customer whose e-mail address matches. SOAP GetCustomerByEmail.
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | The customer's e-mail address. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds nothing behavioral beyond that — 'SOAP GetCustomerByEmail' is implementation trivia, and it omits what happens when no customer matches or how many results come back.
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 fragments, nothing bloated, and the matching criterion comes first. However 'SOAP GetCustomerByEmail' spends one of only two sentences on plumbing detail rather than on information an agent can act on.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations describing return content, the description should say what a successful match returns (a customer object? an ID?) and how a miss is signalled. For an open-world lookup whose main risk is a silent no-match, that omission is significant.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is a single parameter with 100% schema description coverage ('The customer's e-mail address'), which sets the baseline at 3. The description reinforces that matching is on the email field but adds no format, normalization, or case-sensitivity details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The phrase 'The customer whose e-mail address matches' identifies the resource and the lookup key, but it is a noun fragment with no verb, so the action (look up / return a customer) must be inferred from the tool name. It also does not distinguish this from the many sibling customer lookups (kashflow_get_customer, kashflow_get_customer_by_id, kashflow_list_customers).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use an email lookup versus kashflow_get_customer_by_id or kashflow_list_customers. The only implied usage comes from the tool name and the word 'e-mail', which is already in the schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Who you owe money to at a date (default today), aged into current, three periods and older, per supplier. SOAP GetAgedCreditors.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Report date, yyyy-mm-dd (default today, UTC). | |
| limit | No | How many records to return (default 100, max 500). | |
| offset | No | How many records to skip (default 0), to get the next page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the operation as read-only, non-destructive, and open-world. The description adds useful behavioral detail about the report structure: aged into current, three periods, and older, per supplier.
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 short and front-loaded with the core meaning. The trailing 'SOAP GetAgedCreditors' is implementation trivia that adds little for an agent, but overall it remains 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 read-only report with fully documented optional parameters and safety annotations, the description provides enough context about the report content and aging structure. It could mention pagination behavior, but the schema covers that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents date, limit, and offset. The description reinforces the date semantics and default today, but adds no further parameter guidance beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific reporting purpose: who is owed money, aged into buckets, per supplier. It implicitly distinguishes itself from aged debtors by saying 'who you owe money to,' though it does not name the sibling tool 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 usage context is implied by 'who you owe money to at a date' and the aging buckets, but there is no explicit guidance on when to use this versus supplier balance or aged debtors reports.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Who owes you money at a date (default today), aged into current, three periods and older, per customer. SOAP GetAgedDebtors.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Report date, yyyy-mm-dd (default today, UTC). | |
| limit | No | How many records to return (default 100, max 500). | |
| offset | No | How many records to skip (default 0), to get the next page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuine context (default date is today, aging buckets are current/three periods/older, results are grouped per customer) plus the underlying SOAP call name, but says nothing about currency handling, zero-balance customers, or whether the date is UTC.
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?
Effectively one sentence that front-loads the purpose and the aggregation structure, followed by a short SOAP operation reference. Nothing is padded, though the SOAP note is only marginally useful to an agent selecting the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the burden of explaining the return shape, and it does reasonably well by naming the aging buckets and per-customer grouping. Pagination is handled in the schema. Missing only minor details like whether only customers with balances appear or what the period lengths are.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters (date, limit, offset) are already documented with formats, defaults and bounds. The description only restates the date default, adding no semantics the schema lacks. 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?
Specific verb+resource ('Who owes you money at a date') with an explicit description of the output shape: aged into current, three periods and older, per customer. That distinguishes it functionally from get_aged_creditors and the invoice-listing siblings, though no sibling is named directly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied by the resource itself ('who owes you money'). Nothing says when to prefer this over list_overdue_invoices, get_customer_balance, or get_aged_creditors, and there are no stated prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The balance sheet at a date (default today): fixed assets, current assets, current liabilities, capital and reserves with the lines of each. SOAP GetBalanceSheet.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Balance sheet date, yyyy-mm-dd (default today, UTC). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely new context: the shape of the payload (section totals plus their individual lines) and the implicit default date, plus a note that this maps to the SOAP GetBalanceSheet call. It stops short of mentioning permissions, rate limits, or whether historical dates can be back-dated beyond the current ledger.
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, nothing wasted, with the resource and its returned sections front-loaded before the SOAP implementation note. The trailing 'SOAP GetBalanceSheet.' is marginal metadata but costs little.
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 enumeration of sections and lines is doing real work in telling the agent what comes back. Combined with full param coverage and read-only annotations, this is close to sufficient for a simple one-parameter reporting tool; only the absence of any cross-report routing guidance keeps it below 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 100% and a single optional parameter, the schema already documents the yyyy-mm-dd format and the UTC-today default. The description only echoes 'at a date (default today)' and adds no format or edge-case meaning beyond that, 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?
Names the specific resource (balance sheet) and enumerates the sections it returns (fixed assets, current assets, current liabilities, capital and reserves), which separates it clearly from siblings like get_profit_and_loss and get_trial_balance. There is no explicit verb, but the noun phrase plus 'at a date' makes the retrieval 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?
The description never states when to choose this report over the many adjacent financial reports in the sibling list (profit & loss, trial balance, aged debtors/creditors, KPIs). The only guidance-like content is the default-date note, which is a parameter default rather than usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The balance of one bank account on a date (default today). SOAP GetBankBalance.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Balance date, yyyy-mm-dd (default today, UTC). | |
| account_id | Yes | The bank account's AccountID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the useful 'default today' date behavior and discloses the SOAP GetBankBalance origin, confirming a remote round-trip, but says nothing about error behavior for invalid accounts or what the returned balance looks like.
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 resource and scope; nothing is wasted. The trailing SOAP method name is a minor but harmless provenance note.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only two fully documented parameters, the input side is adequately covered. However, there is no output schema, and the description does not say what the balance value comprises (amount, currency, sign convention) or how a missing account is reported — a gap for a tool whose whole purpose is returning a figure.
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 with format and defaults in the schema. The description's '(default today)' and 'one bank account' merely restate that, adding no new semantics; 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?
Names a specific verb and resource — the balance of one bank account on a given date — so the agent knows exactly what is retrieved. It is distinguishable from siblings like list_bank_accounts and list_bank_transactions by the 'balance' noun, though the description never explicitly contrasts itself with kashflow_get_customer_balance or other balance-report tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use or when-not-to-use guidance and no mention of the alternative tools. The need for an account_id implies the agent must first call kashflow_list_bank_accounts, but the description leaves that inference entirely to the caller.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The KashFlow company: name, address, contact, VAT registration, currency, payment terms and business type. SOAP GetCompanyDetails.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the returned field list and notes the underlying SOAP operation, which provides some useful context, but it does not describe authentication, rate limits, or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loads the resource name followed by the returned fields. It uses sentence fragments rather than full sentences, but every element adds information without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only getter with no output schema, the description sufficiently signals what data is available by listing the company fields. It could say more about the return structure, but annotations cover the safety profile and the field list covers the essential output content.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description does not need to explain parameter semantics, and the empty schema is consistent with a no-argument getter.
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 identifies the resource ('The KashFlow company') and enumerates the specific fields returned (name, address, contact, VAT registration, currency, payment terms, business type), which distinguishes it from sibling tools focused on customers, suppliers, invoices, and reports. It lacks an explicit verb like 'retrieve', but the purpose is still clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. The unique zero-parameter nature makes its usage somewhat inferable, but the description itself provides no explicit usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One customer by its KashFlow customer code (the short code shown in the customer list, e.g. ACME01). SOAP GetCustomer.
| Name | Required | Description | Default |
|---|---|---|---|
| customer_code | Yes | The customer code, e.g. ACME01. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that this is a SOAP GetCustomer call and clarifies the code meaning, but it does not discuss lookup failure behavior, return shape, or other operational 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 with no waste. The key resource and lookup method are front-loaded, followed by a compact technical note.
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 getter with complete schema coverage and annotations declaring safety, the description is largely sufficient. It could mention the returned customer or not-found behavior, but nothing critical is missing for an agent to select and invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents the sole customer_code parameter. The description still adds meaning by calling out that it is the short code shown in the customer list, which helps distinguish it from other customer identifiers.
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 identifies a specific resource (one customer) and the exact lookup key (KashFlow customer code), with an example and the underlying SOAP method. It is clear what the tool does, though it does not explicitly contrast itself with siblings such as get_customer_by_id or find_customer_by_email.
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 'by its KashFlow customer code' implies when to use this tool, and the example clarifies that the code is the short customer-list code. However, there is no explicit guidance on when to choose this over the by-ID, by-email, or list-customers alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What one customer owes: the total invoiced value and the outstanding balance. SOAP GetCustomerBalance.
| Name | Required | Description | Default |
|---|---|---|---|
| customer_code | Yes | The customer code, e.g. ACME01. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered structurally. The description usefully adds what the response conceptually contains (invoiced total vs. outstanding) and notes the underlying SOAP call, but says nothing about currency, zero-balance behavior, or error cases for an unknown customer code.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two terse sentences, the payoff definition front-loaded and the SOAP provenance relegated to a trailing note. Nothing 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 read-only single-parameter tool with no output schema, the description conveys both the input (one customer) and the shape of the answer. Minor gaps like currency/zero-balance handling keep it from a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With one parameter at 100% schema coverage (including an example value 'ACME01'), the schema carries the semantics. The description adds no extra meaning about customer_code, 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+resource and even spells out the two values returned (total invoiced value, outstanding balance), which distinguishes it from kashflow_get_customer and the invoice-listing siblings. It does not explicitly name a sibling it replaces, keeping 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?
The phrase 'What one customer owes' implies a collections/AR context, but there is no explicit when-to-use, when-not, or pointer to alternatives like kashflow_get_aged_debtors or kashflow_list_customer_invoices. Usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One customer by its numeric CustomerID (as returned in other replies). SOAP GetCustomerByID.
| Name | Required | Description | Default |
|---|---|---|---|
| customer_id | Yes | The numeric CustomerID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only an implementation note ('SOAP GetCustomerByID') and says nothing about behavior an agent would care about, e.g. whether an unknown ID raises an error or returns empty.
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 clauses, front-loaded with the identifying scope. The trailing 'SOAP GetCustomerByID' is largely redundant with the name and title, but it costs little.
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 declared annotations, the essential information is present. The notable residual gap is the absence of an output schema, so the description could have hinted at what customer fields are returned; otherwise it is fit for purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With a single parameter and 100% schema description coverage, the schema already documents 'The numeric CustomerID.' The description adds a marginal provenance hint ('as returned in other replies') but no format or range detail beyond the schema's minimum/maximum.
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 ('customer') and pins the identifier as the numeric CustomerID, which distinguishes it from kashflow_find_customer_by_email. It does not, however, distinguish itself from the sibling kashflow_get_customer, which an agent must still disambiguate on its own.
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 parenthetical 'as returned in other replies' implies a usage pattern (obtain the ID from a prior list/create call) but does not state when to prefer this over kashflow_get_customer or kashflow_find_customer_by_email. Usage is implied rather than guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One sales invoice by its invoice number: customer, dates, lines (description, quantity, rate, VAT), net, VAT, amount paid and a link. SOAP GetInvoice.
| Name | Required | Description | Default |
|---|---|---|---|
| invoice_number | Yes | The invoice number, e.g. 1042. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, non-destructive, open-world behavior, so the safety profile is covered. The description adds useful output context by listing the returned invoice fields and noting the SOAP method, but it does not mention error behavior such as what happens when the invoice number is not found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loads the core purpose, then efficiently enumerates the returned fields. The trailing 'SOAP GetInvoice' is slightly cryptic but does not bloat the definition.
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 annotations and no output schema, the description gives enough detail about the returned invoice contents to support correct use. It could be more complete by stating not-found behavior or linking behavior, but the essential lookup context is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the single invoice_number parameter is documented with an example. The description only reinforces that the lookup is by invoice number, adding no syntax or format details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: retrieve one sales invoice by invoice number. It also names the returned fields and distinguishes this single-invoice lookup from the many sibling list-invoice tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'by its invoice number' implies the tool should be used when the invoice number is already known, but the description does not explicitly say when to use it instead of kashflow_list_invoices, kashflow_list_customer_invoices, or other invoice-related siblings. The usage context is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The notes attached to one sales invoice, by its InvoiceDBID (the numeric id in invoice replies, not the invoice number). SOAP GetInvoiceNotes.
| Name | Required | Description | Default |
|---|---|---|---|
| invoice_id | Yes | The invoice's InvoiceDBID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds two useful behavioral facts: it discloses the SOAP operation and warns that the numeric id comes from invoice replies rather than the printed invoice number. It doesn't describe what notes look like or whether there may be zero notes.
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 what is returned and followed by the disambiguating identifier note. The trailing 'SOAP GetInvoiceNotes' is compact provenance with no wasted preamble.
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 tool with full schema coverage and complete safety annotations, the description covers what an agent needs to call it correctly. The only omission is the shape of the return value (ordering, whether notes include author or timestamp), which is minor without an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already 100%, with the single parameter documented as 'The invoice's InvoiceDBID'. The description goes beyond that by explaining where the id comes from and explicitly excluding the invoice number, which is the most likely source of a wrong call.
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: retrieves the notes attached to one sales invoice. It scopes to a single invoice and clarifies which identifier is required, so the agent can distinguish it from note-writing tools. It stops short of naming a sibling it might 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?
The parenthetical clarifies which id to supply (InvoiceDBID, not the invoice number), which is an argument-selection hint rather than when-to-use guidance. It never says when to call this versus kashflow_get_invoice or kashflow_add_invoice_note, leaving the choice implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Key figures for a date range (income, expenses, profit and similar, as name/value pairs). SOAP GetKPIs.
| Name | Required | Description | Default |
|---|---|---|---|
| end_date | Yes | End of the period, yyyy-mm-dd. | |
| start_date | Yes | Start of the period, yyyy-mm-dd. | |
| exclude_vat | No | Leave VAT out of the figures (default false). | |
| exclude_same_day_payments | No | Leave out invoices paid the day they were issued (default false). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the return format ('as name/value pairs'), which is genuinely useful since there is no output schema, but it says nothing about which KPIs are returned, aggregation behaviour, or how the exclude_* flags shift results. 'SOAP GetKPIs' is provenance rather than behaviour.
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 purpose and return shape; nothing is redundant. The trailing 'SOAP GetKPIs' is implementation provenance that adds little for an invoking agent, a small amount of waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, 4-parameter, fully documented tool with annotations covering safety, the description is close to sufficient. It falls short on the one thing the schema cannot supply: what distinguishes these KPIs from the other report tools, and what happens when both exclude flags are set.
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% with self-documenting descriptions for end_date, start_date and both exclude flags, so the schema carries the parameter burden. The description only restates the date-range concept and adds no meaning for exclude_vat or exclude_same_day_payments beyond what the schema already says — 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 resource (key figures/KPIs) with the fields it covers (income, expenses, profit) and the return shape (name/value pairs), so the agent knows what comes back. It does not distinguish itself from close siblings like kashflow_get_profit_and_loss, kashflow_get_balance_sheet or kashflow_get_trial_balance, which cover overlapping 'profit/income/expenses' ground.
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 choose this over the other financial-report siblings, which is a real ambiguity given profit_and_loss and trial_balance return similar-sounding figures. The date-range requirement is only implied by the parenthetical, and no exclusions or prerequisites are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The profit and loss report for a date range: turnover, cost of sales, gross profit, expenses and net profit, with the lines of each section. SOAP GetProfitAndLoss.
| Name | Required | Description | Default |
|---|---|---|---|
| end_date | Yes | End of the period, yyyy-mm-dd. | |
| start_date | Yes | Start of the period, yyyy-mm-dd. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context about the report's contents and the fact it returns the lines of each section, but it does not add behavioral details like data freshness, permissions, or pagination. This is a modest value-add beyond structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the resource and scope. The trailing 'SOAP GetProfitAndLoss' is a small implementation detail rather than agent-facing guidance, but it is brief and does not bloat the definition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by listing the report's sections and noting that each section's lines are included, giving the agent a reasonable expectation of the return shape. Inputs are fully documented by the schema, and annotations cover safety; only exact response field formats remain unspecified, which is a minor 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%, and the schema itself documents both parameters with yyyy-mm-dd format. The description only restates that the report is for a 'date range' and adds no syntax, boundary, or interpretation details beyond the schema. Baseline 3 is appropriate when the schema carries parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb-resource pair (profit and loss report) and enumerates the report's sections (turnover, cost of sales, gross profit, expenses, net profit), which clearly distinguishes it from a generic 'get report'. It does not explicitly contrast itself with sibling financial reports such as get_balance_sheet or get_trial_balance, so an agent must infer the difference from the section list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the phrase 'for a date range' and the required start_date/end_date parameters, but the description offers no explicit guidance on when to choose this report versus get_balance_sheet, get_trial_balance, or get_kpis. No exclusions or prerequisites are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One purchase (supplier invoice / receipt) by its receipt number: supplier, dates, lines, net, VAT, amount paid. SOAP GetReceipt.
| Name | Required | Description | Default |
|---|---|---|---|
| receipt_number | Yes | The purchase (receipt) number. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds value by disclosing the return payload fields and the underlying SOAP GetReceipt operation, but says nothing about behavior when the number does not exist (empty result vs. error).
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 and very short: the entity, its identifier, and the returned fields come first, with the SOAP note appended. The trailing 'SOAP GetReceipt.' fragment is terse jargon but earns its place as backend provenance for agents debugging legacy behavior.
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 enumerates the returned record's contents, which is exactly what an agent needs to decide if this call supplies the data. The only gap is not-found/error behavior for an invalid receipt number, a minor omission for a single-parameter getter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is a single parameter with 100% schema description coverage ('The purchase (receipt) number'), so the schema already carries the semantics. The description restates the same concept without adding format, range, or sourcing guidance beyond the schema, making the baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('One purchase ... by its receipt number') and enumerates what the returned record contains (supplier, dates, lines, net, VAT, amount paid). The singular, by-number framing cleanly separates it from the sibling list tools such as kashflow_list_supplier_receipts and kashflow_list_recent_receipts.
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 by-number phrasing implies you call this when you already have a receipt number, but the description never states when to prefer it over list_supplier_receipts or list_recent_receipts, nor any prerequisites or failure conditions. Usage is 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.
One supplier by its KashFlow supplier code. SOAP GetSupplier.
| Name | Required | Description | Default |
|---|---|---|---|
| supplier_code | Yes | The supplier code. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only 'SOAP GetSupplier', an implementation detail, and says nothing about not-found behavior or what fields come back.
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 fragments with the resource and key front-loaded and zero filler. The phrasing 'One supplier by its...' is slightly clipped/awkward but nothing is redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read tool with full annotation coverage and no output schema, the definition is minimally sufficient. It still leaves the agent guessing about the returned representation and error case for an unknown code.
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 there is a single required supplier_code parameter already documented in the schema. The description adds no format, casing, or lookup-failure semantics beyond the schema text, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (get) and resource (supplier) plus the lookup key (KashFlow supplier code), which distinguishes it from create_supplier and list_suppliers. It never names those siblings explicitly, so differentiation is inferred 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?
'By its KashFlow supplier code' implies you must already have a code, which hints at when this applies versus a listing call, but there is no explicit when-to-use, when-not-to-use, or named alternative such as kashflow_list_suppliers.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The trial balance for a date range: every nominal code with debit, credit and balance. SOAP GetTrialBalance.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many records to return (default 100, max 500). | |
| offset | No | How many records to skip (default 0), to get the next page. | |
| end_date | Yes | End of the period, yyyy-mm-dd. | |
| start_date | Yes | Start of the period, yyyy-mm-dd. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered; the description adds the report's row contents and notes it is backed by the SOAP GetTrialBalance call. It does not disclose pagination behavior or that results are truncated by default, which matters since limit/offset exist with a default of 100 and max 500.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact clauses: what the report contains first, then the backend source. Zero filler and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description helpfully names the returned columns (nominal code, debit, credit, balance), which is genuinely useful. However, for a report tool with paging parameters it omits that results are paginated and default-limited, so an agent could silently get an incomplete trial balance.
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 limit, offset and both dates fully documented in the schema, so the description correctly does no redundant work. It adds no meaning beyond the schema, which is the baseline-3 case.
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 ("The trial balance") and clarifies the shape of the result (every nominal code with debit, credit and balance). It doesn't explicitly differentiate from accounting-report siblings like get_balance_sheet or get_profit_and_loss, but the name and content make the distinction reasonably obvious.
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 choose this over sibling reports such as get_balance_sheet, get_profit_and_loss or list_nominal_codes, and no prerequisites or exclusions. The only usage hint is the implied date-range requirement, which the schema already enforces via required start_date/end_date.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The VAT return figures (boxes 1 to 9) for a period, and whether it was submitted to HMRC. SOAP GetVATReport.
| Name | Required | Description | Default |
|---|---|---|---|
| end_date | Yes | End of the VAT period, yyyy-mm-dd. | |
| start_date | Yes | Start of the VAT period, yyyy-mm-dd. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful disclosure of what is returned (boxes 1-9 plus an HMRC submission flag), but says nothing about HMRC connectivity failures, historical period limits, or how unsubmitted periods are represented.
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 tight sentences with the payload described first and the underlying SOAP operation last. No filler, no repetition of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, and the description does sketch the return content (nine VAT boxes plus submission status), which is the key information an agent needs. It could say more about return shape or period granularity, but it is complete enough to select and call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with two required date parameters already documented as yyyy-mm-dd. The description only reinforces that both dates bound a VAT period; it adds no format, range, or alignment guidance 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 resource and scope: VAT return figures for boxes 1 to 9 over a period, plus submission status. The resource (VAT return) is clearly distinct from the sibling kashflow_list_vat_rates, though the description never names that sibling explicitly to reinforce the split.
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 a period' and the required start/end dates. There is no statement of when to prefer this over kashflow_list_vat_rates or any other reporting tool, and no prerequisites or exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The bank accounts (AccountID, name, nominal code). SOAP GetBankAccounts.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds value by enumerating the return fields, which matters since there is no output schema, but it says nothing about whether balances are included or how nominal codes map to transactions. The 'SOAP GetBankAccounts' note identifies the transport but does not add behavioral insight.
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 fragments with no waste, front-loading the resource and its fields. It is very terse and slightly telegraphic, but nothing is padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters, no output schema and annotations covering safety, the description covers the essentials by listing returned fields. Still, it does not clarify whether account balances are present (relevant given kashflow_get_bank_balance exists) or what an agent should do with the nominal code, leaving a moderate gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the schema baseline is 4. The description correctly implies no filtering inputs are required and the call returns all bank accounts.
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 the resource ('The bank accounts') and the returned fields (AccountID, name, nominal code), which lets an agent distinguish it from the sibling kashflow_list_bank_transactions. However, it is a noun fragment with no verb, so the action (list/retrieve all) is only inferable from the tool name and title.
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 versus kashflow_get_bank_balance or kashflow_list_bank_transactions, and no prerequisites or conditions are stated. The agent must infer usage entirely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The transactions of one bank account (date, money in/out, VAT, type, comment, customer/supplier), by AccountID from kashflow_list_bank_accounts, paged here. SOAP GetBankTransactions.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many records to return (default 100, max 500). | |
| offset | No | How many records to skip (default 0), to get the next page. | |
| account_id | Yes | The bank account's AccountID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the returned field set and that pagination is handled by this tool ('paged here'), plus the underlying SOAP method. It says nothing about result ordering, total counts, or rate limits, so it adds only modest context beyond the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the resource and scope, then the field list, then the cross-tool dependency in a single dense sentence; the trailing 'SOAP GetBankTransactions' is short and useful for correlating with raw API docs. The parenthetical field list is compact and earns its place as a substitute for a missing output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by naming the returned fields and the pagination mechanism, and it covers the required-input precondition. Missing only minor operational details such as ordering or how to know when paging is exhausted, which is acceptable for a simple list 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 limit/offset semantics (defaults, max 500) are already documented; the description's 'paged here' merely reinforces that. Its real contribution is provenance for the required account_id, telling the agent where to obtain a valid AccountID, which the schema does not say.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names the exact resource (transactions of a single bank account) and enumerates the returned fields, so an agent knows precisely what it retrieves. It also disambiguates from the sibling kashflow_list_bank_accounts by stating that the AccountID comes from that tool. It stops short of an explicit verb like 'list', relying on the title/name for that framing.
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?
'by AccountID from kashflow_list_bank_accounts' gives an explicit prerequisite chain, telling the agent to call the accounts lister first. It gives no when-not-to-use guidance or alternatives for transaction retrieval (e.g. vs. kashflow_list_payments_by_date), which keeps it below a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
All sales invoices of one customer, by numeric CustomerID (see kashflow_get_customer for the id), paged here. SOAP GetInvoicesForCustomer.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many records to return (default 100, max 500). | |
| offset | No | How many records to skip (default 0), to get the next page. | |
| customer_id | Yes | The numeric CustomerID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the paging behavior ('paged here') and the underlying SOAP operation name, but says nothing about the shape of returned invoice records or page-size limits (which the schema covers).
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 compact sentence with the resource and scoping constraint front-loaded, followed by the implementation note. Slightly telegraphic ('paged here'), 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 read-only, three-parameter list tool with a fully documented schema and no output schema, the essentials are present. It is still thin on what the returned invoices contain and how this differs from the general invoice listings, which is the gap an agent would most likely hit.
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 already carry their own descriptions including defaults and max values. The description reinforces that customer_id is numeric and that limit/offset produce pages, but adds no syntax or semantics beyond the schema — 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 and resource: all sales invoices for one customer, keyed by numeric CustomerID, with paging. It does not explicitly distinguish itself from the siblings kashflow_list_invoices or kashflow_list_unpaid_invoices, so an agent must infer that this is the per-customer scoped variant.
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 usefully routes the agent to kashflow_get_customer for resolving the id, which is real guidance. However, it never says when to prefer this over kashflow_list_invoices, kashflow_list_overdue_invoices, or kashflow_list_unpaid_invoices, so the main sibling choice is left implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
All customers (name, code, contact, email, phone, address, VAT number, payment terms, notes), paged here: the reply says total and next_offset. SOAP GetCustomers.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many records to return (default 100, max 500). | |
| offset | No | How many records to skip (default 0), to get the next page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true). Beyond that, the description adds genuinely new behavioral context: that the result is paged and that the reply carries 'total' and 'next_offset', which tells the agent how to iterate — important since no output schema exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single compact sentence that front-loads the resource and its fields, then the paging behavior. Very little waste, though the SOAP method reference ('SOAP GetCustomers') is filler for an agent that only needs MCP semantics.
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-parameter, no-required-args list tool, the description covers what is returned, which fields appear, and how pagination is surfaced — filling the gap left by the absence of an output schema. Missing only explicit routing guidance against the many sibling lookup tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both limit and offset fully documented including defaults and maximums, so the baseline is 3. The description nods to paging ('next_offset') but adds no format or semantics beyond what the schema already states.
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 ('All customers') and enumerates the fields returned, so the agent immediately knows this is an unfiltered customer dump. It does not explicitly differentiate from siblings like kashflow_get_customer_by_id or kashflow_find_customer_by_email, though 'All customers' plus paging implies 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?
Usage is only implied: 'All customers' suggests this is the bulk-list path rather than a lookup, but there is no explicit when-to-use or when-not-to-use guidance and no named alternative such as find_customer_by_email. An agent must infer the routing decision itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The payments recorded against one sales invoice (date, amount, method, bank account, note), by invoice number. SOAP GetInvoicePayment.
| Name | Required | Description | Default |
|---|---|---|---|
| invoice_number | Yes | The invoice number. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the returned field set and the backend SOAP call name, but says nothing about auth needs, pagination or volume limits for an invoice with many payments.
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 front-loaded sentence with the resource scope first and the return fields compactly parenthesized; the SOAP method tag is small but useful for debugging. 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 read-only one-parameter list tool with full schema coverage and complete annotations, this is nearly sufficient: scope and return fields are stated even though no output schema exists. Only the sibling routing and edge-case behavior are absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single invoice_number parameter, so the baseline is a 3. The description confirms the number identifies a sales invoice, reinforcing the schema meaning rather than merely repeating it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: payments recorded against one sales invoice, keyed by invoice number, plus the return fields. It implicitly distinguishes itself from kashflow_list_payments_by_date through the per-invoice scope, 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?
The usage is implied by 'against one sales invoice... by invoice number', making it clear this is the per-invoice lookup. However, it never states when to use this over kashflow_list_payments_by_date or kashflow_get_invoice, 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.
Sales invoices dated within a range (inclusive; a bare end date means the end of that day), paged here. Dates are yyyy-mm-dd. SOAP GetInvoicesByDateRange.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many records to return (default 100, max 500). | |
| offset | No | How many records to skip (default 0), to get the next page. | |
| end_date | Yes | Last invoice date, yyyy-mm-dd. | |
| start_date | Yes | First invoice date, yyyy-mm-dd. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description earns credit by adding non-obvious behavior the annotations cannot convey: the range is inclusive, a bare end date resolves to end-of-day, and it maps to the SOAP GetInvoicesByDateRange call. It omits result ordering and total-count behavior, which keeps it from a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short clauses with no filler; the scope, date semantics, and paging note are all front-loaded in the first sentence. Every element carries information an agent would otherwise have to guess.
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 saying what comes back, and 'Sales invoices ... paged here' leaves the record shape and whether paging metadata is returned unstated. It also gives no guidance for distinguishing this from the other invoice-list siblings, though the read-only annotations cover the safety dimension.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description still adds real meaning beyond the schema: it clarifies that both bounds are inclusive and that a date-only end_date includes the whole day, semantics the schema's 'Last invoice date' wording does not supply. Limit/offset behavior is only hinted at with 'paged here'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Sales invoices dated within a range ... paged here'), which distinguishes it from date-unrelated siblings like list_overdue_invoices or list_unpaid_invoices. It never names the date-scoped alternatives (kashflow_list_recent_invoices, kashflow_list_customer_invoices) explicitly, so the differentiation is implied rather than spelled out.
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 date-range framing implies when to reach for this tool, and 'paged here' signals the pagination path, but there is no explicit statement of when to prefer it over kashflow_list_recent_invoices or kashflow_list_customer_invoices, and no exclusions. Usage is inferable, not guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The chart of accounts: nominal codes with their names. SOAP GetNominalCodes.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many records to return (default 100, max 500). | |
| offset | No | How many records to skip (default 0), to get the next page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered without description help. The description adds one useful piece of content context — that names are returned alongside codes, i.e. it is self-contained for lookups — but says nothing about ordering, whether the full chart is returned, or how paging interacts with results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the resource and its contents. The trailing 'SOAP GetNominalCodes' is protocol detail of marginal value to an agent, but it costs only a few tokens.
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 paginated read with no output schema, the description should at least sketch the returned fields; it says only 'codes with their names' and omits whether an internal ID or account type is included. Combined with missing ordering/total-count behaviour, this is adequate but not 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 100%: both limit and offset are documented with defaults and maxima in the schema itself. The description contributes nothing about parameters, which is acceptable at this coverage level but earns only the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the resource precisely ('the chart of accounts: nominal codes with their names'), which is unambiguous and clearly distinct from every sibling (customers, invoices, VAT rates, bank accounts). It stops short of a clean verb+resource statement in the sentence itself, relying on the title 'List nominal codes', but an agent can still tell exactly what data comes back.
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 what nominal codes are used for (e.g. mapping transactions or invoice line items to accounts), and no routing to or away from any sibling tool. The agent must infer the usage context entirely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
All sales invoices past their due date and not paid in full, paged here. SOAP GetInvoices_Overdue.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many records to return (default 100, max 500). | |
| offset | No | How many records to skip (default 0), to get the next page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds the overdue/unpaid-in-full filter semantics and the fact that results are paged, but says nothing about ordering, return fields, or the SOAP call's cost/latency.
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?
Very short and front-loaded: the filter condition comes first, pagination second. The trailing 'SOAP GetInvoices_Overdue' is implementation trivia of marginal value but only costs a few words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with full schema coverage and annotations, the essentials are present. However, with no output schema and no statement of what an invoice record contains, the agent cannot anticipate the response shape or the ordering of results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters (limit, offset) are fully documented in the schema with defaults and bounds. The description adds nothing beyond schema, which is the expected baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource (sales invoices) with two concrete filter conditions (past due date, not paid in full) and notes it is paged. An agent can distinguish it from a general invoice list, though the distinction from the sibling kashflow_list_unpaid_invoices 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?
The filter definition implies when the tool applies, but there is no explicit 'use this instead of kashflow_list_unpaid_invoices when...' guidance, even though a near-duplicate sibling exists. Nothing states prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Customer payments received within a date range (date, amount, invoice, method, bank account). KashFlow returns them a page at a time: set page_number 1, 2, ... until a page comes back empty. Dates are yyyy-mm-dd. SOAP GetInvoicePaymentsByDateRange.
| Name | Required | Description | Default |
|---|---|---|---|
| end_date | Yes | Last payment date, yyyy-mm-dd. | |
| start_date | Yes | First payment date, yyyy-mm-dd. | |
| page_number | No | Page number, starting at 1 (default 1). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds real behavioral value beyond that: the pagination termination rule (empty page signals the end) and the SOAP method name. It says nothing about result-size caps for wide date ranges or any auth/rate considerations.
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 what is returned, then pagination mechanics, then format and source method. Nothing is redundant and nothing could be cut without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, three-parameter list tool with no output schema, the description supplies the return field set, the date format, and the full pagination loop, which is enough to call it correctly. It omits any note on behavior when the range spans many pages or the fields absent from a payment record, minor gaps for this complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline would be 3, but the description adds meaning the schema does not: iteration semantics for page_number (repeat until an empty page) rather than just 'page number, starting at 1'. The yyyy-mm-dd note merely restates the schema's date format, so the gain is partial but genuine.
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 ('Customer payments received within a date range') and enumerates the returned fields, so the agent knows exactly what comes back. It does not explicitly distinguish itself from the sibling kashflow_list_invoice_payments, which an agent could plausibly confuse with a date-scoped listing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete invocation procedure: start at page_number 1 and increment until a page returns empty, which tells the agent how to drive the tool to completion. It stops short of stating when to prefer this over kashflow_list_invoice_payments or kashflow_list_recent_receipts, so no explicit exclusions are offered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The product catalogue (name, code, description, price, stock level), paged here. SOAP GetProducts.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many records to return (default 100, max 500). | |
| offset | No | How many records to skip (default 0), to get the next page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the source operation ('SOAP GetProducts') and the returned fields, but says nothing about default sort order, whether a total record count is returned, or rate-limit/throttling behavior on the SOAP backend.
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 fragments with no filler, and the resource is front-loaded. The phrasing 'paged here' is slightly awkward but the entry is appropriately sized for a simple list tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does the right thing by naming the returned fields, which is the main gap it needed to fill. It still omits ordering, whether the response carries a total count for paging, and any note on empty-result behavior, which matters for a paged list endpoint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and both parameters (limit, offset) carry defaults and max values in the schema itself. The description contributes no additional meaning beyond the vague 'paged here', 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?
The description identifies the resource (product catalogue) and enumerates the fields returned (name, code, description, price, stock level), which combined with the title 'List products' makes the operation identifiable. The verb is left implicit in the awkward fragment 'paged here', and no sibling tool covers products, so differentiation is moot but the purpose is still clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to use this tool, no prerequisite or exclusion, and no mention of alternatives. The phrase 'paged here' only implies that limit/offset are the mechanism, without stating how to page or when to stop.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The projects defined in the account (id, name). SOAP GetProjects.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is carried by structured data. The description adds only the fact that this is a SOAP GetProjects call and what fields come back; it says nothing about whether inactive/archived projects are included or how large the result set can be.
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, front-loaded sentences: purpose plus return shape first, protocol note second. 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?
No output schema exists, so the description helpfully names the returned fields (id, name). For a zero-param read tool that is nearly sufficient; the only gaps are pagination/scope of the project list, which are minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters and 100% schema coverage, the baseline is 4. The parenthetical '(id, name)' describes the returned fields rather than parameters, which is a small bonus rather than a parameter clarification.
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 ('projects defined in the account') plus the exact fields returned (id, name), and identifies the underlying SOAP operation. It is not explicitly differentiated from the other list_* siblings, but no other project-related tool exists, so confusion risk is low.
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 can infer you call this to enumerate projects. There is no statement of when to prefer it over anything else, nor any note about how the returned project ids are consumed downstream (e.g. for filtering invoices), though with no sibling alternatives the practical cost is small.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
All sales quotes (same shape as invoices), paged here. SOAP GetQuotes.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many records to return (default 100, max 500). | |
| offset | No | How many records to skip (default 0), to get the next page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds real context beyond them: it discloses that results are paged, and that the record shape mirrors invoices — valuable given there is no output schema. It does not disclose default/max page size or whether a total count 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?
Two brief sentences, front-loaded with the resource and scope. The trailing 'SOAP GetQuotes' is implementation noise that adds little for an agent selecting the tool, but the overall size is well within budget.
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 two-parameter, read-only list tool with full schema coverage and no output schema, the description covers what is retrieved, that results are paged, and how the payload is shaped ('same shape as invoices'). The only gap is pagination termination behavior (no indication of whether a total count is returned).
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%: limit (default 100, max 500) and offset are fully documented in the schema. The description only echoes 'paged' and adds no format, default, or semantics beyond that, 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 the resource (sales quotes) and the operation (list/paged) unambiguously, and adds the useful cross-reference 'same shape as invoices'. It does not need to differentiate from siblings since no other quote tool exists in the sibling list, but it also never explicitly says 'retrieve' or contrasts with invoice listing.
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?
'All sales quotes' implies this is the unfiltered enumeration tool, and 'paged here' hints at iterating pages. However there is no explicit when-to-use statement, no note on when a caller would prefer an invoice-based tool, and no guidance on how to terminate pagination.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The most recently created sales invoices. SOAP GetInvoices_Recent.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | How many invoices (default 20, max 500). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds nothing behavioral beyond that – no ordering (newest first?), no truncation behavior at the 500 cap, no note that results are not filtered by customer or status. The 'SOAP GetInvoices_Recent' line is an implementation detail, not agent-relevant 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 fragments with zero padding, which is good, but the second sentence ('SOAP GetInvoices_Recent') consumes space without helping an agent decide or invoke. Brevity here reads as under-specification rather than discipline.
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 one-parameter, annotated, read-only list tool is a low-complexity case, and the schema covers the only argument. Still missing is the one thing 'recent' leaves ambiguous – whether results are newest-first and how this list is scoped versus kashflow_list_invoices.
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 count parameter already documents default 20 and max 500 in the schema. The description adds no meaning about count, 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?
The description names the resource and a qualifier ('most recently created sales invoices'), so the object is identifiable. But it is a noun phrase with no verb, and it never explains how 'recent' differs from the sibling kashflow_list_invoices or kashflow_list_customer_invoices, so an agent cannot reliably choose between them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to use this tool, no prerequisites, and no reference to the many nearby siblings (kashflow_list_invoices, kashflow_list_overdue_invoices, kashflow_list_unpaid_invoices). The only cue is the word 'recent' in the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The most recently created purchases (supplier invoices / receipts). SOAP GetReceipts_Recent.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | How many purchases (default 20, max 500). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly=true, destructive=false, openWorld=true, so the safety profile is covered. The description adds that results are scoped to the newest records (not a full listing), but says nothing about sort order or how 'recent' is bounded beyond the schema's count parameter. 'SOAP GetReceipts_Recent' is implementation detail rather than 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?
Two short sentences, front-loaded with the resource and scope. The trailing 'SOAP GetReceipts_Recent' is low-value internal plumbing that consumes space without helping an agent decide or invoke.
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 simple read-only list with annotations covering safety, a fully documented single parameter, and no output schema, so the description is close to sufficient. What's missing is how this differs from kashflow_list_supplier_receipts and kashflow_get_receipt, which matters given the dense receipt/invoice sibling set.
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 'count' parameter is fully documented in-schema with default (20) and maximum (500). The description adds no syntax or semantics beyond that, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (list the most recently created purchases / supplier invoices / receipts), with the parenthetical clarifying terminology. It implicitly separates itself from kashflow_list_supplier_receipts and kashflow_get_receipt via the 'most recently created' qualifier, but never names those siblings, so the 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?
'The most recently created' implies the scenario (surveying newest activity) but there is no explicit when-to-use, no exclusion, and no pointer to kashflow_list_supplier_receipts for full/filtered retrieval. Usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
All purchases (supplier invoices / receipts) of one supplier, by numeric SupplierID (see kashflow_get_supplier), paged here. SOAP GetReceiptsForSupplier.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many records to return (default 100, max 500). | |
| offset | No | How many records to skip (default 0), to get the next page. | |
| supplier_id | Yes | The numeric SupplierID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that paging happens 'here' and names the backing SOAP method GetReceiptsForSupplier, but says nothing about ordering, volume, or rate/permission 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 front-loaded sentence plus the SOAP method name; no filler. 'paged here' is slightly cryptic, but the concept is reinforced by the limit/offset parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description carries some burden, but it conveys the record type (supplier invoices/receipts) and paging model, which is enough for correct invocation. It could have noted ordering or whether totals/summaries are included, a minor 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 coverage is 100% so the baseline is 3; the description still adds value by emphasizing that supplier_id is numeric and pointing to kashflow_get_supplier as the source of that ID, which the schema does not say. Limit/offset semantics are left entirely to the schema, which is fine given its 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+resource+scope ('All purchases (supplier invoices / receipts) of one supplier') and pins the identifier to SupplierID, which distinguishes it from kashflow_get_receipt (single) and kashflow_list_recent_receipts (cross-supplier). An agent can select it without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells the agent where the SupplierID comes from ('see kashflow_get_supplier') and that results are paged, giving clear preconditions. It does not explicitly state when to prefer kashflow_list_recent_receipts or kashflow_get_receipt instead, so it stops short of full alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
All suppliers (name, code, contact, email, phone, address, VAT number, payment terms), paged here: the reply says total and next_offset. SOAP GetSuppliers.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many records to return (default 100, max 500). | |
| offset | No | How many records to skip (default 0), to get the next page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the read-only, non-destructive profile, so credit goes to what is added: the set of returned attributes and the fact that the reply carries 'total' and 'next_offset'. This is the paging contract an agent needs and it is not in the annotations; auth/rate-limit details are still absent.
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: scope first, then the field payload, then the paging behavior. Every clause earns its place, including the trailing SOAP operation name for traceability.
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 two-parameter read-only list tool with full schema descriptions and no output schema, the description supplies the missing return-surface information (fields, total, next_offset). Nothing an agent needs to call and paginate it correctly is absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds the paging protocol glue the schema alone doesn't: the reply's 'next_offset' is what feeds the offset parameter, and 'total' signals how much remains. It does not restate limit/offset limits or defaults.
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 ('All suppliers') and enumerates the returned fields, making the tool's identity unambiguous against 'kashflow_get_supplier' and 'kashflow_list_supplier_receipts'. It does not explicitly name a sibling to contrast with, so it stops 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 opening 'All suppliers' implies the tool is for enumerating the full supplier directory rather than fetching one record, and 'paged here: the reply says total and next_offset' tells the agent how to iterate. No explicit when-to-use/when-not guidance or named alternative is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
All sales invoices not yet paid in full, paged here. SOAP GetInvoices_Unpaid.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many records to return (default 100, max 500). | |
| offset | No | How many records to skip (default 0), to get the next page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds essentially nothing beyond that – no ordering, whether partially paid invoices are included, or how much data volume to expect; the SOAP endpoint name ('GetInvoices_Unpaid') is implementation trivia rather than agent-useful 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 fragments with zero padding, and the key scope phrase comes first. The trailing 'paged here' and SOAP method name are slightly awkward but not wasteful enough to drop below a 4.
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 should say something about what a returned invoice contains or its ordering. It covers the filter and pagination adequately, but an agent still can't tell what it gets back or how results are sorted, leaving a clear gap for a tool with this many near-duplicate siblings.
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%, with both limit and offset fully documented including defaults and maxima, so the schema does the heavy lifting. The description only says 'paged here' and adds no meaning about page semantics or what happens at the boundaries, 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 the resource (sales invoices) and the filter (not yet paid in full) with implied list verb, so an agent knows what it returns. However, it does nothing to distinguish itself from close siblings like kashflow_list_overdue_invoices, kashflow_list_invoices, and kashflow_list_recent_invoices; the unpaid-vs-overdue boundary is left for the agent to guess.
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 choose this over list_overdue_invoices or list_invoices, and no exclusions or preconditions. The only usage-adjacent phrase is 'paged here', which signals pagination but not selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The VAT rates set up in the account. SOAP GetVATRates.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds almost nothing beyond that: the 'SOAP GetVATRates' note hints at the backing operation but discloses no return shape, pagination, or freshness of the rate data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short fragments with no filler, which is efficient, but the telegraphic style leaves the purpose under-specified rather than front-loading the key information an agent needs. Brevity is achieved at the cost of substance.
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 say what a VAT rate record contains (e.g., name, percentage, nominal code linkage). It does not, leaving the agent unable to predict the response for a tool that is otherwise simple.
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 clarify. The baseline of 4 applies for a parameterless read operation.
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 identifies the resource (VAT rates configured in the account) but is a noun fragment with no verb, so 'list' is only implied. It does at least clarify the scope (rates set up in the account) rather than restating the title verbatim, and it is distinguishable from kashflow_get_vat_report, but it never names 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?
There is no guidance on when to use this versus alternatives such as kashflow_get_vat_report or the invoice-listing tools that also surface VAT data. The agent must infer the use case entirely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
kashflow_add_invoice_notekashflow_create_customerkashflow_create_supplierkashflow_find_customer_by_emailkashflow_get_aged_creditorskashflow_get_aged_debtorskashflow_get_balance_sheetkashflow_get_bank_balancekashflow_get_company_detailskashflow_get_customerkashflow_get_customer_balancekashflow_get_customer_by_idkashflow_get_invoicekashflow_get_invoice_noteskashflow_get_kpiskashflow_get_profit_and_losskashflow_get_receiptkashflow_get_supplierkashflow_get_trial_balancekashflow_get_vat_reportkashflow_list_bank_accountskashflow_list_bank_transactionskashflow_list_customer_invoiceskashflow_list_customerskashflow_list_invoice_paymentskashflow_list_invoiceskashflow_list_nominal_codeskashflow_list_overdue_invoiceskashflow_list_payments_by_datekashflow_list_productskashflow_list_projectskashflow_list_quoteskashflow_list_recent_invoiceskashflow_list_recent_receiptskashflow_list_supplier_receiptskashflow_list_supplierskashflow_list_unpaid_invoiceskashflow_list_vat_ratesRead FreeAgent contacts, invoices, bills, banking and reports; add contacts, draft invoices, time.
Read ChargeOver customers, invoices, transactions, subscriptions, reports; create customers, quotes.
Read SuperFaktura invoices, clients, expenses, bank and stock; create clients, expenses and drafts.
Read Bokio accounts, invoices and customers; create drafts and journal entries.
Add one secure layer between your agents and this server.