Red by Big Red Cloud

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

With no annotations, the description fully explains the two-step write process, preview behavior, and confirmation requirements. It discloses that preflight is not confirmation and that nothing is written until confirmed. Could mention error handling or side effects, but overall good transparency.

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 well-structured, starting with purpose then detailed workflow. Every sentence adds value, though could be slightly more concise. No redundancy.

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 all parameters, workflow, and confirmation steps. Lacks output format or error handling, but without output schema this is acceptable. Complete for a batch creation tool with complex confirmation logic.

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

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

Schema coverage is 100%, and the description adds significant meaning: for confirmWrite and confirmCounterpartyExplicit, it gives precise conditions for setting true; for connectionRef, explains reuse policy; for priceBasis, explains gross vs net. Adds 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 the tool processes a batch of BRC cash payments and specifies a max of 20 items. It does not explicitly differentiate from sibling batch tools like brc_batch_payments, but the focus on cash payments and the detailed workflow make the purpose 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?

Provides explicit step-by-step instructions: first call without confirmWrite, show preview, get explicit user confirmation, then retry with confirmWrite: true. Also specifies confirmCounterpartyExplicit requirements. Offers clear do's and don'ts, e.g., 'Do not reuse a counterparty from an earlier preview without that confirmation.'

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?

No annotations provided, so description carries full burden. It discloses the batch processing, max limit, and the critical confirmation workflow (preview then confirm). It explicitly states 'Nothing is written to Big Red Cloud until you confirm'. It also explains the counterparty confirmation requirement. However, it doesn't detail error handling or return format.

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 paragraph but contains all necessary instructions. It is front-loaded with the core purpose. While it could be structured with bullet points, every sentence earns its place and there is no redundancy.

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 batch tool with complex confirmation workflow and no output schema, the description covers key aspects: batch limit, preview requirement, confirmation flags, and counterparty confirmation. It lacks details on error responses or the preview format, but overall sufficiently complete for the complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the two-step confirmation workflow and conditions for setting confirmWrite and confirmCounterpartyExplicit. It also clarifies priceBasis in context. This adds meaning beyond schema.

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

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

The description clearly states 'Processes a batch of BRC cash receipts', which is a specific verb+resource. It distinguishes from siblings like brc_batch_cash_payments and brc_create_cash_receipt (single operation). The batch nature is explicit.

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 and how-to-use guidelines: maximum 20 items, two-step confirmation process, preview before posting, requiring explicit user confirmation. It also states what not to do (e.g., never set confirmWrite true on first call).

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?

No annotations provided, so description fully covers behavioral traits: preflight flow, write only after confirmation, max 20 items, and that passing preflight is not confirmation. No contradictions.

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

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

Front-loaded with main action, then key constraints and flow. Every sentence adds value, though could tighten some phrases. No unnecessary 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?

Lacks details on return values after successful confirmation, error handling, and what happens if preflight is not confirmed. No output schema to compensate.

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

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

Schema coverage is 100%, so baseline 3. Description adds some value by explaining the confirmWrite flow and priceBasis context, but much of this is already in schema descriptions. Does not significantly extend beyond schema.

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

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

Clearly states it processes a batch of customers, with specific verb and resource. Differentiates from siblings like brc_create_customer and other batch tools via the preflight confirmation flow.

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

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

Explicitly details the two-step process: first call without confirmWrite returns a preview requiring user confirmation, then retry with confirmWrite true only after explicit confirmation. Warns that preflight is not confirmation.

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?

Fully describes the tool's behavior: preflight returns confirmation_required and preview, nothing is written until confirmWrite is true, and the counterparty must be explicitly confirmed. No annotations are provided, so the description carries the full burden and meets it well.

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

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

The description is detailed but front-loads critical info (max items, workflow). It could be slightly more concise, but every sentence adds necessary context for correct tool usage.

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 main workflow, batch limits, and confirmation steps. Does not detail error handling or output format, but given no output schema, the description provides sufficient context for an agent to use the tool correctly.

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

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

Adds significant meaning beyond the schema descriptions, tying confirmWrite and confirmCounterpartyExplicit to the workflow, explaining the connectionRef reuse, and the conditional nature of confirmCrAnalysisCategory. With 100% schema coverage, it still adds value.

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

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

The description clearly identifies the tool as processing BRC payments in batches, specifying maximum items and the unique confirmation workflow. It distinguishes itself from sibling batch tools like brc_batch_cash_payments by focusing on payments.

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

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

Explicitly states the two-step process (first call without confirmWrite returns preview, then confirm only after user confirmation), sets max items, and requires confirmCounterpartyExplicit after explicit user naming. Provides clear when-to-use and when-not-to-use guidance.

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

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

With no annotations provided, the description carries full burden. It discloses the preflight/confirm pattern and that nothing is written until confirmWrite=true. However, it doesn't explicitly state what type of write occurs (create/update) or potential side effects. The phrase 'Red shows what it will post' is slightly unclear.

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

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

The description is somewhat run-on and could be tightened (e.g., 'Red shows...' and 'Passing preflight is not confirmation' are redundant). However, it contains all necessary information in a few sentences; no unnecessary 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?

Given 6 parameters fully described in the schema, the description covers the critical behavioral pattern and batch limit. No output schema exists, but it describes return values for the first call. For the second call, return is not specified, but the tool is adequately complete for its role among sibling batch tools.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value for confirmWrite (explaining the two-phase process) and max items (though already in schema). Other parameters like priceBasis, companyName, connectionRef, and confirmCrAnalysisCategory are only described in the schema, not in 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 states 'Processes a batch of products' and sets a maximum limit of 20 items, clearly indicating the tool's purpose. It distinguishes from individual product tools like brc_create_product by being batch-oriented, though 'processes' is somewhat vague (could mean create/update/delete).

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

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

Excellent guidance on the two-phase commit pattern: first call without confirmWrite to get a preview, then retry with confirmWrite=true only after explicit user confirmation. Warns that preflight is not confirmation, and notes the maximum batch size. No other sibling tool description provides such clear usage instructions.

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 no annotations provided, the description fully discloses the batch confirmation workflow, data preview requirement, counterparty confirmation, and that nothing is written until confirmed. No hidden behaviors.

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 paragraph with mixed instructions. It front-loads the main action but could be more structured (e.g., bullet points). Some repetition (max items appears twice).

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 workflow and parameter usage well. Does not describe return values or error handling, but the two-step confirmation implies a preview response. For a complex batch tool, it provides a solid foundation.

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

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

