Red by Big Red Cloud

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

The description goes far beyond the annotations (readOnlyHint: false, destructiveHint: true), disclosing partial success per item, the routeToken validity window, that placeholder tokens are invalid, that routeToken does not bypass preview/confirmation, that a call without confirmWrite returns confirmation_required with a preview, that preflight passage is not confirmation, and the counterparty-confirmation scoping. This level of behavioral disclosure — especially the stateful token lifecycle and confirmation semantics — is exactly what an agent needs to avoid misfiring a destructive write.

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 long but every sentence carries operational weight: modes, partial success, token lifecycle, preview/confirmation gating, and counterparty scoping, all front-loaded after the primary action. There is minor redundancy — 'A routeToken does not bypass preview or explicit-confirmation requirements' and 'Passing preflight is not confirmation' overlap in spirit — but each restatement reinforces a different failure mode. No filler or marketing language.

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 transactional tool with no output schema, the description covers the critical workflow: token requirements, preview returns, confirmation application, per-item partial success, and counterparty confirmation. The rich input schema covers parameters fully, and the destructiveHint annotation alerts to side effects. The main gap is the absence of detail on the per-item result structure or final success response — 'Results are reported per submitted item' is asserted but the shape of those results is not described, and with no output schema the description bears that burden.

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

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

Schema description coverage is 100% and the schema itself is unusually rich, documenting the three item variants, the confirmWrite gating rule, routeToken semantics, connectionRef reuse, and confirmCounterpartyExplicit conditions. The description reinforces confirmWrite and confirmCounterpartyExplicit behavior in prose but adds little that the schema descriptions do not already state. Baseline 3 applies because the schema carries the parameter-semantics burden effectively.

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

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

The description opens with a specific verb and resource — 'Processes cash payments' — and narrows scope with the three modes: 'supplier-ledger, bank-lodgement or analysed-expense mode'. 'Results are reported per submitted item and partial success is possible' signals batch behavior that separates it from the single-item sibling brc_create_cash_payment. However, it never names a sibling or explicitly states 'use this for multiple cash payments in one call', so differentiation from brc_batch_payments and brc_create_cash_payment is left mostly to the tool name.

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 implies the usage context — a routeToken-gated, preview-then-confirm transactional workflow — but never explicitly says when to choose this over brc_create_cash_payment or another batch tool. It states preconditions ('Requires a valid routeToken issued for the matching action workflow', 'Requires confirmCounterpartyExplicit: true') and the two-phase call pattern, which is practical guidance. No alternatives are named and no exclusion conditions are given, so when-to-use vs alternatives is only 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 mark destructiveHint=true and readOnlyHint=false, so the write nature is known. The description adds real behavioral detail: the first call without confirmWrite returns confirmation_required and a payload preview, confirmWrite applies the previewed change only after explicit confirmation, and confirmation is scoped to the counterparty in the current preview. This two-phase flow is not inferable from annotations and is critical for safe invocation.

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?

Every sentence earns its place: batch limit, token validity, placeholder invalidity, no-bypass behavior, confirmation response, confirmWrite semantics, and counterparty scoping. The structure is front-loaded with the most important constraints, and the sentence-per-line layout makes the dense information reasonably scannable. Some grouping into bullets would improve scanability, but there is no bloat.

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?

Even without an output schema, the description tells an agent what to expect on the first call (confirmation_required and payload preview) and what confirmWrite: true does. Combined with a rich schema covering connectionRef, items constraints, and date formats, the core execution flow and prerequisites are adequately disclosed. It doesn't detail the exact preview payload shape or error conditions, but the essential transactional behavior is well covered.

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?

Schea description coverage is 100%, so the baseline is 3. The description does add interpretive context for routeToken, confirmWrite, and confirmCounterpartyExplicit, particularly the token's permission-only nature and the confirmation scoping. However, most of these meanings already exist in the schema parameter descriptions, so the marginal value added by the description is moderate rather than substantial.

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 'Processes a batch of BRC cash receipts,' which is a specific verb plus resource and clearly indicates this is a batch operation. The resource name and 'cash receipts' phrasing distinguish it from batch cash payments or other BRC batch tools, though it doesn't explicitly name a sibling for contrast.

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 concrete operational guidance: maximum 20 items per request, valid routeToken required, placeholder tokens invalid, and confirmation flags must only be true after explicit user confirmation. It clearly states when confirmWrite and confirmCounterpartyExplicit should be set, and that preflight alone is not confirmation. It doesn't explicitly discuss when to use the batch form versus a single-create sibling, but the usage constraints are concrete and 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 mark this as a write and destructive, and the description adds substantial behavior beyond that: token validity lifecycle, placeholder token invalidity, preflight returning confirmation_required with a payload preview, confirmWrite:true applying the previewed change only after explicit confirmation, and the warning that passing preflight is not confirmation. This is exactly the kind of high-risk behavioral context an agent needs.

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 dense but efficient: it front-loads purpose and batch size, then covers token validity, preview requirement, and explicit confirmation semantics in five tight sentences. Every sentence carries a constraint or behavior necessary for safe invocation, with no filler.

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

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

Given a complex transactional tool with nested items and no output schema, the description covers the critical workflow: token requirements, preview behavior, confirmWrite semantics, and max batch size. The schema supplies complete parameter documentation. It does not describe success/error response shapes in natural language, but the preview/confirmation flow is adequately disclosed.

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 meaningful parameter-level context beyond the schema, especially for routeToken (valid through lookup, preview, and permitted transaction; placeholder tokens invalid) and confirmWrite (preflight behavior and the distinction between preview and confirmation). This goes beyond the schema's own descriptions.

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 ('Processes') and resource ('a batch of customers') and adds scope ('Maximum 20 items per batch request'). It is clear enough to distinguish from non-customer batch tools, though 'Processes' is less precise than 'Creates' — the create semantics are only fully visible through the schema's opCode const 1.

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 concrete invocation context: a valid routeToken from the matching workflow is required, placeholder tokens are invalid, and the preview/confirmWrite contract is spelled out. It does not explicitly state when to prefer this over single-entity siblings like brc_create_customer, but the batch-specific context is clear and 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 declare readOnlyHint=false and destructiveHint=true, and the description expands substantially: per-item partial success, two-phase confirmWrite behavior, confirmation_required + preview payload without confirmWrite, passing preflight is not confirmation, placeholder tokens invalid, and routeToken not bypassing preview. This is precisely the behavioral nuance that prevents incorrect calls. 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 long but dense: each sentence carries a distinct correctness constraint (token validity, preview non-bypass, preflight semantics, counterparty scoping). It is front-loaded with purpose and then operational rules. Minor redundancy exists with the confirmWrite schema description, which keeps it from a 5.

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

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

Despite having no output schema, the description sets expectations for both phases (confirmation_required and payload preview on first call; per-item results and partial success after confirmation). Parameters, safety profile (destructiveHint), and the two-phase confirmation protocol are all covered. Remaining gaps are minor: no explicit sibling routing and no return schema, but the call flow is well documented.

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% — every parameter (items, routeToken, companyName, confirmWrite, connectionRef, confirmCounterpartyExplicit) already has a thorough schema description, including confirmWrite's explicit 'never true on the first call' rule. The description reinforces the flow (preflight-not-confirmation, token validity scope) but adds little per-parameter meaning, so the baseline 3 applies.

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

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

States a specific verb+resource+scope: 'Processes supplier or analysed bank payments in a batch.' This distinguishes it from single-item payment tools like brc_create_payment and, via 'supplier or analysed', from sibling batch tools such as brc_batch_cash_payments. The per-item results and partial-success clause also sharpen the batch semantics.

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 preconditions and workflow context: requires a routeToken from brc_route_request for the matching action workflow, remains valid through lookup/preview, and spells out the explicit-confirmation requirements (confirmWrite, confirmCounterpartyExplicit). An agent can infer the orchestration sequence from this. It does not explicitly name alternatives or exclusions among the batch/create siblings, 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?

Annotations only declare destructiveHint=true and readOnlyHint=false, so the description carries the burden — and it excels. It discloses the routeToken lifecycle, that tokens do not bypass preview or explicit confirmation, that a call without confirmWrite returns confirmation_required with a payload preview, and that passing preflight is not confirmation. This goes far beyond the bare annotation and is essential for a destructive write tool.

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

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

The description is dense and front-loaded, opening with the core action and batch limit before covering token and confirmation requirements. Each sentence adds important risk or workflow context. It is longer than strictly necessary, and somewhat repeats the confirmWrite semantics already described in the schema, but for a destructive batch tool the length is justifiable.

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 prerequisite routeToken, the 20-item batching constraint, the preview-before-confirm control flow, and the confirmation_required response path. There is no output schema, so a bit more clarity on the success response after confirmWrite=true or error cases would help, but the current description is largely complete for safely invoking this complex transactional tool.

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

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

