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

Beyond annotations, the description discloses meaningful behavioral traits: 'Not idempotent: calling twice with the same name creates two accounts' and 'v1 offers no way to update or delete an account afterwards.' These add important behavioral constraints that are not fully captured by annotations alone and do not contradict the readOnlyHint/idempotentHint values.

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 front-loaded and generally well organized, but it repeats the idempotency warning twice and opens with a broad generic line about creating 'receipts, transactions, postings, invoices, master data' that is only loosely related to this specific tool. It earns a 3 because the structure is serviceable but contains redundant boilerplate.

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?

Given the output schema exists, the description does not need to explain return values. It covers the important operational context an agent needs: when to use it, what not to use it for, non-idempotency risks, the alternative sibling, and the endpoint.

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

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

The input schema already covers 100% of parameter descriptions, including accepted type values and per-field notes. The description does not add new meaning for individual parameters, so it stays at the baseline for high schema coverage. The mention of 'bank, cash or credit-card' loosely maps to schema values but does not clarify parameter formats beyond what the schema already provides.

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

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

The description states a specific verb and resource: 'Use to register a new bank, cash or credit-card account before importing transactions for it' and explicitly distinguishes itself from 'postingaccounts_create'. It also clarifies it is not for chart-of-accounts entries, so an agent can tell it apart from the sibling 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?

Provides explicit when-to-use guidance: 'Use to register a new bank, cash or credit-card account before importing transactions for it. It also gives exclusions and alternatives directly: 'Not for chart-of-accounts entries. To add a posting account number, use postingaccounts_create.' It even tells the agent to 'Check accounts_list first' before creating.

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, idempotentHint=true, and destructiveHint=false, and the description reinforces this with 'READ-ONLY'. It adds useful behavioral context beyond the annotations: there is no update or delete endpoint in v1 and an account created here can only be listed afterwards, which helps set expectations despite the read-only nature.

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 well-structured, front-loaded with the read-only flag, and each section adds value. The bolded 'get all the accounts' repeats the title slightly, but the rest is focused and avoids unnecessary 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 parameters and an output schema present, the description fully covers what an agent needs: what the tool returns conceptually, how it relates to transaction tools, and which sibling to use instead. The lifecycle note about missing update/delete endpoints adds completeness for a no-parameter read operation.

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 and the input schema is empty, so parameter semantics are trivially satisfied. The description still adds relevant context by explaining that the output is used to resolve account names to the numeric account id expected by transaction tools.

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

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

The description uses a specific verb (list) and resource (bank, cash and credit-card accounts) and explicitly contrasts these with the chart of accounts, pointing to postingaccounts_list for posting account numbers. This clearly distinguishes it from sibling tools without requiring schema inspection.

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 exactly when to use the tool: to list accounts that transactions can be booked against and to resolve account names to numeric account ids. It also gives an explicit exclusion ('Not the chart of accounts') and names the alternative tool, postingaccounts_list.

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

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

The description discloses that this is a write operation that is not idempotent ('calling twice may create duplicates'), which aligns with the idempotentHint:false annotation but adds specific consequence. It also reveals the lack of read/edit/delete endpoints, which is not apparent from annotations. These are valuable behavioral insights beyond what annotations 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 description is somewhat verbose, starting with a generic '🟡 WRITE · creates data' block that applies to all write tools, then repeating the title. However, the key information (exactly-one constraint, limitation) is clearly presented. The structure is acceptable but could be tightened by removing the generic header.

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

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

The description covers the required parameter constraint, the use case, and the persistence limitation. It doesn't describe the output, but an output schema exists. For a simple comment-adding tool, the description is sufficiently complete, though it could mention error scenarios or the expected response format.

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%, but the description adds the critical mutual exclusivity rule: exactly one of transaction_id_by_customer or receipt_id_by_customer must be set. The schema merely lists them as optional, so the description provides essential semantics that prevent invalid calls. This goes beyond the schema documentation.

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 clearly states the tool's purpose: 'Add comment to transaction or receipt.' It identifies the specific resource (comments) and the action (add), and provides a concrete use case ('record why a booking was categorised'). This distinguishes it from sibling tools that create other entities like transactions or receipts.

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

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

The description explicitly specifies the required condition: 'Exactly one of transaction_id_by_customer or receipt_id_by_customer must be set.' It also notes the limitation that v1 offers no read/edit/delete endpoints, so comments are only visible in the web app. While it doesn't explicitly say 'use this instead of X', the context is clear and the constraint is actionable.

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 indicate write and non-idempotent, but the description adds concrete consequences: 'calling twice may create duplicates' and the recommendation to check the list first. This goes beyond the annotation by explaining the risk and mitigation. Slight redundancy but still valuable.

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 well-structured with a clear heading and front-loaded warning. It repeats 'Not idempotent' twice, which is mildly redundant, but overall it's efficient and each sentence serves a purpose. The generic opening about creating records is somewhat redundant with the title and annotations.

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

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

The tool is simple with only two parameters and has an output schema, so the description need not detail return values. It covers the core behavioral risk (duplicates) and provides usage guidance. Missing details like permissions or format specifics are not critical given the schema and annotations.

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

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

The input schema already provides full descriptions for both parameters (code and name) with 100% coverage. The description does not add any additional meaning or nuance about the parameters, so the baseline score of 3 applies.

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

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

The description clearly states the verb 'add' and the resource 'cost location', and even gives the use case 'create a cost centre before referencing it from a posting'. It distinguishes itself from siblings like cost_locations_list, cost_locations_update, and cost_locations_delete by explicitly saying 'add'.

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 provides explicit guidance on when to use this tool: 'Use to create a cost centre before referencing it from a posting.' It also warns against duplication and directs the agent to check cost_locations_list first, which is an explicit alternative and a condition for use.

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 include destructiveHint=true and readOnlyHint=false, but the description adds significant context beyond that: the irreversibility ('Permanent. Unlike a deleted receipt there is no restore endpoint'), the requirement to confirm with the user, and a distinction between receipt deletes (restorable) and cost-location deletes (not). This goes beyond what annotations provide and helps the agent understand the consequences. No contradiction with annotations.

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

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

The description is somewhat verbose and repetitive. It states 'Delete a cost location' and then 'Use to remove a cost centre' which is essentially the same. The destructive warning at the beginning is duplicated in the body. The emoji and bold formatting add visual noise. However, it is structured in short paragraphs and includes the endpoint, which is useful. It could be trimmed but is not excessively long.

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?

