SmartAccounts MCP by usefulapi

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

Goes well beyond the annotations: it states this writes a real accounting record that cannot be edited or deleted via this server, that the tool never retries, and it discloses concrete rate limits (60/min, 1000/24h). That is unusually rich behavioral context for a creation tool.

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

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

Front-loads the action, then dedup guidance, then the return values, then irreversibility and rate limits. Four tightly packed sentences with little waste, though the operational caveats could be trimmed slightly for a first-read skim.

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

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

Despite no output schema, the description names the return values (clientId, referenceNumber) and covers mutation permanence, retry policy, and quota—the three things an agent most needs before firing an irreversible 15-parameter create.

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

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

The description contributes no parameter guidance at all, and 5 of 15 parameters lack schema descriptions (67% coverage). The two required fields, name and vat_pc, are documented in the schema, so the schema carries most of the load, but the description adds nothing for the remaining fields such as country, address1/2, or invoice_due_days.

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 new client') and even names the underlying API operation (purchasesales/clients:add). It is immediately distinguishable from siblings like smartaccounts_create_sales_invoice or smartaccounts_create_ledger_entry.

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

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

Explicitly routes the agent to smartaccounts_list_clients first to avoid duplicate creation, and gives a recovery protocol for ambiguous replies ('look in SmartAccounts before calling again'). This is exactly the when/when-not/alternative guidance the dimension asks for.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, but the description goes further by explaining that the entry cannot be edited or deleted via this server and must be corrected in SmartAccounts. It also discloses the no-retry safety rule, the specific return fields (id, number, amount), and concrete rate limits (60/min, 1000/24h), all of which are absent from annotations.

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

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

The description is a dense, front-loaded paragraph that starts with the core action and then layers on constraints, consequences, and rate limits. Every sentence carries actionable information for a destructive, non-idempotent operation, with no filler.

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

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

There is no output schema, but the description names the returned fields (id, number, amount) and covers failure modes, correction workflow, rate limits, and prerequisite account lookup. Nothing critical for an agent to invoke this create tool safely appears to be missing.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters including row-level fields. The description adds only minor semantic context (EUR currency and the debit-credit balancing rule), both of which are already present in the schema's own descriptions. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description names a specific verb and resource: 'Post a manual general ledger entry (journal entry, general/entries:add) in EUR.' It clarifies this is a manual accounting record, distinguishing it from sibling tools like create_sales_invoice or create_payment, and it states the exact API action.

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

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

The description gives clear operational context: account codes must come from smartaccounts_list_accounts, debits must equal credits, and the call fails during a locked period. It does not explicitly name which sibling creation tool to use for other transaction types, but the 'manual general ledger entry' framing and the list_accounts prerequisite provide strong guidance.

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

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

Annotations only declare the write/destructive/non-idempotent profile; the description adds substantial value beyond them: it creates a real book entry that this server cannot edit or delete, corrects must be made in SmartAccounts, it never retries and the caller should inspect SmartAccounts on an unclear reply, and it discloses rate limits (60/min, 1000/24h).

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

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

Front-loads the core action, then layers operational detail (sources, currency rule, return fields, immutability, rate limit). It is on the longer side but each sentence carries distinct information, so little 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?

No output schema exists, yet the description still names the returned fields (paymentId, number, amount), and it covers the mutation caveats, retry behavior and rate limits, leaving nothing essential for a correct call unstated.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-field meaning: the source of account_name (bank/cash account lists) and invoice ids (invoice lists) and the constraint that currency must match the account's currency.

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 ('Record') and resource ('bank or cash payment against one or more invoices'), and disambiguates the two scenarios (client paying a sales invoice vs. payment to a vendor) so an agent can place it among the invoice-related siblings.

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

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

Explicitly routes the agent to smartaccounts_list_bank_accounts / _list_cash_accounts for account_name and to the invoice lists for row ids, giving clear context for when this tool applies. It stops short of naming when NOT to use it or which siblings (e.g. create_ledger_entry) are the wrong choice, so no exclusions are given.

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

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

