Merit Aktiva MCP by usefulapi

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

Annotations declare readOnlyHint=true, so the safety profile is covered. The description adds useful return-shape context (one row per report line with balances) but omits pagination behavior, authentication needs, and any caveats about the POST endpoint used for a read.

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

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

The description is a single front-loaded sentence that states purpose first and parameter behavior second. The trailing POST endpoint is arguably redundant implementation detail, but the overall statement is efficient with no wasted prose.

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 report tool with no output schema, the description adequately conveys what will be returned and how the period parameters interact. It does not cover pagination or response format details, but the core need for correct invocation is met.

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 fully documented in the schema. The description reinforces that per_count counts months back from end_date, adding a bit of relationship context but nothing the schema does not already provide.

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 specific resource (balance sheet) and describes the return shape: one row per report line covering assets, liabilities, and equity. It does not explicitly differentiate from the closest sibling, merit_income_statement, but the stated line items make the distinction inferable.

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 alternatives such as merit_income_statement, and no prerequisites or exclusions. The usage is only implied by the tool name and report content.

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

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

Annotations already declare readOnly=false, idempotent=false, destructive=false and openWorld=true. The description goes well beyond that by disclosing the duplicate-name failure mode ('Merit answers with an error'), the absence of downstream side effects ('Nothing is invoiced, sent or paid'), and the return value, since there is no output schema.

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

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

Front-loaded with the WRITE marker and the highest-value fact (uniqueness/error), then the no-side-effects note, then the conditional rules. Every sentence carries weight; the Estonia sentence's phrasing ('city is required in Estonia for a non-EE country') is slightly dense but not wasteful.

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

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

For a 17-parameter mutation tool with no output schema, it covers the critical gaps: return value, duplicate handling, and country-specific validation. It omits auth/company-scoping prerequisites and the exact error payload shape, which are the remaining unknowns 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 contributes cross-field conditional logic the schema cannot express: not_td_customer must be true for Estonian private persons and foreign companies, and city becomes required for non-EE countries in Estonia. It does not explain the Poland-specific variants 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?

Opens with an explicit WRITE marker and a specific verb+resource+cardinality ('creates ONE new customer record'), which immediately separates it from merit_list_customers and the vendor-side siblings. The uniqueness constraint and POST endpoint name add further precision about what is actually created.

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

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

Gives clear context for use: uniqueness requirement, the fact that an existing customer is never overwritten, and Estonia-specific conditions for not_td_customer and city. It stops short of naming an alternative (e.g. merit_list_customers to check for duplicates first), so the agent must infer the lookup-before-create workflow.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds real value beyond that: it is a POST despite being read-only, it lists the exact returned fields (useful since there is no output schema), and it documents the filter behaviors.

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-first with the returned fields up front, then filter semantics, then the endpoint. Dense but every sentence carries information; only the raw endpoint path is arguably 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 report with no output schema, the description supplies the column list an agent needs to interpret results, and the schema covers as_of, customer_id, max_results and over_due_days. Nothing critical is missing, though pagination/default behavior is left to the schema.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description largely restates those same constraints (empty string = all customers, overdue threshold) without adding new syntax or format detail, so baseline 3 applies.

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

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

States a specific resource and scope: open customer receivables, and enumerates the per-document fields returned (customer, date, due date, total, paid, unpaid). This clearly distinguishes it from merit_customer_payments_report, 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?

Filter semantics are explained (customer_name/id selection, over_due_days threshold), which implies when the tool applies, but there is no explicit when-to-use guidance nor any routing against siblings like merit_customer_payments_report or merit_sales_report.

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 declares this a safe read, and the description adds substantive behavior the annotations cannot convey: only the FIRST page is returned and there is no continuation endpoint, so truncation is a real risk. That is exactly the kind of hidden limitation an agent needs before calling.

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

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

