CashCtrl MCP by usefulapi

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

The destructiveHint annotation already flags this as a write, but the description adds genuinely non-obvious behavioral context: 'WRITE: changes the accounting records' plus the idempotency warning 'Makes one request that is never repeated; check the result before trying again'. That retry/safety guidance is exactly what an agent needs for a non-idempotent mutation and is not derivable from 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?

Four compact sentences, front-loaded with the WRITE prefix and the retry warning before the purpose statement. Every sentence carries information, though the ordering puts safety guidance ahead of what the tool actually does, which slightly slows comprehension.

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 100% schema coverage and an existing destructiveHint annotation, the remaining burdens are mode selection and mutation safety, both of which the description covers. No output schema exists, so the absence of return-value documentation is not a gap.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds the mutual-exclusivity rule between the simple and collective parameter sets and the 'debit and credit sums must match' validation constraint, which is not encoded anywhere in the schema. It is a modest but real increment over the structured fields.

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

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

States a specific verb and resource ('Creates a manual book entry in the journal') and even names the endpoint (POST /journal/create.json), which no sibling shares. An agent can immediately distinguish it from cashctrl_create_order and cashctrl_create_person.

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 lays out the two supported modes ('Either a simple entry (debit_account_id, credit_account_id, amount) or a collective entry (items, whose debit and credit sums must match)'), which is real selection guidance. It stops short of naming when-not or pointing at sibling alternatives (e.g. update/delete journal entries), so it does not reach 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?

Annotations only declare destructiveHint=true, so the description carries most of the load and delivers: it is a WRITE affecting accounting records, it is a single non-repeating request, a booking status also creates journal entries, and no e-mail is sent. The only gap is that, with no output schema, it never says what the response contains (e.g. the new order id) even though it tells the agent to 'check the result'.

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

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

Front-loads the critical 'WRITE: changes the accounting records' warning, then layers scope, defaults, and side effects. Dense but nearly every clause carries information; the retry sentence and the document-type list are both load-bearing.

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 12-parameter, destructive write with no output schema, the description covers scope, idempotency, status semantics, and side effects well. It stops short of describing the return payload or how a created order is subsequently referenced, which is the main remaining gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: category_id selects the document type, status_id drives both the default status and whether journal entries are created, and associate_id is constrained to one customer or vendor. This goes beyond the schema's field-level text.

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 ('Creates ONE order document for ONE customer or vendor') and enumerates the concrete document types (quote, invoice, credit note, purchase bill) driven by category_id. It also implicitly separates itself from cashctrl_create_journal_entry by noting that a booking status generates the journal entries as a side effect.

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 actionable conditional guidance: omit status_id to inherit the category's first status, prefer a draft status unless the user asks otherwise, no e-mail is sent, and check the result rather than retrying. It does not name sibling tools (e.g. cashctrl_list_order_categories) for resolving ids, so it falls short of full alternative routing.

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

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

Annotations only carry destructiveHint=true and a title; the description adds real behavioral context beyond that – it is a WRITE, it is a one-shot request that should not be blindly retried, and the result should be checked. This non-idempotency disclosure is valuable. It stops short of stating permission/auth requirements, so not a full 5.

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

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

Front-loaded with the WRITE warning and every sentence carries information: write scope, retry behavior, required-field rule, duplicate-avoidance workflow. The trailing 'POST /person/create.json' is mildly redundant but harmless.

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 an 11-parameter write tool with 100% schema coverage and no output schema, the description covers mutation nature, non-idempotency, the default-required fields, and duplicate prevention. Auth/permission expectations are the only notable gap.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds a constraint the schema does not encode: 'Give company, first_name or last_name (at least one),' since the schema declares zero required parameters. That materially changes how the agent fills the payload.

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 opens with a specific verb ('Creates') and resource ('a customer, vendor or other contact'), which maps cleanly to the person resource. It distinguishes itself from the read siblings by explicitly naming cashctrl_list_persons as the search-first 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?

It gives a concrete when-to-use workflow: 'Search first with cashctrl_list_persons so no duplicate is created,' and a retry rule: 'check the result before trying again.' Both the alternative tool and the condition selecting it are explicit.

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

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