Goes well beyond the annotations: the invoice number is system-generated, totals and VAT are computed from rows, the entry is booked to the ledger immediately (not a draft), it fails on a locked period, it cannot be edited or deleted through this server, the server never retries, and rate limits of 60/min and 1000/24h are stated.

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

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

Purpose and create-semantics are front-loaded in the first two sentences, with prerequisites, return values, and rate limits following in logical order. It runs long (nine sentences) but nearly every sentence carries actionable information.

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

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

With no output schema, the description compensates by naming the return values (invoiceId, number, totals). It covers the destructive, non-idempotent, non-editable nature of the call and all prerequisite list tools, leaving nothing essential unsaid for a 9-parameter mutation.

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

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

Schema description coverage is 100%, so the schema itself documents every field including nested rows. The description adds only the source-of-truth hints (article codes, VAT codes, client existence), which largely duplicate the schema's own descriptions, so the baseline 3 applies.

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

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

States a specific verb and resource ('Post a new sales (client) invoice') plus the underlying API endpoint, which distinguishes it from sibling creators like create_ledger_entry and create_payment. An agent can identify it as the sales-invoice creator without reading the schema.

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

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

Gives concrete preconditions: the client must exist (pointing at smartaccounts_list_clients), row codes must come from smartaccounts_list_articles, and vat_pc from smartaccounts_list_vat_rates. It also notes failure when the period is locked, but does not discuss when a payment or credit note would be the better call.

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

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

readOnlyHint=true already establishes the safety profile, and the description adds genuinely new behavioral context: concrete rate limits (60 requests/minute, 1000 per 24 hours) and the fact that each call consumes one request. That is useful capacity-planning information an agent cannot get from the annotations. It stops short of describing auth needs or failure behavior, so it is not a 5.

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

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

Two compact sentences, with the core purpose front-loaded and the operational constraint appended; nothing is redundant. The phrase 'The vendor limit' is slightly confusing on a client-facing tool, which keeps it from a 5.

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

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

For a simple read-only lookup with no output schema and full schema coverage, the definition supplies everything needed: what is returned, the addressing id's source (smartaccounts_list_clients), optional filters, and rate limits. Return-value detail is not required here and the safety profile is carried by annotations.

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

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

Schema description coverage is 100%, so all three parameters (id, balance_date, fetch_details) are already documented in the schema with format and defaults. The description adds only the softer notion that the date is 'past' and that details are 'open documents', which does not go meaningfully beyond the schema. Baseline 3 applies.

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

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

States a specific resource and scope: 'the outstanding balance of one client', with the upstream endpoint (purchasesales/clients:getbalance) for anchoring. An agent can immediately tell this reads a single client's balance rather than a list. It does not explicitly name the sibling smartaccounts_get_vendor_balance as the alternate resource, so differentiation is by resource name alone.

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

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

The description hints at optional usage ('optionally on a past date and with the open documents'), which tells the agent these are discretionary. But there is no explicit when-to-use guidance, no mention of when the vendor-balance sibling should be used instead, and no prerequisites or error conditions.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description goes further by disclosing concrete rate limits (60/min, 1000/24h) and clarifying that each call consumes one request, which is genuinely useful operational context. It stops short of describing the return payload beyond the optional document detail.

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

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

Two compact sentences with the core purpose front-loaded and the optional modifiers immediately after. The parenthetical API path and rate-limit clause are slightly incidental but still earn their place for an agent managing quotas.

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 tool the definition covers scope, optionality, and quota behavior. With no output schema, a brief note on the returned balance shape would help, but the mention of 'open documents' via fetch_details gives the agent enough to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents id, balance_date, and fetch_details. The description reframes the two optional parameters ('on a past date and with the open documents') but adds no format, default, or edge-case detail beyond what the schema states, so the baseline of 3 applies.

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

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

States a specific verb+resource ('outstanding balance owed to one vendor') and scopes it to a single vendor, which cleanly separates it from the sibling smartaccounts_get_client_balance. The 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?