Schema coverage is 100%, so baseline 3. The description adds significant context for confirmWrite (never on first call) and confirmCounterpartyExplicit (only after explicit user confirmation), going beyond the schema. Other parameters like priceBasis are well-covered in 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 it processes a batch of purchases, which distinguishes it from single-purchase tools like brc_create_purchase. However, it doesn't explicitly differentiate among sibling batch tools like brc_batch_sales_invoices, but the 'purchases' resource is specific.

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?

Excellent guidelines: explains the two-step confirmation workflow, when to set confirmWrite and confirmCounterpartyExplicit, and warns against premature confirmation. Provides explicit when-to-use and when-not-to-use instructions.

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 no annotations, the description fully discloses the two-step confirmation process, preview requirement, and that nothing is written until confirmWrite is true. Also explains reusing connectionRef and not assuming counterparty without explicit 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 lengthy but each sentence adds value. It is front-loaded with purpose and then provides detailed usage rules. Slightly verbose but well-structured.

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

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

Given 7 parameters, no output schema, and the complexity of the batch quote process, the description covers all necessary behavioral context, including preview, confirmation steps, and counterparty handling.

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?

All parameters have schema descriptions (100% coverage), but the description adds behavioral nuance for confirmWrite and confirmCounterpartyExplicit, and clarifies connectionRef usage 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 'Processes a batch of quotes' and specifies the maximum of 20 items, distinguishing it from other batch tools like brc_batch_sales_invoices.

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 instructions on when to set confirmWrite (only after preview and user confirmation), not to set on first call, and the need for confirmCounterpartyExplicit after user explicitly names counterparty. Also warns about reusing connectionRef.

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?

No annotations exist, so the description carries full burden. It clearly states that productId 0/1 are blocked, the preview-before-posting flow, and confirmation requirements. However, it does not describe error handling or the exact return format after posting, which could be useful.

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

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

The description is lengthy but every sentence serves a purpose: it starts with the main action, lists critical rules, then explains the confirmation process. No wasted words, well-structured for easy digestion.

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

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

Given the complexity of batch processing with multi-step confirmation, the description covers product rules, batch limit, preview-flow, and counterparty confirmation. It lacks details on post-posting response and error handling, but overall it is sufficiently complete for effective 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 coverage is 100% and the description adds significant value beyond the schema for key parameters like items (max 20), priceBasis (when to use net/gross), confirmWrite (detailed steps), and confirmCounterpartyExplicit (conditions). This goes beyond mere schema repetition.

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 it processes a batch of sales credit notes, which differentiates it from siblings like brc_batch_sales_invoices. However, it does not explicitly contrast with all similar batch tools, so it stops short of a 5.

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

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

The description provides explicit when-to-use and when-not-to-use guidelines: do not invent or use placeholder productIds, call brc_list_products first, ask user if no suitable product, max 20 items, two-step confirmWrite process with preview, and confirmCounterpartyExplicit only after explicit user confirmation. This is comprehensive and leaves no ambiguity.

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

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

Fully discloses the two-phase write flow, the need for a plain-English preview, and the distinction between preflight and confirmation. No annotations provided, so the description carries the full burden and handles it comprehensively.

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

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

The description is informative but somewhat lengthy. It front-loads the purpose and constraints but could be more concise. However, every sentence adds necessary detail for correct invocation.

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

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

Covers the essential protocol for a safe write operation, including the preview and confirmation steps. Lacks detail on the return value or error cases, but given the complexity and no output schema, it is largely sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description adds valuable context for confirmWrite and confirmCounterpartyExplicit beyond the schema, explaining their correct usage in the confirmation flow. Other parameters are well-described in 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 'Processes a batch of sales entries' and distinguishes from sibling batch tools like brc_batch_sales_invoices. It also details the confirmation flow, making the tool's unique purpose 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?

Provides explicit step-by-step instructions: maximum 20 items, first call without confirmWrite, then retry with confirmWrite after user confirmation, and requires confirmCounterpartyExplicit after explicit counterparty confirmation. Gives clear when-to-use and when-not conditions.

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 no annotations, the description fully covers behavioral traits: placeholder blocking, VAT validation, price basis handling, CR analysis confirmation, counterparty confirmation, note/deliveryTo defaults, productId constraints, and the confirmWrite workflow. No contradictions.

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 relatively long and has some repetition (e.g., productId 0/1 blocking mentioned twice), but it is logically structured starting with purpose then detailing checks. It could be more concise for quicker parsing.

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

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

Given the complexity (7 parameters, no output schema), the description thoroughly covers the workflow, safety checks, and parameter behaviors. It explains the two-step confirmation and hints at the return payload, making it complete for an AI agent.

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

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

Schema coverage is 100%, but the description adds significant behavioral context beyond parameter descriptions, such as explaining when confirmWrite must be true, the requirement for confirmCounterpartyExplicit, and the default for note. This adds 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 the tool processes a batch of sales invoices and distinguishes it from single invoice tools by specifying the batch behavior and safety checks. Sibling tools include brc_create_sales_invoice for single invoices, so the batch scope is explicit.

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 guidelines on when to use this tool, such as calling brc_list_products for productId, and outlines the two-step confirmWrite pattern. However, it does not explicitly contrast with other batch tools like brc_batch_sales_credit_notes, though the invoice focus 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?

No annotations provided, so description carries full burden. It clearly discloses the non-write behavior on first call (returns confirmation_required and preview) and that only after explicit confirmation does writing occur. Adds nuance that 'passing preflight is not confirmation'. This is good transparency for the critical 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?

Description is concise with 4 sentences, each adding value: purpose, batch limit, confirmation workflow, and a caution about preview. Front-loaded and no wasted 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?

No output schema and description does not mention return values after confirmation, error handling, or side effects. For a batch processing tool, this leaves gaps in understanding the complete behavior. The confirmation flow is well explained, but completeness is lacking.

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 covers all 6 parameters with descriptions (100% coverage). The description adds context about the confirmWrite workflow and priceBasis condition, but mostly reinforces schema info. Baseline 3 is appropriate as schema does the heavy lifting.

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

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

The description clearly states 'Processes a batch of sales reps', using a specific verb and resource. It does not explicitly differentiate from sibling batch tools like brc_batch_customers, but the name and context make the purpose 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?

Provides explicit instructions on batch size limit (max 20) and the two-phase confirmation workflow: first call without confirmWrite returns preview, second call with confirmWrite after user confirmation. Does not explain when not to use or alternatives, but the batch 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?

Discloses the destructive nature and two-phase commit. Describes confirmWrite semantics and payload preview. With no annotations, it carries the full burden and does so reasonably well. Could be more explicit about post-confirmation behavior or error states.

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

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

Very concise: 5 sentences with no redundancy. Front-loads purpose, then constraints and workflow. Every sentence adds 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?