Annotations only declare destructiveHint=true, so the description carries the meaningful remainder: the operation mutates accounting books, deletion is irreversible ('gone from the books'), and it must not be blindly retried. It also discloses the underlying endpoint, which helps an agent reason about failure modes.

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 WRITE warning is correctly front-loaded, followed by the resource scope, irreversibility, and prerequisite in descending order of importance. The trailing endpoint 'POST /journal/delete.json' is the only clause that does not clearly earn its place against everything else packed in.

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, no-output-schema mutation tool, it covers irreversibility, retry behavior, id sourcing, and the manual-entry restriction. It stops short of naming required permissions/authentication and does not describe the success/failure response shape, which would matter given 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 coverage is 100% and the schema itself documents the 1-20 id range plus the cashctrl_list_journal source for ids, so the description's 'by id' adds little. The one extra instruction, confirming ids with the user, is behavioral rather than a semantics clarification, so the baseline 3 is correct.

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

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

The description names a specific verb and resource ('DELETES manual journal entries by id') and immediately scopes it against a sibling category, noting that entries created by orders or salary statements cannot be deleted this way. An agent can distinguish this from cashctrl_delete_orders and the create/get journal tools 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?

It states explicit prerequisites ('confirm the ids with the user first'), the retry policy ('one request that is never repeated; check the result before trying again'), and a hard exclusion (order- and salary-generated entries are not deletable here). That is when-to-use, when-not-to-use, and operational guidance in one place.

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 destructiveHint=true; the description goes well beyond by disclosing that this is a WRITE that mutates accounting records, that deletion cascades to journal entries, that deleted documents are unrecoverable, and that the request is non-idempotent and must not be blindly retried. That is exactly the extra behavioral context the annotation bar leaves room for.

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

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

Front-loads the critical WRITE warning and keeps every clause load-bearing (safety, cascade, retry rule, confirmation, endpoint). It is dense and slightly telegraphic, but there is no filler to cut.

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 destructive tool with no output schema, the description covers everything an agent needs: what it destroys, the side effect on journal entries, irreversibility, the idempotency caveat, and the confirmation step. Nothing material 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 ids parameter is already documented, including the pointer to cashctrl_list_orders for obtaining ids. The description's 'by id' adds nothing 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 (DELETES) and resource (orders), then enumerates the concrete scope: invoices, quotes, purchase documents. It also discloses the cascade (the journal entries they created) and the transport (POST /order/delete.json), which lets an agent distinguish it from cashctrl_delete_journal_entries and cashctrl_update_order_status without opening any schema.

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

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

Gives explicit operating context: confirm the ids with the user first, and check the result before retrying because the request is never repeated. What it lacks is any routing to an alternative (e.g., when to delete the journal entry directly via cashctrl_delete_journal_entries instead), so it stops short of full 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?

readOnlyHint=true already tells the agent this is a safe read with no side effects, so the description carries a lighter burden. It adds the resource scope and endpoint but says nothing about failure behavior (e.g., invalid or missing id) or the shape of the returned account.

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 fragments with no filler; the identifying purpose comes first. The trailing endpoint path is marginally useful for tracing but not strictly necessary for invocation.

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 this is minimally sufficient, and annotations cover the safety profile. However, with no output schema, the description could describe what an account record contains or how a missing id behaves, which would materially help an agent interpret the result.

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 id property is already documented with a useful caveat ('not the account number'), so the schema does the heavy lifting. The description adds nothing beyond restating that lookup is by id, which matches the baseline 3 for high-coverage schemas.

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 account of the chart of accounts by id') plus the underlying endpoint, so the agent knows it retrieves a single account record. It is distinguishable from cashctrl_list_accounts and cashctrl_get_account_balance by the singular scope, though it never names those siblings explicitly.

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

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

There is no when-to-use or when-not-to-use guidance; the only hint is 'by id', implying it is for lookup when an identifier is already known. No alternative is named for fetching multiple accounts (list_accounts) or balance data (get_account_balance).

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 genuinely non-obvious behavior beyond that: the date parameter defaults to the last day of the current fiscal period, which changes what the call returns when date is omitted. No mention of error or auth behavior, hence not a 5.

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

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

One front-loaded sentence carrying the resource, the default behavior, and the endpoint path. No filler.

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

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