Usage is implied by the resource and the optional date/documents framing, but there is no explicit when-to-use vs alternatives guidance (e.g., whether to prefer list_vendors first, or when a past-date balance is appropriate). 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.

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

readOnlyHint already establishes the safe-read profile, and the description goes beyond it with genuinely useful operational facts: the tool is not paged, the underlying endpoint is settings/accounts:get, and the vendor rate limits are 60 requests/minute and 1000/24 hours with each call counting as one request. That rate-limit and pagination disclosure is exactly the kind of context annotations cannot carry.

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

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

Three compact sentences that front-load the resource and its return fields before moving to operational notes. Slightly telegraphic ("(settings/accounts:get). Not paged."), but every fragment carries information and nothing is 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?

With no output schema, the description compensates by enumerating the returned fields and the account type vocabulary, and it discloses pagination and rate-limit behavior. Minor gaps remain — no mention of ordering or whether the list is exhaustive — but for a zero-parameter read tool this is close to complete.

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

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

The tool takes zero parameters, so the baseline is 4; there is no parameter surface for the description to clarify, and the enumerated return fields are the only supplementary detail it could reasonably add.

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 (chart of accounts) and enumerates what it returns — code, type with the ASSET/LIABILITY/INCOME/EXPENSE vocabulary, and bilingual descriptions — so an agent knows exactly what this tool produces. It does not explicitly contrast itself with lookalike siblings such as list_bank_accounts or list_cash_accounts, but the resource is specific enough to distinguish it.

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?

"Use the codes in ledger entries" implies the downstream purpose (fetching valid account codes before creating ledger entries), but it is guidance about what to do with the result, not when to call this tool or when to pick a different list tool. No exclusions or alternative selection criteria are given.

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

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

Beyond the readOnlyHint annotation, the description discloses pagination (100 per page) and hard vendor rate limits (60/min, 1000/24h) with the note that each call consumes one request — operationally critical context an agent needs to avoid throttling. This is substantive behavioral detail not present in 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 its returned fields, then search modes, then paging and limits. Dense but every sentence carries load, given there is no output schema to explain the returned fields elsewhere.

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

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

With no output schema, the description compensates by enumerating returned fields (code, description, type, unit, VAT code, sales/purchase prices, accounts) and covers paging and rate limits. Complete enough for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds an operational model linking parameters to search modes ('by code or name, or by modification time'), which helps the agent understand how code/search_string/modified_from/modified_to combine.

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 or search articles') and clarifies the domain explicitly as 'Products, services and warehouse items' with the underlying endpoint named. An agent can immediately distinguish this from sibling list tools (clients, invoices, payments, accounts).

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 search modes — 'by code or name, or by modification time' — so the agent knows which situations this tool serves. It does not explicitly name alternatives or exclusions, but the resource distinction from siblings is unambiguous.

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

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

Annotations already declare readOnlyHint=true, but the description adds genuinely useful behavioral facts: results are not paged, and there is a vendor rate limit of 60 req/min and 1000 req/24h, with each call counting as one request. That is exactly the kind of operational context annotations cannot express.

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

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

Three compact sentences in a telegraphed style: returned fields first, then endpoint/pagination, then rate limits. Every sentence carries information; the only minor cost is the terse, fragmentary phrasing.

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

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

With no output schema and no parameters, the description compensates by listing the returned fields and the pagination behavior, plus the rate-limit constraint an agent must respect. Nothing critical to correct invocation is missing, though the lack of sibling differentiation is a small residual 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 baseline is 4. The description sensibly uses the space to explain the returned shape instead of inventing parameter guidance.

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

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

