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's READ-ONLY statement agrees with them. Beyond the annotations, it adds meaningful behavioral context: 'v1 offers no update or delete endpoint for accounts. An account created here can only be listed afterwards.' It also reveals the non-obvious endpoint POST /accounts/get. This adds value without contradicting structured metadata.

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: the READ-ONLY warning, purpose, and scope appear first, with the alternative and limitation following. The repeated header 'get all the accounts' is mildly redundant with the title, but the overall length is appropriate and every major section adds useful context.

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

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

For a zero-parameter list tool with an output schema, the description covers all needed operational context: what the tool returns conceptually, why an agent would call it, which sibling to use instead, and the API's limitation of no update/delete. There are no critical gaps that would prevent 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?

The tool has zero parameters and schema description coverage is 100%, so the baseline is 4. The description does not introduce any parameter expectations or ambiguity; it simply describes an unrestricted list operation. There is no parameter-related information missing.

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: 'Use to list the bank, cash and credit-card accounts that transactions can be booked against'. It also actively differentiates from the chart of accounts by stating 'Not the chart of accounts' and naming `postingaccounts_list` as the tool for posting account numbers, so an agent can distinguish it from siblings.

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

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

It explicitly gives the use case: resolve an account name to the numeric `account` id expected by transaction tools. It also provides an explicit alternative and exclusion: 'Not the chart of accounts. For posting account numbers such as 1200 or 4400, use `postingaccounts_list`.' This is concrete when-to-use and when-not-to-use guidance.

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

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

The 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 mark readOnly, idempotent, and non-destructive; the description reinforces this in plain language and adds non-obvious behavior: response rows may not be a grand total, continue paging until empty, and no delete endpoint exists for creditors in v1. No annotation 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?

Mostly tight and front-loaded with read-only status and main purpose. There is slight redundancy between the 'get creditors' heading and 'Get all creditors' sentence, but the extra context (debtors alternative, paging, delete limitation) justifies the length.

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

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

For a simple list tool, the description covers purpose, alternative, pagination behavior, and API lifecycle constraints. Since an output schema exists, return-value detail is not needed.

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 describes limit/offset with defaults, so baseline is 3. The description adds value by explaining these are paging controls and warning not to treat a single response as complete, which is beyond raw 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 uses a specific verb ('list'/'get') with resource 'creditors' and clarifies they are suppliers. It explicitly differentiates from debtors_list, so an agent can select this over the most similar sibling without inspecting schemas.

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

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

It states a concrete use case (resolving a supplier name to creditor id for receipt and posting tools) and directs customers to debtors_list. It also gives paging loop guidance, which is when-to-keep-calling context.

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 readOnly, idempotent, non-destructive. Description reinforces this with 'READ-ONLY' and adds the endpoint, limit/offset support, and the note that v1 has no delete endpoint for debtors, providing lifecycle 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 is front-loaded with safety and purpose, then usage guidance and limitations. It is efficient, though it repeats 'Get all debitors' in a heading which is minor.

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, and with full schema coverage, output schema, and safety annotations, the description covers the use case, alternatives, and API version limitations. 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 already fully documents limit and offset with defaults. Description only mentions they are supported without adding new semantics, so it adds no value beyond schema.

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

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

States a clear verb 'Get all debitors' and resource, and explicitly differentiates from creditors_list by referencing suppliers. Also explains the practical use case of resolving customer names to debtor ids.

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 says when to use: to list customers, and when not: for suppliers use creditors_list. Provides an example scenario, leaving no 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 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 cover readOnly and non-destructive hints, but the description adds crucial behavioral details: supports limit/offset, the full SKR chart is large, 'rows' is not the grand total, and to continue paging or filter. These go beyond annotations and are essential for correct usage.

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-loads the purpose, but includes some tangential notes like 'v1 offers no delete endpoint for posting accounts' that, while informative, are not needed to invoke this tool. Slightly longer than necessary but each part has 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?

The description covers purpose, usage, pagination behavior, and sibling differentiation. With an output schema present and annotations covering safety, nothing essential is missing. An agent has all needed information 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 descriptions for all 7 parameters, so the baseline is 3. The description adds value by explaining limit/offset in context (large dataset, pagination advice) and suggests filtering as an alternative, enhancing understanding of those parameters, though it doesn't elaborate on the exclude_* flags.

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 fetches posting accounts (chart of accounts) with 'Get all postingaccounts' and explains its use case (finding posting account numbers). It explicitly differentiates from accounts_list by stating 'Not bank accounts', so an agent can distinguish it from siblings without opening schemas.

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

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