There is no output schema, so the description must carry the return semantics; it identifies the value as an end-of-day balance but says nothing about the shape (scalar vs. amount/currency object). For a simple read-only lookup with fully documented params, this is nearly 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 coverage is 100%, so the two parameters are already documented (id sourced from cashctrl_list_accounts, date format yyyy-mm-dd). The description adds the default value for date, which the schema does not state, giving real incremental meaning.

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

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

States a specific verb and resource: the balance of one account at the end of a day, plus the underlying endpoint GET /account/balance. It is clearly distinguishable in substance from cashctrl_get_account, but never names or contrasts with that sibling 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 only implied: the agent can infer this is the tool for 'what was this account's balance on date X'. There is no statement of when to prefer it over cashctrl_get_account or cashctrl_get_report_data, and no prerequisites mentioned.

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

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

The readOnlyHint=true annotation already tells the agent this is a safe read, so the description carries only a reduced burden — yet it adds nothing behavioral beyond repeating the read nature ('GET ... read.json'). Error/not-found behavior, whether a missing id errors or returns empty, and response shape are all undisclosed.

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

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

Two short fragments with no filler and the core action front-loaded. It is efficient, though telegraphic enough that it reads more like a stub than a polished 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 one-parameter, read-only lookup with no output schema, a minimal description is nearly sufficient, but it says nothing about the returned entity or failure modes, which is the only remaining gap for an agent calling 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 id parameter is fully documented in the schema (including its source tool and positive-integer constraint), so a baseline of 3 applies. The description's 'by id' restates the schema without adding format or edge-case meaning.

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

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

States a specific verb-plus-resource ('One inventory article by id'), which is clearly distinguishable from the sibling cashctrl_list_articles (plural list) and from the other cashctrl_get_* tools by its 'article' resource. It is terse but unambiguous about what is fetched.

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

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

The phrase 'by id' implies the precondition that an article id is already known, but the description never names cashctrl_list_articles as the way to obtain one (that pointer lives only in the schema) and gives no when-not/exclusion guidance. Usage is inferable rather than stated.

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

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 genuine behavioral content beyond that by noting the response includes child items for a collective entry, but it says nothing about error behavior, missing ids, 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 short sentences with no filler, front-loaded with what the tool returns. The trailing endpoint reference is compact and harmless. Slightly terse rather than padded, which is appropriate here.

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 lookup with no output schema, the description covers the essential contract: fetch one entry by id and note that collective entries include their items. Only minor gaps remain, such as what a not-found id returns.

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 id parameter is fully documented in the schema, including its provenance from cashctrl_list_journal. The description only restates "by id" and adds no format or boundary detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource (get a journal entry by id) and clarifies the scope: a single entry with its items for a collective entry. That scope detail distinguishes it from cashctrl_list_journal, though the sibling is not named explicitly. The phrasing "One book entry by id" is slightly awkward but 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?

Usage is implied by the id parameter and the fact that this is the singular counterpart to cashctrl_list_journal, but the description never states when to use this versus list_journal or the create/delete siblings. No prerequisites or exclusions are given.

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

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 return-content context (items, totals, status) and the backing endpoint, but says nothing about error behavior for an unknown id or about permissions, which is limited added value for a read 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 sentences, with the core purpose front-loaded before the endpoint reference. Nothing is wasted, though the raw endpoint path is marginally less useful to an agent than additional semantics would have been.

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 it adequately by naming items, totals, and status. For a single-id read tool with full schema coverage, only explicit usage routing 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?

There is only one parameter and schema description coverage is 100%, so the schema already documents the id and its origin. The description adds no format, range, or lookup details beyond that, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('One order ... by id') and immediately disambiguates the domain term by naming what an order can be (invoice, quote, purchase document). It also declares the payload scope (items, totals, status), which cleanly separates it from cashctrl_list_orders.

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 or when-not guidance and does not name an alternative such as cashctrl_list_orders or cashctrl_create_order. The only pointer to the id's origin lives in the schema, not the description, so the agent gets no routing context from the text 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?

readOnlyHint=true already declares the safety profile, and the description goes beyond it by disclosing the returned payload (addresses, contact data, bank accounts) and the underlying API endpoint. That return-content detail is genuinely useful since no output schema exists.

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

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

A single front-loaded sentence stating the resource and its returned contents, followed by the endpoint path. Efficient, though the raw endpoint string is marginal value for an agent.

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

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