Two dense sentences with the scope, the pagination caveat, and the endpoint all front-loaded; little waste. The raw POST path is mildly implementation-flavored but not harmful.

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-shape burden and does name the key returned concepts (unpaid amount, overdue flag, has_more). For a read-only report with a fully documented schema, nothing essential is missing, though the customer-vs-debts-report distinction is not resolved.

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 meaning beyond the terse schema text: customer_name and customer_id are framed as alternative ways to identify one customer, and period_start/period_end are described as the bounding period. Currency is left to the schema alone.

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

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

States a specific verb+resource+scope: customer invoices with unpaid amount and overdue flag for a period and a single customer. An agent can distinguish it from list-style siblings, though it never names merit_customer_debts_report or merit_sales_report, which cover adjacent territory.

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 real operational guidance — single-customer scope, and that when has_more is true the agent should narrow the period or customer because continuation is unsupported. However it offers no explicit when-to-use-vs-alternatives routing against the overlapping report siblings, leaving that inference to the agent.

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

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

readOnlyHint=true already tells the agent this is a safe read. Beyond that, the description adds a genuine behavioral disclosure: 'The attachment is never requested,' which prevents the agent from expecting attachment data. It stops short of covering return format, pagination, or auth, so a 3 is appropriate.

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 with the resource and its contents front-loaded, followed by the negative disclosure and the endpoint. Every clause is informative, though the trailing 'POST /api/v1/getglbatch' is of marginal value to an agent already given structured fields.

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

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

For a single-parameter, read-only tool with a 100% covered schema, the description substitutes well for the absent output schema by enumerating the line fields returned. Nothing critical to invoking it correctly is missing.

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

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

Schema coverage is 100% and the schema itself documents the id pattern and even points to the source (GLBId from merit_list_gl_batches). The description adds no additional parameter meaning, 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 (get) and resource (general ledger batch) and enumerates the nested contents (debit/credit lines with account, memo, department, tax, amounts). The singular 'One general ledger batch' implicitly distinguishes it from the plural merit_list_gl_batches sibling, though it doesn't name that sibling explicitly.

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

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

Usage is implied by the singular scope (fetch one batch by id, versus listing batches), but there is no explicit when-to-use, when-not-to-use, or named alternative. The agent must infer the list-vs-detail relationship from the sibling tool names.

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

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

readOnlyHint=true already declares this a safe read, and the description adds real value on top: it scopes the payload ('header, lines, payments') and explicitly notes 'The attachment is never requested', which tells the agent an attached document will be absent. It also exposes the underlying endpoint. No auth or rate-limit detail, but that gap is minor for a read.

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, front-loaded sentences with no padding; the payload scope leads. The raw HTTP endpoint at the end is marginally useful but borders on implementation noise.

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

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

For a single-resource read with one required param and no output schema, the description conveys what comes back and the notable omission of the attachment, which is enough for correct invocation. It stops short of describing any pagination or error behavior, but none is expected here.

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 id parameter (including its PIHId origin and UUID pattern) is fully documented in the schema. The description adds no parameter meaning beyond that, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource ('One purchase invoice in full') and enumerates the returned sections (header, lines, payments), so an agent can tell it retrieves a single fully-hydrated invoice. It does not explicitly name or contrast itself with the sibling merit_list_purchase_invoices, which keeps 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?

The description gives no when-to-use, when-not, or alternative routing. The only hint that this is a follow-up to a listing tool lives in the id parameter's schema description ('PIHId from merit_list_purchase_invoices'), not in the description itself.

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

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

Annotations declare readOnlyHint=true, so safety is already covered, but the description adds genuinely new behavioral context: it discloses that the PDF attachment is never fetched, which prevents an agent from expecting binary content, and it surfaces the underlying endpoint (POST /api/v2/getinvoice), useful for error diagnosis.

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 that front-load the returned content, with the endpoint tacked on as a single trailing clause. Every element earns its place; nothing is repeated from the title or annotations.

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

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

With no output schema, the description correctly carries the burden of describing the response shape at a useful level of granularity. It stops short of stating failure behavior (e.g. what happens for an unknown id), which is the main remaining gap for a single-record fetch 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?

