Bokio MCP by usefulapi

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

Adds real behavioural context beyond the annotations: non-idempotency (two calls = two customers) and the auto-numbering rule when customerNumber is omitted. The annotations already flag destructiveHint=true, so what's left unsaid is a lesser gap — e.g. no mention of permissions or validation failures (duplicate orgNumber).

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, with the primary action first and the risk warning front-loaded before the dedup advice. Every sentence earns its place.

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

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

No output schema exists, yet the description never indicates what comes back (e.g. the created customer ID), which would be useful for chaining into bokio_create_invoice_draft. Otherwise it covers purpose, side effects and a safe pre-check, which is adequate for a create 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 only 50% across 10 parameters (one nested object), so the description should compensate more. It does add genuine semantics for customerNumber (omitted → Bokio assigns next number), but says nothing about required name/type or the enum choices.

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

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

States a specific verb and resource ("Create a customer") plus the tenant scope ("the company's Bokio"), which cleanly separates it from bokio_list_customers and bokio_get_customer. An agent can route to it without opening the schema.

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

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

Explicitly names the alternative ("check bokio_list_customers first") and the condition that should trigger it, given the non-idempotent behaviour. That is exactly the when-to-use/when-to-use-something-else guidance an agent needs.

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?

Adds real value beyond the annotations: it discloses that nothing is bookkept or sent until publishing, and that the call is non-idempotent so a retry creates duplicates. This meaningfully clarifies why destructiveHint=true applies to an operation that sounds harmless, though it doesn't mention auth or side effects on later bookkeeping.

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 a distinct and useful fact (what it makes, when it has effect, retry behavior), with the DRAFT status front-loaded.

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

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

There is no output schema, so the description is the only place to say what comes back — notably a draft invoice id needed for bokio_publish_invoice — and it omits that. Otherwise it covers the essential behavior for a creation 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 description says nothing about any of the 8 parameters, and with 63% schema coverage plus a nested lineItems structure whose rules (itemId vs. taxRate/unitPrice/productType, bookkeepingAccountNumber incompatibility) are the main source of invocation error, the description does not compensate.

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

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

States a specific verb and resource ('Create a DRAFT sales invoice') with the draft qualifier front and center, which immediately separates it from bokio_publish_invoice and bokio_record_invoice in the sibling list.

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

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

Names the follow-up tool (bokio_publish_invoice) and makes the two-stage draft→publish workflow explicit, which is the key routing decision. It does not explicitly contrast with bokio_record_invoice, so the choice between the two creation paths 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?

The annotations already mark the tool as destructive and not read-only, and the description adds substantial context: the action is irreversible, non-idempotent, creates a counter-entry if reversed, and requires prior user confirmation. This goes well beyond what the annotations alone provide.

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

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

The irreversibility warning is front-loaded, followed by accounting constraints and idempotency behavior. Every sentence carries operational value with no filler.

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

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

For a destructive mutation tool with no output schema, the description covers the essential safety profile: irreversibility, non-idempotency, reversal path, and required user confirmation. It also states the core accounting validation rule.

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

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

Schema description coverage is only 33%, and the description does not explain the title, date, or items structure in detail. It does add the critical debit-equals-credit invariant and confirmation requirement, but it only partially compensates for the undocumented parameters.

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

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

The description states a specific verb and resource: post a journal entry (verification) to the ledger. It clearly distinguishes this from bokio_reverse_journal_entry, which posts a counter-entry rather than creating a new journal 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?

It explicitly says to call only when the user has confirmed the exact lines, and it names bokio_reverse_journal_entry as the alternative for undoing an entry. This gives clear when-to-use and when-not-to-use 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?

The readOnlyHint annotation already establishes this as a safe read operation. The description adds only that it returns one account; it does not disclose not-found behavior, authentication needs, rate limits, or any return-format context beyond the annotation.

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

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