Schema coverage is 100%, with every property already well documented (opCode const 1, companyName example, routeToken purpose, confirmWrite policy, item details, etc.). The description reinforces routeToken and confirmWrite semantics but does not need to add new parameter-level meaning because the schema already carries 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 states it 'Processes a batch of products' with explicit product type, VAT, price, and description fields, and notes the 20-item cap. It clearly identifies the resource as products, which helps separate it from sibling batch tools for payments, invoices, customers, etc. However, the verb 'processes' is more generic than 'creates' or 'updates', and the description does not explicitly name its single-product alternative (brc_create_product).

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 strong operational conditions: valid routeToken, maximum 20 items, placeholder tokens invalid, and the confirmWrite/preview requirement. It does not, however, explicitly contrast this with brc_create_product or explain when the batch tool should be preferred over the single-record variants. The usage context is clear but alternatives are not named.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=true), the description discloses partial success, result-per-item reporting, routeToken validity and limitations, preview requirements, confirmation semantics, and the fact that preflight is not confirmation. This is substantial behavioral context that annotations alone do not 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 long but every sentence carries a distinct behavioral constraint; there is no filler. It is front-loaded with the core purpose and then systematically explains token, preview, confirmation, and counterparty requirements. Could be slightly tightened, but the density is justified by the complex confirmation flow.

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

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

There is no output schema, so the description must cover return behavior. It does: results are per item, partial success is possible, and a call without confirmWrite returns confirmation_required with a payload preview. Given the complexity of this transactional tool, this is a reasonably complete picture, though an explicit note on error structure for failed items would make it fully comprehensive.

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 meaningful extra semantics for confirmWrite and confirmCounterpartyExplicit, explaining when they may be true and that preflight does not count as confirmation. This goes beyond the schema-level descriptions and helps an agent avoid critical mistakes.

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

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

The description opens with a specific verb and resource: 'Processes purchases in a batch using structured generated-reference purchase items.' It further distinguishes itself from single-purchase tools by noting per-item results and partial success, so an agent can tell it apart from brc_create_purchase and sibling batch 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 clearly defines the required workflow: a valid routeToken for the matching action workflow is needed, placeholder tokens are invalid, and confirmWrite must only be true after explicit preview and confirmation. This gives strong when-to-use and sequencing guidance, though it does not explicitly name alternative tools or state when not to use the batch endpoint.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, and the description goes well beyond those annotations by explaining token lifetime, placeholder-token invalidity, preview-and-confirm flow, preflight-not-confirmation, and counterparty-explicit confirmation scope. This is high-value behavioral context. There is no contradiction between description and annotations, so behavioral transparency is strong.

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

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

The description is a compact paragraph that front-loads the core action, then covers the token, preview, and confirmation rules without redundancy. It packs a lot of information into a dense block but each sentence contributes important constraints. A slightly more structured layout might help, but it is appropriately sized and not padded.

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

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

For a destructive, high-stakes transactional tool with no output schema, the description covers the confirmation protocol, token lifetime, and batch limit. It does not explicitly mention connectionRef reuse or CR analysis category confirmation, but those are documented in the schema. It also does not describe return values beyond confirmation_required and payload preview, which is sufficient because no output schema exists but the key response behavior is stated. Overall it is complete enough for an agent to call 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 schema already documents every parameter including the elaborate nested quote structures. The description adds semantics for routeToken, confirmWrite, and confirmCounterpartyExplicit—namely token validity, preview-before-confirm, and explicit counterparty confirmation—which are not fully captured by the schema descriptions. It does not describe every nested field, but the schema carries that load. Given 100% coverage and rich schema descriptions, a 4 is appropriate since the description adds the operational 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?

The description clearly states the tool processes a batch of quotes via two payload forms and sets the 20-item limit, so the verb and resource are specific enough to distinguish it from single-quote create tools and other batch tools. It doesn't explicitly name a sibling like brc_create_quote, but the batch name and scope are evident.

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

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

The description strongly implies when to use this tool with routeToken requirements, the need for confirmWrite true and confirmCounterpartyExplicit true, and the fact that preflight is not confirmation. It even warns placeholder tokens are invalid and describes the confirmation flow, effectively guiding the agent through the correct call sequence. It doesn't name alternative tools explicitly, but the workflow rules are otherwise explicit. Since explicit when/when-not guidance is present through the confirmation-flow rules, this earns 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?

Annotations only say readOnlyHint=false and destructiveHint=true; the description carries the real burden and succeeds fully. It discloses partial success with per-item results, the token validity window, that tokens never bypass preview/confirmation, the two-phase confirmWrite flow, and that passing preflight is not confirmation. This is exemplary disclosure for a destructive batch tool.

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

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

The description is long — nine sentences — but it is front-loaded with the core purpose and every sentence carries a distinct operational fact. There is mild overlap between 'does not bypass preview or explicit-confirmation' and 'passing preflight is not confirmation'. For a high-stakes destructive batch tool, the density is justified.

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

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

With no output schema, the description gives a useful-level statement of results (per-item reporting, partial success possible) without overpromising. The safety protocol — preview, explicit confirmation, counterparty confirmation, token requirements — is thoroughly covered. Minor gap: the 20-item batch cap lives only in the schema, and detailed return structure is absent, but the description does its job.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema. It explains routeToken lifecycle (valid through lookup, preview, transaction; placeholders invalid), the confirmWrite two-step semantics, and counterparty-confirmation scoping. This enriches the short schema field descriptions.

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 — 'Processes sales credit notes' — and immediately scopes it as a batch operation, distinguishing it from single-document siblings like brc_create_sales_credit_note. The mention of reconciled product, VAT and Sales-analysis lines adds precision about what the batch consumes. The purpose is unambiguous and differentiated.

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

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

Gives very clear workflow context: a first call returns confirmation_required plus a payload preview, and confirmWrite: true may only follow explicit user confirmation. It also pins down prerequisites — a valid routeToken for the matching action workflow and confirmCounterpartyExplicit: true. It names no alternative tool or explicit exclusion, so it stops just short of full when-to-use-vs-sibling guidance.

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

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

With destructiveHint: true and readOnlyHint: false, annotations already signal mutation, but the description adds substantial behavioral context beyond that: routeToken lifecycle and invalidity of placeholders, the token's non-bypass of preview/confirmation requirements, the exact two-phase response behavior (confirmation_required plus payload preview), the 'passing preflight is not confirmation' nuance, and counterparty-confirmation scoping. This meaningfully exceeds what annotations provide and does not contradict 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 dense (~9 sentences) but every sentence earns its place for a destructive batch tool: purpose, item cap, token requirement, token lifecycle, placeholder invalidity, no-bypass guarantee, two-phase response behavior, preflight caveat, and counterparty confirmation. The core purpose is front-loaded. It is on the longer side, but security-critical confirmation semantics justify the length; minor restructuring into explicit phases could improve scannability.

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 destructive batch tool with 7 parameters and no output schema, the description covers the essential operational ground: the confirmation protocol, token requirements, and preview behavior. The schema documents all parameters at 100% coverage, including confirmCrAnalysisCategory and connectionRef. Remaining minor gaps are the lack of an explicit single-vs-batch routing statement and no mention of what a successful final response returns, though these are partly compensated by schema and sibling names.

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 goes beyond the schema by explaining workflow semantics for key parameters: how confirmWrite triggers the two-phase flow (without it, confirmation_required + preview; with it, the previewed change is applied), routeToken validity through lookup/preview/transaction, and the scoping of confirmCounterpartyExplicit to the currently previewed counterparty. This adds real meaning beyond the field-level schema text.

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

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

States a specific verb and resource — 'Processes a batch of sales entries' — and the batching scope is clear (max 20 items). The title and name distinguish it from single-entry siblings like brc_create_sales_entry and from other batch resources (invoices, credit notes). The verb 'processes' is slightly generic (create vs. post vs. validate is not stated directly), but the opCode schema constraint and confirmation-flow language make the core purpose understandable.

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 strong invocation guidance for the two-phase workflow: call without confirmWrite to get a confirmation_required response and preview, then confirmWrite: true to apply the change; explicitly states that preflight is not confirmation and that confirmCounterpartyExplicit must be true. However, it gives no explicit guidance on when to choose this batch tool over brc_create_sales_entry or alternative batch tools, leaving the selection to inference from the name.

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

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

The description thoroughly discloses behavioral traits beyond the annotations: partial success is possible, results are per submitted item, placeholder tokens are invalid, routeToken does not bypass preview/confirmation, a call without confirmWrite returns confirmation_required plus a payload preview, and preflight is not confirmation. This adds significant 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 compact and front-loaded with the core processing purpose before moving into the token/confirmation constraints. Every sentence contributes a distinct point (batch behavior, token validity, preview semantics, confirmation rules). It is slightly dense in the middle but still efficient; no filler or repetition.

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

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