Single required parameter with 100% schema description coverage, including a UUID pattern and the source field (SIHId from merit_list_sales_invoices). The description adds nothing about the identifier beyond what the schema already states, 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 ('One sales invoice in full') and enumerates the returned payload — header, lines with items/quantities/VAT/accounts, payments and dimension allocations. The 'in full' / single-record framing implicitly separates it from merit_list_sales_invoices and merit_search_sales_invoices, though none is named 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?

No when-to-use guidance, no prerequisites, and no mention of alternatives such as merit_list_sales_invoices or merit_search_sales_invoices. The only routing hint (that the id comes from merit_list_sales_invoices) lives in the schema, not the description.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds useful behavior beyond that: rows map one-per-report-line, periods count backward from end_date and are ordered newest first. It omits anything about pagination, currency rounding, or what a balance column contains, and the raw "POST /api/v1/getprofitrep" transport detail adds little for an agent.

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

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

Front-loaded with the report identity, then the output granularity and window, then the optional filter — three compact sentences with little waste. The trailing API path is the one piece that doesn't earn its space in an agent-facing description.

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 report with full schema coverage and no output schema, the essentials (period window, row granularity, department narrowing) are present. However, with no output schema and no description of the returned balance fields or row structure beyond "one row per report line," the agent still can't anticipate the payload 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?

Schema description coverage is 100%, with end_date, per_count, and department_code all documented including bounds and the source of department codes. The description restates the per_count/end_date relationship but adds no syntax or constraints 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?

It names a specific verb+resource ("profit and loss report") and specifies the row granularity (one row per report line), which is clear enough to distinguish it from list-style siblings. It doesn't explicitly contrast with merit_balance_sheet, the closest sibling, so the agent must infer the accounting difference 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 description notes an optional department filter but gives no guidance on when this tool applies versus merit_balance_sheet or the sales/purchase reports. There are no stated prerequisites, exclusions, or alternative-selection rules.

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

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

The readOnlyHint annotation already declares the tool safe and non-mutating. The description adds the returned fields and the underlying API endpoint, but does not disclose pagination behavior, authentication needs, or rate limits, so it is useful context rather than rich behavioral detail.

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

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

The description is two short, front-loaded sentences with no filler. The endpoint reference is the only arguably non-essential detail for an agent, keeping it just shy of 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 list tool with one fully documented parameter and no output schema, the description gives enough to invoke it correctly by identifying the resource and returned fields. It stops short of explaining return ordering or pagination beyond what the max_results schema implies.

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 max_results is fully documented in the schema. The description adds no additional meaning or constraints beyond what the schema already provides, 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 a specific resource (general ledger chart of accounts) and enumerates the returned fields (code, names, VAT, parent flag, active flag). It does not explicitly differentiate from sibling list tools such as merit_list_taxes or merit_list_customers, 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?

There is no when-to-use guidance, no mention of alternatives, and no prerequisites. An agent must infer that this lists all accounts with no filtering options.

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 already covering the safety profile, the description adds meaningful behavior: the 3-month Merit limit, the workaround of making several calls, and that results include the documents each payment paid. It does not describe pagination or response shape, but max_results semantics are handled by the schema.

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

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

The description is two front-loaded sentences that state the action, scope, return content, period limit, fallback strategy, and endpoints without waste. Every clause carries useful information.

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

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

For a read-only list tool with a fully described input schema and readOnlyHint annotation, the description is nearly complete: it explains the bank-account scope, direction, date-period limit, and that documents each paid are included. It stops short of describing the response structure in more detail, which is relevant because there is no 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 description coverage is 100%, so the schema already documents all five parameters, including direction and the 3-month date constraint. The description restates direction values and the date-period limit but adds no syntax or parameter meaning beyond what the schema provides.

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

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

The description uses a specific verb ('List') with a precise resource: income or expense payments booked on one bank account for a document-date period. It distinguishes this from general payment-list siblings by specifying the bank-account scope and the income/expense direction.

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

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

It clearly states the context for calling the tool and gives an important operational constraint: the period may span at most 3 months, so longer spans require several calls. It does not explicitly name alternative tools or when-not to use this one, so it falls short of a 5.

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

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