Given that an output schema exists (has output schema: true), the description doesn't need to explain return values. The description covers the core aspects: the action, when to use it, the irreversibility, and the confirmation requirement. It also mentions the HTTP endpoint. It lacks any mention of preconditions (e.g., whether the cost location must exist or have no dependencies), but for a simple delete tool this is adequate. Overall it is fairly complete.

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

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

The schema has one parameter 'code' with a clear description ('The cost location code'). The tool description does not add any additional semantic meaning to the parameter beyond what the schema provides. Since schema coverage is 100%, the baseline is 3. The description doesn't mention format, examples, or related fields, but it's not necessary given the schema covers it.

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

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

The description clearly states the verb 'Delete' and the resource 'cost location' (also referred to as 'cost centre'). It distinguishes from siblings like cost_locations_list, cost_locations_create, and cost_locations_update by specifying the action. The first sentence is explicit and unambiguous.

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

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

The description provides clear context: 'Use to remove a cost centre that is no longer needed.' It also gives an important usage guideline: confirm with the user before calling, because the delete is permanent and has no restore endpoint. It doesn't explicitly say when not to use, but the purpose is clear enough for an agent to decide. It could have mentioned alternatives (e.g., update if the cost centre is still needed) but that is implied.

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, openWorldHint, idempotentHint, and destructiveHint=false, so the bar is lower. The description adds useful behavior beyond those annotations: each request is capped at 1000 cost locations, and the response shape is described as row count plus an array. It also explicitly says 'Makes no changes to the accounting records,' aligning with 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?

The description is well-structured and front-loaded with the read-only note, followed by purpose, response info, limit warning, and use case. It includes a minor redundant bold heading 'get cost locations' that duplicates the title, but overall every main 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?

Given the simple 3-parameter read-only tool, robust annotations, complete schema coverage, and existing output schema, the description covers the essential operational context: purpose, return contents, limit, and where the data applies. Nothing critical is missing for correct invocation.

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

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

Schema description coverage is 100%, so the schema fully documents `code`, `limit`, and `offset`. The description reinforces the 1000 limit but does not add meaningful parameter-level meaning beyond what the schema already 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 uses a specific verb and resource: 'Get cost locations for a specified customer account' and explicitly states the response contains returned row count and an array of cost locations data. It further clarifies its role as listing cost centres for the `cost_location` fields on posting tools, which distinguishes it from mutation siblings like cost_locations_create/update/delete.

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 explicit guidance: 'Use to list the cost centres available for the `cost_location` fields on the posting tools.' It also notes the 1000-item request limit, helping agents understand pagination needs. It does not explicitly mention when not to use it or name alternatives, so it falls short of a 5.

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

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

Discloses that updates happen in placeclip, that sent fields are overwritten, and that a preceding read is needed for partial changes. Annotations already label it as a write and non-destructive operation; the description adds useful overwrite behavior without contradicting 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?

The description is short and front-loaded with the action and scope. It contains some redundancy with the repeated 'update cost location' heading and the endpoint line, but most sentences earn their place by adding behavioral guidance.

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?

Given only two required parameters, an existing output schema, and annotations covering write/idempotency/non-destructiveness, the description is mostly complete. It lacks an example or clear explanation of how `code` behaves when changing a number, but that is a minor gap.

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

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

Schema coverage is 100%, so `code` and `name` are already documented directly. The description adds the rename/number use case but does not clarify whether `code` is the record identifier or the new number, so it adds only marginal semantics over 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 that it modifies existing cost locations in place, and specifies the target fields (name/description) and use cases (rename a cost centre or change its number). It is clearly distinct from create/list/delete siblings, though 'change its number' is ambiguous relative to the `code`/`name` schema fields.

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

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

Explicitly tells the agent to use the tool for renaming or changing an existing cost centre, and instructs reading `cost_locations_list` first before a partial change. It does not explicitly name create/delete as alternatives, but the 'existing' wording makes the intended context clear.

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 provide readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description adds valuable context beyond annotations: 'Not idempotent: calling twice may create duplicates,' 'v1 offers no delete endpoint, so a creditor created here can only be updated afterwards, never removed,' and advises checking creditors_list first. This adds meaningful behavioral detail without contradicting annotations.

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

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

The description is reasonably concise and well-structured with a clear header and bullet-like sentences. The initial generic write note ('🟡 WRITE · creates data') is somewhat redundant given the annotations, but it doesn't detract significantly. Each subsequent sentence adds specific value, and the content is front-loaded with the core purpose.

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?

Given the complexity (array parameter with many fields), the description covers the key points: usage, array format, non-idempotency, no-delete limitation, and the alternative tool. An output schema exists (though not provided), so return values are likely documented there. The description is complete enough for an agent to call the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds clarification on the array parameter: 'Takes one or many: pass an array of creditors in creditors. A single record is an array of one.' This explains the required array structure, which is not immediately obvious from the schema alone, providing extra value.

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 clearly states 'Create a creditor account' and 'Use to create one or more suppliers,' specifying the resource and action. It also explicitly differentiates from debtors_create by saying 'For customers you invoice, use debtors_create.' This makes the purpose unambiguous and distinguishes it from a key 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?