The description is a single front-loaded sentence with no wasted clauses. It is appropriately sized for a simple lookup, though the sentence-fragment style leaves it slightly under-structured.

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

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

For a one-parameter read tool with full schema coverage and a readOnly annotation, the description is sufficient to invoke the tool. However, no output schema exists and the description does not explain returned account fields or behavior when the account number is not found.

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

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

Schema description coverage is 100%, and the schema already documents the account number parameter with the same 1930 example. The description repeats that example without adding format, range, or validation details beyond the schema.

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

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

The description states retrieval of one chart-of-accounts account by number, with example 1930. It implicitly distinguishes a single-account lookup from the sibling list_chart_of_accounts by saying 'One account', though it does not name that alternative.

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 explicit when-to-use, when-not-to-use, or alternative is provided. The phrase 'by its number' implies the tool is appropriate when the account number is known, but the description never directs the agent to list_chart_of_accounts when the number is unknown.

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 is a safe read, so the description doesn't need to argue safety. Its real contribution is enumerating the returned fields, which matters because there is no output schema; however, it says nothing about behaviour when no company is connected or about error/empty responses.

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

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

A single short sentence, front-loaded with the resource and then the concrete fields. Nothing is padded and nothing important is buried.

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

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

With no output schema present, the description carries the burden of describing return values, and it does so by listing name, organisation number, company type, address and contact details. Only the empty/not-connected case is unaddressed, which is a minor gap for a zero-param getter.

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

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

The tool takes zero parameters and the schema is an empty object, so there is no parameter semantics to explain. Baseline 4 applies; the description correctly avoids inventing 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?

The description names a specific resource, the connected Bokio company, and enumerates the returned fields, so the agent knows exactly what data comes back. It doesn't explicitly contrast with siblings, but the singleton-company scope is self-evidently distinct from the customer, invoice and journal tools.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no alternative is named. For a zero-parameter singleton getter the intended usage (retrieve company identity and address data, e.g. for invoicing or reporting) is strongly implied by the field list 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?

The readOnlyHint annotation already declares this is a safe read, so the description needn't restate that. It adds one useful piece of context — the response includes line items — but with no output schema, it does not describe what happens when the id doesn't exist, what fields the credit note carries, or whether related records are expanded.

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

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

A single short sentence with no filler, front-loading the cardinality ('one') and the lookup key ('by id'). The only weakness is that it is a fragment terse enough to border on under-specification rather than elegance.

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

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

For a one-parameter read tool with annotation-supplied safety and a fully documented schema, the definition covers the essentials plus the notable detail that line items are returned. Only edge-case behavior (not-found id) is absent, which is minor at this complexity.

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

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

Schema coverage is 100% and the single parameter is fully documented as a GUID with a pattern, so the schema does the work. The description only echoes 'by id' and adds no meaning beyond the schema, which is the expected baseline for a one-parameter tool.

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

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

States a specific resource and scope: a single credit note fetched by id, plus the fact that line items are included. This implicitly separates it from bokio_list_credit_notes, though it never names that sibling. Clear enough for an agent to know it retrieves one record rather than a collection.

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?

'One credit note by id' implies single-record lookup, which indirectly signals when to use it versus the list tool, but there is no explicit when-to-use guidance, no prerequisites, and no mention of how to obtain the id (e.g., from list_credit_notes). Usage is inferred rather than stated.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds nothing beyond that—no note on what happens when the id is unknown (error vs empty), no mention of return 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?

It is a single short phrase with no waste, but it is under-specified rather than genuinely concise—it reads like a title fragment rather than a sentence that earns its place.

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

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

For a one-parameter read tool with full schema coverage and a readOnly annotation, most needs are met. The lack of any return-value description leaves a small gap since 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% and the sole parameter is documented as a GUID with a regex pattern. The description adds no further meaning, so the baseline 3 applies.

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

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