readOnlyHint=true already covers the safety profile, so the bar is lower. The description adds that this returns the bank/cash account set with its field shape and that BankId is the foreign key consumed by the payment tools — useful context beyond the annotation. It does not discuss ordering or the fact that results are bounded (that lives only in the schema).

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

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

Two compact sentences: the resource and returned fields lead, then the downstream dependency, then the endpoint. Every clause carries information and nothing is repeated from the schema or annotations.

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

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

With no output schema, the description helpfully names the returned columns and the endpoint, which is enough for an agent to call and consume the result. Minor gaps remain (ordering, whether cash accounts are mixed with bank accounts) but nothing essential is missing for a one-optional-parameter list call.

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

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

There is a single optional parameter with 100% schema description coverage, so the schema already explains max_results (default 100, max 1000, total count reported). The description adds nothing about it, which puts this at the baseline 3.

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

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

States a specific resource (the company's bank and cash accounts) and enumerates the returned fields (BankId, name, IBAN, currency, ledger account), which separates it from generic siblings like merit_list_accounts. The verb is only implied by the name/title and no sibling is named explicitly, 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?

Usage is implied rather than stated: 'BankId feeds the payment tools' tells the agent this is the lookup for payment-related IDs, which is a genuine routing hint. However, there is no explicit when-to-use versus merit_list_bank_payments, merit_list_accounts, or merit_list_payment_types, and no exclusions.

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

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

readOnlyHint already declares this is a safe read, and the description adds genuinely new behavior: the hard one-filter minimum, why it exists (no full-list reply), and the underlying POST /api/v1/getcustomers call. It does not mention result cap behavior beyond what max_results already documents.

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 filter semantics front-loaded and the hard constraint immediately after; the endpoint is a compact trailing detail. No filler or restatement 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?

With readOnlyHint covering safety, 100% schema coverage on all six parameters, and no output schema to explain, the description supplies the one thing the schema omits: the mandate that a filter be provided. Nothing needed to call this correctly is missing.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds meaning the schema does not: which keys match partially versus exactly, and that at least one of them must be supplied (the schema marks zero required parameters). That materially improves correct invocation.

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

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

States a specific verb (search) and resource (customers) plus the exact searchable keys and their match semantics (partial name, exact registry/VAT number, id, changed_since). An agent can separate this from merit_list_vendors or merit_create_customer without opening any schema.

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

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

Explicitly states the gating condition: at least one filter is required because Merit cannot return the whole customer list in one reply. That is real when-to-use guidance, though it names no alternative tool for the cases it excludes (e.g. where to go for vendor searches or full exports).

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 safe-read profile is covered. The description adds only the GET endpoint and returned fields; it does not disclose pagination details, permissions, or rate limits. With annotations carrying the safety burden, a 3 is appropriate for the modest added 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?

One short line that front-loads the resource and lists the return fields; no wasted words. The endpoint is a compact implementation hint.

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 no output schema, the description supplies the key return fields and endpoint. Pagination/total-count behavior is covered by the schema parameter, so the definition is largely complete, though it could explicitly state that it lists all departments.

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 max_results parameter is fully documented in the schema, so the description need not repeat it. Baseline 3 applies when the schema does the heavy lifting.

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

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

The description names the resource (departments) and the fields returned (code, name, active flag), plus the endpoint. However, it lacks an action verb and relies on the tool name/title to convey 'list', giving no sibling differentiation beyond the unique resource name. Adequate but minimal.

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

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

No when-to-use guidance, no alternatives, no exclusions. The agent must infer from the tool name that this is the tool for listing departments rather than any other entity.

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 adds useful context: default excludes expired dimension values, the DimId/name/value code/expiry shape of a row, and the underlying endpoint. It does not discuss result size limits or behavior beyond max_results, which is already in the schema.

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

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

Two tight sentences with the resource and row fields front-loaded; nothing is padded. The trailing 'POST /api/v2/getdimensions' is transport detail that adds little for an agent choosing a 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 helpfully enumerates the returned fields, and both optional parameters are covered by the schema. Missing only guidance on when to prefer this over sibling list tools, but nothing required for a correct invocation 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 description coverage is 100%, so both parameters are fully documented in the schema itself; baseline 3 applies. The description's restatement of all_values (including expired values) is consistent with but not additive to the schema wording.

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

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

States the resource (accounting dimensions and their values) and even enumerates the returned fields (DimId, name, value code, expiry), which cleanly separates it from siblings like merit_list_accounts or merit_list_departments. The verb is only implied via the title rather than stated in the description, but the intent is unambiguous.

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

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

No guidance on when to choose this tool versus the other list_* tools, no prerequisites, and no mention of pagination strategy despite max_results. The only conditional hint is 'all_values = true also lists expired values', which is parameter behavior rather than usage guidance.

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

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

readOnlyHint=true already tells the agent this is a safe, non-mutating read, so the description's main added value is disclosing the HTTP endpoint (POST /api/v2/getaccperiods) and confirming the returned attributes. It reveals nothing about ordering, whether inactive periods are included, or whether authentication is required, so it is useful but not rich.

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

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

Two compact clauses with no padding; the resource and returned fields are front-loaded. The trailing API endpoint is arguably internal plumbing an agent cannot use, but it is brief enough not to crowd out the signal.

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 and no output schema, the description shoulders the burden of conveying what comes back, and it does so adequately by naming start, end and active flag. It would be complete at 5 if it mentioned result ordering or whether the list is exhaustive versus paginated.

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 are no parameter semantics to explain and the baseline of 4 applies. Nothing in the description misleads about inputs.

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 (accounting periods / financial years) and previews the returned fields (start, end, active flag), which cleanly distinguishes it from sibling list tools like merit_list_payment_types or merit_list_dimensions. It lacks an explicit verb in the description body, relying on the name and title ('List financial years') to supply it, so it stops 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?

There is no when-to-use or when-not-to-use guidance whatsoever. It never says, for example, that this should be called first to resolve a financial-year identifier before invoking report tools like merit_balance_sheet, nor does it point to any alternative. The agent must infer the use case entirely.

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

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

Annotations already establish readOnlyHint=true, so the safety profile is covered; the description adds non-annotation behavior in the form of a hard server-side constraint (3-month Merit limit) and the endpoint shape (POST /api/v1/getglbatches). It does not describe pagination interaction with max_results, which is a minor omission given the schema documents it.

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 with the resource and scope front-loaded, followed by the constraint and endpoint. No filler, though the parenthetical endpoint path is arguably redundant since the tool wrapper handles transport.

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 columns and states the scope limit, which is what an agent needs to call it correctly. It omits any note on pagination behavior or empty-result handling, leaving some gaps for a 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 description coverage is 100%, so all four parameters (period_start, period_end, date_type, max_results) are already fully documented in the schema. The description only echoes the period constraint and the returned columns, adding little parameter-level meaning beyond what the schema provides. 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 batches) and enriches it with the semantic scope: journal entries plus entries generated from invoices and payments, and the fields returned (batch code, number, date, total). It is clearly distinguishable from the singular sibling merit_get_gl_batch, 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?