Given the tool's complexity (batch, transactional, requires routeToken and explicit confirmation), the description covers all essential operational facts: partial success, per-item results, routeToken lifecycle, preview/confirmation flow, and the counterparty confirmation requirement. The absence of an output schema is compensated by the description explicitly stating what kind of response is returned (confirmation_required with payload preview).

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds crucial semantics for routeToken, confirmWrite, confirmCounterpartyExplicit, and priceBasis, which are not fully explained by the schema alone. It also enriches understanding of items with the note about matching brc_create_sales_invoice_gen_ref. A small deduction because the description doesn't elaborate on companyName or connectionRef beyond what the schema already says.

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 ('processes') and resource ('sales invoices in a batch using reconciled product, VAT and Sales-analysis lines'), which clearly identifies what the tool does. It also explicitly notes partial success and per-item reporting, distinguishing it from single-invoice creation tools like brc_create_sales_invoice.

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 when-to-use guidance, including the requirement for a valid routeToken issued for the matching action workflow, the behavior without confirmWrite: true, and the mandatory confirmCounterpartyExplicit: true setting. It also clarifies that confirmWrite must only be set after explicit user confirmation, which effectively distinguishes this from preview-only or read-only 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?

The description goes well beyond the destructiveHint annotation: placeholder tokens are invalid, routeToken doesn't bypass preview/confirmation, no confirmWrite returns confirmation_required with a payload preview, and passing preflight is not confirmation. This fully discloses the transactional write behavior an agent needs before invoking.

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 dense yet compact, front-loading the core operation and limits before the token/confirmation rules. Every sentence contributes a distinct constraint or behavior; there is no filler.

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

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

For a transactional write tool with no output schema, the description covers the necessary invocation sequence: required token, batch limit, confirmation_required response, and what confirmWrite: true does. Combined with fully-described parameters and annotations, an agent has enough to call it correctly.

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

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

Schema description coverage is 100%, so the parameter baseline is already high. The description adds operational meaning to routeToken and confirmWrite (token validity period, preflight not being confirmation) and restates the 20-item batch limit, which is useful but partly redundant with 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 identifies a specific resource ('sales representatives'), the batch mode, and the fields used ('explicit code and name fields'), which sets it apart from single-record siblings like brc_create_sales_rep. It stops short of a 5 because 'Processes' is a generic verb; the schema's opCode const 1 is needed to confirm this is a batch create rather than an update or 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?

It clearly frames the tool for batch processing ('Maximum 20 items per batch request') and gives operational prerequisites such as a valid routeToken and confirmWrite flow. It does not explicitly name sibling alternatives or list when-not-to-use scenarios, but the intended context 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?

Annotations already mark this as destructive and non-read-only, and the description adds substantial context: token validity through lookup/preview, placeholder token invalidity, no bypass of preview/confirmation, confirmation_required return without confirmWrite, and 'preflight is not confirmation'. This gives an agent a realistic picture of the tool's safety behavior and is fully consistent 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 dense and well-structured: action, batch limit, auth requirement, token lifecycle, and confirmation behavior are all covered in seven sentences. Minor redundancy with the schema's confirmWrite and routeToken descriptions keeps it from being a 5.

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

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

For a write tool with no output schema, the description sufficiently explains invocation preconditions, authentication, and the no-confirm return path. It does not describe the success response after confirmWrite, error cases beyond invalid tokens, or clarify what 'explicit identity' means, but the rich input schema compensates for most gaps.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining routeToken lifecycle details and the confirmWrite/confirmation_required behavior in operational terms rather than just schema constraints. It does not add new meaning for companyName, items, or connectionRef 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 clear batch operation on suppliers with a 20-item cap, so the resource and scope are identifiable. However, it says 'Processes' rather than explicitly 'creates' — the create semantics only appear in the schema's opCode — and it does not explicitly differentiate from brc_create_supplier or other batch 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 provides clear operational context: batch requests, maximum 20 items, required routeToken, and the preview/confirmation flow. It does not explicitly state when to prefer this tool over brc_create_supplier or when not to use it, so alternative selection is left to inference from the name and schema.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that it returns warnings and does not provide an overall score, which helps set expectations. It does not reveal whether the result is a list of warnings, a status object, or whether some workflows can return empty results, but the read-only nature is already well covered by annotations.

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

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

Single sentence plus a short clarifying clause. Every word earns its place, the scope is front-loaded, and the negative clarification prevents an agent from over-interpreting the tool's 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 that this is a read-only, single-workflow check with a fully documented schema and no output schema, the description is almost complete. The only slight gap is that the return value's shape is not described, but since there is no output schema, a brief note on what the warnings look like would have been helpful. Still, the negative scope note and read-only annotations make the context adequately complete.

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

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

The schema description coverage is 100%, so the schema already documents all three parameters well. The description does not add parameter-specific guidance beyond what the schema contains. The connectionRef parameter has extensive guidance within the schema itself, so the description does not need to repeat it. Baseline 3 is appropriate.

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

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

The description states a specific verb ('Returns'), a specific resource ('processing-setting warnings for one specified transaction workflow'), and usefully distinguishes itself by noting it does not provide an overall company-readiness score. It is clear and actionable, though it does not explicitly name sibling tools like brc_company_readiness_check in the text.

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

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

The description implies when to use it: when you need warnings for a single workflow, and it explicitly says it is not for overall company-readiness scoring. However, it does not explicitly say 'use brc_company_readiness_check for the overall score' or list exclusions against other siblings, so the usage guidance is adequate but not fully explicit.

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

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

The annotations already mark destructiveHint=true, and the description adds the important scope that this clears all company contexts from MCP server memory. However, it does not disclose the after-effects, such as requiring re-authentication or invalidating all existing connectionRefs beyond the immediate deletion.

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 one sentence with no filler or redundant restatement of the title. It front-loads the core behavior and scope immediately and earns its place without extra noise.

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

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

For a destructive, global operation, the description is minimally sufficient but lacks important operational context: no mention of irreversibility, re-authentication requirements, what the success response looks like, or explicit contrast with the single-company clearing tool. The lack of an output schema makes the missing return/effect guidance more noticeable.

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 provides 100% coverage: the single optional connectionRef parameter has a detailed explanation. The description adds no parameter-level meaning beyond that. Since the schema does the heavy lifting, 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 states a precise action and scope: 'Clears all connection credentials for all company contexts from MCP server memory.' It clearly distinguishes this from the singular sibling tool brc_clear_company_api_key by emphasizing 'all company contexts' and 'memory,' so an agent can identify the global variant.

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

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

No guidance is given about when to use this tool vs. brc_clear_company_api_key, and there is no warning that it should only be used when a full global reset is intended. The context is implicit from the name and description, but the description never explicitly states 'use this only when you need to clear every company context's credentials.'

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 destructiveHint=true and readOnlyHint=false, and the description adds materially richer safety context: unconfirmed calls return confirmation_required with a payload preview, confirmWrite: true only applies after explicit user confirmation, and preflight is not confirmation. It also narrows the blast radius by scoping the action to the MCP server session.

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

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

Three sentences, no wasted words: the core action and scope are front-loaded, then the unconfirmed path, the confirmed path, and the preflight caveat each get one earned sentence. Nothing duplicates the schema or annotations.

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

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

For a destructive gated tool with no output schema, it discloses the unconfirmed response (confirmation_required plus payload preview) but not the confirmed/success response. More importantly, it never mentions confirmClear — the parameter literally named for this action — so an agent cannot be certain of the full confirmation protocol.

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

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

Schema description coverage is 100%, so the baseline is 3 and the description need not restate parameter docs. It adds flow-level meaning around confirmWrite, but it never clarifies the relationship between confirmClear and confirmWrite, leaving an agent unsure whether one or both booleans must be true.

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

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

The description names a specific verb, resource, and scope: 'Clear the Red audit log for this MCP server session.' It distinguishes cleanly from the viewing sibling brc_list_audit_log and from the brc_clear_company_api_key / brc_clear_all_company_api_keys tools, which target a different 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 explains how the confirmation flow works but never states when to choose this tool versus alternatives; brc_list_audit_log is not named as the viewing counterpart, nor are the other clear-* siblings excluded. Usage is implied by the name and scope rather than explicitly routed.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds 'from MCP server memory', which clarifies the scope of the effect, but it does not state consequences such as irreversibility, whether the key is immediately invalidated, or what happens on subsequent calls.

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 one short, focused sentence that states the action, target, and memory location. There is no redundant wording or irrelevant detail.

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 destructive tool with fully documented parameters and clear annotations, the description is nearly complete. It could be slightly richer by explicitly pointing to brc_clear_all_company_api_keys as the multi-company alternative or noting practical consequences, but nothing critical is missing for invoking 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 parameters are already fully documented in the schema. The tool description adds no additional parameter-level meaning beyond the 'named company context' phrase, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Clears') and a precise resource ('API key for a named company context from MCP server memory'). It clearly indicates this is a targeted, per-company destructive action and is distinguishable from the sibling brc_clear_all_company_api_keys.

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

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

The phrase 'for a named company context' implies this tool is for clearing one company's key rather than all keys, and the sibling brc_clear_all_company_api_keys shows the alternative. However, the description does not explicitly state when to prefer this tool over the all-variant or when not to use it.

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

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

The description discloses important behavioral traits beyond the annotations: routeToken validity through lookup/preview/transaction, placeholder tokens being invalid, no bypass of preview/confirmation, confirmation_required with payload preview when confirmWrite is absent, and the rule that preflight is not confirmation. This is exactly the kind of behavioral nuance an agent needs.

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, front-loaded with the core purpose, and every sentence conveys necessary behavioral or workflow information. There is no filler or repetition of schema details beyond reinforcing critical confirmation semantics.

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 transactional tool with no output schema and sparse annotations, the description covers the critical confirmation workflow, token requirements, and expected intermediate response. It does not describe the success response shape or error cases in detail, but the essential invocation protocol is well covered.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds meaningful semantics for routeToken (lifecycle, placeholder invalidity) and confirmWrite (preflight not confirmation, previewed change application), going beyond the schema's parameter descriptions.

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

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