The description gives explicit when-to-use context ('Use to list the chart of accounts, for example to find the posting account number for office supplies before booking') and when-not-to-use by directing to accounts_list for bank accounts. It also mentions pagination and filtering as alternatives, leaving no ambiguity about selection.

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

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

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?

The description matches and extends annotations: it confirms this is a write operation, explicitly warns that calling twice may create duplicates (consistent with idempotentHint=false), and adds reversibility details via postings_unconfirm_for_receipt while the posting is not fixed. This goes well beyond the annotation 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 with warnings, usage guidance, alternatives, and a clear endpoint. It is longer than average, and 'Not idempotent' is repeated, but the information density is high and each section serves a distinct 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?

For a write tool that books complex multi-line postings, the description covers the key operating constraints: activation prerequisite, foreign-currency handling, array positional semantics, duplicate risk, reversibility, and the free-posting alternative. The output schema exists, so return-value documentation is not required.

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 already 100%, but the description adds crucial usage semantics: receipts can be a single-element array or multiple receipts, and the inner arrays are positional and must have the same length. These details are not obvious from the schema alone and help the agent construct valid input.

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 ('Add postings for a specified receipt') and the resource ('receipts'), and clarifies the actual use case: booking one or more existing receipts split across posting accounts, VAT rates and cost centres. It also distinguishes itself from postings_create_free, making its 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 explains when to use this tool vs postings_create_free, and gives prerequisites: receipt postings are only available if creditor or debtor posting is activated. It also warns about the foreign-currency prerequisite, so an agent knows what must be checked before calling.

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 the operation as write and non-idempotent, but the description adds valuable specifics: calling twice may create duplicates, the action is reversible with `postings_unconfirm_for_transaction` while the posting is not fixed, and the API accepts one or many transactions. This goes beyond structured hints and helps the agent anticipate side effects. 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 front-loaded with the write/non-idempotency warning and the action statement, then covers routing, batching shape, positional constraints, reversibility, and endpoint. It is slightly redundant because 'Not idempotent' appears twice, but nearly every sentence adds a distinct fact.

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 batch create endpoint, the description covers purpose, alternative tool, batching shape, positional-array invariant, reversibility, and endpoint. Field-level validation and details are already present in the schema and output schema, so nothing essential 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?

Schema coverage is 100%, so the schema fully documents the `transactions` array and its nested fields. The description adds meaning beyond the schema: a single record is an array of one, per-transaction arrays are positional and must all have the same length, and the purpose is splitting across accounts, VAT rates, and cost centres. That is useful added usage semantics.

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

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

States a specific verb and resource: 'Add postings for a specified transaction' and 'book one or more bank transactions, splitting each across posting accounts, VAT rates and cost centres.' It also explicitly distinguishes itself from `postings_create_free` for journal entries without a bank transaction, so an agent can tell it apart 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?

Gives clear when-to-use context: booking bank transactions and splitting them across posting accounts, VAT rates, and cost centres. It names `postings_create_free` as the alternative when there is no bank transaction. It does not mention every possible sibling such as `postings_create_for_receipt`, but the primary routing decision is covered.

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 declare read-only/idempotent/non-destructive, and the description adds important operational behavior beyond that: the 1000-postings request limit, the response shape (number of returned rows plus an array of postings), support for limit/offset, and guidance to prefer bounded date ranges over pagination. 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?

Well-structured with read-only status, function, limit, use case, and pagination advice leading into the endpoint. Minor redundancy exists in repeating 'get postings' under the title and restating read-only facts that annotations already provide, but each sentence otherwise contributes usable 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?

Complete for a complex 11-parameter tool: annotations cover safety/idempotence, schema covers all parameter details, output schema covers return values, and the description supplies rate-limit, response-structure, and pagination strategy context. No critical calling information 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?