Covers the confirmation workflow and max items well. But lacks description of success response format (e.g., what is returned after confirmed write) and error handling. With no output schema, more detail on post-confirmation behavior would improve completeness.

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 well-documented. The description adds critical workflow context for confirmWrite and reinforces max items. confirmCrAnalysisCategory is not mentioned in the description but is covered by schema. Adds moderate value beyond schema.

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

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

Explicitly states 'Processes a batch of suppliers', includes batch limit and two-phase confirmation workflow. Cleary distinct from other batch tools like brc_batch_customers.

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 step-by-step usage for the confirmation workflow: first call without confirmWrite, show preview, then retry with confirmWrite only after user confirmation. Warns that preflight is not confirmation. Does not specify when to use alternatives (e.g., single supplier creation via brc_create_supplier).

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?

Mentions returning warnings, and the 'check' nature implies no side effects. However, without annotations, it could explicitly state read-only behavior or prerequisites.

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

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

Two sentences plus an alternative reference, every word contributes. No redundancy.

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 simplicity of a check tool with no output schema, the description adequately covers return value (warnings), usage context, and differentiation from sibling.

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 covers 100% of parameters, and the description adds context (e.g., enumerates allowed workflows with explanatory note). The connectionRef parameter has a lengthy explanation beyond the schema.

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

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

The description clearly states the tool checks BRC company processing settings before VAT-sensitive or payment-terms-sensitive workflows, and explicitly distinguishes from the sibling brc_company_readiness_check by specifying a different scope.

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

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

Provides explicit guidance: use before creating/changing records for a single workflow, and name the alternative tool for overall readiness checks.

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?

No annotations are present, so the description must fully disclose behavioral traits. It mentions clearing credentials from memory but does not specify side effects, such as what happens to active sessions or whether the action is reversible. The description is too brief to be transparent.

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 sentence, which is concise, but it sacrifices completeness. It could be expanded to include important details without being overly verbose.

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 operation that clears all API keys, the description is insufficient. It does not explain the return value (e.g., success message or error), nor does it cover potential impacts or confirmations. The single parameter is well-described, but the overall context of use is lacking.

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 the parameter connectionRef described in detail within the schema. The tool description adds no extra meaning beyond what the schema provides, so a 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 it clears all connection credentials for all company contexts from MCP server memory, which defines the verb and resource. However, it does not distinguish from the sibling tool brc_clear_company_api_key (singular), so it lacks 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?

No guidance is provided on when to use this tool versus alternatives like brc_clear_company_api_key or brc_clear_audit_log. There is no mention of prerequisites or context for usage.

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?

No annotations provided, so description carries full burden. It explains the two-step confirmation flow, preview behavior, and that Red waits for confirmation. However, it does not explicitly state that the audit log entries are permanently deleted or destroyed, which is a critical behavioral trait for a clear operation.

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 slightly verbose but well-structured with actionable instructions. It front-loads the core purpose and then provides detailed workflow steps. Could be more concise, but every sentence adds 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?

Given the schema covers all parameters completely and the description adds workflow guidance, the tool is well-documented. No output schema exists, but the description implies the response includes a preview on first call and a success indicator on confirmation, which is sufficient for an agent to understand the interaction.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. The description adds context beyond schema for confirmWrite, explaining its role in the confirmation workflow and that 'Passing preflight is not confirmation.' This adds meaningful guidance.

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 clears the Red audit log for this MCP server session. It distinguishes itself from sibling tools like brc_list_audit_log by specifying the action (clear) and the scope (session).

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 step-by-step workflow: first call without confirmWrite:true returns preview, then show plain-English preview in chat, then retry with confirmWrite:true only after user confirmation. Also warns not to set confirmWrite:true on first call or without explicit confirmation.

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 only states 'clears' without detailing side effects (e.g., whether it invalidates the connection, requires re-authorization, or is idempotent). Since no annotations are provided, the description should disclose more behavioral traits.

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 sentence of 11 words, which is concise and to the point. However, it could include more useful context without becoming verbose.

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?

As a destructive mutation tool with no output schema and no annotations, the description is incomplete. It does not clarify what happens after clearing (e.g., need to reconnect), success indicators, or error scenarios.

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?

Both parameters have schema descriptions (100% coverage). The tool description adds no new meaning beyond them; it merely restates 'named company context'. Baseline 3 is appropriate.

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

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

The description clearly states the specific verb 'clears' and the resource 'API key for a named company context', distinguishing it from sibling tools like brc_clear_all_company_api_keys which clears all 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?

No explicit guidance on when to use this tool versus alternatives like brc_clear_all_company_api_keys, or prerequisites such as having an active connection. The connectionRef parameter description provides some context but does not address tool selection.

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

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

With no annotations, the description fully discloses the two-step behavior, that no writing occurs until confirmation, and that preflight is not confirmation. It explains the mutation nature and the need for explicit user consent.

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 three sentences, well-structured with purpose first. The last sentence about 'Red shows what it will post' is slightly vague and not fully necessary, but overall concise.

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?

While the workflow is well explained, the description lacks details on the final return value upon successful closure. Also does not mention prerequisites (e.g., quote must be open) or error cases. Given the complexity, there are gaps.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description does not add new meaning beyond restating the confirmWrite usage. Baseline 3 is appropriate.

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

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

The description clearly states the tool closes a BRC quote, and distinguishes it from siblings like delete or reopen by detailing a two-step confirmation process. It uses a specific verb and 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?

Explicitly instructs to call first without confirmWrite: true to get a preview, then retry with confirmWrite: true only after explicit user confirmation. Also warns never to set confirmWrite on first call or based on initial request. This provides clear when and when not to use.

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

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

No annotations provided, so description carries full burden. It states 'Read-only' indicating no side effects, and lists the data reported. However, it does not mention rate limits or specific error conditions, which are minor omissions.

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

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

Two sentences plus a helpful contrast with sibling. No unnecessary words, front-loaded with purpose, and efficient.

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

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

Given no output schema, the description lists the types of data returned (connection status, financial year, reference data, etc.). It also contrasts with a sibling tool, making the context complete for a readiness check 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 both parameters already described in the input schema. The description does not add additional semantic meaning beyond what the schema provides, meeting baseline.

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

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

The description clearly states 'Read-only company health and readiness check' and lists specific reported items (connection status, financial year, etc.). It also distinguishes from the sibling brc_check_transaction_settings by contrasting scope.

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

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

Explicitly says 'Use this for overall company readiness before starting work' and contrasts with brc_check_transaction_settings for specific VAT-sensitive workflows, providing clear when-to-use and when-not-to-use guidance.

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

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