The fragment 'One customer by id' implies retrieving a single customer by identifier, which is understandable. However it is telegraphic, does not use an explicit verb, and does not distinguish itself from bokio_list_customers beyond the implicit singular/plural difference.

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

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

There is no statement of when to use this versus bokio_list_customers or bokio_create_customer. The singular 'One customer' weakly implies single-record lookup, but no alternative or condition is named.

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 by structured data. The description adds nothing beyond that: no note on what happens with an unknown or malformed id, no indication of error behavior, and no hint about the returned record's shape. With annotations doing the heavy lifting, the description still contributes essentially no extra behavioral context.

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

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

A single front-loaded sentence with zero waste, but it is terse to the point of under-specification rather than efficiently informative. It reads as a fragment rather than a structured statement of action and scope.

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

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

For a one-parameter read tool with full schema coverage and annotations covering safety, the definition is minimally sufficient to invoke correctly. But with no output schema present, the description could have described the returned fiscal-year record or error cases, and it does not.

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

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

Schema description coverage is 100% — the single parameter is fully documented as a GUID with a regex pattern — so the schema already carries parameter semantics. The description's "by id" merely echoes this, adding no format, sourcing, or lookup guidance beyond the schema.

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

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

"One fiscal year by id" states the resource (a single fiscal year) and the lookup key, which implicitly distinguishes it from bokio_list_fiscal_years. However, it carries no verb of its own and leans on the tool name/title to convey the retrieval action, making it close to a restatement rather than a specific statement of purpose.

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

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

There is no guidance on when to use this versus bokio_list_fiscal_years or any other sibling, and no note on prerequisites (e.g., needing a valid company context or a known GUID). The only usable signal is the word "id," which an agent must infer means "use this when you already have the identifier."

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 one genuinely useful behavioral detail — the response includes line items — but says nothing about what happens when the id is unknown or whether totals/payments/status are included.

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?

Eight words, front-loaded with the resource and the retrieval key, and the one payload note ('with line items') appended last. Nothing is wasted.

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

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

There is no output schema, so the description is the only signal about return contents, and it discloses only that line items are present. For a simple single-param read with annotations covering safety this is workable, but the agent still cannot anticipate the full invoice shape or not-found behavior.

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 invoiceId is documented as a GUID with a pattern, so the schema does the heavy lifting. The description's 'by id' merely restates that; 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), resource (sales invoice), and cardinality ('one ... by id'), which implicitly separates it from bokio_list_invoices. It does not name a sibling explicitly, but the retrieval-by-identifier purpose 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?

'by id' implies you must already have an invoice GUID, which is a usable precondition. However, it never says when to prefer this over bokio_list_invoices or bokio_get_credit_note, and offers no exclusions or fallback 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?

The readOnlyHint annotation already establishes this as a safe read operation. The description adds that the response includes journal entry lines, which is useful return-content context, but it does not address not-found behavior, error conditions, or deeper retrieval 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?

The description is very short and front-loaded, with no wasted words. It is perhaps overly terse, and the parenthetical '(verification)' is slightly ambiguous, but it remains efficient.

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

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

For a simple one-parameter getter with annotations covering read-only safety, the description provides the minimum viable context by naming the returned entity and its lines. However, with no output schema, it does not describe the response shape or failure behavior, leaving some gaps.

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

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

Schema description coverage is 100% for the lone journalEntryId parameter, and its GUID pattern is documented in the schema. The description adds no additional parameter meaning, so the baseline of 3 is appropriate.

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

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

The description identifies a single journal entry and notes that its lines are included, clearly distinguishing it from the plural list_journal_entries sibling. The verb is implied by the tool name/title rather than stated in the description itself, but the resource and scope are unambiguous.

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

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

There is no guidance on when to use this tool versus siblings such as bokio_list_journal_entries, bokio_create_journal_entry, or bokio_reverse_journal_entry. It also omits any prerequisites or conditions for retrieval.

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 this as a safe read operation. The description adds useful behavior beyond annotations: it says the result is the complete chart, lists included fields, and states that the result is not paginated. It does not describe ordering or permissions, but those are modest gaps for a simple read-only list.

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

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