Although the input schema covers all 11 parameters at 100%, the description adds semantic value by tying filters to use cases ('filtered by date range or posting account') and explaining the intended interaction between limit/offset and date-range bounds. This goes beyond the schema's per-parameter descriptions without replacing them.

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 operation ('Get postings' / 'read the booking journal') and resource, and clearly frames itself as a read operation ('🟢 READ-ONLY: Fetches data. Makes no changes'), separating it from sibling postings tools like postings_create_free and postings_cancel. The mention of filtered postings resolves what is being listed.

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 says 'Use to read the booking journal, filtered by date range or posting account' and gives selection advice about requesting a bounded date range instead of paging through a whole financial year. It does not enumerate exclusions or name alternative tools, but the read-only framing plus the postings-specific verb makes the intended use 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 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. The description reinforces this with 'READ-ONLY' and 'Makes no changes to the accounting records.' It adds valuable behavioral context beyond annotations: the ID is a per-customer counter (not global) and the response includes an array of receipt data. No contradictions exist, and the added context is meaningful, so a 4 is appropriate.

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

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

The description is well-structured and front-loaded with the safety note. Each sentence has a purpose: safety, title clarification, description, usage guidance, alternative, and ID semantics. It's not overly verbose, though the title repetition and endpoint line could be trimmed. Overall, it is efficient and readable.

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 presence of a rich input schema (100% coverage), clear annotations, and an output schema, the description covers the essential context: what it does, when to use it, what the ID means, and how to obtain it. It doesn't mention error scenarios or edge cases, but these are minor for a simple lookup tool. The description effectively complements the structured metadata.

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 descriptions for both parameters (100% coverage). The description supplements this by defining `id_by_customer` as a per-customer counter shown in the UI, which is not explicitly stated in the schema. This adds semantic value beyond the schema's basic description, so a 4 is warranted.

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 function: 'Get a single receipt for a specified customer account by id_by_customer.' It explicitly distinguishes from the list tool by noting that searches/paging use `receipts_list`, and it clarifies that the ID is a per-customer counter, not a global database ID. The purpose is unambiguous and well-differentiated from siblings.

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

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

The description gives explicit usage direction: 'Use to fetch a single receipt whose id you already have' and directly contrasts with searching/paging via `receipts_list`. It also explains how to obtain the ID using the '/receipts/get method' first, giving a clear workflow. This fully covers when to use this tool versus alternatives.

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 carry readOnly/idempotent/destructive hints; the description adds operational behavior by explaining that rows counts only the returned page and that callers should page until empty, deduplicate IDs, and check progress. It stops short of covering auth or rate-limit context, but the annotation coverage lowers that burden.

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 read-only status and core purpose, then gives use guidance, the alternative, and paging details. The repeated 'get receipts' heading and emoji are slight redundancies but do not bloat the text.

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 13-parameter list tool, the description supplies enough orientation: required direction, search use cases, an alternative for single lookups, pagination protocol, and response summary. The phrase 'specified customer account' is slightly vague since no customer account parameter exists, but the schema and paging guidance compensate.

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 descriptions cover all 13 parameters, so the baseline is 3. The description earns extra by calling out list_direction as required and giving limit/offset paging semantics beyond the schema's default/maximum details.

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

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

The description opens with a clear verb and resource ('get receipts') and immediately states the search dimensions: direction, date range, or payment status. It also distinguishes itself from receipts_get_by_id, so an agent can route a 'fetch one known receipt' request away from this list 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 explicitly says 'Use to search receipts by direction, date range or payment status' and names the sibling tool for single-receipt lookups. The READ-ONLY framing also signals that this is not the tool for mutations.

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 mostly repeats that by saying READ-ONLY and 'Makes no changes.' It adds the prerequisite for obtaining id_by_customer, but does not go beyond annotations in depth.

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?

Well-structured and mostly front-loaded, but the READ-ONLY line and bold description repeat the title and annotations. Still, every section serves a purpose and the text is compact.

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?

Complete for a two-parameter read-only tool: it provides the use case, alternative direction, prerequisite lookup, and endpoint, while the annotations and output schema cover safety and return values.

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 applies. The description reinforces that receipt_id_by_customer is the key parameter and how to get it, but does not add additional meaning beyond the schema.

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

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

States a specific verb and resource: get all transactions assigned to a specific receipt. It clearly distinguishes itself from the sibling transactions_list_assigned_receipts by naming it as the opposite direction.

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

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

Gives an explicit use case ('check whether an invoice has been matched to a payment'), tells the user how to obtain the required id_by_customer via /receipts/get, and routes to the alternative tool for the reverse lookup.

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.