Provides explicit usage guidance: 'Use to create one or more suppliers,' and instructs to check creditors_list first due to non-idempotency. It names the alternative tool for customers (debtors_create), giving clear when-to-use vs. when-not-to-use direction. Also explains the array format for one or many records.

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, openWorldHint, idempotentHint, and destructiveHint. The description reinforces this with 'READ-ONLY: Fetches data. Makes no changes' and adds behavioral details beyond the annotations: pagination behavior ('the response reports the total in rows') and the lifecycle note that creditors can only be created, listed, and updated. No contradiction.

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 well-structured and front-loaded with the read-only callout, followed by purpose, alternative, pagination, and lifecycle. There is minor redundancy (read-only line + heading + 'Get all creditors'), but each section contributes distinct 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 two-parameter list call with an output schema and extensive annotations, the description covers purpose, use case, sibling differentiation, pagination behavior, and lifecycle constraints. Nothing an agent needs to correctly invoke the tool is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds functional meaning to `limit` and `offset` by explaining the pagination contract and how the reported `rows` total guides paging. This goes beyond the basic schema descriptions without restating every default.

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: 'Get all creditors' and explains the intended use case: 'resolve a supplier name to the creditor id the receipt and posting tools expect.' It explicitly differentiates from the sibling `debtors_list', leaving no ambiguity about what this tool does.

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

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

It clearly says when to use this tool—to list suppliers—and explicitly names the alternative for customers: 'For customers you invoice, use debtors_list.' It also gives practical pagination guidance ('page until you have seen that many rows'). This is strong, explicit usage guidance.

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

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

The description discloses important behavioral traits beyond the annotations: it is a write operation ("WRITE · updates data"), modifies existing master data in place, and overwrites the fields sent. It also warns to read the current record before partial updates. Annotations already signal readOnlyHint=false and idempotentHint, so the description adds useful overwrite semantics without contradicting annotations.

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

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

The description is short and mostly focused, with the core purpose and key behavioral warning front-loaded. There is minor redundancy between the title, bold header, and first sentence, but overall the structure is efficient and scannable.

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?

Given the full schema coverage and existing annotations, the description includes the crucial operational context: which fields can be updated, the overwrite behavior, the need to read first for partial changes, and the endpoint. It does not explain validation rules, but those are captured in the schema, and an output schema exists, so nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already fully documents all 13 parameters with their individual meanings and validations. The description adds only a high-level grouping (address, bank details, payment terms) and does not materially enhance parameter understanding 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 clearly states a specific verb and resource: "Update a creditor account" and further clarifies the scope with "change a supplier's address, bank details or payment terms." This distinguishes it from sibling tools like creditors_create and creditors_list through the explicit focus on modifying existing creditor 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?

The description provides clear context on when to use the tool (to change supplier address, bank details, or payment terms) and advises reading the current record with creditors_list first for partial changes. It does not explicitly mention when not to use it or alternatives like creditors_create, but the usage intent is clear.

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 description goes beyond annotations by explaining the non-idempotent behavior ('calling twice may create duplicates') and the lack of a delete endpoint ('can only be updated afterwards, never removed'). It also flags the write nature. This is valuable context not available from annotations alone.

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

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

The description is moderately long but each sentence serves a purpose: it states the operation, distinguishes from the alternative, explains batch usage, warns about idempotency, and notes the lack of deletion. The use of bold headings and bullet-like phrasing keeps it scannable, though the initial broad statement about creating multiple record types is slightly extraneous.

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

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

With an output schema present, the description doesn't need to explain return values. It covers the essential operational details: batch capability, idempotency risk, deletion limitation, and the alternative tool. No critical information for correct invocation is missing.

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

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

The schema already provides detailed field descriptions, but the tool description clarifies the batch usage: 'pass an array of debtors in debtors. A single record is an array of one.' This adds practical meaning beyond the schema's generic array description.

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

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

The description clearly states 'Create a debtor account' and 'Use to create one or more customers,' providing a specific verb and resource. It explicitly distinguishes from the sibling tool creditors_create, making it unambiguous which tool to select.

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 'For suppliers you buy from, use creditors_create' and advises checking debtors_list first due to non-idempotency. This gives clear when-to-use and when-not-to-use guidance, as well as a recommended pre-check.

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, idempotentHint, and destructiveHint, and the description reinforces those. It adds useful behavioral context beyond the annotations: support for limit/offset, the version limitation that debtors can only be created/listed/updated, and the POST 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?

The description is well-structured and front-loaded with the read-only notice and core purpose. Some redundancy exists with the annotations and the repeated 'get debitors' heading, but it remains compact and easy to scan.

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 list tool with two optional parametersmates and an existing output schema, the description provides everything an agent needs: purpose, use case, alternative tool, pagination support, and API endpoint. No critical call context 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 both limit and offset already have clear descriptions and defaults. The description only says 'Supports limit and offset' without adding new semantic information, so it stays at the baseline.

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

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

The description clearly identifies the operation as retrieving debtors/customers ('Get all debitors', 'list customers') and names the specific resource it operates on. It also distinguishes the tool from creditors_list by explicitly contrasting customers vs suppliers.

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 use case ('resolve a customer name to the debtor id the receipt and posting tools expect') and an explicit alternative ('For suppliers you buy from, use creditors_list'). It also notes the API limitation around no delete endpoint, helping an agent understand scope.

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 indicate this is a write operation, but the description adds valuable behavioral context: it modifies data 'in place' and overwrites only the fields sent, with a caution to read first for partial changes. This goes beyond the annotations without contradicting them.

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

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

The description is compact and front-loaded with the write nature and core behavior first. Minor redundancy exists ('update debtor' appears in the heading, bold line, and prose sentence), but the overwrite warning and read-first hint earn their 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?

Given the 13 parameters, output schema, and annotations, the description covers the essential operational semantics: it is an update, it overwrites sent fields, it is for master data, and a read-first step is recommended. It does not discuss validation or response behavior, but the schema and annotations cover those details sufficiently.

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 every parameter. The description adds only high-level groupings ('address, bank details or customer number') that map loosely to parameters, but does not provide deeper meaning beyond what the schema contains.

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 action ('Update a debtor account') and a concrete resource, with explicit examples of what can be changed: address, bank details, or customer number. This clearly distinguishes it from sibling update tools like creditors_update or postingaccounts_update.

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 provides clear when-to-use guidance: changing existing debtor master data, and explicitly recommends reading the current record with debtors_list before a partial change. It does not explicitly mention when not to use it or alternatives like debtors_create, but the update-focused wording makes the intended scope reasonably clear.

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 mark readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description adds concrete behavioral context: creates data, not idempotent (a second call issues a second invoice with a new number), and v1 offers no endpoint to list/change/cancel. This goes beyond the annotation flags and gives practical operational details.

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 efficient: it opens with a generic write warning, then a bold 'create invoice' heading, and a concise paragraph covering purpose, alternatives, and caveats. It's slightly longer than necessary but each sentence adds value—no fluff. The key differentiators are 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?

For a complex tool with 32 parameters (9 required) and a rich output schema, the description covers purpose, usage guidance, behavioral caveats, and alternatives. The schema handles parameter details, so nothing critical is missing. The agent can decide when to invoke and what 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 description coverage is 100%, so the input schema already explains every parameter. The description does not add parameter-specific semantics beyond what the schema provides, though it does mention the 'type' (invoice/credit/offer) implicitly through 'final outgoing invoice'. Baseline 3 is appropriate since the schema carries the parameter documentation.

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 clearly states the tool creates invoices for a specified customer, and explicitly distinguishes it from siblings (invoices_create_draft, invoices_create_e_invoice) by noting when to use each. The verb 'create' and resource 'invoice' 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?

The description explicitly says when to use this tool (final outgoing invoice that is booked immediately) and when not to (for editable drafts or structured XML e-invoices), naming the alternative tools. It also warns about non-idempotency and lack of list/change/cancel endpoints, which informs usage decisions.

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 concrete behavioral details beyond the annotations: 'Not idempotent: calling twice may create duplicates,' 'A draft is not booked and carries no invoice number,' and 'Releasing happens in the web app.' These are nuances not captured by the annotations (readOnlyHint=false, idempotentHint=false, openWorldHint=true) and are valuable for agents.

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 well-structured with a clear front-loaded write warning, purpose statement, use-case, and endpoint. It is slightly verbose (the generic 'WRITE · creates data' prelude is not tool-specific), but every other sentence earns its place. Overall, it is concise enough for an agent to parse quickly.

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?

Given the high parameter complexity, an output schema, and a rich set of sibling tools, the description covers the essential context: the draft workflow, the non-idempotence, and the explicit alternative for final invoices. It does not explain return formats, but the output schema exists to cover that. The only minor gap is that it doesn't mention other invoice-related siblings like invoices_create_e_invoice, but that is not necessary for selecting this 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%, so the input schema already documents every parameter thoroughly. The description provides no additional parameter-level information, but per the rubric the baseline is 3 when the schema carries the burden. The description does not introduce ambiguity or omissions.

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 ('Add an invoice draft'), the resource ('for the specified customer'), and clearly distinguishes itself from the sibling tool invoices_create by explaining the difference (draft vs. final invoice). It also notes that drafts are not booked and have no invoice number, making the tool's purpose 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?

Explicitly describes when to use this tool: 'Use to prepare an invoice that a human should review and release' and contrasts it directly with the alternative: 'To issue a final invoice directly, use invoices_create.' Additionally, it states that v1 offers no listing/editing/release endpoints, informing the user of workflow limitations.

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 indicate readOnlyHint=false and idempotentHint=false, and the description adds meaningful behavioral context: 'Not idempotent: calling twice may create duplicates' and 'v1 offers no endpoint to list or cancel an e-invoice once created.' This tells the agent the write is non-reversible through the API, which is valuable beyond 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?

The description is compact and front-loaded with the write nature, definition, use case, alternative, and caveat. It is slightly redundant: 'Not idempotent' is repeated twice, but the rest is purposeful and well organized.

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 large 34-parameter tool with 16 required parameters, the schema carries most of the invocation burden, and the description supplies the missing selection context: when to choose e-invoice vs `invoices_create`, the no-list/no-cancel caveat, and the endpoint. It could mention `invoices_create_draft` as another sibling option, but that is not essential for correct use.

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 input schema has 100% schema description coverage, so the description does not need to repeat parameter details. The description only refers generically to 'the specified customer' and does not add parameter-level meaning beyond the schema, so a 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 states a specific action and resource: 'Add an e-invoice for the specified customer.' It also differentiates from the sibling tool `invoices_create` by explicitly saying that ordinary PDF invoices should use that tool instead, so an agent can immediately distinguish the two.

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

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

It gives an explicit when-to-use condition: when the recipient requires a structured electronic invoice, with a concrete example (German public-sector customer expecting XRechnung). It also names the alternative (`invoices_create` for ordinary PDF invoices) and warns about the non-reversibility limitation, which helps prevent misuse.

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 provide readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description adds context beyond these: 'v1 offers no delete endpoint, so a posting account created here can only be updated afterwards.' This clarifies the consequence of non-idempotency and the tool's limitations, adding value beyond 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?

The description is well-structured with a bolded heading and front-loaded warning about writes and idempotency. While slightly long, every sentence adds value (purpose, usage, constraint, endpoint). It is efficient and not wasteful.

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

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

The tool has an output schema covering return values, and the description provides the endpoint, usage guidance, and important constraints (non-idempotent, no delete). It also distinguishes from related tools. For a simple create operation with three well-documented parameters, nothing essential 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% with each parameter having a meaningful description. The tool description does not add extra semantic detail beyond the schema, so the baseline of 3 is appropriate. It doesn't need to compensate because the schema fully documents the 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 clearly states 'Create a postingaccount' and specifies its purpose: 'add an account number to the chart of accounts that the standard chart does not cover.' It distinguishes from accounts_create, which is for bank or cash accounts, making the tool's unique function unmistakable.

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

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

Explicitly states when to use the tool ('Use to add an account number to the chart of accounts that the standard chart does not cover') and when not ('To register a bank or cash account, use accounts_create'). Also mentions the lack of delete endpoint, guiding usage expectations.

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, idempotent, and non-destructive, and the description reinforces READ-ONLY and adds context beyond that: pagination support, the need to page until all rows are covered, and the absence of a delete endpoint. No contradiction with annotations.

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

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

The description is informative and well-structured, with the READ-ONLY notice front-loaded. Though it includes some repetition of the tool name, every major section earns its place and it is not bloated.

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?

Given the output schema exists and all parameters are documented in the schema, the description provides enough context for correct invocation: purpose, use case, alternative tool, pagination behavior, and endpoint.

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

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

Schema coverage is 100%, so the schema fully documents each parameter. The description adds practical meaning around `limit` and `offset` by explaining the large size of a chart and advising to page until `rows` is covered.

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

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

The description uses a specific verb and resource: 'Get all postingaccounts' and clarifies this is the chart of accounts. It explicitly distinguishes itself from `accounts_list` for bank accounts, so an agent can tell siblings apart.

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 use case: finding a posting account number before booking office supplies. It also names when to use a different tool (`accounts_list`) and explains pagination strategy because the full chart can run to several hundred rows.

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 description adds the critical behavioral detail that it 'overwrites the fields you send,' which goes beyond what annotations state. It also advises reading the record first, indicating the overwrite semantics. This is consistent with readOnlyHint: false and doesn't contradict any annotation. It doesn't mention idempotency, but that's already covered by idempotentHint: true.

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

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

The description is compact and front-loads key information like the overwrite behavior and the advice to read the record first. The structure is clear with a heading and bullet. However, it starts with an emoji and 'WRITE' which adds visual noise and is unnecessary, slightly detracting from conciseness.

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 update tool with two parameters and an output schema, the description covers purpose, usage, and the crucial overwrite behavior. It doesn't discuss error handling or non-existent records, but that's not essential for this simple operation. The guidance to read the record first is valuable. Overall, it's complete for the tool's 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 input schema already documents both parameters with clear descriptions (name = new name, postingaccount_number = number to update). The description mentions 'rename a posting account or change its properties' but doesn't add parameter-specific detail beyond what the schema provides. Since schema coverage is 100%, the description adds little value here.

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

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

The description clearly states the tool updates an existing postingaccount, with specific use cases (rename or change properties). It distinguishes from the list tool by referencing postingaccounts_list for reading, and the verb 'update' is precise. While it doesn't explicitly contrast with postingaccounts_create, the name and context make the purpose 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?

It provides clear guidance on when to use: for renaming or changing properties. It also advises reading the current record first for partial changes, which is a practical tip. It doesn't explicitly name alternatives like postingaccounts_create, but the context implies that creation would be a different tool, so it's effective.

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 description discloses that the operation links/unlinks records, is reversible, and is a write operation (🟡 WRITE). It also notes the endpoint. Annotations already indicate readOnlyHint=false and destructiveHint=false, and the description adds the reversible and link/unlink semantics, which go beyond the annotations. Minor gap: no detail on side effects or idempotency, but the reversible note is valuable.

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

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

The description is compact and front-loaded with the write/reversible warning, then the purpose, then the alternative. The endpoint line is slightly redundant with the tool name but adds useful routing info. No wasted sentences, though the emoji and repeated title could 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 simple 2-parameter link operation with full schema coverage and an output schema, the description covers the core use case, the alternative, and the reversibility. It doesn't explain what the response contains, but the output schema exists, so that burden is not on the description. The only missing context is any prerequisite (e.g., the posting must be free), which is implied by the name but not explicitly stated.

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 both parameters. The description does not add extra meaning about the parameters beyond their names and schema descriptions. Baseline 3 is appropriate because the schema carries the burden.

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 clearly states the verb 'assign' and the resource 'receipt to a free posting', and explains the purpose: attaching a receipt to a free posting that was booked without one. It also distinguishes itself from the sibling transactions_assign_receipts, which is a different target resource.

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 explicitly says when to use this tool: to attach a receipt to a free posting booked without a supporting document. It also names the alternative tool (transactions_assign_receipts) and the condition for choosing it (linking to a bank transaction instead). This is clear 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 description goes well beyond the destructiveHint annotation by explaining what happens to fixed vs non-fixed postings, the two-visible-entries consequence of reversals, and the requirement to confirm with the user. The note that 'receipt deletes are restorable; cost-location deletes are not' adds context but is somewhat disconnected from a postings-cancel operation and could cause confusion.

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 front-loads the destructive warning and confirmation requirement, which is good. However, the fixed/unfixed deletion vs reversal behavior is explained multiple times in different paragraphs, and the endpoint line plus generic delete preamble add redundancy that could be trimmed without losing safety-critical 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 single-parameter tool with an output schema and safety annotations, the description covers purpose, side effects, user confirmation, and alternatives to sibling tools. It stops short of top marks because the restorability sentence feels tangential and idempotency is only implied by annotations, not clarified in the description.

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 schema already provides 100% coverage for the single parameter, describing it as 'The id_by_customer of the posting.' The description does not add further semantic detail about where this identifier comes from or how it resolves to a posting, 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?

Identifies the exact operation ('Cancel a specified posting') and the resource it acts on phosphorylate. It also distinguishes itself from the postings_unconfirm_* sibling tools by explaining the deletion vs reversal semantics, so an agent can disambiguate purely from the description.

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

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

Explicitly states when to use the tool ('Use to take a booking out of the books entirely') and contrasts it with alternative unconfirm tools, including a concrete preference rule ('Prefer unconfirming when the goal is to edit and rebook'). It also instructs the agent to confirm with the user before calling, which is strong usage guidance.

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

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

Annotations already indicate readOnlyHint=false and idempotentHint=false, and the description repeats the 'Not idempotent' trait. However, it adds valuable context beyond annotations: reversibility with `postings_unconfirm_for_receipt` while not fixed, the foreign currency prerequisite, and the 'WRITE' marker. No contradiction with annotations.

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

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

The description is lengthy but well-organized with headers, bolded key points, and a clear logical flow. Every sentence adds relevant information (prerequisites, array semantics, reversal). It is not overly verbose given the complexity of the operation.

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

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

The description covers all necessary steps: prerequisites (activation), special case (foreign currency), array structure, distinction from sibling tool, and reversal method. It does not explain return values, but an output schema exists, so that is not required. For a complex mutation tool, this is highly complete.

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

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

The schema itself provides descriptions for each parameter, so coverage is high. The description adds crucial structural meaning beyond the schema: the positional relationship across arrays (index 0 of each describes the same split line) and the one-or-many array convention. This clarifies usage not evident from individual parameter 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?

The description clearly states the tool's purpose: 'Add postings for a specified receipt' and 'book one or more receipts that already exist', distinguishing it from `postings_create_free` which is for journal entries without receipts. It also specifies the resource (receipts) and the action (adding postings), making it 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?

Explicitly explains when to use this tool (for existing receipts) and when not (use `postings_create_free` for journal entries without receipts). It also lists prerequisites (creditor/debtor posting activated) and a special condition (foreign currency requires fetching receipt first). No alternative is left vague.

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=false, idempotentHint=false, destructiveHint=false. The description adds valuable behavioral context: '🟡 WRITE · creates data', 'Not idempotent: calling twice may create duplicates', and 'Reversible with `postings_unconfirm_for_transaction` while the posting is not fixed.' It also mentions the endpoint. This goes beyond the annotations by explaining the non-idempotency consequence and the reversal path. It doesn't detail error conditions or side effects beyond duplicates, but the annotations plus description cover the key behavioral traits well.

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 well-structured with a clear warning header, a concise summary, usage guidance, and an endpoint reference. It is somewhat long but every section earns its place: the warning about non-idempotency, the alternative tool, the batch semantics, and the positional array constraint. The emoji and bold formatting help front-load the critical write/non-idempotent nature. It could be slightly tighter, but it's appropriately sized for a complex 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?

Given the tool's complexity (nested arrays, positional constraints, multiple VAT options), the description covers the essential context: what it does, when to use it, the alternative, non-idempotency, reversibility, and batch behavior. The output schema exists, so return values don't need explanation. The only minor gap is that it doesn't explicitly state prerequisites (e.g., transaction must exist), but the schema's required fields and the reference to `transaction_id_by_customer` imply this. Overall, it's complete enough for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds meaningful context about the overall structure: 'The per-transaction arrays are positional and must all have the same length' and 'A single record is an array of one.' It also clarifies the batch nature of the `transactions` parameter. The schema itself is rich with per-field descriptions, so the description doesn't need to repeat them. The added structural guidance about positional arrays is valuable 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 clearly states the tool's purpose: 'Add postings for a specified transaction' and 'book one or more bank transactions, splitting each across posting accounts, VAT rates and cost centres.' It distinguishes itself from the sibling `postings_create_free` by explicitly noting that this tool is for transactions with a bank transaction behind them, while `postings_create_free` is for journal entries without one. The verb 'add' and resource 'postings for a transaction' are specific and unambiguous.

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

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

The description provides explicit usage guidance: it says to use this tool to book bank transactions, and explicitly names the alternative `postings_create_free` for journal entries without a bank transaction. It also explains the batch behavior ('Takes one or many: pass an array of transactions in `transactions`. A single record is an array of one.') and the positional array requirement. This is 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?

Annotations already declare idempotentHint=false, and the description reinforces this: 'Not idempotent: calling twice may create duplicates.' and 'Not idempotent, so a repeated call books the amount twice.' It adds context about attaching a receipt later via `postings_assign_receipt_to_free`, which is useful lifecycle information. No contradiction with annotations. The description provides practical behavioral implications beyond what annotations state.

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 well-structured with a clear warning header, then a purpose statement, usage guidance, and batch/non-idempotency notes. It is somewhat long but every sentence adds useful information—no filler. The most critical warnings (write, non-idempotent) are front-loaded, which is good for agent attention.

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

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

The tool has an output schema, so return format is defined. The description covers what the tool does, when to use it, batch behavior, non-idempotency, and related tools for attaching receipts. It does not mention potential errors or authentication, but those are not expected given the output schema and annotations. Overall it is complete enough for an agent to call it correctly.

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

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

Schema coverage is 100% with each parameter described in the schema, so the description doesn't need to restate them. It does add meaning by explaining the concept of a 'free' posting (you name both sides yourself via `postingaccount_debit` and `postingaccount_credit`) and clarifies that the `free_postings` parameter is an array even for a single posting. This adds semantic value beyond the schema's basic field definitions.

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 clearly states that this tool adds free postings (debit/credit pairs not tied to a receipt or bank transaction) and explicitly distinguishes it from `postings_create_for_receipt` and `postings_create_for_transaction`. The verb 'add' plus the resource 'free posting' is specific, and it disambiguates against sibling tools.

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

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

The description gives explicit guidance on when to use it: 'Use to book a debit/credit pair that is not tied to an existing receipt or bank transaction, such as a manual accrual or a correction.' It also states alternatives: 'If the booking documents a receipt, use postings_create_for_receipt. If it settles a bank transaction, use postings_create_for_transaction.' This fully covers when and when-not, and names the alternative tools.

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

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

Annotations already cover readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the description doesn't need to repeat safety traits. It adds the critical limit of 1000 postings per request, which is a behavioral constraint beyond annotations. It also mentions the response includes row count and an array, providing some transparency, though output schema likely covers details. This is good value beyond structured fields.

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

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

The description is well-structured, starting with a clear READ-ONLY flag, then a purpose statement, key limits, and usage advice. It is concise without excess, though it redundantly repeats 'get postings' in the description. Overall, it is efficiently organized and front-loaded with the most important 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?

Given 11 parameters with full schema coverage, an output schema, and safety annotations, the description is largely complete. It covers the core purpose, the 1000-row limit, and practical usage tips. It doesn't explain every parameter or edge case, but the schema and output schema fill those gaps. The description adequately complements the structured data for an agent to use 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%, so all parameters are already documented in detail, including formats and defaults. The description's mention of 'Supports `limit` and `offset`' is redundant with the schema, and the advice about bounded date ranges is more usage guidance than parameter semantics. It adds minimal new meaning beyond the schema, so 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 clearly states the tool's action and resource: 'Get postings for a specified customer account' and 'read the booking journal'. It specifies a verb (get), a resource (postings), and a scope (customer account), making it distinct from sibling tools like postings_cancel or postings_create_*. The READ-ONLY label further disambiguates it from write operations.

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 'Use to read the booking journal, filtered by date range or posting account', providing clear context for when to invoke it. It also gives practical advice to 'Ask for a bounded date range rather than paging through a whole financial year', which is helpful guidance. However, it does not explicitly name alternatives or exclusions, though the sibling list makes the read/write distinction obvious.

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 description discloses that this is a state-reverting WRITE, explains it is reversible, keeps the posting, and clearly says it only clears confirmation. It goes beyond the annotations by describing the side effect and precondition, though the 'restore a deleted receipt' phrase adds ambiguity.

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 longer than necessary and repeats the fixed-not-fixed condition twice, but it front-loads the most important behavioral context up front. Most sentences add useful information such as reversibility, use case, alternative, and endpoint.

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 tool with a full input schema and an output schema, the description provides the essential behavior: what is changed, when it is allowed, and what it does not do. It could clarify behavior when the posting is already unconfirmed or fixed, but nothing critical 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 the input schema already fully describes `receipt_id_by_customer`. The description adds no extra semantic detail beyond referring to 'the receipt', so the schema carries the burden as expected at high schema coverage.

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

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

The description clearly identifies the action: unconfirm receipt postings by receipt, and distinguishes itself from `postings_cancel` for removing a posting. The core resource and verb are unmistakable despite the slightly confusing 'restore a deleted receipt' phrase.

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 use case: send a receipt posting back to unconfirmed state for correction. It also states the precondition that postings must not be fixed and points to `postings_cancel` as the alternative for removal. It does not explicitly contrast with `postings_unconfirm_for_transaction` or `postings_unconfirm_free`, but enough guidance is present.

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

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

Beyond the annotations, the description adds useful behavioral context: the operation is reversible, it only clears confirmation rather than deleting the posting, and it only works while the posting is not fixed. The 'restore a deleted receipt' parenthetical is an inaccurate behavioral claim for this specific tool, but it does not contradict 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?

The description repeats the fixed-posting condition twice ('This will only work if the postings are not fixed' and 'Only works while the posting is not fixed'), and overlaps 'Remove postings...' with 'Use to send a transaction posting back...' The opening line also adds padded, partly off-topic content.

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 one fully documented parameter, an output schema, and annotations covering the write/idempotent/non-destructive profile, the description provides the essential invocation context: what it does, when it works, and which alternative to use for deletion. The out-of-scope receipt-restoration mention is the main thing keeping it from being fully clean.

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 input schema has 100% description coverage for the only parameter, transaction_id_by_customer, which is already documented as 'The id_by_customer of the transaction.' The description merely refers generically to a 'specified transaction' and adds no new parameter-level 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?

The core action is clear: 'Remove postings for a specified transaction by unconfirming them' and it explicitly distinguishes itself from deletion with 'To remove the posting itself, use postings_cancel.' However, the opening parenthetical 'restore a deleted receipt' references behavior that seems outside this transaction-posting tool's scope, slightly muddying the 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?

The description says to use this tool when a transaction posting needs to be returned to the unconfirmed state for correction, and it gives the precondition that the postings must not be fixed. It also explicitly routes removal of the posting itself to postings_cancel, providing a clear alternative.

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 description goes beyond the annotations by explaining that this is a reversible state revert, that it keeps the posting, and that it only clears confirmation. It also discloses the fixed-posting restriction. The mention of 'restore a deleted receipt' is ambiguous and not consistently integrated with the rest of the behavior description, so it slightly weakens an otherwise transparent explanation.

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 front-loaded with the WRITE indicator and core effect, which is good)Skip. However, it is repetitive: the fixed-posting constraint is stated twice ('This will only work if the posting is not fixed' and 'Only works while the posting is not fixed'), and the broad 'restore a deleted receipt' line adds ambiguity. It could be tightened without losing 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 single-parameter tool with an output schema, the description is largely complete: it explains the effect, reversibility, the fixed-posting limitation, and the alternative for deletion. It does not define what 'fixed' means, and the confusing 'restore a deleted receipt' phrase is left unresolved, but overall an agent has enough context 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?

There is only one parameter, posting_id_by_customer, and the schema already describes it as 'The id_by_customer of the free posting.' The description refers to 'a specified free posting' but adds no new parameter-level detail beyond the schema, so the baseline 3 applies due to full schema description coverage.

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

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

The core purpose is clear: 'unconfirm free posting' and 'Remove a specified free posting by unconfirming it.' It also distinguishes itself from postings_cancel by noting that this tool keeps the posting while cancellation removes it. However, the opening line mentions 'restore a deleted receipt,' which is not clearly part of this tool's specific action and could mislead an agent about its scope.

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 explicitly states when to use it: to send a free posting back to the unconfirmed state so it can be corrected. It also gives a clear when-not condition: it only works if the posting is not fixed. It names a concrete alternative, postings_cancel, for when the posting itself should be removed.

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 annotations that already indicate non-idempotency, the description adds crucial behavioral details: repeated calls create duplicates, and the response reports per-item success so partial failures leave successful entries intact. This is value-added context not present in the structured annotations.

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

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

The description is well structured with a clear warning prefix, a dedicated 'add a receipt' section, and line breaks for readability. However, it repeats the non-idempotency note twice, which is slightly redundant given the annotation already flags it.

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?

Given the tool's complexity (write operation, one array parameter, output schema present), the description covers all necessary aspects: purpose, usage conditions, alternative tool, behavioral caveats, and input format. No critical information is missing for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents the receipts parameter thoroughly. The description merely restates the array input and points to the /receipts/add endpoint for field details, adding no new semantic 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?

The description states a specific verb ('add') and resource ('receipt'), and clearly differentiates from the sibling receipts_upload by emphasizing 'without a file'. It also lists the broader effect ('creates new records') without ambiguity.

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 instructs when to use this tool ('Use this endpoint, to add a receipt without a file!') and when not, naming the alternative 'receipts_upload' for file-based receipts. It also clarifies the array input format, leaving no guesswork.

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 and readOnlyHint, but the description adds important context: it states the operation is destructive and requires user confirmation, clarifies that receipt deletes are restorable (unlike cost-location deletes), and describes the soft-delete nature ('mark as deleted'). It also mentions the behavior for cancelling postings, though that is tangential. This goes beyond the annotations and provides useful behavioral insight.

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

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

The description is longer than necessary and includes information about cost-location deletes and cancelling postings that is not directly relevant to this specific tool. The opening warning block repeats the destructive nature, and the text could be streamlined to focus on receipts_delete. However, it is front-loaded with the destructive warning and the core action is stated early.

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?

Given that there are no parameters and an output schema exists, the description covers the essential aspects: the action, how to get the identifier, when to use it, and restorability. It also includes the important user-confirmation requirement. It doesn't mention error cases or permissions, but for a simple delete operation with no params, this is reasonably complete.

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

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

There are no parameters in the input schema (0 properties). The description explains how to obtain the id_by_customer, which is essential for the call, even though it is not a request body parameter (likely a path parameter). Since there are no params, the baseline is 4, and the description adds value by explaining how to get the required identifier.

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 clearly states the action: 'Mark a receipt as deleted for a specified customer account by id_by_customer.' It identifies the specific resource (receipt) and the key identifier (id_by_customer). It also distinguishes from restore by mentioning recoverability, and notes it is for removing a mistakenly filed receipt, so the 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?

The description provides clear usage guidance: it says to use this to remove a receipt filed by mistake, mentions the prerequisite of obtaining id_by_customer via '/receipts/get method', and instructs to confirm with the user before calling. It also contrasts with receipts_restore for recovery. However, it doesn't explicitly state when not to use it or compare with other deletion tools like cost_locations_delete, leaving some room for ambiguity.

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, idempotentHint, and destructiveHint=false, and the description's READ-ONLY banner matches them. Beyond the annotations, it adds the per-customer counter semantics, the endpoint, and the fact that the response contains an array. No contradiction with annotations.

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

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

The text is reasonably compact and front-loads the read-only and single-receipt behavior, but it restates the same idea in the title-like line and in 'Use to fetch a single receipt...' after already saying it. A couple of redundant sentences could be merged without losing content.

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-optional-parameter tool with an output schema and strong annotations, the description is nearly complete: it gives the endpoint, the id semantics, the file-return behavior via schema, and how to retrieve the id. The only minor gap is not explicitly stating how id_by_customer is passed in the request, though the endpoint path implies it.

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

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

The only schema parameter, get_file, is fully described in the schema with enum-type behavior for e_invoice_type values, so the description need not repeat it. It adds useful context about id_by_customer as a UI counter, but that is path/id context rather than schema parameter detail. Baseline 3 applies because schema coverage is 100%.

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

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

The description uses specific verb 'get' and resource 'single receipt for a specified customer account by id_by_customer', and explicitly distinguishes itself from receipts_list by saying it fetches a single receipt. The endpoint line reinforces exactly what operation is invoked. This is enough for an agent to know what the tool does.

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 'Use to fetch a single receipt whose id you already have' and 'To search or page through receipts, use receipts_list.' It also tells the agent how to obtain id_by_customer first via /receipts/get. That is strong when-to-use vs alternative 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 and destructiveHint=false, so the description reinforces but doesn't contradict. It adds useful behavioral context: the response includes row count and array, the requirement of list_direction, and the POST endpoint. No contradictions found.

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

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

The description is front-loaded with a read-only note, then explains the purpose and usage. It's reasonably concise, though it includes some redundancy (repeating 'get receipts' and the endpoint). Still, every sentence contributes 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 tool with 13 parameters and nested objects, the description covers the main use cases and points to the correct sibling. Since an output schema exists, the description doesn't need to detail return values. It's adequately complete.

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

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

Schema coverage is 100%, so the schema documents all parameters thoroughly. The description adds a little extra by noting list_direction is required and that limit/offset are supported, but it doesn't go beyond the schema in any substantial way. 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 states a specific verb ('get receipts') and resource, and clarifies it fetches receipt data for a customer account. It explicitly differentiates from receipts_get_by_id, so an agent can tell them apart.

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

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

It clearly states when to use this tool (search by direction, date range, or payment status) and explicitly names the alternative (receipts_get_by_id) for fetching a single known receipt. This provides strong 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, idempotentHint=true, and destructiveHint=false, so the description's 'READ-ONLY: Makes no changes' statement mostly restates structured metadata. It adds some context around the use case and directionality, but does not disclose additional behavioral traits like pagination, confirmation behavior, or error conditions beyond what annotations and schema already convey.

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

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

The description is compact and mostly front-loaded with the read-only indicator and the core purpose. Some repetition exists between the title, the bolded heading, and the first sentence, but each paragraph adds a distinct element: safety, primary function, usage example, and alternative sibling. The endpoint line is a small bonus.

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?

Given the tool has only 2 parameters, full schema coverage, a rich output schema, and strong annotations, the description is complete enough for an agent to select and invoke it correctly. It covers the use case, the source of a required parameter, the opposite-direction sibling, and confirms safety.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds practical value by explaining that `id_by_customer` can be obtained from `/receipts/get`, which is useful for locating the required parameter value. It also frames `receipt_id_by_customer` as the key identifier, reinforcing the schema without being redundant.

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

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

The description uses a specific verb and resource: 'get all transactions assigned to a specific receipt' for a given customer receipt. It clearly distinguishes itself from the sibling tool `transactions_list_assigned_receipts` by naming it as the opposite direction. The scope is precise and an agent can distinguish this tool from sibling 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?

The description explicitly tells when to use it: to see which bank transactions are linked to a given receipt, e.g., checking whether an invoice has been matched to a payment. It also names the alternative for the opposite direction (`transactions_list_assigned_receipts`), and explains how to obtain `id_by_customer` via `/receipts/get method` first, which is actionable 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=false, destructiveHint=false, and idempotentHint=true. The description adds that this is a WRITE operation that reverts prior state and is reversible, which is useful behavioral context beyond the annotations. It does not describe side effects on related transactions or repeated restores.

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 front-loaded but repetitive, restating the restore concept multiple times. The opening parenthetical mentioning 'un-confirm a posting' adds noise because it is not the focus of this tool and could confuse an agent selecting between siblings.

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

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

The description is reasonably complete for a simple restore operation: it names the target resource, the trigger, the prerequisite lookup, and the endpoint. It is weaker operationally because the key identifier `id_by_customer` is referenced in prose but absent from the structured input schema, leaving ambiguity about how the tool call should be constructed.

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 input-schema parameters, the baseline is 4. The description contributes meaningful parameter guidance by identifying `id_by_customer` as the restore key and explaining how to obtain it. The main gap is that the input schema does not actually expose `id_by_customer`, so the passing mechanism is only implied by the endpoint.

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 clearly states the operation: restore a marked-as-deleted receipt for a specific customer account using `id_by_customer`. It also distinguishes itself from the sibling `receipts_delete` by saying it brings back a receipt deleted with that tool.

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

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

It gives an explicit use case: use when a receipt was deleted via `receipts_delete`. It also provides the prerequisite of obtaining `id_by_customer` from the `/receipts/get` method. However, it does not explicitly say when not to use it or point to the correct sibling for the un-confirm-posting case mentioned in the first line.

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 description discloses non-idempotency ('calling twice may create duplicates') and rate limiting ('max 10 requests per minute'), which are behavioral traits not fully covered by annotations alone. It also explains the processing via BuchhaltungsButler and the response filename, adding valuable context beyond annotations.

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

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

The description contains redundancy: 'Not idempotent' appears twice and 'Rate limited to 10 requests per minute' also appears twice. The inclusion of the 'Endpoint: POST /receipts/upload' line is unnecessary as it is not behaviorally relevant. While structured, the repetition prevents a higher score.

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 tool with 15 parameters and an output schema, the description covers the primary purpose, alternatives, rate limit, non-idempotency, and the response format (filename). The schema handles parameter details, so the description is sufficiently complete for an agent to decide when and how to invoke the tool. Minor gaps like e-invoice behavior are covered in the schema, so a 4 is justified.

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 parameters are already documented in the schema. The description does not add any parameter-specific semantics beyond what the schema provides; it only offers general notes about rate limiting and non-idempotency. Thus, 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 explicitly states 'Upload a receipt into the specified customer account' and clearly identifies the resource and action. It also differentiates from the sibling tool receipts_create by noting 'To record a receipt without a file, use receipts_create', making the purpose unambiguous.

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

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

The description explicitly states when to use it ('Use to send the actual receipt file') and when not to ('To record a receipt without a file, use receipts_create'). It also mentions the rate limit and non-idempotency, giving clear context for usage decisions.

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