Names the resource (the company's bank accounts) and enumerates the returned fields (name, ledger account, currency, IBAN, SWIFT), so an agent knows exactly what data comes back. It does not explicitly distinguish itself from similarly named siblings like smartaccounts_list_accounts or smartaccounts_list_cash_accounts, which is the only thing keeping it from 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?

Usage is implied by the list semantics and the '(settings/bankaccounts:get)' endpoint reference, and the 'Not paged' note tells the agent it can consume results in one shot. However, there is no explicit when-to-use statement or pointer to the sibling list tools it could be confused with.

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

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

Beyond the readOnlyHint annotation, the description discloses that results are not paged, gives the API endpoint (settings/cashaccounts:get), and states the vendor rate limits (60/min, 1000/24h, one request per call). That is meaningful operational context the annotations do not carry.

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

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

Three short sentences, each carrying distinct information: what it returns, the endpoint, and the constraints. Front-loaded with the resource and field list; no filler.

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

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

With no output schema, the description correctly compensates by naming the returned fields, and it covers pagination behavior and rate limits. An agent has essentially everything needed to invoke and interpret the call; only an explicit pointer to sibling alternatives is missing.

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

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

The tool takes zero parameters, so the baseline is 4. The description still adds value by clarifying which account fields come back and how 'name' maps to 'accountName' downstream, though it cannot document parameters that do not exist.

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 — 'the company's cash registers' — and enumerates the returned fields (name, ledger account, currency), which cleanly separates it from siblings like list_bank_accounts or list_accounts. It does not explicitly name those siblings, so it falls just short of a 5.

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

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

The parenthetical 'name (used as accountName in payments)' implies the practical use case — retrieving the identifier needed when creating payments — but there is no explicit when-to-use statement or comparison against the other list_* account tools. Usage is implied rather than stated.

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

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

Beyond the readOnlyHint annotation, the description discloses pagination size (100 per page) and explicit rate limits (60/min, 1000/24h) with the note that each call counts as one request. These are meaningful operational constraints the annotation does not carry. It omits return shape details, but the field list partly compensates.

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?

Compact and front-loaded: identity and fields first, then filters, then paging/limits. Every sentence carries information, with no boilerplate 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 output schema, the description usefully enumerates returned fields and covers paging plus rate limits, which is what an agent needs to call it correctly. The main residual gap is optional fetch_contacts/fetch_addresses, which are only documented in the schema.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters, giving a baseline of 3. The description restates the filter dimensions (name/registry code, id, modification time) but adds no syntax or format detail beyond the schema, and never mentions fetch_contacts or fetch_addresses.

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 (customers/clients) and enumerates the returned fields (id, name, regCode, vatNumber, due days, discount, VAT code), so an agent knows exactly what this returns. The verb 'List or search' plus the endpoint hint (purchasesales/clients:get) makes the action unambiguous. It does not explicitly differentiate itself from smartaccounts_list_vendors, but the subject makes the target 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?

Gives concrete filter modes (by name or registry code, by id, by modification time), which implies when the tool is useful. However, it names no alternatives (e.g., get_client_balance for balance) and states no exclusion conditions, so routing between siblings is left to inference.

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

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

Annotations already declare readOnlyHint=true, so safety is covered, but the description adds genuinely useful operational context absent from structured fields: pagination of 100 per page and the vendor rate limits (60 requests/minute, 1000 per 24 hours, one request per call). It stops short of describing return shape or ordering, but this is solid added value.

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

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

Three dense sentences with no filler: scope first, then filters, then paging and rate limits. Every sentence carries new information and nothing is front-loaded poorly.

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

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

For a read-only, zero-required-parameter list tool with no output schema, the description covers scope, filtering surface, pagination and rate limits — enough to invoke it correctly. The only minor gap is that it does not hint at what fields a returned entry contains.

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

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

Schema description coverage is 100%, so the schema already documents all nine parameters including enums and date formats. The description's filter summary (date, type, text, payment status) largely restates schema content without adding syntax or edge-case guidance, so the baseline 3 applies.

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

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

States a specific verb and resource (list general ledger entries) and enumerates the entry types it covers (manual entries, invoices, payments, VAT returns, depreciation), which distinguishes it from the narrower sibling lists such as smartaccounts_list_payments and smartaccounts_list_sales_invoices.

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

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

It describes the available filter dimensions (date, type, text, payment status), which implies how to narrow results, but never states when to prefer this tool over the type-specific list siblings. Usage context is inferable rather than explicit.

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

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

Annotations only declare readOnlyHint=true, so the description earns credit for adding paging behavior ('Not paged'), concrete rate limits (60/min, 1000/24h), and the underlying endpoint (settings/paymentmethods:get). This is genuinely useful operational context an agent could not get from the annotations alone.

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

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

Four short clauses, front-loaded with the resource and returned fields, then endpoint, paging, and limits. Dense but each clause carries distinct information; only the parenthetical endpoint is arguably of low value to an agent.

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

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

With no output schema and no parameters, the description compensates by naming the fields returned and stating that results are not paged, plus rate limits. This is close to complete for a simple read-only listing tool.

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

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

The tool takes zero parameters, so the baseline is 4. The empty schema leaves nothing to document, and the description correctly does not invent 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?

States a specific verb (list) and resource (payment methods) and enumerates the salient fields returned (name, ledger account, whether cash). It is clearly distinguishable from sibling list tools like list_payments or list_accounts, though it never explicitly names a contrasting 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?

Usage is only implied: the agent can infer this is the way to enumerate payment-method settings. There is no statement of when to prefer this tool over related siblings such as list_payments or create_payment, and no prerequisites are given.

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

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

Annotations only declare readOnlyHint=true, but the description adds genuinely useful behavior: pagination at 100 per page and hard rate limits (60 requests/minute, 1000 per 24 hours) with the clarification that each call counts as one request. It does not cover auth requirements or ordering, 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?

Front-loaded with purpose and returned fields, then pagination and rate limits; there is almost no filler. It is dense and slightly list-like, but each clause carries constraints an agent needs.

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

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

With no output schema, the description carries the return-value burden and does so: it enumerates the returned fields (date, partner, account, currency, amount, optional rows) and documents pagination and rate limits. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema by explaining that the returned rows show which invoices were paid (the schema only says 'Include the payment rows') and by restating the 100-per-page paging tied to the page parameter.

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

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

States a specific verb (list) and resource (payments), scopes it to bank and cash payments from clients/to vendors, and even cites the backing endpoint (purchasesales/payments:get). An agent can distinguish it from list_purchase_invoices or list_ledger_entries without opening a schema.

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

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

The description implies this is the read path for payment records and notes the payment-vs-modification date filtering, but never states when to prefer it over siblings like list_purchase_invoices, get_vendor_balance, or create_payment. Usage is inferable rather than explicit.

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

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

With readOnlyHint=true already covering the safety profile, the description adds genuinely useful context: pagination size (100 per page) and the vendor quota (60/min, 1000/24h) plus the note that each call consumes one request. That quota framing is exactly the sort of operational detail annotations do not provide; it stops short of describing the response envelope, but the field list partially covers that.

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

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

Four compact sentences, front-loaded with purpose and resource identifier before the filtering and rate-limit details. Dense but every clause carries information; only the field enumeration slightly overlaps with the 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?

For a 10-parameter paginated read with no output schema, the description compensates by listing returned fields and explaining pagination and quota limits. Annotations cover safety. It is close to complete; a note on how the response exposes the next page number would close the last gap.

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

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

Schema description coverage is 100%, so all 10 parameters are already documented in the schema, including enum values and date formats. The description merely restates the filterable dimensions and does not add syntax, defaults, or interactions beyond what the schema provides, 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 (list) and a precisely scoped resource (purchase/vendor invoices), explicitly contrasted with the sibling sales-invoice tool via the '(vendor)' qualifier. It also enumerates the returned fields (number, vendor, dates, amounts, VAT, outstanding amount, optional rows), so an agent knows both what it fetches and roughly what 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?

The description conveys usable filter dimensions (date, vendor, number, payment status with unpaid/overdue) but gives no explicit when-to-use guidance or routing against alternatives like list_sales_invoices. Usage is implied by the resource name rather than stated, leaving the agent to infer selection.

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

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

With readOnlyHint=true already covering safety, the description adds rate limits (60/min, 1000/day), page size (100 per page), request cost per call, and returned fields including optional rows. This is useful context beyond annotations, though auth and error behavior are not covered.

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

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

Three compact sentences front-load the resource and returned fields, then filtering, then rate limits. No filler; every clause adds operational value.

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

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

For a 10-parameter list tool with no output schema, the description covers return fields, filtering, paging, and rate limits. It omits details like default sort order or the full pagination response shape, but these are minor given the schema and endpoint context.

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

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

Schema description coverage is 100%, so all 10 parameters are already documented in the schema. The description restates filter categories and optional rows but adds little syntax or semantic detail beyond what the schema provides.

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

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

States a specific verb ('List') and resource ('sales (client) invoices'), and lists the returned fields. It clearly separates sales invoices from other resources, though it does not explicitly name the purchase-invoice sibling to distinguish the two.

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

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

Provides filter dimensions (date, client, number, payment status) and paging, but no explicit when-to-use or when-not-to-use guidance versus alternatives. Usage is implied by the filter options rather than stated as routing guidance.

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

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

Annotations only supply readOnlyHint, so the description carries the rest and does so well: it discloses that results are not paged, gives concrete rate limits (60/min, 1000/24h), and notes each call counts as one request — all operationally relevant and beyond the annotation. It stops short of describing error behavior or response size.

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

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

Compact and free of filler, with rate-limit and pagination notes packed into short clauses. It front-loads the returned field enumeration rather than the purpose statement, which is slightly suboptimal, but the title already establishes purpose so no meaning is lost.

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 parameters, the description usefully compensates by listing the fields a caller will receive and stating the non-paged/rate-limit behavior. For a simple zero-arg list tool this is complete enough, though it could note the response envelope shape.

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

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

The tool takes zero parameters, so the baseline is 4 with nothing for the description to disambiguate. The field enumeration in the description applies to output, not inputs, and is not penalized here.

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

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

The name and title state the verb+resource (list VAT rates) clearly, and the description confirms by enumerating the returned fields (vatPc code, percentage, descriptions, active-for-sales/purchases, accounts). It does not explicitly contrast with any sibling, but no sibling overlaps in domain, so disambiguation is effectively unnecessary.

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?

"Use vatPc in client and invoice rows" is a genuine usage hint that tells the agent where the returned codes are consumed. However there is no stated condition for when to call this versus alternatives, no prerequisites, and no exclusions — usage is implied rather than directed.

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

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

Annotations only declare readOnlyHint=true, so the description goes beyond them by disclosing pagination granularity (100 per page) and explicit rate limits (60 requests/minute and 1000 per 24 hours, with each call counting as one request). Those operational constraints are genuinely useful for planning. It stops short of describing error behavior or what happens for an invalid id.

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?

Compact and front-loaded: identity of the resource and returned fields come first, then filters, then paging and limits. Every clause carries information, though the run-on comma-listing of fields and filters is dense and could be structured more readably.

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

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

With no output schema, the description compensates by enumerating the returned fields, and it covers paging plus quota limits. What remains thin is the absence of guidance on combining filters or how next-page continuation ties in, but the essentials for calling it correctly are present.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters in detail, establishing a baseline of 3. The description corroborates the filterable dimensions but adds no syntax, precedence, or behavior beyond the schema text (e.g., it never mentions fetch_contacts or fetch_addresses enrichments).

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 (list or search) and resource (vendors/suppliers of the company), and pins the underlying endpoint purchasesales/vendors:get. It also enumerates the returned fields (id, name, regCode, vatNumber, bank account, VAT code), making it plainly distinguishable from sibling tools like list_clients or get_vendor_balance.

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

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

It does list the available filter axes (name or registry code, id, modification time) and notes paging, which implies how to use it. However, it never states when to prefer this over the sibling get_vendor_balance, nor any when-not condition or alternative tool reference, leaving routing to inference.

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