The description is a single front-loaded sentence with no wasted words. It efficiently covers resource scope, returned fields, and the non-paginated behavior.

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

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

For a one-optional-parameter read-only list tool with no output schema, the description covers the resource scope, included fields, and pagination behavior. It does not describe ordering or the exact response envelope, but it is sufficient for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, and the optional query parameter already has detailed filter syntax in the schema. The description does not mention the query filter or add meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description names the resource precisely as the company's complete chart of accounts and enumerates returned fields such as account number, name, and base-plan/custom. It does not explicitly contrast with the sibling get_account tool, but the word 'complete' implies all accounts rather than one.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no alternative sibling is named. The phrases 'complete chart of accounts' and 'Not paginated' imply this is the tool for retrieving the full account list, but usage remains inferred.

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

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

The annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds only that both draft and published credit notes are included, which is a small useful scope detail. It does not discuss pagination, filtering behavior, result ordering, or any other operational 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 short, but its brevity reflects under-specification rather than efficient communication. It is a sentence fragment with no front-loaded statement of what the tool actually does.

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 listing tool with three optional parameters and no output schema, the description should at least clarify that it returns a paginated collection and how it relates to bokio_get_credit_note. It provides almost none of that context, leaving the schema and annotations to carry nearly all the burden.

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 input schema already documents page, query, and pageSize thoroughly, including filter syntax and examples. The description adds nothing about parameters, but the baseline is 3 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 is essentially a restatement of the tool name and title: 'Credit notes (draft or published).' It does not state a verb such as list, though the tool name supplies that context. It adds only a minor scope note about draft/published status and does not distinguish this tool from bokio_get_credit_note.

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

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

There is no guidance on when to use this tool versus alternatives. It does not mention bokio_get_credit_note or explain that this is the collection-listing counterpart. An agent gets no help deciding between listing credit notes and fetching a single credit note.

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 externally. The description adds the useful ordering trait ('highest customer number first'), but says nothing about pagination behavior, total counts, or empty-result handling.

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

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

A single short sentence, front-loaded with the resource and a distinguishing detail. It is efficient, though it reads as a fragment rather than a complete statement of behavior.

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

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

For a three-optional-parameter list tool with readOnly annotations and a fully documented schema, the definition is minimally adequate. It leaves out result shape and pagination semantics, which matter since no output schema exists.

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%, including the Bokio query filter syntax and page/pageSize bounds, so the schema carries the parameter burden. The description adds no parameter meaning beyond the schema baseline.

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

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

The description names the resource ('Customers of the company') and implies listing via the title and tool name, and adds a sort order detail. It does not explicitly say 'list/retrieve all' nor distinguish itself from the sibling bokio_get_customer for a single record.

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

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

There is no guidance on when to use this versus bokio_get_customer or bokio_list_suppliers, and no mention of how pagination or filtering should be applied to narrow results. Usage is only implied by the tool name.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description adds value by disclosing the returned field set (with no output schema, that is useful), but says nothing about pagination behavior, default page size, or how filtering affects results.

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

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

The single noun phrase is compact with no wasted words, but it is under-specified rather than genuinely concise — it omits a verb and any operational context. Shortness here comes at the cost of guidance, not efficiency.

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 field enumeration is a helpful stand-in for return values, and zero required parameters keeps the tool simple. However, for a list tool with filtering and pagination, the absence of any mention of the query filter or page controls leaves the description only minimally adequate.

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

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

Schema description coverage is 100%, so all three parameters are documented in the schema itself; baseline 3 applies. The description adds no extra semantics beyond the field list, and notably omits mentioning the powerful 'query' filter (filterable fields: startDate, endDate, accountingMethod, status) that would help an agent use the tool effectively.

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

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