Despite no annotations, the description thoroughly discloses behavioral traits: it returns an opaque connectionRef, should be passed silently not shown to users, never exposes credentials, and must be reused across session rotations. It lacks mention of side effects or idempotency but covers critical safety aspects.

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 provides necessary usage details. While somewhat lengthy, every sentence contributes valuable information. It could be slightly more concise, but structure is logical.

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 no output schema, the description adequately explains the return value (connectionRef) and its usage. It covers session rotation, client examples (Vibe/Mistral), and security. It is complete for a connection-confirmation 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%, and the description adds value by explaining that 'code' comes from the success page and that 'connectionRef' is returned by this tool and must be reused. It also provides guidance on handling ('pass silently', 'do not show'), going 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 it 'Claims a completed secure Red connection code for the current MCP session.' with a specific verb and resource, and distinguishes itself from the sibling tool brc_start_company_connection by instructing not to call it while the connectionRef still works.

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

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

Explicitly states when to use (after user submits secure connection page and returns with confirmation code, when session ids rotate) and when not to use (do not call brc_start_company_connection while connectionRef works). Provides clear alternatives and context.

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

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

With no annotations, the description carries the full burden. It reveals two key behaviors: the tool only accepts the parent transaction shape and generates the reversing child automatically. It also warns about the confirmWrite flag. However, it omits return value, side effects, and permission 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?

Two concise sentences. The first sentence states the core purpose, the second explains a critical usage nuance. No wasted 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?

Given 10 parameters and no output schema, the description explains the parent/child creation flow and confirmWrite constraint. It does not mention the return value or prerequisites like having a connectionRef, but the schema covers connectionRef. Overall, it provides sufficient context for effective 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 coverage is 100%, so the description adds only marginal value. It repeats the confirmWrite caveat already in the schema and elaborates on connectionRef, but does not provide any new parameter-level context beyond what the schema already contains.

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

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

The description explicitly states 'Creates a new parent Accrual', clearly identifying the verb and resource. It distinguishes from sibling tools like update/delete by using 'parent' and explaining the reversing child transaction, which is unique to creation.

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 a clear when-not-to-use instruction: 'Do not call with confirmWrite=true until the user has reviewed the preview and explicitly confirmed creation.' It implies a preview step, but does not explicitly mention when to use this tool vs. alternatives (though none exist for creating accruals).

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?

No annotations are provided, so the description must disclose behavioral traits. It covers the confirmation step and auto-creation of category, but lacks details on side effects, return values, error handling, or authentication 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 front-loaded with the primary purpose and warnings, then details. At multiple sentences, it is concise but could be more structured with bullet points. No unnecessary repetition.

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

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

For a complex tool with 19 parameters, no output schema, and no annotations, the description is insufficient. It omits behavior for many parameters (e.g., address, balance), return values, and error scenarios, leaving the agent underinformed.

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 meaning by listing required fields (acCode, details, lastChq, nominalAcCode) not in the schema's required list, but it contradicts the schema which only marks companyName as required. It also explains optional behavior for categoryId. However, the contradiction misleads.

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

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

The description clearly states that the tool creates a BRC bank account, and it adds specific details like the confirmation workflow and required fields, which distinguishes it from other create tools among the 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 includes explicit guidance on when not to call with confirmCreate=true, lists required fields, notes optional parameters, and mentions a prerequisite for nominalAcCode. However, it does not compare to alternative tools like brc_update_bank_account.

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?

No annotations provided, so the description fully discloses behavior: it explains the confirmation mechanism, that a first call returns a payload preview, and that writing occurs only after explicit confirmation. It also mentions preflight and counterparty 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 well front-loaded with the purpose and then structured into use cases and workflow. It is relatively long but appropriate given the complexity; every sentence adds value. Slightly verbose but effective.

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 complexity (19 parameters, no output schema), the description covers all essential aspects: three usage modes, confirmation workflow, constraints on analysis categories, and counterparty confirmation. It provides sufficient context for correct usage.

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 84% schema description coverage, the schema already documents most parameters. The description adds significant value by grouping parameters into use cases and providing crucial semantics for confirmWrite and confirmCounterpartyExplicit, which are not fully explained 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 clearly states it creates a BRC cash payment and distinguishes three specific use cases: supplier payments, bank lodgements, and analysed expenses. It differentiates from sibling tools like brc_batch_cash_payments by being a single creation tool.

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

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

Explicitly provides when to use each variant (supplierId + ledger for supplier payments, etc.) and detailed workflow guidance for the confirmation process, including when to set confirmWrite and confirmCounterpartyExplicit. Clearly states not to reuse counterparties without explicit confirmation.

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 no annotations, the description discloses key behaviors: two-step confirmation, default dates, conditional VAT fields, and that nothing is written until confirmWrite is true. Missing some specifics like error handling for direct confirmWrite calls, but overall strong behavioral coverage.

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 verbose and includes some redundant phrasing ('Red shows what it will post and waits for confirmation'), but it is front-loaded with the main purpose and structured with logical flow. Could be more concise without losing critical information.

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

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

For a complex tool with 31 parameters, nested objects, and no output schema or annotations, the description is incomplete. It lacks parameter descriptions for most fields, does not explain nested object structures (acEntries, vatEntries), and omits return value details beyond preview/confirmation. Missing overall completeness.

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?

While schema coverage is low (13%), the description adds meaning for a few parameters: entryDate/procDate default to today, VAT fields conditional, and full explanation of confirmWrite and confirmCounterpartyExplicit. However, most parameters (total, acCode, ledger, etc.) remain undocumented, so compensation is partial.

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 first sentence clearly states 'Creates a BRC cash receipt,' specifying the verb and resource. It also mentions acceptance of raw payload or flat fields, and the tool's name distinguishes it from siblings like brc_create_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?

Provides explicit step-by-step workflow: first call without confirmWrite, preview, user confirmation, then retry with confirmWrite. Also details confirmCounterpartyExplicit requirement and warns against reusing counterparties without confirmation. This fully guides when and how to invoke the tool.

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?

No annotations exist, so description carries full burden. Discloses that it does not create opening balance transactions, the two-step confirmation flow, that nothing is written until confirmWrite is true, and that preview is returned on first call. Also mentions email mismatch warning 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?

Description is well-structured starting with purpose then constraints then workflow. Slightly verbose but every sentence adds value. Could be slightly more concise but still effective.

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 no output schema and nested payload, description covers behavior, constraints, workflow, and error conditions (email mismatch). Addresses all necessary context for correct invocation despite missing annotations.

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

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

Schema has 100% coverage, but description adds crucial context: confirmWrite's specific workflow (never true on first call, only after preview and explicit confirmation), connectionRef's reuse after successful calls, and payload being raw BRC-compatible payload. Adds significant value beyond schema.

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

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