For a one-parameter read tool with annotations covering safety and no output schema, the description supplies the missing return-shape information (addresses, contacts, bank accounts), which is what an agent most needs here. Only the list-then-get relationship is left implicit.

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 only one parameter and schema description coverage is 100% — the schema already documents the id and its provenance from cashctrl_list_persons. The description adds no format or constraint detail beyond it, 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 retrieval verb implicitly ('One person or company by id') and names the resource, plus enumerates the payload contents (addresses, contact data, bank accounts). An agent can distinguish it from cashctrl_list_persons by the singular scope, though the description never explicitly contrasts the two.

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

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

Usage is only implied: the schema note '(from cashctrl_list_persons)' hints at the list-then-fetch flow, but the description itself gives no when-to-use statement or alternatives. Adequate but leaves the agent to infer the 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 and the description doesn't contradict it. The description adds that data can be scoped by fiscal period or date range, which is useful context, but says nothing about permission requirements, pagination, or result size.

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

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

Two compact sentences: the purpose first, then the endpoint. Nothing is wasted, though the endpoint path is arguably redundant operational detail that pushes the line count without adding selection value.

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

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

For a simple read tool with a fully documented schema and annotation-covered safety, the description is minimally adequate but omits the return shape and any routing guidance relative to the report-tree sibling, which is needed to call it correctly in a multi-step report workflow.

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 start_date, end_date, fiscal_period_id, and their replacement relationship, so the description needn't document them. It adds only the notion of period vs. date range, which is already implied by the schema. Baseline 3.

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

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

The description states a specific verb and resource — retrieving the data of one report element, with concrete examples (balance sheet, income statement). It names the endpoint, but it does not differentiate from the sibling cashctrl_get_report_tree, which retrieves the element tree rather than the element's data.

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 guidance on when to use this versus cashctrl_get_report_tree or the balance-specific tools. The only usage hint is indirect, via element_id's schema reference to the tree tool, so an agent must infer the 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 the safe read-only nature is covered by structured data. The description adds minimal behavioral context beyond that, only revealing the underlying endpoint (GET /report/tree.json). It does not describe pagination, depth, or output size, which would be genuinely useful for a tree fetch.

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 resource description front-loaded and the sibling linkage and endpoint trailing. Every element carries information; no filler.

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

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

With no output schema, the description carries the burden of describing return content, and it does so reasonably – it states the result is a tree of collections and elements and gives examples. What's missing is finer shape detail (element fields, hierarchy depth), but for a discovery tool this is largely 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?

The tool takes zero parameters, which is the baseline 4 case; there is nothing for the description to disambiguate. The description correctly implies no inputs are needed to retrieve the full tree.

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 ('reports set up in CashCtrl ... as a tree of collections and elements') and concretely enumerates examples (balance sheet, income statement), so an agent knows it fetches report structure. It also distinguishes itself from the sibling cashctrl_get_report_data by noting the element id is that tool's input. The verb is only implied via the endpoint rather than stated outright, keeping it 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?

Usage is implied through the workflow hint that 'the element id is the input of cashctrl_get_report_data', which tells an agent this is a discovery step preceding data retrieval. However, there is no explicit when-to-use statement or exclusion, so guidance remains inferential 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 read-only nature is covered. The description adds genuinely useful context beyond that: the data is 'Sensitive personal data', which signals handling caution, and it exposes the underlying endpoint. It does not, however, describe auth requirements, what happens with invalid ids, or the shape of the salary items.

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 fragments with zero padding, and the core purpose is front-loaded ahead of the sensitivity note and endpoint. Slightly telegraphic, but no sentence is wasted.

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

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

For a single-item read with a complete schema and no output schema, the description covers the essential elements: what is fetched, that it includes salary items, and that the data is sensitive. Auth/error behavior is unaddressed but minor for a read-only lookup.

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 id parameter is fully documented in the schema, including its source and constraints. The description's 'by id' adds no syntax or format detail beyond that, so the baseline of 3 applies.

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

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