The description opens with a specific verb and resource: 'Closes a BRC quote.' This clearly identifies the operation. It does not explicitly differentiate from related siblings like brc_reopen_quote, brc_update_quote, or brc_delete_quote, so it stops short of full sibling differentiation.

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 clear operational context: a valid routeToken is required, placeholder tokens are invalid, and confirmWrite must only be true after explicit confirmation. It explains the two-phase confirmation flow well. However, it does not explicitly state when to choose this tool over alternatives such as update_quote or delete_quote.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful scope context by listing the specific readiness areas checked, but it does not disclose what 'readiness' means, what the output contains, or any failure behavior. This 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 is a single concise sentence with front-loaded verb and resource, followed by a compact list of readiness areas. There is no filler or repeated information from the schema or title.

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

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

For a simple read-only tool with well-documented parameters and safety annotations, the description covers the main purpose and scope. However, there is no output schema and the description does not indicate the shape or granularity of the returned readiness result, which would make the tool slightly more complete.

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

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

Schema description coverage is 100%, and the schema already documents both companyName and connectionRef, including the important connectionRef reuse guidance. The description adds no additional parameter semantics beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states a specific verb ('Returns') and resource ('overall company readiness') and enumerates the readiness domains: connection, financial year, reference data, VAT, analysis categories, and settings. It is distinguishable from most sibling batch/get/create tools, though it does not explicitly distinguish itself from closely related tools like brc_check_transaction_settings or brc_get_company_setup_config.

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 implies this tool is used to check overall readiness, but it gives no explicit guidance on when to prefer it over alternatives or when not to use it. There are many sibling tools covering settings and transaction checks, and the description does not clarify which one an agent should choose based on the situation.

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 provide only that this is not read-only and not destructive, leaving the description to explain side effects and data handling. The description adds behavioral value by noting the code is short-lived, that connection credentials are not returned, and that the returned reference is reusable and opaque. It does not mention that the code is single-use, but the transparency provided is solid.

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

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

Two concise sentences front-load the core purpose and immediately state the most important behavioral caveat ('Connection credentials are not returned'). Every sentence adds necessary information with no filler.

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

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

For a two-parameter tool with no output schema, the description covers what is confirmed, what is returned, and what is not returned. It is adequate for an agent to invoke correctly, though it could explicitly mention that the code is consumed or single-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?

Schema description coverage is 100% and both parameters have detailed descriptions, so the description does not need to compensate. It adds conceptual context about the connection reference being reusable and credential-free, but the schema already carries most of the 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 description names a specific verb ('confirms'), a precise resource ('short-lived company-connection code'), and the expected result ('connected companies plus a reusable opaque connection reference'). It clearly differentiates this from brc_start_company_connection by describing the confirmation step rather than the initiation step.

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

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

The phrase 'short-lived' and the schema's note that the code comes from the Red connection page success message make the invocation context clear. It does not explicitly name alternative tools, but the confirmation-vs-start distinction is strongly implied and adequate for an agent.

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

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

Annotations only provide destructiveHint: true. The description goes well beyond that by disclosing the confirmation workflow: calls without confirmWrite return confirmation_required and a payload preview, confirmWrite applies the previewed change, placeholder tokens are invalid, and routeToken does not bypass preview or confirmation requirements.

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 dense and front-loaded with the core action. Every sentence contributes something useful, though there is slight redundancy between 'returns an unconfirmed payload preview' and the later explanation of the preview/confirm flow.

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

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

For an 11-parameter creation tool with no output schema, it explains the essential confirmation protocol, routeToken lifecycle, and the meaning of confirmWrite. A minor gap is that it does not describe what the final successful response after confirmWrite: true looks like.

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 meaningful semantics for confirmWrite and routeToken beyond the schema: no-confirm returns a preview, confirmWrite applies the previewed change, and the token remains valid through lookup/preview/transaction. This gives the agent concrete decision guidance for those parameters.

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

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

The description states a specific verb and resource ('Creates an accrual') and immediately adds the distinguishing two-phase preview-then-confirm behavior. This clearly separates it from the update/get/delete accrual siblings even without comparing them explicitly.

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

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

It gives strong operational guidance: a routeToken is required, confirmWrite: true must only follow explicit user confirmation, and preflight does not count as confirmation. It does not explicitly name sibling alternatives or state when not to use this tool, so it stops 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?

Annotations only indicate readOnlyHint=false and destructiveHint=false, so the description carries the burden of explaining that this is a mutation tool. It goes beyond the schema by stating that placeholder tokens are invalid, that the routeToken does not bypass preview or confirmation, and that the token remains valid across lookup, preview, and the permitted transaction. These are important behavioral constraints that prevent misuse and are not captured by annotations.

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

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

The description is compact at two sentences and gets to the point quickly. The key constraint (requires an unconfirmed preview and explicit confirmation) is front-loaded. Some could argue the phrase 'unconfirmed preview' is slightly jargon-heavy, but overall it is efficient and free of fluff.

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 20 parameters and no output schema, the description is too thin. It does not describe the preview step (how to obtain the preview), what the tool returns, or any side effects beyond the confirmation. An agent would need to inspect the schema and possibly related tools (like brc_route_request) to fully understand the workflow. This is a significant gap given the complexity of the operation.

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

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

The schema has 55% description coverage (11 of 20 parameters have descriptions). The tool description does not add any parameter-level meaning; it only references routeToken and confirmCreate, which are already well-described in the schema. For the many parameters lacking descriptions (e.g., acCode, address, balance, sortCode, accountName, etc.), the description provides no clarification, so it does not compensate for the coverage gap.

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 a bank account and explicitly differentiates it from other create tools by tying it to a preview/confirmation workflow. It names the specific resource (bank account) and the required confirmation mechanism, so an agent can distinguish it from brc_update_bank_account or other creation tools 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?

The description provides workflow context: it must be used after an unconfirmed preview, requires a valid routeToken from brc_route_request, and confirmCreate must be true only upon explicit user confirmation. It does not explicitly list alternative tools or say when not to use it, but the preview-and-confirm guidance gives a clear sense of the correct invocation sequence, which is enough for most agents.

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 this as destructive and read-write, and the description adds substantial behavioral nuance: routeToken validity, placeholder token invalidity, the confirmation_required response without confirmWrite, preflight not being confirmation, and the scoping of counterparty confirmation. It also makes the destructive character concrete by explaining that nothing is written until confirmWrite is 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 dense but every sentence contributes critical workflow information. It front-loads the core purpose, then explains the routeToken lifecycle and the confirmation requirements in a logical order. No fluff or redundancy prevents it from being appropriately sized for a complex transactional tool.

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

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

Given 20 parameters, no output schema, and a two-phase write workflow, the description covers the most critical invocation semantics, including what happens without confirmWrite. It does not enumerate all mode-to-parameter mappings, but the schema covers those details, so the description is largely sufficient 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 85%, so the schema already documents most parameters. The description complements it by explaining the workflow semantics around routeToken, confirmWrite, and confirmCounterpartyExplicit, including the preflight response. This goes beyond the schema's per-parameter descriptions.

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 precise verb and resource: 'Creates a cash payment' and immediately names the three supported modes (supplier-ledger, bank-lodgement or analysed-expense). This clearly distinguishes it from sibling tools like brc_create_cash_receipt, brc_create_payment, and brc_update_cash_payment.

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 clearly explains the operational context: it requires a routeToken from a matching action workflow and describes the preview/confirmation flow. It does not explicitly name alternative tools or state when not to use this tool, but the mode list and resource type give an agent clear context for selecting it.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, and the description goes far beyond them: it discloses the two-phase confirm/apply flow, the confirmation_required preview return, routeToken lifecycle and validity scope, entryDate/procDate defaults, conditional VAT field sending, and counterparty-confirmation scoping. No contradiction with annotations; the prose substantially enriches the safety profile.

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

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

Eight dense sentences, front-loaded with the purpose line, and each following sentence covers a distinct safety- or behavior-critical point. There is mild redundancy among the confirmation warnings ('does not bypass preview', 'preflight is not confirmation'), but for a destructive two-phase write that repetition is justified. Length is proportionate to the transactional complexity.

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

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

For a destructive tool with no output schema, the description covers the phase-one return (confirmation_required plus payload preview), all prerequisites, token handling, and the confirmation scoping. The success-path response shape is undisclosed and no alternative-routing guidance exists, but every constraint an agent must respect before posting is 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?