Description starts with 'Creates a BRC customer using a raw BRC payload' – clear verb+resource. Distinguishes from siblings like brc_batch_customers and brc_update_customer. Also clarifies it does not handle opening balances, adding specificity.

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 step-by-step workflow: first call without confirmWrite, show preview, obtain explicit confirmation, then retry with confirmWrite: true. Also advises warning on opening balance and email mismatches. Clearly states when to use and the required confirmation protocol.

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?

No annotations provided, so description carries full burden. It mentions creation and balanced debit/credit requirement, and the two-step process (preview then confirm). However, it lacks details on side effects, permanence, or error conditions.

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: first states purpose, second provides crucial usage warning. No redundant information, highly efficient.

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

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

With 100% schema coverage and 8 parameters well-described, the description is fairly complete. Missing only output details and error handling, but tool complexity is moderate.

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 description adds limited value. The description highlights confirmWrite usage and balance requirement, but most parameter meanings are already in schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool creates a nominal journal batch, with specific verb 'Creates' and resource 'Nominal Journal Batch'. It distinguishes from siblings like brc_create_sales_invoice and brc_batch_* tools by focusing on accounting journals.

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

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

Explicitly warns not to call with confirmWrite=true until confirmed by user, providing clear when-not-to-use guidance. However, it does not mention alternatives like brc_update_nominal_journal_batch or brc_delete_nominal_journal_batch for modifications.

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?

No annotations provided, but the description discloses the write behavior (nothing written until confirmed), the preview step, and the need for explicit counterparty confirmation. It could mention reversibility or error handling, but it's transparent about the confirmation safeguard.

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

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

The description is moderately long but front-loaded with the main purpose. Each sentence serves a purpose, though it could be more structured (e.g., bullet points). No wasted content.

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

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

Given the complexity of 18 parameters and no output schema, the description covers the critical workflow and parameter dependencies. It lacks return value details and error conditions, but the confirmation mechanism mitigates risk.

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 meaning beyond the schema by explaining parameter groupings and the purpose of confirmWrite and confirmCounterpartyExplicit. With 67% schema coverage, it effectively compensates for undocumented parameters through workflow context.

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 it creates a BRC payment from the Payments book. It distinguishes two payment types (supplier vs analyzed bank) and differentiates from siblings like brc_create_cash_payment by specifying the book and parameters.

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 guidance on when to use supplierId vs analysisCategoryId+accountCode. Details the confirmation workflow with confirmWrite and confirmCounterpartyExplicit, including when to set them and the preview step.

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 no annotations, description reveals that the tool creates a parent and relies on shared logic to generate a reversing child transaction. Warns about confirmWrite. Could mention permissions or rollback, but fairly transparent.

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

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

Two sentences, no fluff. Front-loaded with the main action. Every word earns its place.

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

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

Covers the core workflow (preview then confirm) and the parent/child transaction. However, with 10 parameters and no output schema, it lacks information about return values or error conditions. Adequate but not fully complete.

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

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

Schema coverage is 100%, so every parameter has a description. The tool description doesn't add meaningful detail beyond schema; it merely references confirmWrite which is already described. 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?

Clearly states 'Creates a new parent Prepayment' with specific verb and resource. Distinguishes from siblings like brc_update_prepayment and brc_delete_prepayment. Adds detail about parent transaction shape and reversing child transaction.

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 guidance: 'Do not call with confirmWrite=true until the user has reviewed the preview and explicitly confirmed creation.' Implies a two-step preview-then-confirm workflow. No explicit alternatives but clear context.

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

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

Discloses the preflight confirmation behavior, that confirmWrite prevents writes until explicitly set, and that preview is not confirmation. No annotations provided, so description carries full transparency burden; it largely meets it.

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?

Description is moderately long but every sentence is meaningful and front-loaded. Minor redundancy could be trimmed, but overall efficient.

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

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

For a two-step creation tool with no output schema, the description covers the workflow, the preview requirement, and the confirmation step. Missing details like error handling or output format are acceptable at this complexity level.

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

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

Schema coverage is 100%, but the description adds crucial context: confirmWrite usage rules, connectionRef reuse guidance, and payload purpose. This goes beyond baseline 3.

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

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

The description clearly states the tool creates a BRC product using a raw payload, and distinguishes it from sibling create tools by detailing the two-step confirmWrite workflow.

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

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

Explicit step-by-step guidance: first call without confirmWrite for preview, then retry with confirmWrite only after user confirmation. No ambiguity about when to use each step.

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?

No annotations provided, so description carries full burden. It discloses that first call without confirmWrite returns confirmation_required and payload preview, and that nothing is written until confirmWrite: true. However, it does not detail the final response format or error behaviors.

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

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

One dense paragraph with all critical information, no filler. Could be broken into bullet points for readability, but is efficient and front-loaded with the core action.

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

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

For a complex tool with 17 params, no output schema, and no annotations, the description explains workflow and key booleans well. However, it does not clarify the final response after successful creation (beyond mentioning preview), nor emphasize the need for connectionRef from brc_confirm_company_connection. Some gaps remain.

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 covers all 17 parameters with descriptions (100% coverage). Description adds meaning beyond schema by explaining the workflow for confirmWrite and confirmCounterpartyExplicit, and noting the reference requirement. This is useful behavioral context not present in 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?

Description clearly states 'Creates a BRC purchase' using a specific verb and resource. It distinguishes from sibling brc_create_purchase_gen_ref by noting when to use each, so the agent can differentiate.

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

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

Explicitly provides when-to-use and when-not-to: prefer brc_create_purchase_gen_ref if company is configured for manual references. Describes the two-call workflow (preview then confirm) and conditions for confirmWrite and confirmCounterpartyExplicit.

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 no annotations, the description discloses key behaviors: no immediate write, returns confirmation_required, requires explicit confirmation. It explains the preview-and-confirm flow. Lacks details on response format but covers essential safety aspects.

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

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

Four sentences packed with useful information. Could benefit from bullet points or clearer separation of steps, but front-loads purpose and usage.

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?

While covering the confirmation workflow well, it does not explain the expected response format (payload preview) nor provide parameter details. With 16 parameters and no output schema, more context is needed for effective 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 coverage is only 25%; description does not add meaning to most parameters. Only confirmWrite and confirmCounterpartyExplicit are explained in usage context, leaving the other 12 parameters (including required ones like netAmount, supplierId) without additional guidance.

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 it creates a purchase with an auto-generated reference, distinguishing it from sibling tools like brc_create_purchase (manual reference).

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

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

Explicitly states when to use (auto-generated references) and provides detailed step-by-step instructions for the two-step confirmation workflow, including when to set confirmWrite and confirmCounterpartyExplicit.

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 no annotations, the description fully carries the burden. It discloses critical behaviors: nothing is written until confirmation, the two-step preflight process, requirements for explicit user confirmation for counterparty and CR category, and warnings against inventing values. This is comprehensive and accurate.

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 verbose and could be more concise. It includes repeated warnings and run-on sentences. However, it is front-loaded with the core purpose, and the information density is high given the tool's 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?