States a specific verb+resource ('one payroll statement by id') and clarifies it returns the statement with its salary items. Implicitly distinguishes itself from the list sibling via 'by id', though it does not name cashctrl_list_salary_statements as the plural counterpart.

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 through 'by id'; there is no explicit when-to-use guidance or stated alternative for bulk/listing needs. The schema's note that the id comes from cashctrl_list_salary_statements hints at the workflow, but the description itself adds no routing guidance.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds only the domain enumeration and the REST path; it says nothing about ordering, pagination, whether sub-categories are nested or flat, or the response shape despite there being 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?

A single front-loaded sentence with the resource named first, the parenthetical enumeration second, and the endpoint last. No filler or repetition.

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 no-parameter, read-only lookup with no output schema, the description gives enough to know what comes back conceptually (category names and their sub-categories). It could say more about ordering or nesting, but coverage is adequate for a tool this simple.

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

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

The tool takes zero parameters, so the baseline of 4 applies. The description cannot and need not add parameter detail; there is simply nothing to document.

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

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

Names the resource precisely ('categories of the chart of accounts') and enumerates the concrete category types, which distinguishes it from siblings like cashctrl_list_accounts and cashctrl_list_order_categories. The list verb is carried by the tool name/title rather than the description text, so it falls just short of a fully self-contained verb+resource statement.

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

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

There is no indication of when to reach for this tool versus cashctrl_list_accounts (the accounts that belong to these categories) or any other list sibling. The description is purely descriptive of content, leaving the agent to infer the use case.

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 one genuine behavioral fact beyond annotations — 'Not paged' — which matters for how the agent handles large result sets, plus the endpoint path. It does not cover the fiscal-period defaulting behavior or any rate/limit context, 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 short clauses plus an endpoint reference, with zero filler. It front-loads the content of the listing rather than the operation name, which is a minor ordering weakness but costs nothing in length.

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, unpaged list tool with full schema documentation and no output schema, this covers what the agent needs: what the resource is, which fields come back, and that the result is not paginated. Nothing essential 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 description coverage is 100% and all seven parameters (dir, sort, query, filter, category_id, only_active, fiscal_period_id) are documented in the schema itself, so the baseline of 3 applies. The description only hints at the fiscal-period dimension of the result and adds no syntax or default information 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 names the resource (chart of accounts) and enumerates the returned fields (number, name, category, balance for the fiscal period), which is specific enough to separate it from cashctrl_get_account (single account) and cashctrl_list_account_categories. It never states the verb 'list' explicitly, but 'The chart of accounts:' plus the endpoint makes the operation 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 cashctrl_get_account (single lookup) or cashctrl_list_account_categories. The agent must infer the list-vs-get distinction from the name alone; no exclusions or prerequisites are stated.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful value by disclosing the underlying endpoint and the shape of returned records (number, name, price, stock, accounts), but says nothing about pagination behavior, defaults, or result volume 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?

Two compact clauses with zero padding; the resource and returned fields are front-loaded before the endpoint reference. Efficient, though the bare endpoint string is of marginal value to an agent that cannot call HTTP paths directly.

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 documented 9-parameter schema, the description is adequate but thin — it omits pagination semantics (next_start), default row counts, and sorting defaults, all of which live only in the schema. Nothing critical is missing, but it does not round out 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 all nine parameters (sort, dir, limit, query, start, filter, category_id, only_active, only_restock) are already fully documented in the schema. 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?

States a specific resource (inventory articles, clarifying they are products and services) and enumerates the returned attributes (number, name, price, stock, accounts), so an agent knows exactly what it retrieves. It does not explicitly contrast itself with the sibling cashctrl_get_article, but the 'list' framing makes the distinction reasonably 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 guidance on when to use this tool versus cashctrl_get_article for a single article, nor any stated prerequisites or when-not conditions. The agent must infer usage entirely from the name and endpoint.

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, so the bar is lower. The description adds value by naming the fields the listing returns (name, IBAN, linked ledger account), which partially substitutes for the missing output schema, but says nothing about ordering, pagination, or result size.

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

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

One front-loaded sentence stating purpose plus the returned fields; the trailing REST endpoint is mildly redundant padding but costs little. No wasted preamble.

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

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

For a simple read-only listing with no input parameters and no output schema, the description covers what the tool returns and what it is for. Only ordering/pagination behavior is unaddressed, 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?