Gives an actionable operational rule: the period may span at most 3 months and longer spans require several calls. That is real when/how guidance for invocation. It does not, however, discuss when to prefer this list over related report siblings such as merit_get_gl_batch or the invoice/payment list tools.

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

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

readOnlyHint=true already establishes the safe read profile, and the schema already documents that location_code 'adds goods on hand quantity and cost.' The description restates that effect and adds the returned field set (price, unit, VAT, accounts), which is useful but largely duplicates structured data. No pagination, permission, or rate-limit context is added.

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 with the scope front-loaded and no filler; the filter list and the location_code behavior follow logically. The trailing 'POST /api/v1/getitems' is minor metadata but costs almost nothing.

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 six optional params, no output schema, and full schema coverage, the description supplies the missing return-shape context (price, unit, VAT, accounts) and the conditional stock/cost behavior. An agent has enough to call it correctly, though guidance on result pagination beyond max_results 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 description coverage is 100%, so the schema already defines every parameter, including the partial-match semantics of code/description and the type enum values. The description's filter list adds no syntax or format detail 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?

States a specific verb (List) and resource (items, services and stock articles) plus the returned attributes (price, unit, VAT, accounts), which is well beyond a tautology. It does not differentiate itself from the many other merit_list_* siblings, 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?

It enumerates the available filters ('code or description (partial), type, id') and notes what location_code does, implying how to narrow results. However, it never says when this tool is the right choice versus the other list/report siblings, and there are no explicit exclusions.

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

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