Given the high parameter count (29), no output schema, and no annotations, the description is remarkably complete. It covers the workflow, prerequisites, parameter semantics, and safety checks. Missing details like the exact return structure beyond 'confirmation_required' are acceptable without an output schema.

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

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

Despite only 38% schema coverage, the description adds substantial meaning for key parameters: saleRepId/saleRepCode, analysisCategoryId/accountCode, confirmWrite, confirmCrAnalysisCategory, confirmCounterpartyExplicit, and reference. It explains their roles and constraints, compensating for schema gaps.

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 it creates a BRC quote using structured MCP fields. It specifies the verb (creates) and resource (quote), and the detailed workflow distinguishes it from siblings like brc_create_quote_gen_ref by outlining the manual reference and confirmation process.

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

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

Provides explicit when-to-use and when-not-to-use guidance, such as requiring saleRepId/saleRepCode and analysisCategoryId/accountCode, warning against default/demo values, and instructing not to set confirmWrite=true on first call. However, it does not explicitly name sibling tools like brc_create_quote_gen_ref, though the context implies differentiation.

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 no annotations, the description fully discloses the two-step confirmation workflow, preview behavior, safety guarantees (nothing written until confirmed), requirements for confirm flags, and the auto-generation logic. It covers critical behavioral traits beyond the schema.

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

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

The description is verbose and contains some redundancy (e.g., multiple reminders about nothing being written until confirmation). While front-loaded with purpose, it lacks a clear structure and could be more concise.

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 creation workflow and parameter conditions but does not describe the response structure beyond mentioning 'confirmation_required' and a payload preview. Given no output schema, more detail on success/error responses would improve completeness.

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 low (38%), and the description adds significant meaning for key parameters like saleRepId, saleRepCode, analysisCategoryId, accountCode, confirmWrite, confirmCounterpartyExplicit, and confirmQuotesAutoGenerateInBrc. However, not all parameters are addressed, though the most complex ones are well explained.

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

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

The description explicitly states it creates a BRC quote with a generated reference. It distinguishes from sibling 'brc_create_quote' by specifying the condition for auto-generated references, providing a clear verb+resource+scope.

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

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

Provides explicit when-to-use conditions (auto-generated references or user confirmation after Unknown), and gives detailed instructions on when not to use default/demo values, how to confirm counterparty, and the two-step posting process. Effectively guides selection vs. alternatives.

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

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

Since no annotations are provided, the description carries the full burden. It discloses key behavioral traits: two-step confirmation with preview, requirement for user confirmation flags, and that nothing is written until confirmWrite=true. However, it lacks details on error handling or rate limits.

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

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

The description is lengthy and thorough but could be more concise. It front-loads the purpose and then lists requirements and process steps in a logical order, though some redundancy (e.g., repeating 'first call without confirmWrite' details) could be trimmed.

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

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

Given the tool's complexity (24 parameters, no output schema), the description is incomplete. It omits standard output structure, error responses, and many parameter semantics. While it covers the confirmation workflow, it leaves significant gaps for a production-grade tool.

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

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

Schema description coverage is low (29%), so the description must compensate. It adds meaning for critical parameters (confirmWrite, confirmCounterpartyExplicit, saleRepId, etc.) and explains the confirmation flow, but many required parameters (e.g., companyName, customerId, netAmount) are not addressed, leaving gaps.

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 'Creates a BRC sales credit note using structured MCP fields' and explicitly contrasts with the sibling brc_create_sales_credit_note_gen_ref, making the tool's purpose and when to choose it well-defined.

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: requires reference when manual references are configured, otherwise prefer the gen_ref sibling. It also details prerequisites (saleRepId, saleRepCode, analysisCategoryId, accountCode) and warns against default values, with step-by-step instructions for the confirmation workflow.

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

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

Despite no annotations, the description fully discloses behavioral traits: the two-step confirmation process, requirement for explicit user confirmation for counterparty and analysis category, and the preview before posting. No contradictions.

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 verbose but every sentence adds value given the complexity. It is front-loaded with the main purpose. Slightly longer than ideal but necessary for clarity.

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 confirmation flow and required preconditions well. However, it does not describe the return value structure beyond the first call preview. Given no output schema, a brief note on successful response would improve completeness.

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?

While schema coverage is high (83%), the description adds critical context beyond parameter names and types, such as explaining when to set confirmWrite, confirmCrAnalysisCategory, and confirmCounterpartyExplicit to true. This is essential for correct invocation.

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 it creates a BRC sales credit note with an auto-generated reference, which differentiates it from sibling tools like brc_create_sales_credit_note (without gen_ref). It provides specific verb and resource, making the purpose unambiguous.

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

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

The description explicitly states when to use (company configured for auto-generated references) and provides detailed step-by-step guidance, including what to avoid (default/demo sales rep values) and the confirmation flow. It effectively guides the agent on proper usage.

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 no annotations, the description carries full burden. It details the non-destructive preview behavior (returns confirmation_required and payload preview), the requirement for explicit user confirmation before writing, and the counterparty confirmation requirement. It does not mention other side effects or rate limits, but the critical safety behavior is well covered.

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 paragraph that front-loads the purpose and then provides necessary workflow details. It is somewhat lengthy but every sentence adds value for correct usage. Minor improvement could be breaking into shorter sentences or bullets.

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 16 parameters, 13 required, and no output schema, the description covers the essential usage workflow but omits explanations of many required fields like note, acCode, procDate, etc. The connectionRef parameter is explained in the schema. The description is adequate for the behavioral context but leaves gaps for other parameters.

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 low (25%), but the description adds significant meaning for key parameters by explaining the two-phase confirmation workflow for confirmWrite and the counterparty confirmation rule for confirmCounterpartyExplicit. It compensates for the lack of schema descriptions on these critical booleans, though many other parameters remain without explanation.

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 begins with 'Creates a BRC sales entry using structured MCP fields,' which clearly states the verb (creates) and resource (BRC sales entry). The sibling tools include batch variants and other document types, distinguishing this as a single sales entry creation tool.

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

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

The description provides explicit instructions for the two-phase confirmation workflow: first call without confirmWrite:true, show preview, then retry with confirmWrite:true after user confirmation. It also requires confirmCounterpartyExplicit:true after explicit counterparty confirmation. It does not compare directly to sibling tools but the 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?