The tool takes zero parameters and schema coverage is 100%, so there is nothing for the description to disambiguate. Per the baseline for parameterless tools, a 4 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 (list) and resource (bank accounts), and the parenthetical 'name, IBAN, linked ledger account' distinguishes it from the sibling cashctrl_list_accounts (the general ledger chart of accounts). It stops short of explicitly naming that sibling, so it is clear but not fully differentiated.

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

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

No indication of when to prefer this over cashctrl_list_accounts or the other list_* siblings, and no prerequisites stated. For a zero-argument read tool usage is fairly self-evident, but the description offers no routing guidance.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered by structured data. The description adds the useful behavioral fact that the result includes exchange rates and names the underlying endpoint, but it says nothing about ordering, inclusion of inactive/base currencies, or response shape.

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

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

Two short fragments, front-loaded with the result content. The raw endpoint reference (GET /currency/list.json) is developer-oriented noise for an agent caller, so it is not perfectly waste-free but costs little.

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

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

For a parameterless read-only list with no output schema, the description conveys enough to call it and to understand the payload's key attribute (exchange rates). Ordering, pagination, and whether inactive currencies appear are unaddressed, but the complexity is low.

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 no parameters, so the baseline of 4 applies. The description does clarify what the returned entries contain (exchange rates), which is a mild value-add over an empty schema.

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

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

The description names the resource ('the currencies set up in CashCtrl') and adds distinguishing content ('with their exchange rates'), which is more specific than the title alone. It does not, however, explicitly differentiate itself from the many other list_* siblings, though the resource name makes that largely self-evident.

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 alternatives named. For a zero-parameter list tool the need is modest, but the description provides no routing guidance whatsoever beyond the resource 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?

With readOnlyHint already covering the safety profile, the description adds return-field details and the important cross-tool ID relationship. It does not mention pagination or auth needs, but these are lower-burden gaps given 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?

Two very short, front-loaded fragments state the resource and fields first, then add the ID mapping and endpoint. Every sentence earns its place 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 zero-parameter list tool with no output schema and readOnlyHint already set, the description supplies the returned fields and explains how the id is used elsewhere. This is sufficient for an agent to call and use the result 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?

The tool has zero parameters, so parameter semantics are not applicable. The baseline for no parameters is 4, and the description does not introduce any misleading parameter behavior.

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 (fiscal periods) and the returned fields (id, name, start, end, current flag), making the operation immediately identifiable. It also distinguishes its role by noting the id is the fiscal_period_id used by other 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?

Does not explicitly say when to use this tool versus alternatives or name any sibling tool. However, the note that the id is the fiscal_period_id of other tools implies the intended usage: obtaining period IDs for downstream calls.

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 only readOnlyHint=true in annotations, the description adds real value: the newest-first ordering, the default fiscal-period scoping, and the exact fields returned. It does not mention pagination behavior or result-size limits, but the safety profile is fully 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?

A single dense sentence with the scope constraint and default behavior front-loaded, ending with the endpoint. Every clause carries 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 15-parameter list tool with no output schema, the description usefully enumerates the returned field set so the agent knows what a row looks like. Remaining gaps (pagination semantics, filter interaction) are covered by the schema's own descriptions.

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 15 parameters are documented in the schema. The description only reinforces fiscal_period_id's override behavior, adding no syntax beyond what the schema already 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 (book/list) and resource (journal entries), enumerates the returned fields, and gives the sort order and endpoint. It is clearly distinguishable from the singular cashctrl_get_journal_entry 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?

It explains the default scope ('current fiscal period unless fiscal_period_id is set') but gives no guidance on when to use this list versus cashctrl_get_journal_entry or when to prefer the many filter flags. Usage is implied rather than stated.

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

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

Annotations only declare readOnlyHint=true, so the description carries the rest of the burden. It discloses the shape of the returned data (categories, statuses, default accounts, sequence numbers) and the underlying GET endpoint, which is meaningful since there is no output schema. It does not mention pagination, sorting, or auth, keeping it below a 5.

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

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

Two tight sentences plus the endpoint reference. The resource and returned fields come first, the usage hint second, with no filler or restated 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?

With no output schema and only a readOnly annotation, the description does the heavy lifting by describing what the call returns and how to use the ids. It is nearly complete for a read-only list tool; only pagination/ordering behavior is unaddressed.

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

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