With 32 parameters and only 16% schema description coverage, most fields are undocumented, and the description cannot fully compensate. However, it adds real meaning by explaining the dual calling convention (raw payload object vs common flat fields), the date defaults, and the conditional VAT behavior. The three flow-critical params (routeToken, confirmWrite, confirmCounterpartyExplicit) are also restated in prose, though slightly redundant with their schema descriptions.

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 opening sentence 'Creates a BRC cash receipt' states a specific verb and resource, immediately differentiating the tool from the update/get/delete/list cash receipt siblings and from create_cash_payment. The singular 'a' also separates it from brc_batch_cash_receipts without requiring schema inspection.

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

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

The description gives exceptionally clear procedural context: routeToken must come from the matching brc_route_request workflow, confirmWrite:false returns a preview, confirmWrite:true applies only after explicit confirmation, preflight is not confirmation, and confirmCounterpartyExplicit must be true. What is missing is any explicit mention of alternatives — e.g., use brc_batch_cash_receipts for multiple receipts or brc_create_cash_payment for payments — so there are no exclusions or alternative routing.

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

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

Beyond annotations, it discloses routeToken lifecycle, invalid placeholder tokens, no bypass of preview requirements, the confirmation_required first-call behavior, that confirmWrite applies the previewed change, and that opening-balance fields are not posted. There are no contradictions 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?

Dense but well-organized: function first, then prerequisites and the confirmation workflow. Each sentence adds a distinct behavioral fact with no filler or redundant surface-level detail.

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?

Very complete for a complex transactional tool with no output schema: covers routeToken, preview, confirmWrite, and the confirmation_required return case. It does not describe the final success response or explicitly route to batch/update siblings, but the essential invocation contract is present.

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

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

Although schema coverage is 100%, the description adds crucial meaning for the opaque payload parameter: explicit code and name fields, optional fields omitted when absent, and opening-balance fields not posted. It also reinforces routeToken and confirmWrite semantics, materially improving call correctness.

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 action and resource: creates a BRC customer. It narrows the operation by noting explicit code and name fields and that opening-balance fields are not posted, clearly separating creation from update or batch alternatives.

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 strong operational context: requires a routeToken from the matching workflow, preview before posting, confirmWrite behavior, and no write until explicit confirmation. It does not explicitly name alternative tools or exclusion conditions, so it is clear context without full sibling routing.

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

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

Annotations only say destructiveHint=true and readOnlyHint=false; the description adds the critical two-phase confirmation behavior, routeToken lifecycle, invalidity of placeholder tokens, and the fact that preflight is not confirmation. This is exactly the kind of behavioral context an agent needs before invoking a mutating tool.

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

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

Every sentence contributes a distinct constraint or behavior. The description is about seven sentences long for a complex transactional workflow and does not waste words on obvious boilerplate. The key purpose and confirmation model 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 mutating tool with no output schema, the description covers the non-obvious workflow fully: token requirements, preview semantics, confirmation, and what cla call without confirmWrite returns. Minor gaps: it does not explicitly mention the balance requirement or the effect of accountTransactions validation, but the schema already documents those. Overall sufficient for an agent to safely call the tool.

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

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

The schema already covers all 9 parameters (100%), so the baseline is 3. The description adds value by explaining parameter interplay: routeToken remains valid through the workflow, confirmWrite toggles preview vs apply, and placeholder tokens are invalid. This goes beyond individual field descriptions.

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?

Starts with a specific verb and resource ('Creates a nominal journal batch') and adds the distinguishing behavior: it returns an unconfirmed payload preview before committing. This is unique among the substantial sibling list and an agent can clearly separate it from list/update/delete nominal-journal tools.

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

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

Provides clear execution conditions: a valid routeToken from the matching action workflow, a preview step, and an explicit confirmWrite: true before persisting. It does not name alternative tools explicitly, but the usage workflow is specific enough that an agent knows where it fits among create/update/delete siblings.

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

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

Annotations already mark destructiveHint=true and readOnlyHint=false, and the description goes well beyond that by explaining token validity, placeholder-token invalidity, the confirmation_required response, the role of confirmWrite, the meaning of preflight, and the scoping of counterparty confirmation. This is rich behavioral context that annotations alone would not 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 front-loaded with its core purpose and then builds into the confirmation workflow. It is longer than average, but nearly every sentence carries operative information about token handling or confirmation semantics. A small amount of redundancy exists between 'routeToken does not bypass' and 'passing preflight is not confirmation.'

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

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

Given the tool's complexity and lack of an output schema, the description covers the most critical operational facts: required routeToken, confirmation_required return behavior, confirmWrite semantics, and counterparty confirmation. It does not fully describe return payloads after successful confirmation or map all mode-specific parameters, so it is not perfect, but it is strong enough for an agent to invoke the tool safely.

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

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

Schema coverage is 68%, and the description adds meaningful semantics for the most safety-critical parameters: routeToken, confirmWrite, and confirmCounterpartyExplicit. It explains what happens when confirmWrite is absent, and that a routeToken does not bypass preview. Some parameters like acCode, accountCode, and supplierId are not mapped in the description, but their schema descriptions cover the basic intent.

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

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

The description opens with a specific verb and resource: 'Creates a bank payment' and further clarifies two distinct modes: supplier or analysed-account. This cleanly separates the tool from sibling create-payment tools like brc_create_cash_payment and brc_create_purchase.

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

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

It clearly states the prerequisite routeToken requirement and the confirmation flow. However, it does not explicitly name alternatives (e.g., 'use brc_create_cash_payment for cash payments'), so the when-not-to-use guidance is mostly implied by the word 'bank payment.'

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 substantially discloses behavior beyond annotations: token lifecycle through lookup/preview/transaction, placeholder token invalidity, no bypassing of preview or confirmation, confirmation_required response without confirmWrite true, and preflight not being confirmation. This is rich, accurate behavioral context that annotations alone do not 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?

Every sentence of the description earns its place: it leads with the main purpose, then covers token validity, confirmation behavior, and the preflight pitfall. There is no filler or repetition, and the most important caveats 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, destructive write operation with 11 parameters and no output schema, the description is unusually complete. It explains the required workflow, the exact behavior when confirmWrite is missing, and the special constraints on routeToken and preflight. An agent has enough to invoke the tool correctly without additional inference.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description goes further by clarifying the two most subtle parameters. It explains that routeToken is routing permission only, remains valid through the workflow, and does not replace confirmWrite; and that confirmWrite true applies the previewed change only after explicit confirmation. This adds genuine semantic value 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 action and resource: 'Creates a prepayment' after returning a payload preview. It distinguishes this create operation from related prepayment tools like get, update, and delete by naming the exact resource and workflow. The verb and scope are unambiguous.

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

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

The description provides clear context for when to call this tool: a valid routeToken must be present, and an explicit confirmWrite true step is required. It also warns against placeholder tokens and preflight-as-confirmation, so an agent knows the prerequisites. It does not explicitly name sibling alternatives such as update_prepayment, but the create-vs-update distinction is implicit and 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 only indicate non-read-only and non-destructive. The description adds substantial behavior: routeToken lifecycle, no bypass of preview or confirmation, confirmation_required behavior without confirmWrite, and the distinction between preflight and confirmation. It discloses the mutation semantics clearly and contradicts nothing.

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 core purpose and then communicates distinct operational rules with no filler. Every sentence adds information about token validity, preview, confirmation, or preflight, so the length is justified.

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 transactional tool with no output schema, the description covers the crucial confirmation workflow, token prerequisite, and non-bypass guarantees. It does not describe the success response shape or how connectionRef interacts with the call, but those are partially covered by the schema and are less critical than the confirmation semantics.

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 parameters are already documented. The description goes beyond by explaining routeToken validity and matching-workflow requirements, placeholder-token invalidity, and the precise confirmation semantics of confirmWrite. It does not elaborate the iaw payload inner structure, but the schema covers the parameter itself.

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

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

The description opens with a specific verb and resource: 'Creates a BRC product using a raw BRC payload.' It clearly states what the tool does, but it does not explicitly distinguish it from sibling tools like brc_batch_products or brc_update_product, so it misses the full sibling-differentiation bar.

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 workflow guidance: a valid routeToken from brc_route_request is required, tokens remain valid through lookup/preview/transaction, placeholder tokens are invalid, and confirmWrite must follow explicit user confirmation. It does not explicitly name alternatives or exclusions, such as using a batch tool for multiple products, so it stops 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?

Annotations only say destructiveHint=true and readOnly=false; the description adds crucial behavioral detail: without confirmWrite:true the call returns confirmation_required and a preview, preflight is not confirmation, placeholder tokens are invalid, and 'Nothing is written to Big Red Cloud until you confirm.' This is substantial transparency beyond 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?

Every sentence serves a purpose: purpose, token requirement, confirmation semantics, and counterparty scoping. It is longer than average, but the tool is high-risk and complex; there is no redundancy or filler.

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

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

For a complex 18-parameter destructive tool with no output schema, the description covers the full decision flow: what happens without confirmWrite, what confirmWrite does, what preflight does not do, token validity, and counterparty confirmation requirements. Combined with the fully-described schema, 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics for the most safety-critical parameters: confirmWrite must follow a plain-English preview plus explicit confirmation, confirmCounterpartyExplicit must be tied to the currently selected counterparty, and routeToken grants routing permission only. This is valuable nuance beyond the schema fields.

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

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