Despite no annotations, the description fully discloses behavior: preview-first workflow (first call without confirmWrite returns confirmation_required), nothing written until explicit confirmation, blocking of invalid values (productId 0/1, non-Sales VAT rates), and default behaviors for note and deliveryTo. Explains that passing 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 very long (multiple paragraphs) and dense with instructions. While every sentence adds value, it lacks structural elements like bullet points or sections. For a tool with 27 parameters, some conciseness could be improved by organizing information more efficiently.

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

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

Given the high complexity (27 parameters, 18 required, no output schema), the description is thorough in covering input constraints, workflow, and edge cases (preview, blocking, defaults). However, it does not describe the output structure or return value, which would be helpful for an agent to interpret results.

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

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

Schema description coverage is 56%, and the main description adds substantial context beyond schema, such as explanation of productId/productCode usage, priceBasis conditions, and confirmation flags. However, some parameters like acCode have no schema description and lack additional explanation in the main text, which slightly reduces the score.

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 starts with 'Creates a BRC sales invoice using structured MCP fields' which clearly states the action and resource. It also distinguishes from the sibling brc_create_sales_invoice_gen_ref by specifying when to prefer that alternative based on manual reference configuration.

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 comprehensive when-to-use guidance: requires reference when company is configured for manual references, otherwise prefer alternative. Also details prerequisites like saleRepId, analysisCategoryId, and gives rules for confirmWrite, confirmCrAnalysisCategory, confirmCounterpartyExplicit, and priceBasis. Explicitly states not to invent values or use placeholders.

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 no annotations provided, the description fully covers behavioral traits: preview-before-posting, validation rules, blocked values (productId 0/1, non-Sales VAT rates), default behavior for note and deliveryTo, and the requirement for nested acEntries. This is comprehensive.

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

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

The description is very long (over 500 words) and includes some redundancy (e.g., note and deliveryTo optionality repeated). It lacks clear structure or bullet points, though the content is essential. Could be more concisely organized.

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

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

Given the complexity of the tool (7 parameters, nested objects, no output schema), the description covers all aspects: validation, preview, confirmation flow, default behaviors, blocked values, required fields, and references to sibling tools (brc_list_products). It 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?

Although schema coverage is 100%, the description adds significant value beyond the schema by explaining defaults (note defaults to customer name), conditional requirements (priceBasis when Gross Price Entry enabled), and cross-parameter constraints (saleRepId and saleRepCode must be non-default).

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

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

The description clearly states it creates a BRC sales invoice with an auto-generated reference, distinguishing it from its sibling brc_create_sales_invoice which likely requires a manual reference. The verb 'Creates' and resource 'BRC sales invoice' are specific.

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

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

Explicitly says 'Use when the company is configured for auto-generated sales references.' Also provides detailed guidance on confirmation flags (confirmWrite, confirmCounterpartyExplicit, confirmCrAnalysisCategory) and when not to use default values.

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 no annotations provided, the description carries the full burden of behavioral disclosure. It clearly explains the two-step confirmWrite workflow, that nothing is written until confirmed, and that the first call returns a preview. It does not cover error handling or idempotency, but the key behavioral trait (safe creation with user confirmation) is well explained.

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

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

The description is moderately sized and front-loaded with the core purpose. Every sentence serves a purpose: defining the action, explaining the workflow, and clarifying the confirmWrite parameter. However, it could be slightly more concise without losing essential guidance.

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

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

Given the tool has 5 parameters (3 required), no output schema, and no annotations, the description should cover more. It explains the creation workflow and confirmWrite behavior but does not mention what the tool returns after a successful write (only mentions the preview return) or any prerequisites like needing a company connection. This leaves some gaps for the agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value for the confirmWrite parameter by explaining the required workflow (first call without confirmWrite, then retry with true). For other parameters (code, name, companyName, connectionRef), the description adds little beyond the schema, but the total added context justifies a 4.

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 starts with 'Creates a BRC sales rep using structured MCP fields,' clearly stating the verb (creates) and resource (BRC sales rep). It distinguishes from sibling tools like brc_batch_sales_reps (batch), brc_get_sales_rep (read), brc_delete_sales_rep (delete), and brc_update_sales_rep (update) by focusing on creation of a single entity.

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 step-by-step usage instructions: first call without confirmWrite: true, show the preview, then retry with confirmWrite: true after user confirmation. It clarifies that passing preflight is not confirmation. However, it does not explicitly mention when to avoid using this tool (e.g., in favor of batch operations).

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 no annotations, the description fully discloses the preflight/confirm mechanism, that no opening balance is handled, and the need for user 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?

Concise with all sentences earning their place, but could be slightly more structured (e.g., separation of workflow steps).

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 (multi-step), the description covers workflow, return values (confirmation_required, preview), and edge case (opening balance) completely.

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?

Adds significant value beyond schema by explaining confirmWrite's step-by-step usage, connectionRef's nature, and payload as raw BRC structure. Schema coverage is 100%, but description enriches all 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 tool creates a BRC supplier with a raw payload, distinguishes from opening balance tools, and includes specific workflow details.

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 instructions on the two-step confirmWrite process and warning about opening balance, but does not directly compare to sibling create 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?

No annotations are provided, so the description carries the full disclosure burden. It mentions the deletion action, the prerequisite timestamp requirement, and the confirmWrite safety flag. It does not detail consequences or permissions, but for a delete tool this is adequate.

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 with no filler. The first sentence states the action, the second gives a prerequisite, and the third warns about confirmWrite. It is front-loaded and every sentence adds 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?

With no annotations and no output schema, the description covers the essential aspects: purpose, required workflow (get accrual first), and a critical safety note. It could mention what happens on success or error, but for a single-action delete tool it is sufficiently complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by specifying the timestamp is in Base64 format and that confirmWrite must be true only after user confirmation. It also provides an example for companyName. This surpasses 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 clearly states it removes an accrual by id, with the specific verb 'Removes' and resource 'parent Accrual'. However, it does not explicitly differentiate from other delete tools like brc_delete_bank_account, but the name and action are distinct enough.

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

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

Explicitly instructs to call brc_get_accrual first to retrieve the timestamp, and warns to not set confirmWrite=true until user confirms deletion. This provides clear when-to-use and when-not-to-use guidance.

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

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

No annotations are provided, so the description must fully disclose behavioral traits. It warns about the confirmWrite parameter but does not explain deletion consequences, irreversibility, required permissions, or what happens on success/failure. Additional detail would improve transparency.

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

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

Two sentences, each carrying essential information: action and prerequisite in the first, safety warning in the second. No redundant words, well-structured.

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

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

For a mutation tool with 4 parameters, no annotations, and no output schema, the description covers purpose, prerequisite, and a safety constraint. However, it lacks information about return values, error handling, and side effects, leaving some gaps for an agent to handle.

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 100% schema coverage, the baseline is 3. The description adds value by explaining that the 'id' comes from brc_list_allocated_transactions and that confirmWrite must only be true after user confirmation. It does not elaborate on companyName or connectionRef beyond schema, but the added context is useful.

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

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