Schema description coverage is 100% and both parameters (type, fiscal_period_id) are already documented in the schema, including the SALES default and the pointer to cashctrl_list_fiscal_periods. The description only echoes the PURCHASE type hint, so the baseline 3 applies.

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

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

The description names a specific verb and resource (listing order categories), enumerates the concrete category types (Quote, Invoice, Credit note, Purchase invoice) and the attached data (statuses, default accounts, sequence numbers). This clearly separates it from siblings such as cashctrl_list_account_categories and cashctrl_list_sequence_numbers without needing to open 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?

It explicitly states the intended use: 'Use it to find category_id and status_id (type PURCHASE for purchase documents).' That tells the agent why and when to call it, and ties the PURCHASE enum value to a concrete scenario. It stops short of naming alternatives or when-not-to-use conditions, so it is clear context but not full routing guidance.

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

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

The readOnlyHint annotation already establishes this is a safe read. The description adds useful context beyond that: the default sort order (newest first) and the shape of returned rows (number, date, customer, status, total). It says nothing about pagination or limits, which matters for a 13-parameter list tool with a 500-row cap.

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

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

Two sentences, front-loaded with the resource definition and closed with ordering and return fields. The trailing raw endpoint 'GET /order/list.json' is the one element that does not earn its place 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 compensates by listing the returned row fields, and the safety profile is covered by the readOnlyHint annotation while all 13 parameters are documented in the schema. The remaining gap is pagination behavior (start/limit interplay, the default period scoping of fiscal_period_id), which an agent may need for a list endpoint capped at 500 rows.

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 every parameter (dir, sort, type, limit, query, start, filter, only_open, only_overdue, person_id, status_id, category_id, fiscal_period_id) is already documented in the schema, several with cross-references to sibling list tools. The description adds no parameter detail, so the baseline 3 is appropriate.

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

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

The description names the specific resource (sales/purchase documents) and enumerates the concrete document types it covers (quotes, order confirmations, invoices, delivery notes, credit notes, vendor bills) plus the fields returned. This is clearly distinguishable from siblings like cashctrl_get_order (single record) or cashctrl_list_journal, though it never states the verb 'list' explicitly and relies on the title for that.

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: nothing tells the agent when to pick this over cashctrl_list_journal, cashctrl_list_order_categories, or cashctrl_get_order for a single document. 'Newest first' hints at a default ordering but is not usage guidance, and 'GET /order/list.json' is an implementation detail rather than a selection criterion.

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 only job is to add context — and it adds none. It says nothing about pagination behavior (despite start/next_start semantics in the schema), maximum result sizes, or what a list reply looks like, though those details live in the schema rather than the prose.

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 fragments with no filler, and the resource identity plus returned fields are front-loaded. It is arguably under-specified rather than padded, which is a completeness problem more than a conciseness one.

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 an 11-parameter read tool with no output schema, the description at least enumerates the fields a person row carries, which partially compensates for the missing return documentation. However, it omits pagination behavior, filter semantics and sibling routing, leaving meaningful gaps for a tool of this surface area.

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% across all 11 parameters, so the schema itself fully documents sort, dir, limit, query, start, filter and the only_* flags. The description adds no parameter meaning beyond that, so the baseline 3 for high-coverage schemas is correct.

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 its subtypes precisely ('Customers, vendors, employees and other contacts') and even lists the fields carried (name, company, number, roles, addresses), so an agent knows what this list contains. It lacks an explicit verb, but the GET /person/list.json endpoint and the naming pattern versus get_person make the list-vs-get distinction inferable rather than stated.

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

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

There is no guidance on when to use this tool versus the obvious alternative cashctrl_get_person for a single record, nor when to use the only_customers/only_vendors/only_employees/category_id narrowing options. The agent must infer usage entirely from the name and schema.

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

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

readOnlyHint=true already declares the operation safe, and the description adds genuinely useful context: a 'Sensitive personal data' warning and the default 'newest first' ordering. It stops short of describing pagination semantics or rate limits, which would have pushed it higher.

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 fragments with the resource and returned fields front-loaded, followed by the sensitivity warning and endpoint. Every element carries information, though the raw endpoint path is marginally redundant with 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 read-only list tool with full schema coverage and no output schema, the description supplies the returned columns, default ordering, and a sensitivity flag—enough for correct invocation. Missing only pagination and filter-flag behavior details that would make it exhaustive.

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

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