The description names the resource and enumerates its fields (id, start/end date, accounting method, open/closed status), which combined with the title 'List fiscal years' makes the operation clear. It does not distinguish itself from the sibling bokio_get_fiscal_year (singular lookup), leaving a small ambiguity for an agent choosing between list and get.

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

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

There is no statement of when to use this list tool versus bokio_get_fiscal_year, nor any mention that pagination and the 'query' filter are available. An agent gets the resource but no routing or prerequisite guidance.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description adds nothing further. It does not mention pagination behavior, ordering of the returned payments, or whether an empty list vs. an error results from an invoice with no payments. For a list tool this is thin, but not contradictory.

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

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

It is certainly short, but it is a sentence fragment rather than a front-loaded structured statement, so the minimal length reflects under-specification more than disciplined editing. Nothing is redundant, yet nothing is organized for quick scanning either.

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?

This is a simple read tool with full schema coverage and a readOnly annotation, so the bar is modest, but the description still leaves the agent unsure whether payments also appear inside bokio_get_invoice and how results are ordered or paged. A single clause distinguishing it from that sibling would have closed the gap.

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

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

Schema coverage is 100% — invoiceId is documented as a GUID pattern and page/pageSize have ranges and defaults — so the schema carries the parameter burden. The description adds only the implicit constraint that invoiceId must refer to a single sales invoice, which is marginal but slightly useful.

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 fragment identifies the resource — payments tied to a single sales invoice — which is more specific than the name alone. But it is a noun phrase with no verb, so the fact that this is a paginated list operation comes only from the tool name, not the description. An agent can guess what it returns but not how it behaves.

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

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

There is no statement of when to use this versus alternatives such as bokio_get_invoice (which may or may not embed payments) or bokio_list_invoices. Nothing excludes it from related scenarios, and no prerequisites (e.g., the invoice needing to exist, or being a sales invoice rather than a supplier invoice) are mentioned.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description's residual job is to disclose return shape; it does contribute something by noting line items and totals are included (useful since no output schema exists). It says nothing about pagination behavior, filtering capability, or whether results are scoped to a company, which is where the real ambiguity lies.

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 fragment with no filler, but being a noun phrase rather than a verb-led sentence means the action is not front-loaded — the agent has to borrow the verb from 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?

For a zero-required-parameter list tool with no output schema, the description covers scope and payload but omits anything about result ordering, total counts, or that the query parameter is the intended way to narrow by status/date/customer. Adequate but with recognizable gaps.

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

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

Schema description coverage is 100%, so page, pageSize, projectId, and the fairly intricate 'query' filter DSL are fully documented in the schema; the description only obliquely references the status filter through its status enumeration. Baseline 3 is appropriate since the schema does all the work.

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 fragment names the resource ('Sales invoices') and enumerates the statuses it covers, plus what payload it includes, but it never states a verb (the 'list' action comes only from the name/title) and gives no explicit contrast with close siblings such as bokio_list_supplier_invoices, bokio_list_credit_notes, or bokio_list_invoice_payments.

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

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

There is no statement of when to use this tool versus alternatives — no mention of using bokio_get_invoice for a single record, or list_supplier_invoices/list_credit_notes for other invoice families. The reader must infer the selection rule from the sibling names alone.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered and the description only needs to add context. It adds that these are 'reusable' items composed of the listed attributes, but says nothing about result volume, default page size of 25, or ordering beyond what the schema 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?

The description is a single short clause with no filler, but its brevity comes at the cost of clarity: without a verb it reads as a restatement of the schema's field list rather than a front-loaded statement of what the call returns.

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 zero required parameters and a fully described schema, the minimum an agent needs is present, and the field list hints at the returned shape. However, with no output schema and no note that the response is paginated or a list, the description is only just sufficient.

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 page, pageSize, and the filter query syntax fully documented in the schema, including the && filter grammar and example. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