Annotations only declare readOnlyHint=true; the description adds a real constraint beyond that — the hard 3-month maximum span and the batch-call workaround — plus what content is returned (the documents the payments settled). No auth, rate limit, or truncation behavior is described, but the safety profile is already covered by annotations.

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

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

Three tightly packed sentences: purpose and returned content first, then the binding constraint, then the underlying endpoint. No filler, and the most decision-relevant fact (3-month limit) is front-loaded.

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

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

With no output schema, the description carries the burden of stating what comes back ('the documents they paid'), which it does, and the total-count/limit behavior is covered in the schema. It is nearly complete; only pagination/truncation behavior for very large result sets goes unmentioned.

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

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

Schema description coverage is 100%, so all six parameters, including the date_type enumeration, max_results cap, and the cross-reference to merit_list_payment_types, are already documented in the schema. The description adds nothing about parameter formats or interactions, 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 (List payments) and defines scope precisely with the parenthetical 'customer and vendor receipts and payouts... with the documents they paid', which implicitly separates it from narrower siblings like merit_customer_payments_report and merit_list_bank_payments. It is clear, but it never explicitly names or contrasts with an alternative tool.

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

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

Gives concrete operational context: the period may span at most 3 months (Merit limit) and longer spans require several calls. It lacks explicit when-to-use/when-not guidance relative to the payment-report siblings, so an agent must infer which tool fits a customer-only or bank-only question.

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 adds one genuinely useful non-obvious trait: it is a POST endpoint (POST /api/v2/getpaymenttypes) despite being a read-only list, which helps an agent calling raw HTTP. It says nothing about result shape or ordering, so a 3 is appropriate.

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

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

Two short sentences with the resource scope front-loaded before the endpoint detail. Every element is brief, though the raw endpoint path is arguably noise for an agent that already has the tool wired up.

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

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

For a simple two-param, zero-required read-only list tool with no output schema and no nested objects, the description covers what the resource is and the scope enum values it maps to. Nothing critical is missing, though it never mentions how results are returned (only the schema hints at row counts).

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 params are fully documented in the schema, including the 1/2/3 mapping for type and the default/max for max_results. The description restates the purchases/expense reports/sales scope but adds no syntax or format detail beyond the schema, so baseline 3 holds.

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+resource ('List payment types') and elaborates the resource with concrete examples (cash, banks, reporting entities, ledger accounts), which separates it from sibling merit_list_payments. It does not explicitly state how it differs from near-neighbours like merit_list_banks or merit_list_payments, so a 4 rather than 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 phrase 'usable for purchases, expense reports or sales' implies this is a lookup used to resolve valid payment sources when creating those documents, which is reasonable implied context. There is no explicit when-to-use, when-not-to-use, or named alternative among the many list_* siblings.

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

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

readOnlyHint=true already covers the safety profile, and the description adds real behavioral context beyond that: the hard 3-month period ceiling, the chunking strategy, and the underlying endpoint POST /api/v2/getpurchorders. It does not mention pagination interplay with max_results or rate limits, but the key constraint is disclosed.

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

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

Two sentences, zero waste, and the constraint and chunking advice are front-loaded after the purpose. Nothing extraneous.

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

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