Schema description coverage is 100%, so the schema already documents all nine parameters including sort, limit, start, and the filtering flags. The description adds only the default ordering note, leaving the schema to carry the parameter burden, which matches the baseline 3.

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

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

States a specific verb-resource pairing (list salary statements) and enumerates the returned fields (employee, date, status, gross and net amounts), which lets an agent distinguish it from the singular cashctrl_get_salary_statement. It does not explicitly name that sibling, so differentiation is implied by name rather than stated.

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

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

The description notes default ordering ('newest first') but offers no explicit when-to-use guidance or routing to alternatives like cashctrl_get_salary_statement for single records. Usage is only implied by the 'list' framing.

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 real context — that returned ids feed the sequence_number_id of write tools and gives the underlying endpoint — but says nothing about return shape or ordering, which matters 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?

Three short, front-loaded fragments with no filler. The resource and the downstream use of the id are stated immediately; nothing needs to be trimmed.

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

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

For a zero-parameter read-only list tool, the description covers the resource, the endpoint, and the practical link to write tools. Only the return contents are unspecified, a minor gap given the absence of an output schema.

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

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

The tool takes zero parameters, so the baseline of 4 applies. The description correctly adds no parameter detail because none exists.

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?

Identifies a specific resource (number sequences) and clarifies its domain role — journal references, order numbers, customer numbers. The listing verb is carried by the name rather than the description, but the resource and its purpose are unambiguous and clearly distinct from siblings like cashctrl_list_journal.

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 line 'The id is the sequence_number_id of the write tools' implies when this tool is needed (to obtain an id before calling a write tool), but there is no explicit when-to-use statement, no mention of alternatives, and no exclusions. Usage is inferable rather than stated.

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

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

The readOnlyHint annotation already establishes this as a safe read, so the burden on the description is lower. The description adds the concrete return fields and the cross-tool id mapping, which is useful, but says nothing about result size, caching, or whether inactive tax codes 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?

Two short sentences, front-loaded with the resource and its fields, with no filler. The trailing 'GET /tax/list.json' is implementation detail that an agent calling the MCP tool cannot act on, slightly reducing the value of the otherwise tight phrasing.

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

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

For a parameterless read-only list with no output schema, the description supplies the essential missing piece — the returned fields — plus the id's role in write flows. It omits pagination/volume expectations, but the tool is simple enough that this is a minor gap.

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

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

With zero parameters, the baseline is 4, and the description does not need to explain any input. It instead documents the shape of what comes back, which is a reasonable substitute for the absent output schema.

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

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

The description names a specific resource (VAT tax codes) and even enumerates the returned fields (id, code, name, rates), which makes it easy to distinguish from siblings like list_currencies or list_accounts. The 'List' verb comes from the title rather than the description text, and no sibling is named for contrast, 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 id is the tax_id of the write tools' gives a real usage link — it tells the agent this tool is the lookup step preceding write tools that need a tax_id. However, there is no explicit when-to-use/when-not guidance and no naming of alternatives among the 27 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?

Beyond destructiveHint=true, the description discloses that the operation books journal entries, moves stock, and therefore changes the books, plus that the request is non-idempotent ('never repeated'). This is exactly the extra context annotations cannot convey, and it also names the underlying endpoint.

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

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

Front-loads the critical 'WRITE:' marker and stays to a few tight clauses with no filler. Only the trailing endpoint string is marginally low-value for an agent that will not call HTTP directly.

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 mutation with no output schema, the description covers the write nature, side effects on books and stock, batch size, and retry caution. It leaves open what happens if some of the 20 orders fail and what the response confirms, which would be the last useful detail.

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 by illustrating the kind of status transitions status_id represents and reaffirming the 1-20 batch limit that governs ids. It stops short of documenting id sourcing or failure semantics for partial batches.

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 ('Sets the status of 1-20 orders') and grounds it with concrete transitions (Draft to Open, Open to Paid). An agent can distinguish this from cashctrl_delete_orders or cashctrl_create_order 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 through the example transitions; there is no explicit when-to-use vs an alternative, nor any stated precondition such as required permissions. The retry advice ('check the result before trying again') is behavioral guidance rather than task-routing guidance.

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