The description is a noun fragment listing item fields (description, product type, unit price, tax rate, bookkeeping account) rather than a verb+resource statement; only the title and tool name convey that this lists reusable invoice items. The resource ('items') is distinguishable from siblings like bokio_list_customers or bokio_list_invoices, but the agent must infer the retrieval 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?

There is no statement of when to use this tool, no prerequisites, and no mention of alternatives (e.g., using items when creating an invoice draft vs. listing existing ones). The description offers no routing guidance at all.

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. The description adds useful content context (each entry carries its debit/credit lines), but says nothing about default result size, pagination behavior, or ordering, which matter for a list 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?

Two short, front-loaded sentences with no filler; the resource definition comes first and the filtering hint second. Slightly thin rather than padded, but every phrase earns its place.

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

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

With no output schema, the description does cover the return shape at a high level (entries plus debit/credit lines). It omits pagination/ordering behavior and the unfiltered default case, leaving the agent to infer how large a result set to expect.

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

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

Schema coverage is 100%, so page, pageSize, and the query syntax are fully documented in the schema. The description's 'filter by date or number' only partially reflects the query parameter's actual filterable fields (which also include title and reversal links), 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 the resource precisely (bookkeeping journal entries, with the domain synonym 'verifications') and clarifies that debit/credit lines are included. Combined with the name/title this clearly distinguishes it from the singular bokio_get_journal_entry, though the description itself never uses a list verb or explicitly contrasts with that sibling.

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

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

The phrase 'Filter by date or number' hints at the intended query patterns, but there is no explicit when-to-use guidance, no mention of when to prefer bokio_get_journal_entry for a single entry, and no note on what happens when no filter is supplied.

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

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

The readOnlyHint annotation already establishes this as a safe read operation. The description adds useful context that results include remaining amounts and their journal entry, but it does not disclose pagination behavior, filtering behavior, or other operational constraints.

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

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

The description is a single concise phrase with no wasted words. It is front-loaded with the core resource and key returned fields, though its fragment structure is terse even for a short definition.

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

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

For a read-only list tool with complete parameter schema coverage and no output schema, the description adequately signals the key return content. However, it does not cover usage context, alternatives, or pagination/filter behavior, leaving noticeable gaps.

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

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

Schema description coverage is 100%, so the schema already fully documents page, query, pageSize, and projectId. The description adds no parameter-specific meaning beyond what the schema provides, making the baseline 3 appropriate.

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

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

The description names the specific resource (supplier/purchase invoices) and the notable returned data (remaining amounts and journal entry). It distinguishes this from the sibling bokio_list_invoices by specifying supplier/purchase invoices, although it does not use an explicit verb like 'list'.

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

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

There is no guidance on when to use this tool versus alternatives such as bokio_list_invoices or bokio_list_suppliers. The description gives no context or exclusions for filtering or pagination.

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 this is a safe read, so the description's only contribution is the phrase 'with payment details,' which vaguely suggests the returned records carry payment information. It says nothing about pagination behavior, default ordering, empty results, or how filtering narrows the set, all of which would be useful context beyond the annotation.

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

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

It is a single short fragment with no wasted words, but it is under-specified rather than concise: the sentence is not front-loaded with a verb and conveys almost no actionable information. Brevity here comes at the cost of usefulness.

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

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

With no output schema, the description should clarify what a supplier record contains and how results are paged, but 'with payment details' is the only hint and is ambiguous. For a paginated list tool with three parameters, an agent still lacks enough information to know what comes back or how to page through results.

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

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

Schema description coverage is 100%, with page, query, and pageSize each fully documented in the schema including the filter syntax and examples. The description adds nothing about parameters, so the baseline of 3 applies since the schema does all the work.

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 text is a noun phrase, 'Suppliers of the company with payment details,' that essentially restates the name and title 'List suppliers' rather than stating an action. The only added information is that supplier records include payment details, which hints at return content but does not distinguish this tool from siblings like bokio_list_supplier_invoices or bokio_get_customer.

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

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