The description clearly states the tool's action ('Reverses/deletes a single allocation') and specifies the resource ('by allocation resolver id'). It distinguishes from sibling tools by focusing specifically on allocation resolvers, not other 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 provides a clear prerequisite ('Use brc_list_allocated_transactions first to find the allocation id') and a safety warning about confirmWrite. However, it does not explicitly exclude alternative tools or specify when not to use this tool.

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?

No annotations provided, so description carries full burden. It discloses that first call returns confirmation_required and payload preview, and that nothing is written until confirmed. This is transparent and covers the core behavioral trait of a destructive action with safeguards.

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?

Description is a single paragraph with front-loaded purpose. Every sentence adds information about the confirmation flow. Could be slightly more concise, but it is well-structured and not overly verbose.

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 no output schema, description adequately explains the return behavior (confirmation_required and preview). It covers the essential parameter confirmWrite and the overall process. Lacks mention of confirmDelete role, but the tool's core behavior is sufficiently 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 80% (4 out of 5 params described). Description adds value beyond schema by explaining the critical confirmWrite parameter's behavior in the multi-step process. However, it omits mention of confirmDelete (present in schema) and connectionRef (already described in 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?

Description clearly states 'Deletes a BRC bank account by id' – specific verb and resource. It also outlines a unique multi-step confirmation process, distinguishing it from other delete tools in the sibling list.

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

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

Explicitly instructs to only call after user confirms deletion, describes two-step process (first call without confirmWrite, show preview, then confirm). Contrasts with what not to do (passing preflight is not confirmation). Clear when and how to use.

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

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

No annotations are provided, so the description fully carries the burden. It discloses the two-phase confirmation behavior, including that the first call returns a preview and that confirmWrite triggers the actual delete. 'Red shows what it will post' hints at UI behavior. This is comprehensive for a delete 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 four sentences, well-structured with a logical flow: purpose, first step, second step, warning. It is informative but could be slightly more concise by removing 'Red shows what it will post' (ambiguous) or combining sentences.

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 core deletion workflow but omits details about error handling, return values, permissions, or side effects. Given the tool has five parameters and no output schema, more context on what happens on success/failure would improve completeness.

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 80%, so descriptions exist for most parameters. The description adds value by explaining the workflow for confirmWrite and confirms that companyName and id are used as expected. It does not add much for confirmDelete or connectionRef, but the schema already covers them adequately.

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 deletes a BRC cash payment by ID. The verb 'deletes' and resource 'cash payment' are specific and distinguish it from sibling delete tools like brc_delete_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?

Explicitly outlines a two-step process: first call without confirmWrite to get a preview, then retry with confirmWrite only after user confirmation. Warns that preflight is not confirmation, providing clear when-to-use guidance.

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

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

No annotations exist, so the description bears full responsibility. It fully discloses the two-step process, that nothing is written until confirmation, and the preview requirement, ensuring safe usage despite destructive nature.

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

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

Four concise sentences front-load the purpose and then efficiently detail the workflow. Every sentence adds value without redundancy.

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?

Without an output schema, the description covers the core deletion workflow thoroughly but omits details on success/error responses. Prerequisites like company connection are implied via connectionRef parameter. Adequate for the tool's complexity.

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

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

Schema coverage is 80% (missing confirmDelete description). The description adds significant context for confirmWrite (preview, confirmation flow) beyond schema. Other parameters like connectionRef are already well-described in 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 'Deletes a BRC cash receipt by id', specifying the verb and resource. It distinguishes itself from sibling delete tools by focusing on cash receipts and detailing a unique two-step confirmation workflow.

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: first call without confirmWrite for preview, then only with confirmWrite after user confirmation. It also warns 'Passing preflight is not confirmation', preventing misuse.

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

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

No annotations provided, so description carries full burden. It details the two-step workflow, side effects (returns preview, requires confirmation), and key behaviors like 'Red shows what it will post' and 'Passing preflight is not confirmation.' All behavioral traits are disclosed.

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?

Concise yet comprehensive. Every sentence serves a purpose: stating action, explaining the two-step process, setting expectations, and clarifying constraints. No fluff; clear and direct instructions.

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 no output schema, the description sufficiently explains the return behavior (confirmation_required and preview). Workflow is fully covered, including post-confirmation. Siblings are numerous, but the description uniquely defines this tool's deletion process.

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?

Description adds significant meaning beyond the input schema: explains how confirmWrite operates as a safety gate, the requirement for explicit user confirmation, the role of confirmDelete (default false), and that connectionRef must be reused. Schema coverage is high but description enriches understanding.

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?

Clearly states 'Deletes a BRC customer by id' and distinguishes from sibling delete tools (e.g., brc_delete_supplier). The two-step confirmation process is thoroughly described, making the tool's purpose unambiguous.

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

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

Provides explicit step-by-step instructions: first call without confirmWrite for preview, then retry with confirmWrite only after user confirmation. Clearly states when not to use (e.g., not setting confirmWrite on first call).

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?

No annotations are provided, so the description carries full disclosure responsibility. It reveals that the operation is destructive (removal), requires a Base64 timestamp, and has a safety mechanism (confirmWrite). This provides key behavioral context beyond the schema, though it omits potential error conditions or side effects.

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 three sentences, each serving a distinct purpose: stating the action, noting a requirement, and providing usage instructions. It is front-loaded with the core purpose and avoids any extraneous content.

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

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

Given the lack of output schema, the description adequately covers the deletion workflow and safety mechanisms. It provides enough context for an agent to use the tool correctly, though it could be more complete by mentioning error cases or what happens on success.

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 100% schema description coverage, the baseline is 3. The description adds value by explaining the dependency of timestamp on a prior get call and the conditional use of confirmWrite. However, it does not significantly enhance understanding of id or companyName beyond the schema.

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

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

The description clearly states the action ('Removes an existing Nominal Journal Batch by id') and identifies the specific resource. It also provides a key prerequisite (timestamp retrieval), which distinguishes this tool from sibling delete tools that target different resources.

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

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

The description gives explicit guidance: use brc_get_nominal_journal_batch to obtain the timestamp before deletion, and defer setting confirmWrite=true until user confirmation. This clearly directs the agent on the correct invocation sequence, though it does not explicitly mention when not to use the tool.

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 no annotations provided, the description fully carries the burden of behavioral disclosure. It explains the destructive nature of the tool, the confirmation mechanism to prevent accidental deletion, and explicitly states that nothing is written until user confirms. This is highly transparent.

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