For a read-only list tool with no output schema, the description usefully names the returned fields and notes that the reply reports the total row count. The main gap is that pagination behavior across max_results is not spelled out, but the essentials for correct invocation 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 all five parameters are already documented in the schema, and the description adds no syntax beyond the 3-month limit on period_start/period_end. The field list it provides describes the response, not the inputs. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('List purchase invoices (vendor bills)') and enumerates the returned fields (bill number, vendor, dates, totals, paid flag). This clearly separates it from merit_get_purchase_invoice (single invoice) and merit_list_sales_invoices (the sales-side 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?

Gives concrete operational guidance: the period may span at most 3 months and longer spans require several calls. It does not explicitly name alternatives (e.g. merit_get_purchase_invoice for a single bill, or merit_purchase_report for aggregates), so routing to siblings is left implicit.

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; the description adds real behavioral context beyond that: the Merit 3-month hard limit on the period, that results are header-level (no line detail), and the underlying endpoint. It omits paging/auth behavior, but the material constraint is disclosed.

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, zero filler, front-loading what is returned, then the period constraint, then the sibling for line detail. Nothing is padded or 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?

With no output schema, the description compensates by enumerating the returned header fields, and it covers the key constraint and the sibling hand-off. Minor gaps remain around result paging/ordering, but an agent has 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 date_type, max_results, unpaid_only and both period bounds are already documented in the schema, including the same 3-month cap. The description restates the period limit but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource plus the exact header fields returned (number, customer, dates, totals, paid flag), and explicitly distinguishes itself from merit_get_sales_invoice, which returns lines. An agent can select it against siblings without opening a schema.

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

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

Gives a clear condition and remedy for long spans ('at most 3 months... for longer spans make several calls') and routes line-level needs to merit_get_sales_invoice. It does not mention merit_search_sales_invoices, which is a plausible alternative for filtered lookups, so the guidance stops short of full alternative coverage.

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 tells the agent this is a safe read, so the bar is lower; the description adds genuine value by disclosing the shape of the response (field list) for a tool that has no output schema. It does not mention pagination or total-count behavior beyond what the parameter schema already states.

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 plus an endpoint path — the resource and returned fields are front-loaded with no padding. The raw 'GET /api/v2/taxes' path is mildly redundant for an agent that only invokes the tool, but it costs almost nothing.

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 one well-documented optional parameter, the description covers the resource, the returned fields (compensating for the absent output schema), and the key relational fact of what TaxId means. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100% and the single max_results parameter is fully documented in the schema, including the default of 100, the max of 1000, and the total-count reply semantics. The description adds nothing about it, 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 resource (all VAT rates of the company) and enumerates the exact fields returned (TaxId, code, name, percent, active flag), which no other sibling list tool covers. An agent can tell this apart from merit_list_items, merit_list_accounts, etc. without opening any schema.

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

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

Usage is only implied — the description notes 'The TaxId is what invoice rows refer to,' which hints at when an agent needs this data (resolving invoice-line tax references), but it never says when to call this versus other list tools or whether any prerequisites exist. Adequate context, no explicit when/when-not 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?

With readOnlyHint=true already declaring a safe read, the description adds genuine behavioral context: the mandatory-filter rule, the reason (no bulk listing), and the underlying POST /api/v1/getvendors endpoint. It stops short of describing ordering, pagination, or error behavior, but the annotation carries the safety profile.

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, both earning their place: the first defines filters and matching semantics, the second carries the guardrail and endpoint. The most important constraint is front-loaded and nothing is repeated from 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 read-only filtered search with six well-documented optional parameters, the description plus schema cover what an agent needs; the max_results total-count behavior is documented in the schema. No output schema exists, but the tool's return shape is simple enough that omitting it is acceptable.

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 per-parameter descriptions exist, but the schema declares zero required parameters while the description supplies the crucial anyOf-style constraint that at least one filter must be supplied. It also adds the matching-mode distinction (partial vs exact) that maps parameters to lookup intent.

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 (Search) and resource (vendors/suppliers) and enumerates the supported lookup keys with matching semantics (name partial, reg/VAT exact, id, changed_since). This clearly distinguishes it from sibling list tools like merit_list_customers and merit_list_items.

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

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

It states a hard usage precondition — at least one filter is required because the whole vendor list cannot be returned — which tells the agent when the tool will not work. It does not, however, explicitly name a sibling alternative or cover the unfiltered-enumeration case beyond that.

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 this is a safe, non-mutating read, so the description does not need to restate safety. It adds the grouping dimension and the REST endpoint, but says nothing about auth requirements, rate limits, or what the totals actually contain (net, tax-inclusive, currency). Modest added value on top of 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?

Two sentences, front-loaded with what the report returns, followed by the endpoint. Zero filler. The endpoint sentence is the weakest element since it adds little for an agent choosing a tool, but it costs almost nothing.

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 is the only place the return shape could be described, yet it never states the fields or structure of the returned totals or how totals are aggregated. Schema coverage is complete for inputs, so the gap is confined to output expectations.

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%: start_date/end_date formats, max_results default and cap, and report_type values 1-4 are all documented in the schema. The description's grouping list merely restates report_type, adding no new meaning. 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: 'Purchase totals for a period, grouped by invoice, vendor, item or fixed asset.' That is a clear verb-free but identifiable report operation, and 'purchase' inherently separates it from merit_sales_report and merit_customer_debts_report. It stops short of naming any sibling explicitly, so it is clear but not differentiated in-text.

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

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

There is no when-to-use guidance, no prerequisites, and no routing to alternatives such as merit_list_purchase_invoices or merit_get_purchase_invoice for a single invoice. The only usage signal is the implied 'report' framing, which the agent must infer.

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 tells the agent this is a safe read, and the description adds only the endpoint path (POST /api/v2/getsalesrep), which is trivia rather than behavior. It discloses nothing about aggregation semantics, pagination beyond the schema's own max_results note, response shape, or permissions.

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 purpose front-loaded and no filler. The trailing "POST /api/v2/getsalesrep" is essentially noise for an agent that only needs the tool name.

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

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

For a simple parameterized report with fully documented parameters and readOnly annotations, the definition covers enough to invoke it correctly. The absence of any return-shape note is a minor gap since no output schema exists, but the grouping list conveys the aggregation grain.

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 start_date, end_date, max_results and report_type are all self-documented, making 3 the baseline. The description's grouping list loosely mirrors report_type but omits type 5 ("countries (general)"), so it adds no meaning 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?

States a specific verb and resource ("Sales totals for a period") plus the available grouping dimensions, so an agent can tell it is a sales aggregation report. It does not explicitly contrast itself with near siblings like merit_income_statement or merit_purchase_report, 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 description says what the report is but never when to choose it over the many other report tools (income statement, customer debts, purchase report) or what conditions/prerequisites apply. Usage is only inferable from the name and grouping list.

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

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

The readOnlyHint annotation already establishes that this is a safe read operation, so the description only needs to add context beyond that. It adds the "at least one" filter requirement and exposes the underlying POST endpoint, but says nothing about matching behavior (exact vs partial), result ordering, or pagination semantics.

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

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

A single compact sentence carries the purpose, keys, and constraint; the trailing endpoint path is low-value but harmless. Nothing is buried or padded.

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

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

For a four-parameter read-only search with full schema coverage and no output schema, the description covers the essentials: what it finds, by which keys, and the minimum input requirement. The main omission is routing guidance relative to the list/get siblings, which is a modest gap rather than a blocker.

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 parameter details are already documented, but the description adds a genuine cross-parameter constraint the schema lacks: at least one of invoice_no, customer_id, or customer_name must be supplied (the schema declares zero required fields). That elevates it above the baseline 3.

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

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

The description names a specific verb+resource ("Find sales invoices") and the three search keys, so an agent can tell this is a lookup-by-identifier tool. It does not explicitly distinguish itself from siblings like merit_list_sales_invoices or merit_get_sales_invoice, leaving that inference to the reader.

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?

"give at least one" provides a useful invocation constraint, but there is no explicit when-to-use guidance, no mention of alternatives (e.g., use merit_list_sales_invoices to enumerate all invoices), and no statement of when this tool is inappropriate.

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