There is no guidance on when to use this list endpoint versus bokio_list_supplier_invoices, bokio_get_customer, or bokio_list_customers. The read-only retrieval nature is only implied by the word 'suppliers' and the readOnlyHint annotation, not by any explicit when-to-use statement.

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

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

Annotations already flag destructiveHint=true / readOnlyHint=false, and the description goes well beyond them: it explains irreversibility, that the record becomes immutable and receives a number, and critically that no bookkeeping entry is created and no e-mail is sent to the customer. Those side-effect disclosures are exactly what an agent cannot infer from the annotations.

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

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

Three short sentences, with the irreversible warning front-loaded in capitals before any detail. Every clause carries distinct information: risk, outcome, scope exclusions, and the confirmation precondition.

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

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

For a one-parameter irreversible mutation with no output schema, the description covers everything the agent needs: the state change, the numbering side effect, what does NOT happen downstream, and the human confirmation requirement.

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 parameter at 100% schema coverage, and the schema already defines it as a GUID with a pattern. The description adds no format or sourcing detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('publish a draft invoice') and immediately clarifies the resulting state: official, immutable, assigned an invoice number. It explicitly distinguishes itself from the sibling bokio_record_invoice, so an agent can route correctly without comparing schemas.

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

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

Gives an explicit gate ('Only call when the user has confirmed this exact invoice') and names the alternative operation that performs the adjacent step ('use bokio_record_invoice for that'). Both when-to-use and the nearest alternative are spelled out.

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

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

The annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds useful context beyond them: the action is irreversible, it posts to the ledger, and it derives accounts from the invoice line items. It does not cover duplicate-call behavior or failure modes, so it is strong but not exhaustive.

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

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

The description is a single tight sentence with the irreversible warning front-loaded. Every phrase contributes to purpose, prerequisite, or confirmation requirements.

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

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

For a one-parameter mutation with no output schema, the definition supplies the critical missing context: irreversibility, ledger posting behavior, prerequisite publish step, and user confirmation gate. An agent has enough information to invoke it correctly.

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

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

Schema description coverage is 100%, and the single invoiceId parameter is already documented in the schema as a GUID for the published invoice. The description does not add syntax or meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: record/bookkeep a published invoice, then explains the concrete effect of posting it to the ledger using line-item accounts. It clearly distinguishes this terminal bookkeeping action from creation, publishing, and reversal siblings.

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

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

It gives an explicit sequencing rule, 'Call after bokio_publish_invoice,' and an explicit confirmation gate, 'only when the user has confirmed.' This tells the agent both when to use the tool and when not to use it.

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

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

Annotations already declare destructiveHint=true, yet the description still adds real context: the mechanism (counter-entry, not deletion), that the original remains in the ledger, and that only API-created entries qualify. These are consequences an agent cannot infer from the safety hints 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?

Three short clauses with the danger marker front-loaded and zero filler. Every sentence carries a distinct constraint: irreversibility, mechanism, eligibility, confirmation.

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

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

With no output schema, the description does not say what comes back (e.g., the new counter-entry's id), and it omits any date/period considerations. Otherwise it covers everything needed to invoke a single-parameter destructive tool safely.

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

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

Schema coverage is 100% and the single parameter carries a description plus GUID pattern, so the schema fully documents it. The description adds nothing about journalEntryId, which is the expected baseline when the schema does the work.

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 mechanism ('post a counter-entry that cancels a journal entry'), not just a verb+resource, which distinguishes it from bokio_create_journal_entry and bokio_get_journal_entry. The leading 'IRREVERSIBLE' tag further disambiguates it from the read/list siblings.

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

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

Explicit when-to-call ('Only call when the user has confirmed') and an eligibility precondition ('Only entries created through the API can be reversed'). It does not name an alternative path for non-API entries or suggest verifying state first, so it stops short of the top band.

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