The description opens with a specific verb and resource: 'Creates a purchase' and immediately distinguishes the caller-supplied reference mode from the likely auto-reference sibling brc_create_purchase_gen_ref by tying it to 'manual purchase references are configured.' An agent can identify what this tool does and why it differs from nearby create-purchase 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 clear conditions: caller-supplied reference only when manual references are configured, a valid routeToken is required, and confirmWrite/confirmCounterpartyExplicit must follow explicit user confirmation. It does not explicitly name brc_create_purchase_gen_ref as the alternative for automatic references, but the manual-configuration condition makes the appropriate usage sufficiently 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?

Beyond annotations, it discloses the mutation guardrail: no write until confirmWrite:true after explicit confirmation, first call returns confirmation_required with a preview, and confirmation is scoped to the selected counterparty. This is exactly the behavioral context needed for a destructive write tool.

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

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

The description is seven dense, load-bearing sentences: purpose first, then token requirements, then confirmation behavior. No filler, no repetition of schema properties, and every sentence adds safety-relevant 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?

The description covers the highest-risk aspects completely: token validity, preview, explicit confirmation, counterparty scoping, and preflight caveat. It does not describe the return shape after confirmWrite or the remaining field semantics, but the transaction flow is the main hazard and is well specified.

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?

It adds meaningful semantics for routeToken, confirmWrite, and confirmCounterpartyExplicit, but those are also documented in the schema. With only 29% schema coverage, many required fields such as acCode, procDate, bookTranTypeId, and analysisCategoryId are left to name-based inference, so the description only partially compensates.

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 clear action ('Creates a purchase') and the specific mode ('using the company's generated-reference configuration'), which distinguishes it from brc_create_purchase without naming it. It does not explicitly call out the sibling alternative, so it stops short of full differentiation.

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 strong operational context: a valid routeToken for the matching workflow, token validity scope, and the confirmWrite two-step process. It also explicitly excludes shortcuts ('does not bypass preview or explicit-confirmation', 'Passing preflight is not confirmation'), but it does not state when to pick this tool over the plain purchase or other create variants.

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 annotations by disclosing that a call without confirmWrite:true returns confirmation_required with a payload preview, that preflight is not confirmation, and that a routeToken does not bypass preview or explicit-confirmation requirements. It also clarifies the scope of confirmCounterpartyExplicit, which is highly non-obvious behavior.

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 purpose and then logically progresses through token requirements, preview behavior, and confirmation constraints. It is dense but focused; slight redundancy with schema-level descriptions is acceptable given the transactional complexity.

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 30-parameter transactional tool with no output schema and sparse schema coverage, the description covers the highest-risk operational aspects: routeToken validity, preview-before-posting, explicit confirmation, and counterparty confirmation scoping. It does leave gaps in how the many required fields interrelate and what a successful response looks like, but the core call sequence is well specified.

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

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

Schema description coverage is only 40%, so the description must compensate, but it only partially does. It groups product, VAT, and Sales-analysis fields into reconciled lines and explains routeToken/confirmWrite semantics, yet most required parameters such as customerOwnerId, acCode, entryDate, procDate, saleRepId, and similar fields receive no meaningful descriptive help beyond their raw names.

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 opening sentence names the exact operation ('Creates a quote') and specifies a 'caller-supplied reference' and 'reconciled product, VAT and Sales-analysis lines.' This clearly distinguishes the tool from its auto-reference sibling brc_create_quote_gen_ref and from other create_* 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 provides clear invocation context: a valid routeToken for the matching action workflow is required, and the two-phase preview/confirmWrite flow is explained. It does not explicitly name alternatives or exclusions, but the caller-supplied reference trait implies when this tool, rather than the generated-reference variant, is appropriate.

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

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

Annotations only say readOnlyHint=false, openWorldHint=false, destructiveHint=false. The description adds critical behavioral context: token validity scope, placeholder token invalidity, the two-phase confirmWrite semantics, and that the token does not bypass preview/confirmation. It doesn't fully disclose error cases or idempotency, but given the annotations are minimal, the description carries the burden well. Minor deduction for not explaining what happens to reconciled lines if a parameter is invalid.

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

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

The description is a dense single paragraph covering purpose, token requirements, confirmation semantics, and counterparty confirmation. It front-loads the primary purpose and then details the workflow guards. Slightly verbose in places (repeated emphasis on explicit confirmation), but every sentence adds operational value.

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

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

For a high-complexity transactional tool with 30 params and no output schema, the description covers the essential workflow, token, and confirmation semantics. It doesn't describe the output/return payload (confirmation_required is mentioned but full response shape is not), and it doesn't enumerate prerequisites like company connection. However, given the schema covers many params and the description addresses the riskiest aspects, it 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?

Schema coverage is only 40%, so the description must compensate. The description explains the routeToken semantics (routing permission only), the confirmWrite semantics, confirmCounterpartyExplicit, and confirmQuotesAutoGenerateInBrc's purpose. It does not walk through all 30 params, but the critical workflow-guarding params are well explained. The description adds real meaning beyond the schema for the confirmation-related parameters.

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

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

The description states it creates a quote with generated references and reconciled product/VAT/Sales-analysis lines, distinguishing it from brc_create_quote (manual reference) and siblings with _gen_ref suffix. It clearly identifies the resource (quote) and the action (create). It could be sharper about why this tool vs brc_create_purchase_gen_ref or brc_create_sales_invoice_gen_ref, but the verb+resource is clear.

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 the workflow prerequisites: requires a valid routeToken from brc_route_request, requires confirmWrite: true only after explicit confirmation, requires confirmCounterpartyExplicit: true, and explains that passing preflight is not confirmation. It also explains the confirmation_required response path. This gives an agent clear when-to-use and when-to-confirm 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 extensively discloses behavioral requirements beyond the annotations: the routeToken flow, its validity, that it does not bypass preview/confirmation, the confirmWrite semantics, and the confirmCounterpartyExplicit requirement. It also clarifies that passing preflight is not confirmation and that nothing is written until confirmWrite. This is rich, non-obvious context that greatly helps the agent.

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

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

The description is detailed but well-structured, front-loading the core purpose and then logically progressing through token, preview, and confirmation requirements. Each sentence adds meaningful information; it is not padded. It could be slightly more compact, but given the complexity of the workflow, the length is justified.

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 25 parameters, 20 required, and no output schema, the description covers the critical confirmation workflow and routeToken handling well. However, it does not describe the success response format, error scenarios beyond confirmation_required, or date/format constraints. An agent may still be uncertain about what a successful confirmWrite returns or how to handle validation errors, leaving incomplete guidance for a complex mutation.

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

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

Schema description coverage is only 32%, and the description does not compensate by explaining most parameters. It mentions 'caller-supplied reference' and 'negative document amounts' at a high level, but does not describe key fields like companyName, customerId, acCode, dates, product, etc. The description adds little semantic value beyond what the schema already provides for the few covered 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 the action (creates a sales credit note) and adds specific characteristics (caller-supplied reference, reconciled negative document amounts). It does not explicitly mention sibling alternatives like brc_create_sales_credit_note_gen_ref or brc_update_sales_credit_note, so it lacks explicit differentiation, but the verb and resource are unambiguous.

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

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

There is no explicit guidance on when to use this tool versus alternatives such as batch creation or gen_ref tools. It discusses prerequisites (routeToken, confirmation) but not the situational context for choosing this tool over others. An agent would have to infer that this is the single-document create path.

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

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

Annotations only say destructive/non-read-only; the description adds the routeToken lifecycle, placeholder invalidity, confirmation_required return behavior, preview application semantics, and the rule that preflight is not confirmation. This significantly exceeds annotation coverage and contains no contradiction.

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

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

Seven sentences, all substantive and front-loaded with purpose then token and confirmation behavior. It is dense but appropriately so for a destructive transactional tool; a little tightening of repeated confirmation concepts would push it higher.

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 transactional tool with nested payload and no output schema, it covers token lifecycle, write barier, confirmation flow, and counterparty scoping unusually well. It does not explain payload construction or the success return shape, but the routeToken workflow implies the payload comes from earlier stages, so the gap is tolerable.

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 high (86%) and the schema already documents routeToken, confirmWrite, connectionRef, and confirmCounterpartyExplicit in detail. The description adds workflow-level meaning by tying these parameters to stages (lookup, preview, transaction) and clarifying confirmation_required outputs, which is valuable but not a full replacement for per-parameter detail.

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

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

Names a specific verb ('creates') and resource ('sales credit note'), and adds the distinguishing traits 'generated references' and 'reconciled negative document amounts.' This makes it identifiable against sibling tools like brc_create_sales_credit_note even though that sibling isn't explicitly referenced.

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 an explicit operational workflow: valid routeToken required, preview and explicit confirmation not bypassable, confirmWrite true semantics, preflight-vs-confirmation distinction, and confirmCounterpartyExplicit. It does not name the alternative non-gen_ref credit note tool or state when to choose it, so it stops short of full exclusions.

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

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

The description richly discloses behavior beyond the annotations: routeToken validity and placeholder-token rejection, the confirmation_required preview path, the exact meaning of confirmWrite: true, the fact that preflight is not confirmation, and scoping of counterparty confirmation. This is exactly the kind of non-obvious confirmation behavior an agent needs.

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 dense and front-loaded with the purpose, followed by critical routing and confirmation constraints. Every sentence contributes a real behavioral rule, so there is no filler. It could be more scannable as bullets, but it is appropriately sized for a tool with this confirmation complexity.

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

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

For a 17-parameter tool with no output schema, the description covers the trap-prone part of the workflow well: routeToken requirements, preview/confirmation, and counterparty-confirmation scoping. It does not describe the successful post-confirm response or field-level formats for dates/codes, which leaves some gaps for an agent, but the core invocation flow is 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 description adds meaningful semantics for routeToken, confirmWrite, and confirmCounterpartyExplicit, including validity windows and explicit-confirmation rules. But schema description coverage is only 29% and the remaining 14 required params (entryDate, procDate, acCode, accountCode, netAmount, vatRateId, etc.) get no explanation beyond their names and types, so the description only partially compensates for the low 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 opens with a specific verb and resource: 'Creates a BRC sales entry'. This clearly separates the tool from get/update/delete sales-entry tools, and the sales-entry resource is distinct from sales-invoice or credit-note. It does not explicitly contrast with brc_batch_sales_entries or brc_create_sales_invoice, so sibling differentiation is incomplete.

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 workflow context: you need a valid routeToken from the matching action workflow, must preview first, and must set confirmCounterpartyExplicit/confirmWrite only after explicit user confirmation. However, it never states when to choose this tool instead of brc_batch_sales_entries or brc_reate_sales_invoice, so it relies on the agent to infer the boundary.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false; the description goes far beyond them by disclosing token validity windows, placeholder token invalidity, the fact that a routeToken does not bypass preview or confirmation, that a call without confirmWrite returns confirmation_required plus a payload preview, that passing preflight is not confirmation, and that counterparty confirmation is scoped to the current preview. No contradiction with the annotations exists.

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

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

The description is dense (~130 words) and front-loaded with the core action before moving into the confirmation protocol. Every sentence carries operational weight; the mild redundancy between 'A routeToken does not bypass preview or explicit-confirmation requirements' and 'Passing preflight is not confirmation' is acceptable given the financial impact of misconfirmation.

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 28-parameter, no-output-schema tool, the description covers the critical return behavior of the pre-confirmation call (confirmation_required plus payload preview) and the full token/preview/confirm lifecycle. It does not describe the final success response shape or the concrete preview payload contents, and several required accounting params remain unexplained; however, the workflow hazards most likely to cause agent errors (invalid tokens, premature confirmation, unconirmed counterparties) are thoroughly addressed.

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 57%, so the description must partially compensate. It adds meaning for reference ('caller-supplied reference'), customer contact behavior ('Missing customer contact values remain absent'), and the token/confirmation flags, but it says nothing about the undocumented accounting fields (acCode, entryDate, procDate, bookTranTypeId, analysisCategoryId, accountCode, customerId, vatPercentage), which remain semantically empty in both the schema and the 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 opens with a specific verb and resource: 'Creates a sales invoice with a caller-supplied reference and reconciled product, VAT and Sales-analysis lines.' This precisely distinguishes it from sibling create tools like brc_create_sales_entry and brc_create_sales_credit_note, and from brc_create_sales_invoice_gen_ref which only generates a reference rather than creating the invoice.

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 establishes a clear workflow context: a routeToken from brc_route_request that remains valid through lookup, preview and the permitted transaction, plus an explicit two-phase confirmation protocol (confirmWrite: true only after preview and explicit confirmation; confirmCounterpartyExplicit required). However, it never names sibling alternatives such as brc_batch_sales_invoices or brc_generate_sales_invoice_from_quote, so tool-selection among create-variants is left to inference rather than explicit routing.

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

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

Annotations only expose destructiveHint=true/readOnlyHint=false, so the description carries the burden and carries it exceptionally well: it discloses token validity scope, that placeholder tokens are invalid, that a token does not bypass preview/confirmation, the exact two-phase confirmWrite behavior, that preflight is not confirmation, and the counterparty-confirmation scoping. It also reveals the side effect that missing customer contact values remain absent. 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 a dense single paragraph but well ordered: purpose first, then token lifecycle, then preview/confirm protocol, then counterparty scoping. Nearly every sentence earns its place. Minor redundancy exists with the schema's routeToken and confirmWrite parameter text, but the description stands alone appropriately for a tool this complex.

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

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

This is a complex transactional tool (8 parameters, deep nested payload, destructive, confirmation-gated) with no output schema, so the description must cover the operational protocol — and it does, thoroughly: token requirements, the non-confirmed return shape, the preflight caveat, and counterparty confirmation scoping. The one gap is that the success-path return (what confirmWrite true ultimately yields, e.g. the created invoice identifier) is never 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 baseline is 3. The description mostly reinforces what the schema already states about routeToken, confirmWrite, and confirmCounterpartyExplicit rather than adding new per-parameter meaning. It does add one behavioral detail — that a non-confirmed call returns confirmation_required with a payload preview — but does not elaborate on formats, dates, or success-path outputs.

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 opening sentence states a specific verb and resource: 'Creates a sales invoice using generated references and reconciled product, VAT and Sales-analysis lines.' The 'generated references' qualifier captures the distinguishing trait of the gen_ref variant. However, it never names or contrasts the siblings brc_create_sales_invoice (non-generated reference) or brc_generate_sales_invoice_from_quote, leaving the agent to infer the difference.

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

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

There is dense operational guidance: a valid routeToken is required, calls without confirmWrite true return confirmation_required plus a preview, preflight is not confirmation, and confirmCounterpartyExplicit must be true. But the description gives zero guidance on when to choose this tool over brc_create_sales_invoice or brc_generate_sales_invoice_from_quote, which are the key selection decisions an agent faces.

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?

Goes well beyond the annotations by detailing the routeToken lifecycle, invalid placeholder tokens, preview-only behavior without confirmWrite, and the requirement that confirmWrite:true must follow explicit user confirmation. The warning that 'passing preflight is not confirmation' adds important safety context. This is substantial behavioral disclosure.

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 first sentence states purpose immediately, followed by logically ordered constraints on routeToken and confirmWrite. Every sentence carries operational information with no filler. The density is justified for a transactional tool with confirmation requirements.

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

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

Covers the essential invocation context: prerequisite routeToken, confirmation gate, preview behavior, and first-call semantics. The input schema handles individual parameter details well. It does not describe the success response payload, and there is no output schema, but the critical safety and workflow context is present.

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

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

Schema coverage is 100% with already-detailed parameter descriptions, so the baseline is 3. The description adds workflow-level semantics for confirmWrite and routeToken validity, including invalid placeholders and the relationship between preview and confirmation. It supplements rather than merely repeats 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 precise verb and resource — 'Creates a BRC sales rep' — which clearly distinguishes it from the update, delete, list, and batch sales rep sibling tools. The title reinforces the same action. There is no ambiguity about what entity is created.

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

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

Provides explicit prerequisites: a valid routeToken issued for the matching action workflow and sourced from brc_route_request. It also explains the confirmWrite workflow and preview requirement. It does not explicitly name alternatives or conditions for when not to use this tool in favor of brc_update_sales_rep or brc_batch_sales_reps, 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?

Annotations only indicate readOnly=false and destructive=false. The description goes far beyond that by explaining the two-phase write flow: without confirmWrite, the call returns confirmation_required and a payload preview; confirmWrite applies the previewed change only after explicit confirmation. It also warns that placeholder tokens are invalid, routeToken does not bypass preview, and preflight is not confirmation.

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 core action and packed with dense, useful caveats. Every sentence contributes value, though there is slight redundancy between 'Does not create or update opening balance transactions' and 'Opening-balanace fields are not possted by this tool', which prevents a perfect 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 mutation tool with no output schema, the description covers the entire call flow: routeToken provenance and validity, placeholder invalidity, the preview/confirmation contract, the response to an unconfirmed call, and the opening-balanace exclusion. The schema already covers companyName and connectionRef, 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 baseline is 3, but the description adds meaning beyond the schema by explaining routeToken validity through lookup, preview, and the permitted transaction, and by clarifying that passing preflight is not the same as user confirmation. These nuances enrich the semantics of confirmWrite and routeToken beyond their schema descriptions.

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

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

The description opens with a specific verb and resource ('Creates a BRC supplier using a raw BRC payload'), making the tool's core function unmistakable. It also explicitly distinguishes itself from opening-balanace tools by stating that opening-balanace fields are not possted by this tool, removing ambiguity against sibling get/list supplier opening-balanace 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 clear usage context: it creates a single supplier, does not handle opening balances, and requires a routeToken with the full preview/confirmation workflow. It does not name a specific alternative tool like brc_batch_suppliers, but the opening-balanace exclusion and the explicit preconditions are sufficient guidance for an agent.

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

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

The description richly discloses behavior beyond the annotations: routeToken validity scope, placeholder token invalidity, the non-bypass of preview/confirmation, and the exact confirmation_required + preview response when confirmWrite is omitted. This is especially valuable because the tool is destructive and the description clarifies the safety flow.

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 primary purpose and then provides sequenced workflow details. It is somewhat dense and repeats the confirmation theme a couple of times, but overall each sentence contributes meaningful information for a destructive transactional tool.

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

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

Given six parameters, no output schema, and a destructive operation, this description covers the essential workflow: obtaining/using a routeToken, previewing, explicit confirmation via confirmWrite, and the consequence of not passing it. The remaining details, such as connectionRef, are adequately documented in the schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning to the timestamp (concurrency constraint), routeToken (workflow scoping and invalidity of placeholders), and confirmWrite (explicit-confirmation semantics). This goes beyond the raw schema descriptions, though it does not deeply explain every parameter.

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 concrete verb and resource: 'Deletes an accrual using its current concurrency timestamp.' This clearly identifies the operation and its distinguishing requirement. It is not a tautology and is easily differentiated from get/update/list accrual 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 strong contextual usage guidance: it requires a routeToken, a confirmWrite: true after explicit user confirmation, and explains that preflight is not confirmation. It does not explicitly name alternative tools or say when not to use this tool, but the transactional workflow 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?

Annotations already indicate destructiveHint=true, and the description goes well beyond that by explaining the two-step behavior: without confirmWrite: true the call returns confirmation_required and a preview; with confirmWrite: true it applies the previewed change after explicit confirmation. It also discloses that routeToken does not bypass preview or confirmation, placeholder tokens are invalid, and preflight is not confirmation. This gives a thorough behavioral contract for a destructive tool.

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

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

The description is compact and front-loaded with the core operation, then efficiently adds token validity, placeholder-token caveat, preview/confirmation flow, and the preflight distinction. Each sentence contributes a distinct fact needed for safe invocation, with no repetition or filler.

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

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

Given there is no output schema, the description covers the most important runtime behavior: the unconfirmed preview, confirmation_required response, and the effect of confirmWrite: true. It also addresses token lifecycle and connection context implicitly through the routeToken requirements. It does not spell out the exact success/error shape after confirmWrite: true, but the preview/confirm cycle is sufficiently described for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, so the schema already documents every parameter. The description adds meaningful semantics for two key parameters by explaining how confirmWrite controls preview vs. application, and how routeToken relates to the action workflow and does not replace preview/confirmation. This enriches the parameter model beyond the schema descriptions without needing to repeat id or companyName.

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

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

The description opens with a specific verb and resource: 'Reverses or deletes the specified allocation after returning an unconfirmed preview.' This clearly identifies the operation as a delete/reverse action on an allocation resolver, which distinguishes it from the many other delete_* sibling tools. The preview/confirmation workflow further differentiates it from simpler delete tools in the same family.

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 workflow context: a valid routeToken is required, the token remains valid through lookup, preview and the permitted transaction, and confirmWrite: true is needed only after explicit confirmation. It does not explicitly name alternative tools or state when-not-to-use, but the delete-via-preview workflow is unambiguous enough for an agent to follow.

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 destructiveHint: true and readOnlyHint: false, and the description aligns by stating deletion. Beyond the annotations, it discloses the routeToken validity window (valid through lookup, preview, and the permitted transaction), that placeholder tokens are invalid, that the token does not bypass preview or confirmation, and that preflight is not confirmation. This is rich behavioral disclosure. The only gap is that the confirmDelete parameter appears in the schema but is never explained in the description, leaving ambiguity about which flag actually triggers the deletion.

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 purpose and every subsequent sentence carries safety or workflow information relevant to a destructive transactional call. There is mild redundancy (placeholder-token invalidity restates the valid-token requirement, and confirmation is reiterated several times), but the repetition is justified for a tool where the confirmation requirement is the critical property an agent must not miss.

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

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

With no output schema and a 6-parameter destructive operation, the description carries the burden of explaining behavior, and it covers the critical path well: preconditions (routeToken), the two-phase preview/confirmation flow, and one return case (confirmation_required with preview). It falls short of complete because it never describes the success-path response and leaves confirmDelete undefined, but the safety-critical aspects an agent needs to avoid an unintended deletion are thoroughly covered.

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 83%, so the baseline is 3 and the schema already documents routeToken, companyName, confirmWrite, and connectionRef well. The description adds genuine value by explaining the confirmWrite mechanism (confirmation_required response, preview payload, preflight caveat) and the token's validity window. However, confirmDelete has no schema description and gets zero mention in the tool description, so its interaction with confirmWrite remains unclear — a meaningful gap the description does not compensate for.

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 opening sentence, 'Deletes the specified bank account after explicit confirmation,' names a specific verb and resource and adds a distinctive qualifier (explicit confirmation) that sets this apart from plain lookup or update tools. Among the many delete_* siblings, it is unambiguously the bank-account deleter, clearly distinguishable by resource and by the transactional confirmation workflow it describes.

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 strong when-to-use guidance through the workflow it prescribes: a valid routeToken is required, a call without confirmWrite: true returns confirmation_required with a payload preview, and confirmWrite: true applies the change only after explicit confirmation. It also warns that preflight is not confirmation. It does not explicitly name alternative tools or exclusion conditions, so it stops short of a 5, but the context for correct usage is clearly established.

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 (destructiveHint=true, readOnlyHint=false), the description reveals the full two-phase behavior: a call without confirmWrite:true returns confirmation_required with a payload preview, confirmWrite:true applies the previewed change only after explicit confirmation, passing preflight is not confirmation, and tokens stay valid through lookup/preview/transaction. This is exactly the kind of behavioral nuance annotations cannot convey.

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

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

Seven sentences, every one carrying information — core action first, then token lifecycle, then the confirmation gate. Dense but warranted for a destructive transactional tool with a preview-before-posting workflow; zero filler.

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

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

For a destructive tool with no output schema, the description covers the essential operational context: token requirements, invalidity conditions, preview obligation, and the confirmation semantics. The one real hole is confirmDelete, a parameter present in the schema with only a default and no explanation in either schema or 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?

Schema coverage is high (83%), and the description adds real semantic value on top for the two most critical parameters: routeToken (placeholder tokens invalid, validity window across the workflow) and confirmWrite (what happens with and without true). The notable gap is confirmDelete, which has no schema description and is never mentioned in the tool description, leaving its relationship to confirmWrite ambiguous.

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 opening sentence states a specific verb, resource, and key ('Deletes a BRC cash payment by id'), making the core action unambiguous. However, it never explicitly differentiates from sibling delete tools such as brc_delete_cash_receipt or brc_delete_payment; the resource name 'BRC cash payment' does that work only implicitly.

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 clear conditions for valid use: a valid routeToken issued for the matching action workflow, placeholder tokens rejected, and confirmation after a plain-English preview. It stops short of naming alternatives or stating exclusions ('use X instead when...'), but the prerequisite context is concrete and 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 mark the tool destructive, and the description adds substantial behavioral detail: token validity through lookup/preview/transaction, placeholder-token invalidity, no bypass of preview or explicit confirmation, the confirmation_required response pattern, and the fact that preflight does not count as confirmation.

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 core action and then packs only essential caveats into six dense sentences. There is no filler; each sentence contributes either prerequisite, token behavior, or confirmation semantics.

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

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

For a destructive transaction tool with no output schema, the description covers the essential workflow: routeToken requirement, preview, confirmation_required response, and confirmed execution. The main gap is that confirmDelete is left unexplained and the successful-deletion response is not described.

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 high at 83%, so the baseline is 3. The description adds useful meaning for routeToken and confirmWrite, but the confirmDelete parameter has no schema description and is never mentioned in the description, leaving an important destructive-confirmation flag ambiguous.

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 'Deletes a BRC cash receipt by id,' which names a specific verb, resource, and key selector. This is enough to distinguish it from sibling tools like brc_delete_cash_payment or brc_update_cash_receipt.

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 clear operational prerequisites: a routeToken from brc_route_request is required, preflight is not confirmation, and confirmWrite controls whether the previewed change is applied. It does not explicitly name alternatives or when not to use the tool, but the conditions for correct use are 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 destructiveHint=true and readOnlyHint=false, but the description goes well beyond by explaining token validity, placeholder invalidity, that routeToken does not bypass preview/confirmation, the confirmation_required response, and that preflight is not confirmation. 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?

Six dense sentences, each carrying essential information. The main action is front-loaded, and every sentence explains a required nuance without wasting words.

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

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

For a destructive transactional tool with no output schema, the description covers prerequisites (routeToken, confirmWrite), the confirmation flow, the non-confirmation nature of preflight, and the expected response (confirmation_required with payload preview). 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?

Schema coverage is 83%, so the schema already documents most parameters. The description adds crucial behavioral meaning for routeToken and confirmWrite, explaining their interplay and the exact confirmation requirement — value not present in 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 opens with 'Deletes a BRC customer by id' — a specific verb, resource, and mechanism. This clearly distinguishes it from the many other brc_delete_* tools in the sibling list, which target different entities.

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 conditions for use: requires a valid routeToken, the token's lifecycle, the invalidity of placeholders, and the exact confirmWrite semantics. It does not explicitly name alternatives or when not to use the tool, but for a delete transaction the workflow guidance is unusually precise.

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