Red by Big Red Cloud

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

Annotations already mark the tool as destructive, but the description adds meaningful behavioral context beyond that: nothing is written until preview and confirmWrite/confirmDelete, a routeToken grants routing permission only, and counterparty confirmation must be explicit in the current conversation. This is exactly the type of safety-critical behavior disclosure an agent needs.

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

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

The description is dense and front-loaded with the core purpose and batch limit, and the workflow caveats are important. It is slightly repetitive with schema-level statements such as routeToken and confirmWrite descriptions, but the extra length is justified for a multi-step, safety-critical transactional tool.

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

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

Given the tool's complexity, the destructive annotation, and the absence of an output schema, the description is complete enough for safe selection and invocation. It covers the routing prerequisite, token reuse rule, pre-posting confirmation rule, counterparty confirmation rule, and the 20-item batch cap, with the schema covering the remaining parameter details.

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

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

The input schema already provides detailed descriptions for all 8 parameters, so the baseline is 3. The description adds valuable non-redundant guidance around routeToken lifecycle and confirmCounterpartyExplicit semantics, but it does not significantly extend the meaning of the other 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 opens with a specific verb and resource: "Processes a batch of BRC cash payments." It also adds the 20-item batch limit, which clearly identifies this as the batch cash-payment tool and distinguishes it from the many create/list/update sibling tools.

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

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

The description gives explicit workflow ordering: call brc_route_request first, retain the routeToken through lookup/preview/confirmation, and pass the same token on the final permitted transactional call. It also gives explicit negative guidance such as "Never invent a placeholder token" and "do not reuse a counterparty from an earlier preview without 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?

Annotations already set destructiveHint=true and readOnlyHint=false. The description adds crucial behavioral details: the routeToken is not permission to post, confirmCounterpartyExplicit is mandatory after explicit confirmation, and counterparty cannot be reused from earlier previews. This goes beyond the annotation's binary flags, clarifying the safety workflow.

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

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

The description is dense but efficient – every sentence delivers a critical constraint or step: maximum items, routeToken sourcing, retention, no placeholders, confirmation requirements, and counterparty validation. The purpose is front-loaded, and there is no extraneous content. Slightly long, but every part earns its place 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?

The description thoroughly covers the workflow prerequisites and security checks, but it does not mention the output/return behavior (e.g., whether it returns success/failure per item, batch references, or any confirmation IDs). Since there is no output schema, the agent has no guidance on what to expect after invoking the tool. This gap could lead to uncertainty in post-processing, so completeness is only adequate.

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

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

The input schema covers 100% of parameters with descriptions, setting a baseline of 3. The description adds extra meaning by emphasizing the lifecycle of routeToken (retain from routing, don't invent, not permission) and the strict condition for confirmCounterpartyExplicit (only after explicit user confirmation in current conversation). These details are not fully articulated in the schema, making the description valuable.

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 'Processes a batch of BRC cash receipts' – a specific verb and resource. It explicitly states the batch nature and a maximum of 20 items, distinguishing it from single-item tools like brc_create_cash_receipt. This leaves no ambiguity about the tool's core function.

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

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

The description clearly instructs to call brc_route_request first, retain the token, and pass the same token on the final transactional call. It also warns against placeholder tokens and reinforces that preview-before-posting and confirmWrite still apply. While it doesn't explicitly say 'use this instead of single cash receipt tools', the batch context is evident from the name and the guidance is actionable.

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

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

The description adds substantial context beyond the annotations. It discloses destructive behavior (posting is final), the need for preview-before-posting and confirmWrite, and the importance of not treating routeToken as absolute permission. It also warns against inventing tokens and clarifies that confirmWrite must only be true after explicit user confirmation. This is much richer than the simple destructiveHint=true annotation.

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

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

The description is two sentences, but it is densely packed with essential workflow information. Every clause adds value: the 20-item limit, the routeToken requirement, the sequence, and the confirmation gate. 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?

For a transactional tool with no output schema, the description is remarkably complete. It covers prerequisites, workflow steps, confirmation requirements, and critical caveats (no placeholder tokens). The exception is that the description doesn't explain what the response looks like, but given the schema coverage (100%) and the complex workflow, the description does its job thoroughly.

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

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

The schema coverage is 100% (all parameters have descriptions). The description itself adds value by explaining the workflow requirements for routeToken and confirms confirmWrite semantics. Some parameters like confirmCrAnalysisCategory and connectionRef are only briefly mentioned in the schema, but the description points to the routing workflow. The description adds context beyond the schema (e.g., routeToken is not permission to post).

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 customers, starting with a specific verb and resource. The primary gap is the lack of explicit differentiation from sibling tools like brc_batch_sales_invoices or brc_batch_sales_entries, which likely follow the same batch pattern. The description does not explicitly mention 'customers' in a way that contrasts with other batch tools.

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

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

The description is exemplary: it explicitly states the precondition ('Requires routeToken from brc_route_request'), the order of operations ('Call brc_route_request first...'), and critical constraints ('Never invent a placeholder token', 'A routeToken is not permission to post'). It clearly explains how to use this tool within the broader workflow, including the retention of the token through lookup, preview, and 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 clearly indicates this is a transactional write operation (destructiveHint: true) and emphasizes confirmWrite requirements, preview-before-posting, and that routeToken alone is not permission to post. It adds significant behavioral context beyond the annotations by explaining the confirmation workflow and counterparty explicit confirmation requirement. Minor deduction as it doesn't explicitly mention what happens on failure or rollback, but given annotations already cover the destructive flag, the description adds substantial value.

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

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

The description is well-structured with clear sentences that front-load the core purpose (batch processing) and key constraint (max 20 items). It efficiently covers the workflow, routeToken requirements, and confirmation prerequisites without excessive verbosity. A minor deduction for slightly repetitive emphasis on confirmWrite/confirmCounterpartyExplicit which appears in both the description and schema, but the description adds workflow context that justifies the repetition.

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

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

Given the high parameter count (8), 100% schema coverage, and destructive annotations, the description fully compensates for the absence of an output schema. It covers the critical workflow dependencies (brc_route_request, confirmWrite, confirmCounterpartyExplicit), the max batch size, and the routing semantics. For an agent to correctly invoke this transactional tool with all safety confirmations, the description provides complete contextual guidance beyond what schema and annotations alone offer.

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

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

Schema coverage is 100%, so the schema already documents all parameters well. The description adds value beyond the schema by explaining the relationship between routeToken and brc_route_request, the workflow ordering (lookup → preview → confirmation), and clarifying that routeToken is routing permission only. It reinforces the confirmWrite and confirmCounterpartyExplicit semantics that are in the schema but adds workflow context about when to set them true. Slight deduction as it doesn't elaborate on items structure beyond max items, but the schema handles that.

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 BRC payments with a maximum of 20 items per request. It distinguishes itself from sibling batch tools (e.g., brc_batch_cash_payments, brc_batch_purchases) by specifying 'BRC payments' and mentioning the required routeToken workflow context, making it unique among the many similar batch tools.

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

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

The description provides explicit when-to-use and workflow guidance: call brc_route_request first, retain the routeToken through lookup/preview/confirmation, and pass the same token on the final permitted transactional call. It also clearly states when not to use it (never invent a placeholder token) and what prerequisites are needed (confirmCounterpartyExplicit, preview-before-posting, confirmWrite). This exceeds typical tool description guidance.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the tool's write/destructive nature is known. The description adds valuable behavioral context beyond the annotations: the routing workflow requirement, the need to retain the token, and that previewing/confirmation still apply. It does not restate the annotations but enriches them with operational nuance.

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 two sentences: the first conveys purpose and batch limit; the second packs the essential routing workflow and confirmation warnings. Every sentence earns its place, is front-loaded, and contains zero 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 the tool's complexity (7 params, routing prerequisite, confirmation flags) and no output schema, the description covers the critical workflow well: it explains the prerequisite, the flow, and the confirmation requirement. It does not explicitly state which action (create/update/delete) the batch performs, but that is likely determined by the routeToken, making the description sufficiently complete for agent selection and safe invocation.

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

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

Schema description coverage is 100%, so all parameters already have strong descriptions in the schema. The tool description adds flow-level context (e.g., how routeToken and confirmWrite are used) but does not introduce new parameter meanings beyond the schema. This meets the baseline for high schema coverage.

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

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

The description starts with 'Processes a batch of products,' clearly identifying the verb and resource. It explicitly mentions the maximum batch size (20 items), distinguishing it from sibling batch tools for other entities (e.g., brc_batch_customers, brc_batch_purchases). The purpose is specific and immediately clear.

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

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

The description provides explicit step-by-step usage guidance: call brc_route_request first, retain the routeToken through all steps, and pass it on the final transactional call. It also warns against inventing tokens and clarifies that routeToken is not permission, requiring confirmWrite/confirmDelete. This offers strong when-to-use and when-not-to-use guidance, even naming the prerequisite sibling 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?

Annotations already establish destructiveHint=true and readOnlyHint=false; the description adds meaningful context by clarifying that routeToken is only a routing permission, not permission to post, and that preview/confirmation safeguards still apply. It could go slightly further by stating the concrete record-level effects of a confirmed batch, but it does not contradict the annotations.

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

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

The description is dense and front-loaded with its core purpose, and every sentence carries a necessary precondition or constraint. However, it is written as one long running paragraph; a bulleted structure for route workflow and confirmation rules would improve scannability.

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

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

For a complex transactional batch tool with no output schema, the description communicates the critical prerequisites: routeToken workflow, explicit counterparty confirmation, preview-before-posting, and the 20-item batch limit. Combined with full schema descriptions, an agent has sufficient context to sequence and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces routeToken and confirmCounterpartyExplicit behavior, but it does not add materially new parameter semantics beyond what the schema already provides for fields like priceBasis, confirmWrite, or connectionRef.

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

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

The description opens with 'Processes a batch of purchases,' giving a specific verb and resource that clearly distinguishes it from sibling batch tools like batch payments or batch invoices and from single-purchase create tools. The 'Maximum 20 items per batch request' detail further scopes the operation.

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 instructs the agent to call brc_route_request first, retain the returned routeToken through lookup/preview/confirmation, pass the same token on the final transactional call, and never invent a placeholder. It also states when confirmCounterpartyExplicit is required and that preview-before-posting and confirmWrite/confirmDelete still apply, giving strong when/when-not guidance.

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

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

Despite annotations already flagging destructiveHint=true and readOnlyHint=false, the description adds critical safety context: routeToken is not permission to post, preview-before-posting and confirmWrite/confirmDelete still apply, and explicit counterparty confirmation is required. Nothing contradicts the annotations (a write-oriented workflow with destructive potential is consistent with the hints).

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

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

The description is a dense single paragraph of ~130 words. Every sentence carries meaningful workflow or safety information, but the lack of any structural breaks or separation between purpose, token workflow, and confirmation rules makes it harder to scan than the clean two-sentence standard in the calibration examples.

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 batch operation with 8 parameters and no output schema, the description covers the essential workflow (route token acquisition and retention, batch size, confirmation gates, counterparty explicitness). The only meaningful gap is the absence of any note about response/error semantics for partial batch failures, which the missing output schema leaves entirely unspecified.

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

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

Schema description coverage is 100%, so the baseline is 3. The description nevertheless adds value beyond the schema by defining the token's lifecycle (retained through lookup, preview, and confirmation) and reinforcing the counterparty-explicitness rule with a "current conversation" scoping that the schema's param text only partially conveys.

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?

"Processes a batch of quotes" uses a specific verb+resource and is immediately differentiated from the many sibling batch tools (batch_purchases, batch_sales_invoices, etc.) and single-record tools like create_quote/update_quote. The maximum 20-item constraint further scopes the operation.

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 workflow guidance is provided: call brc_route_request first, retain the routeToken through lookup/preview/confirmation, pass the same token on the final transactional call, and never invent a placeholder token. It also clarifies when confirmCounterpartyExplicit may be true and warns against reusing a counterparty from an earlier preview — far beyond typical usage guidance.

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

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

Annotations declare destructiveHint=true, readOnlyHint=false. Description adds meaningful behavioral context beyond annotations: productId 0/1 are blocked regardless, routeToken is not permission to post (preview and confirm still apply), and it explains the confirmation workflow. No contradiction. The only slight gap is not stating exactly what is destroyed/changed (credit notes are created/written) but that's inherent in 'batch sales credit notes'.

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

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

The description is dense and long, covering multiple behavioral caveats and workflow steps. It is appropriately front-loaded with the primary purpose, but subsequent sentences pack many details in a single paragraph. While all are relevant, it borders on verbose; some content (e.g., 'Never invent a placeholder token') could be integrated more tightly. It is not inefficient, but readability suffers slightly from the block structure.

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 (8 parameters, 3 required, no output schema, nested items array), the description covers critical contextual details: product selection prerequisite, routeToken lifecycle, confirmation flags, company context, and max items. It explains when and how to interact with the agent for missing products, and clarifies that routeToken does not bypass confirmation. This is thorough 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 significant value beyond schema: it explains the runtime blocking of productId 0/1, the flow of routeToken through lookup/preview/confirmation, and the explicit requirement for confirmCounterpartyExplicit only after user confirmation. It clarifies behavioral constraints on parameters not fully evident from names alone.

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 credit notes and specifies the action (process) and resource (sales credit notes). It distinguishes from siblings like brc_batch_sales_invoices by the credit note domain, though both share the 'batch' prefix. It adds specific operational detail not present in the bare name.

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

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

Provides explicit when-to-use guidance: do not invent productId, must call brc_list_products first, when to ask user, max 20 items, must call brc_route_request first and retain token, and when confirmCounterpartyExplicit is set. It also mentions alternatives (brc_list_products) and exclusions (productId 0/1 blocked). This is comprehensive.

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

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

The description discloses important behavioral caveats that annotations alone do not convey: routeToken is not permission to post, preview-before-posting and confirmWrite still apply, and never invent a placeholder token. It also clarifies that confirmCounterpartyExplicit must be set explicitly based on the user's current-conversation confirmation, which is critical for safe transactional behavior.

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

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

The description is packed with necessary instructions without redundancy. Each sentence serves a purpose: defining the batch limit, specifying the routeToken requirement, the routing workflow, the confirmation stipulations, and the do-not-invent guidance. It is concise given the complexity of the transactional workflow described.

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 essential context for correct usage: the batch maximum, the prerequisite routeToken, the workflow steps, and the explicit confirmation requirements. It also addresses edge cases like empty or partial data and session rotation. No output schema exists, but the description sufficiently explains the invocation context without needing to detail return values.

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

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

The input schema already provides detailed descriptions for every parameter (100% coverage), so the baseline is 3. The description adds value by explaining the interplay between routeToken, confirmWrite, and confirmCounterpartyExplicit, and by emphasizing the workflow context (e.g., routeToken from brc_route_request, confirmWrite only after preview). This enriches parameter understanding beyond the schema, but not to the level of a 5 since the schema itself is very thorough.

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

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

The description clearly states the tool's purpose: 'Processes a batch of sales entries.' It uses a specific verb and noun, and the sibling context (brc_batch_sales_credit_notes, brc_batch_sales_invoices) distinguishes it as the batch handler for sales entries. No ambiguity exists about what this tool does.

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

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

The description provides explicit usage instructions: call brc_route_request first, retain the returned routeToken through lookup/preview/confirmation, and pass it on the final permitted transactional call. It also explains when confirmCounterpartyExplicit is required. This goes beyond mere context and gives a clear step-by-step invocation flow.

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

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

Annotations indicate destructiveHind=true, but the description goes far beyond, detailing placeholder blocking, VAT category validation, priceBasis handling, confirmation requirements (CR category, counterparty), note/deliveryTo defaults, and the rule that nothing is written until confirmWrite is true. No contradiction with annotations; these behavioral details are essential.

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, front-loaded with purpose and then systematic safety/guideline details. Every sentence contributes to operational clarity; however, it is verbose and could be tightened while retaining essential caveats.

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 (8 params, no output schema), the description is exceptionally complete. It covers prerequisites (routeToken), safety checks, confirmation flags, edge cases (product placeholder, VAT, multiple customers), and post-posting behavior. It fully equips an agent to invoke the tool correctly.

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

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

With 100% schema coverage, baseline is 3, but the description adds critical semantics: it explains productId 0/1 placeholder blocking (affecting items), clarifies that confirmCrAnalysisCategory and confirmCounterpartyExplicit require explicit user confirmation, and describes the meaning of priceBasis. These enrich parameter understanding beyond the schema, especially for the generic items array.

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' with specific verb+resource. It explicitly distinguishes from single invoice tools by mentioning 'batch' and contrasting with 'single sales invoices' throughout, making its unique scope 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 clear usage context: requires routeToken from brc_route_request, must call brc_list_products for product lookup, and specifies maximum items per batch. However, it does not explicitly state when to use this batch tool versus the single sales invoice tool, though the batch nature is implied.

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

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

The annotations indicate destructiveHint=true and readOnlyHint=false, correctly signaling a write operation. The description reinforces this by mentioning confirmWrite and preview-before-posting, and by noting the token is not permission to post. This fully discloses the side effects and required confirmations.

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 concise (three sentences) and effectively structured. However, it repeats some information already present in the schema descriptions (e.g., routeToken and confirmWrite semantics), which could be seen as redundant. Still, it does not bloat the entry and remains focused.

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 provides sufficient context for a skilled agent to invoke the tool correctly, including the workflow order, token retention, and confirmation requirement. It does not mention expected output or failure modes, but the absence of an output schema and the presence of sibling tools mitigate this gap. Overall, it covers the essential operational context.

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

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

The input schema provides detailed descriptions for all 7 parameters, with 100% coverage. Each field (e.g., routeToken, confirmWrite, companyName) has an explicit explanation of its purpose, source, and constraints. The description adds no additional parameter details, but none are needed given the schema's completeness.

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 reps, distinguishing it from other batch tools like brc_batch_customers or brc_batch_invoices. The verb 'processes' and specific resource 'sales reps' make the purpose unambiguous.

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

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

The description provides explicit usage instructions: how to obtain the required routeToken (via brc_route_request), that it must be retained through the workflow, and that confirmWrite/confirmDelete still apply. It also warns against inventing placeholders and clarifies that the token does not grant posting permission. This is thorough and actionable.

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

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

The description adds valuable safety context beyond the destructiveHint annotation: routeToken does not grant posting permission, preview-before-posting is mandatory, and confirmWrite/confirmDelete still apply. It gives an agent concrete guardrails for a destructive operation. The mention of confirmDelete is slightly ambiguous because the input schema only exposes confirmWrite.

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

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

The description is front-loaded and efficient, putting the operation and item limit first, then the route workflow and confirmation safety rules. Every sentence carries useful guidance and there is little wasted text.

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

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

Given the destructive nature and the seven parameters, the description explains routing and confirmation carefully, but it does not explain what each item in the batch must contain or what the batching action ultimately does. The mismatched sales-invoice-focused schema descriptions further increase ambiguity, so an agent still needs substantial guesswork.

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?

Since schema description coverage is 100%, the description does not need to restate every parameter, and it adds batch limits, routeToken flow, and confirmation behavior. Yet the items parameter remains an opaque generic object, and schema descriptions like priceBasis and confirmCrAnalysisCategory appear to refer to sales documents, not suppliers, which the description does not correct.

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

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

The description identifies the resource ('suppliers') and the batch scope, so an agent knows it is a batch supplier tool. However, 'processes' is vague and never states whether this creates, updates, or deletes supplier records, leaving the actual action to be inferred from the route 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 explicitly requires calling brc_route_request first, retaining the routeToken, and passing that same token on the final permitted transactional call. It also warns against inventing a token and clarifies that the token is not permission to post. It is strong on when to use, though it does not explicitly compare against single-item supplier tools.

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

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

Annotations already declare readOnlyHint: true and destructiveHint: false, so the safety profile is known. The description adds that it returns warnings and should be used before mutations, providing context beyond the annotations. It doesn't contradict annotations, and the added detail about returning warnings in advance is 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?

Two sentences, no filler, information is front-loaded: the purpose is stated immediately, then usage guidance and alternative. Every clause contributes value, making it 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?

The tool is a read-only check with a simple purpose. The description explains what it checks, when to use it, what it returns (warnings), and how it relates to a broader alternative. No output schema is present, but the description's mention of warnings sufficiently conveys the return value. It's complete for its scope.

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 with clear descriptions. The description adds meaning to the workflow parameter by explicitly listing its valid values (sales invoice, purchase, cash receipt, or statement), reinforcing the enum and clarifying purpose. It also connects connectionRef indirectly by referencing the workflow context, though that's already well-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?

Clearly states the tool checks BRC company processing settings before VAT-sensitive or payment-terms-sensitive workflows, and returns warnings to show before creating or changing records. It explicitly distinguishes itself from brc_company_readiness_check, showing a specific verb and resource beyond the tool name.

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

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

Provides explicit guidance: use for one workflow (sales invoice, purchase, cash receipt, or statement) and names the alternative brc_company_readiness_check for overall readiness, with a clear description of the alternative's scope. This is a textbook example of when-to-use vs. 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?

The description indicates the destructive nature by specifying that it clears all credentials, which aligns with the destructiveHint annotation and adds specific detail about what is affected (all company contexts). It does not mention any other side effects, but the core destructive behavior is conveyed.

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, direct sentence with no redundant words, effectively conveying the tool's purpose.

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

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

The description lacks information about reversibility, consequences of clearing credentials (e.g., invalidating active connections), or any return values. Given the destructive nature, this omission leaves the user without crucial context.

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 single parameter (connectionRef) is fully described in the schema with detailed guidance on its usage and what it is not. The top-level description adds no further information about parameters, so the baseline score of 3 applies given 100% schema coverage.

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

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

The description clearly states the action (clears), the object (all connection credentials), and the scope (all company contexts) from MCP server memory, making it unambiguous.

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

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

The description provides no guidance on when to use this tool, when not to use it, or any alternatives. It only states what it does, leaving the user to infer the appropriate usage context.

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

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

The two-step confirmation flow is disclosed, but the description introduces confusion by referencing 'confirmWrite' while the schema includes both 'confirmClear' and 'confirmWrite', and the exact role of each is unclear. This undermines transparency about actual behavior.

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

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

The description is repetitive: 'show a plain-English preview before posting in chat, then retry with confirmWrite: true' is nearly duplicated by 'Red shows what it will post and waits for confirmation.' This could be condensed significantly.

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 output (confirmation_required and payload preview) and specifies the scope ('this MCP server session'), but it lacks clarity on parameter usage and final outcomes, leaving the overall picture incomplete.

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 context about the confirmation flow but only mentions 'confirmWrite', ignoring 'confirmClear' and 'connectionRef'. The schema already provides descriptions, so the added value is limited and muddled by the parameter mismatch.

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 audit log, but the use of 'Red' is ambiguous (likely a company name) and could confuse agents. The purpose is still discernible.

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

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

The description explains the two-step confirmation process, which is a usage guideline, but it does not differentiate this tool from sibling clearing tools (e.g., brc_clear_company_api_key) or mention when not to use it.

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

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

The annotations declare destructiveHint=true, which this description does not contradict, but the description adds minimal behavioral detail. It does not state whether the operation is reversible, whether it affects the live API connection, whether the key is erased from memory only or also from persistent storage, or whether confirmation is required. Since the annotation already communicates destructiveness, the description should add context about the scope and side effects; it only vaguely says 'clears... from MCP server memory'.

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, focused sentence with no filler words. It front-loads the action and resource. It could be slightly more concise by dropping 'named' or adding behavior details, but as written it is efficient and clear.

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

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

This is a destructive mutation tool with no output schema and no description of return value or side effects. For a tool annotated destructiveHint=true, the agent needs to know what happens after clearing (e.g., subsequent API calls fail, must re-confirm connection) and whether this is reversible. The description is too thin to fully prepare an agent for the consequences of invoking it.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description itself doesn't add parameter-level meaning beyond what the schema provides, so a baseline of 3 is appropriate. It does implicitly signal that companyName is the key identifier and connectionRef is an opaque reference, but that's already in the schema descriptions.

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

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

The description uses a specific verb ('Clears') and identifies the exact resource ('API key for a named company context from MCP server memory'). It clearly distinguishes this tool from its sibling brc_clear_all_company_api_keys (single vs. all) and from brc_get_company_api_key_status (status vs. clearing).

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 existence of brc_clear_all_company_api_keys and brc_get_company_api_key_status in siblings implies when to use this vs. alternatives, though the description doesn't explicitly say 'use this for one named company, use clear_all when...'. The tool name and description make the single-company scope clear enough that an agent would infer the proper alternative.

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

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

The description adds important behavioral context beyond the annotations: 'A routeToken is not permission to post — preview-before-posting and confirmWrite/confirmDelete still apply.' This informs the agent about safety and approval requirements. Annotations already indicate a non-read-only, non-destructive action, and the description complements rather than contradicts them. It could add more detail about post-close effects, but it provides meaningful context.

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

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

The description is compact, front-loaded with the core action, and every sentence provides value. It packs prerequisite routing, token-handling instructions, and confirmation caveats into four short sentences 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?

The tool sits in a multi-step workflow, and the description explains the prerequisite routeToken flow and safety checkpoints well. It does not describe return values, but no output schema exists and none is strictly required for a close action. The missing details (e.g., specific side effects on the quote) are minor given the schema and annotations coverage.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds useful context about routeToken's lifecycle and purpose, which goes slightly beyond the schema, but it does not explain id, companyName, confirmWrite, or connectionRef. The meaningful additions are limited to token handling and confirmation requirements, so a 3 is appropriate.

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

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

The description clearly states a specific action with a specific resource: 'Closes a BRC quote.' This distinguishes it from sibling tools like brc_reopen_quote, brc_delete_quote, and brc_update_quote. It also frames the tool as the terminal transactional step in a route workflow, which further clarifies its unique role.

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 sequencing guidance: 'Call brc_route_request first with the user's complete original action request' and 'Retain the returned routeToken through lookup, preview, and confirmation.' It also warns against inventing placeholder tokens. However, it does not explicitly say when NOT to use this tool or name direct alternatives, so it falls just short of a 5.

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

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

Annotations already state readOnlyHint=true and destructiveHint=false, so the read-only nature is covered. The description adds value by detailing the scope of what is reported (connection status, financial year, VAT rates, settings) and explicitly says 'reports' rather than implying mutation. The mention of 'no user/workspace filtering' analogy isn't here, but the description still adds concrete behavioral detail beyond annotations without contradicting them.

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

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

The description is two sentences, front-loaded with the core purpose, and efficiently enumerates the scope. Every sentence contributes: the first defines what it does and reports, the second provides usage guidance and sibling differentiation. Zero waste.

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

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

For a read-only diagnostic tool with 100% schema coverage, readOnlyHint annotation, and no output schema, the description is complete: it enumerates the aspects checked, indicates it's a readiness score, and provides clear usage boundaries relative to sibling tools. No output schema means explaining return values isn't required, and the description sufficiently sets expectations for what the tool will report.

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 parameters are fully described in the schema. Despite this, the description adds value by clarifying the operational usage of connectionRef—explaining that it's an opaque reference returned by brc_confirm_company_connection, should be reused, not an API key, and not contain credentials. This goes beyond the schema's basic description, especially for the connectionRef semantics.

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

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

The description clearly states 'Read-only company health and readiness check' and enumerates specific items checked (connection status, financial year, sample reference data, Sales VAT rates, etc.). It distinguishes itself from the sibling tool brc_check_transaction_settings by contrasting overall readiness scoring vs. workflow-specific warnings.

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 usage guidance: 'Use this for overall company readiness before starting work.' It also explicitly names the alternative tool (brc_check_transaction_settings) and explains when to use that instead, satisfying the when/when-not criteria.

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

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

Beyond the annotations, the description explains that the tool 'Claims a completed secure Red connection code for the current MCP session', returns an opaque connectionRef, never exposes credentials, and should be used across session-id rotations. This adds meaningful behavioral context that the annotations alone do not provide, and there is no contradiction with readOnlyHint/destructiveHint.

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 purpose and triggers, but it contains redundancy such as repeating the action synonyms and stating 'This tool is brc_confirm_company_connection.' The security and session-rotation guidance is useful, though a few sentences could be tightened without losing meaning.

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

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

Despite having no output schema, the description fully covers the tool's return value (opaque connectionRef), its lifecycle, when to use it, and critical security constraints. It is complete enough for an agent to invoke the tool correctly and handle the resulting connection reference properly.

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 the schema already covers both parameters, the description adds essential semantics: the code comes from the secure page success message, connectionRef is returned by this tool, must be passed silently, should be reused on later calls, and is not an API key or credential. This goes well beyond the schema field descriptions.

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

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

The description states the specific action ('Confirm company connection'), lists equivalent user phrasings, and clarifies the underlying operation ('Claims a completed secure Red connection code'). It also distinguishes the tool from its sibling brc_start_company_connection by instructing the agent not to start a new connection while a 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?

It gives explicit trigger conditions: when the user says 'confirm company connection', 'finish connection', 'complete connection after the secure page', or pastes a confirmation code. It also specifies the correct timing (after the secure page submission) and explicitly warns not to call brc_start_company_connection while a valid connectionRef exists.

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?

Even with annotations indicating a write/destructive operation, the description adds valuable behavioral context: the API generates the reversing child automatically, routeToken is not posting permission, and preview-before-posting plus confirmWrite/confirmDelete still apply. This significantly exceeds annotation-only disclosure.

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

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

The description is front-loaded with the core purpose and then provides essential routing, confirmation, and safety warnings. It is somewhat long, but each sentence adds meaningful workflow or behavioral detail rather than repetition or padding.

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 11-parameter transactional tool with no output schema, the description covers the essential workflow prerequisites, routeToken lifecycle, preview/confirmation behavior, and parent-child generation. It does not describe return values or error conditions, but it is otherwise sufficient for safe invocation.

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

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

All 11 parameters are already well described in the input schema (100% coverage), but the description adds important semantic context for routeToken (must come from brc_route_request, never a placeholder, reused across the workflow) and confirmWrite (only after explicit confirmation). It does not clarify remaining params, but the schema handles those.

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

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

The description opens with 'Creates a new parent Accrual,' naming the specific verb and resource. It further distinguishes this tool from sibling create/update/delete tools by explaining the parent-transaction shape and automatic reversing child transaction, which is unique to accrual 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 gives clear workflow context: call brc_route_request first, retain and reuse the returned routeToken, and do not pass confirmWrite=true until the user has explicitly confirmed. It does not explicitly name alternative tools for comparison, but the workflow guidance is strong.

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

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

Annotations (all false) provide minimal safety signals, but the description adds rich behavioral context beyond them: the explicit user-confirmation gate before confirmCreate=true, the side effect that BRC may auto-create the Bank Payments category when categoryId is omitted, and the crucial clarification that a routeToken is 'not permission to post — preview-before-posting and confirmWrite/confirmDelete still apply.' It also accurately implies a write operation, which is consistent with readOnlyHint=false. No contradiction with annotations.

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

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

Six dense sentences with zero fluff, front-loaded with the action verb and immediately followed by the highest-stakes warning (confirmation gate). Every sentence earns its place: required fields, optional-field behavior, token lifecycle, and safety caveats. It is long but proportionally so given the 20-parameter surface and the complex routing workflow.

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

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

Despite 20 parameters, nested objects, and the non-obvious routeToken routing protocol, the description covers the critical ground: creation semantics, confirmation safety, token lifecycle, and constraints on nominalAcCode. It mentions the canonical route_request sibling by name and the preview-before-posting protocol. Minor gap: no post-conditions (e.g., how the created account is referenced in subsequent calls) beyond implicit creation, and no mention of connectionRef/company context even though that is schema-documented.

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

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

The description significantly enriches the schema at 55% coverage. It names acCode, details, lastChq, and nominalAcCode as required — a detail that arguably conflicts with the schema's 2 required params but provides domain-meaningful guidance. It adds non-obvious behavior for categoryId (auto-creation when omitted) and clarifies nominalAcCode must reference an existing balance-sheet bank nominal account, surpassing what the schema's brief descriptions provide.

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

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

The opening phrase "Creates a BRC bank account" is a specific verb+resource statement that clearly identifies the tool's function. However, it does not explicitly differentiate from sibling tools like brc_update_bank_account or the broader create_* family, relying on the tool name alone for that distinction. This matches 'clear but no 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?

Provides strong workflow guidance: call brc_route_request first, retain the routeToken through lookup/preview/confirmation, and never invent a placeholder token. It also specifies the confirmation gate for confirmCreate=true. However, it never names alternative tools to use instead (e.g., brc_update_bank_account for modifications, brc_get_bank_account for reads), so there are no explicit when-not alternatives.

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

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

Annotations provide destructiveHint=true and readOnlyHint=false, but the description goes further: it clarifies that a routeToken is not permission to post, that preview-before-posting and confirmWrite still apply, and that nothing is written until user confirmation. It also specifies the counterparty confirmation rule, adding significant behavioral context beyond the annotations.

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

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

The description is long but each sentence delivers essential information for a 20-parameter transactional tool. It is front-loaded with purpose, then usage modes, then workflow constraints. No fluff; the structure is logical and information-dense, though slightly verbose compared to simpler tools.

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 (20 params, no output schema), the description fully covers the three use cases, the required routeToken sequencing, confirmation gates, and counterparty rules. It also mentions bookTranTypeId default and analysis category constraints. It is comprehensive enough for an agent to correctly invoke the tool without relying solely on schema.

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

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

Schema coverage is high (85%) with per-parameter descriptions, so baseline is 3. The description adds value by grouping parameters into the three usage modes (e.g., supplierId+ledger, bankAccountId+lodgement) and explaining how accountCode must match analysisCategoryId (CP01-CP03). It also elaborates on confirmWrite and confirmCounterpartyExplicit semantics not fully captured 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 states 'Creates a BRC cash payment' with specific verb+resource, and clearly distinguishes the three usage variants (supplierId+ledger, bankAccountId+lodgement, analysisCategoryId+accountCode). This differentiates it from sibling tools like create_cash_receipt or create_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?

Explicitly describes when to use each parameter combination, mandates calling brc_route_request first, and explains the required workflow with routeToken, preview-before-posting, confirmWrite, and confirmCounterpartyExplicit. It even warns against inventing placeholder tokens and reusing counterparties from previews, providing strong when-to-use and when-not-to-use guidance.

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

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

The description discloses key behavioral traits beyond annotations: entryDate/procDate default to today, VAT fields are conditionally sent, and the requirement to retain and reuse the same routeToken and connectionRef. It also explicitly states 'Nothing is written to Big Red Cloud until you confirm,' aligning with the destructiveHint. No contradictions with annotations.

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

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

The description is well-structured and front-loaded with the purpose, then gives essential usage workflow. Each sentence adds value, avoiding redundancy. It is moderately long but appropriate for the tool's complexity, with clear logical flow: purpose, defaults, VAT condition, then prerequisites and confirmations.

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

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

For a complex transactional tool with 32 parameters, the description provides substantial operational context: the routing workflow, confirmation flags, connection handling, and conditional field behavior. It does not enumerate all fields or explain return values, but it covers the most critical aspects. Given the destructive nature and lack of output schema, it is quite complete, though a list of common flat fields would push it to a 5.

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

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

The schema coverage is only 16%, so the description must add meaning for the many undocumented parameters. It does explain critical ones: routeToken, companyName, confirmWrite, confirmCounterpartyExplicit, connectionRef, and the default date behavior. However, it does not cover the majority of flat fields (e.g., total, discount, acCode) leaving the agent with little guidance for those. It partially compensates but leaves 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 the tool's purpose: 'Creates a BRC cash receipt.' It distinguishes itself from siblings like brc_create_cash_payment and brc_create_sales_invoice by specifying the cash receipt type and the required routeToken workflow. The verb and resource are explicit and 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?

Provides explicit when-to-use instructions: 'Call brc_route_request first with the user's complete original action request.' It also states prerequisites (routeToken, confirmCounterpartyExplicit) and warns against misuse ('Never invent a placeholder token'). It clarifies that routeToken is not permission to post, reinforcing the preview/confirm flow.

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

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

The description discloses non-destructive behavior (no opening balance creation), emphasizes not inventing data, and clarifies that routeToken is not permission to post. It also warns against placeholder tokens, adding transparency beyond the sparse annotations.

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

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

The description is repetitive, restating the same instructions multiple times (e.g., not inventing values, routeToken handling). It could be condensed significantly without losing meaning, reducing 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?

Despite verbosity, the description covers the full workflow: required fields, optional handling, routeToken acquisition, confirmation, and exceptions (opening balance, email match). It is complete but could be more efficient.

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 enriches the schema by explaining that payload requires code and name, clarifies the role of routeToken, confirmWrite, and connectionRef, and adds guidance on when to ask the user. This goes beyond the schema's already detailed parameter descriptions.

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

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

Clearly states it creates a BRC customer, distinguishing it from other create tools. The phrase 'using a raw BRC payload' is slightly ambiguous but the payload parameter is described separately.

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: ask for missing required fields, omit optional fields, do not invent values, call route_request first, and follow preview/confirmation steps. These guidelines are specific and actionable for the agent.

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

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

While annotations indicate destructiveHint=true, the description goes further by explaining the write semantics: it requires balanced lines, mandates preview-before-posting, and clarifies that routeToken is not permission to post. It also cautions about token reuse and the confirmWrite gate, adding meaningful behavioral context beyond the annotations.

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

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

The description is concise yet information-dense, covering purpose, balanced-line requirement, workflow steps, and critical warnings in about six sentences. It is front-loaded with the primary action ('Creates a new Nominal Journal Batch') and each subsequent sentence earns its place by adding essential workflow or safety details. No filler.

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

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

Given the tool's complexity (9 params, nested accountTransactions, transactional workflow), the description sufficiently covers the required routeToken sequence, preview-before-posting, confirmWrite gating, and balanced journal constraint. It addresses the main operational risks and prerequisites without needing an output schema, as creation tools typically return simple confirmation. The combination of description and detailed schema makes the tool self-explanatory for an 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?

The schema already provides 100% parameter descriptions, so baseline is 3. The description adds semantic value by explaining the balanced-debits-and-credits invariant for accountTransactions and the role of confirmWrite in the two-step confirmation flow. It also explains the routeToken's lifecycle (retained through lookup/preview/confirmation), which is not fully captured in the schema. This exceeds the baseline by enriching the meaning of key 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 explicitly states 'Creates a new Nominal Journal Batch' – a specific verb+resource that immediately distinguishes it from sibling batch tools like brc_batch_sales_invoices. It further clarifies the balanced debit/credit requirement and the transactional workflow, making the tool's role 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 guidance on when to call: 'Call brc_route_request first', 'Do not call with confirmWrite=true until the user has reviewed the preview and explicitly confirmed creation', and 'Requires routeToken from brc_route_request'. It also states the token must be retained and reused, and warns against inventing placeholders. This clearly outlines the intended usage sequence and prerequisites.

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

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

Beyond the destructiveHint annotation, the description discloses important behavioral requirements: confirmation flags (confirmWrite, confirmCounterpartyExplicit) and the fact that routeToken alone grants no posting permission. It also warns against inventing placeholder tokens, adding safety context.

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 logically structured, covering purpose, usage modes, prerequisites, and confirmations without unnecessary fluff. 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?

The description explains the workflow and confirmation steps well, but does not mention what the tool returns on success or failure. Given the absence of an output schema, this omission leaves the description incomplete regarding expected outcomes.

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 clarifies relationships among parameters (e.g., supplierId vs analysisCategoryId/accountCode) and explains the role of routeToken and confirmation flags. However, it does not elaborate on all parameters, leaving some (like bankAccountId) unexplained, though the schema provides descriptions for many.

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

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

The description clearly states the tool's purpose (creates a BRC payment from the Payments book) and distinguishes between supplier payments and analysed bank payments, though it doesn't explicitly differentiate from sibling payment tools 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 specific usage guidance: which parameters to use for different payment types, and mandates the prerequisite call to brc_route_request with token handling. It does not explicitly mention alternatives, but the context is clear enough for selecting the right 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?

Even though annotations indicate destructiveHint: true and readOnlyHint: false, the description adds substantial context: it generates a reversing child transaction, requires preview-before-posting, and outlines confirmWrite semantics. It also warns that routeToken does not override preview requirements. No contradiction with annotations found; instead it enriches the safety profile.

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

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

The description is about 120 words, which is slightly long but each sentence adds critical workflow information. It front-loads the core action, then explains required prerequisites and confirmWrite rules. No filler or redundancy; the length is justified by the complex transactional workflow.

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 11 parameters, many similar create tools, and a required routing workflow, the description covers the essential steps: obtaining routeToken, preview-before-posting, and confirmWrite. It doesn't explain return values (no output schema), but that's not expected. The child transaction generation is clearly noted. Overall, it provides the necessary context for correct invocation without being exhaustive.

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

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

The schema covers 100% of parameters with descriptions, so baseline is 3. The description adds extra workflow semantics for routeToken (retain, never invent, reuse) and confirmWrite (must be true only after explicit confirmation), which goes beyond the schema's generic field descriptions. This justifies a score above 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 the tool creates a new parent Prepayment and specifies the parent transaction shape with shared logic generating the reversing child transaction. It uses a specific verb (creates) and resource (prepayment), and the mention of parent/child distinguishes it from other create 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?

The description gives explicit workflow guidance: call brc_route_request first, retain the routeToken, and never invent a token. It also states when not to call (confirmWrite=true only after user confirmation), and clarifies that routeToken is not permission to post. This clearly guides when and how to use the tool relative to the routing process.

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

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

Annotations already indicate readOnlyHint=false, destructiveHint=false, but the description adds crucial behavioral context: the routeToken is not permission and confirmWrite must be true only after explicit user confirmation, with nothing written until confirmed. This goes beyond annotations, though it doesn't detail what happens to existing data or error states explicitly.

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 few sentences long, front-loaded with the core action, and includes important workflow details without excess. However, it repeats some information already in the schema (e.g., confirmWrite and routeToken details), but it adds the workflow sequence which is essential; it's efficient but could be slightly 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 (multiple steps, prerequisites, confirmation flow) and the rich annotations and schema, the description covers the critical workflow context: routeToken prerequisite, token retention, and confirmation requirements. Since there is no output schema, it doesn't explain the return value, but for a create tool with good schema coverage this is acceptable. It is complete enough for an agent to use correctly.

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

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

Schema description coverage is 100%, so the schema already documents all 5 parameters. The description does not add extra meaning about parameters beyond what's in the input schema, but it does reinforce the routeToken and confirmWrite semantics, which is useful though not necessary. 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 it creates a BRC product using a raw BRC payload, and it mentions a necessary prerequisite involving routeToken. It differentiates from siblings by emphasizing the raw payload and the required routing workflow, distinguishing it from batch product creation and updates.

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_route_request first with the user's complete original action request, to retain and pass the same routeToken, and to never invent a token. Also differentiates from transactional tools by noting that routeToken is not permission to post and that preview-before-posting and confirmWrite still apply, giving 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=true), the description reveals important behavioral traits: historical dates are not automatically refused and the endpoint decides support, routeToken is not permission to post, and confirmations are mandatory. It also discloses the need for explicit counterparty confirmation in the current conversation. These insights substantially exceed what annotations alone provide.

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

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

The description is lengthy but every sentence carries operational value for a complex, high-stakes tool. The main verb and purpose are front-loaded in the first sentence, and warnings about routeToken and confirmations are repeated for emphasis. Though slightly repetitive, the structure mirrors the actual workflow and is not wasteful given the 18-parameter 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?

With 18 parameters, no output schema, a large sibling list, and destructiveHint=true, the description supplies a complete operational picture: the alternate tool, the route workflow, date handling, confirmation gates, and counterparty rules. It gives an agent everything necessary to select and safely invoke this tool without external lookup.

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

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

The input schema already covers all 18 parameters with descriptions (100% coverage), and the description adds meaningful guidance for key parameters: reference is required under manual-ref configuration, routeToken must come from brc_route_request and be retained, and confirmCounterpartyExplicit must be true only after explicit user confirmation. While it doesn't dive into every parameter, it enriches the semantics of the most critical ones, lifting it above the schema-only 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 opens with a specific verb and resource: 'Creates a BRC purchase using structured MCP fields.' It immediately differentiates from the sibling brc_create_purchase_gen_ref by calling out the manual-reference scenario and explicitly pointing to the alternative, making the purpose unmistakably clear.

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

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

The description gives explicit when-to-use guidance: 'Requires a reference when the company is configured for manual purchase references; otherwise prefer brc_create_purchase_gen_ref.' It also prescribes a complete workflow: call brc_route_request first, retain and reuse the routeToken, and never invent a placeholder token. It further states that confirmWrite/confirmDelete and confirmCounterpartyExplicit prerequisites apply, leaving no ambiguity about 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?

Annotations only state destructiveHint: true and readOnlyHint: false, so the description carries the transparency burden and exceeds it. It discloses the routeToken workflow requirement, that 'A routeToken is not permission to post,' that the endpoint (not the client) decides historical date validity, the confirmWrite/confirmDelete gate, and gives counterparty confirmation conditions. These are valuable behavioral details well beyond annotation data, with no contradiction.

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

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

The description is dense (~160 words) but efficiently structured: purpose → usage condition → date edge-case → token workflow → confirmation guards. Every sentence adds necessity, especially given the tool's destructive nature, and the critical workflow caveats ('Never invent a placeholder token', 'Do not reuse a counterparty') justify the length. No filler or 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 highly complex tool (17 params, 14 required, destructive, part of a multi-step workflow with tokens and confirmations) with no output schema and minimal annotations, this description covers all critical operational aspects: preconditions (auto-gen-ref config), prerequisite calls (brc_route_request), token lifecycle, confirmation requirements, and date/index edge cases. The only omission is return-value behavior, but given the tool's complexity is workflow-driven rather than payload-driven, the description 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?

Schema description coverage is low at 29% (only 5 of 17 params), so the burden falls on the description, which compensates meaningfully for routeToken and confirmCounterpartyExplicit by explaining their workflow role and trust conditions. However, the remaining ~12 parameters (e.g., netAmount, vatRateId, procDate) get no additional semantic context beyond the schema's type info, leaving a significant portion of the parameter space under-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 opening sentence uses a specific verb-plus-resource construction ('Creates a Purchases Book purchase with a generated reference using structured fields') and clearly differentiates from sibling brc_create_purchase via the 'generated reference' qualifier and the condition 'Use when the company is configured for auto-generated purchase references.' The purpose is unambiguous and distinct from its 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 explicitly states when to use the tool ('Use when the company is configured for auto-generated purchase references') and gives a clear call sequence ('Call brc_route_request first... pass the same token'). However, it stops short of explicitly naming an alternative tool to use when the company does NOT use auto-generated references, so while context is strong, explicit exclusion/alternative naming is absent.

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

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

Discloses that 'Nothing is written to Big Red Cloud until you confirm,' preview behavior for missing phone/email, and that 'A routeToken is not permission to post.' These go well beyond the sparse annotations (all false) and clarify side effects and 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 long but every sentence carries critical information for a 30-parameter transactional tool. It is front-loaded with the core purpose and then logically walks through prerequisites, confirmation flags, and exclusions. Could be improved with bullet points, but 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 no output schema and no annotations, the description covers the full workflow: prerequisites, routeToken lifecycle, preview behavior, confirmation requirements, and parameter constraints. It doesn't mention return values, but for a create tool the emphasis on preconditions and side effects is more important.

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 to key parameters: quote reference requirements, saleRepId/saleRepCode (no defaults, list if missing), analysisCategoryId/accountCode (from Sales Analysis, don't default), and confirm flags. Schema coverage is only 40%, so this compensation is valuable, though many simpler params like quantity and unitPrice are left to the schema.

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

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

The description opens with 'Creates a BRC quote using structured MCP fields,' a specific verb and resource. It further clarifies scope by stating when a quote reference is required and when not to use the tool, though it doesn't explicitly name sibling tools like brc_create_quote_gen_ref.

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-not guidance: 'Do not use when Quotes reference setting is Unknown unless the user has provided a quote reference.' It also outlines the required workflow (call brc_route_request first, retain routeToken) and gives fallback instructions ('list sales reps or ask the user to choose one').

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

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

The description goes beyond the annotations by detailing the required confirmation workflow: 'Nothing is written to Big Red Cloud until you confirm', 'preview-before-posting and confirmWrite still apply', and 'routeToken is not permission to post'. These are critical behavioral safeguards not captured in the readOnlyHint/destructiveHint annotations.

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

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

The description is a single, lengthy paragraph with redundant repetitions of key points (e.g., routeToken requirements, confirmation rules). It repeats 'Nothing is written to Big Red Cloud until you confirm' and 'preview-before-posting and confirmWrite still apply' multiple times, making it overly verbose and difficult to parse.

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 essential workflow prerequisites (routeToken, confirmations, sales rep, analysis category) and mentions the special case of blank customer phone/email in previews. However, it omits guidance on other parameters like productId, vatRateId, or companyId, and does not clarify the overall sequence of calls beyond routeToken retrieval, leaving some gaps for a complex tool.

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

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

The description adds meaningful context for several parameters (e.g., saleRepId/saleRepCode must come from brc_list_sales_reps, analysisCategoryId must not default to CR01, routeToken must be retrieved from brc_route_request). However, not all 30 parameters are explained in the description, relying on schema descriptions for some, and the schema coverage is only 40%.

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 the exact function: 'Creates a BRC quote with a generated reference using structured MCP fields.' This clearly distinguishes it from sibling tools like brc_create_quote, which likely handles manual references, and includes the specific 'generated reference' 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?

It explicitly states when to use this tool: 'Use when quote references are auto-generated in Big Red Cloud, or when the user has confirmed auto-generate after Quotes reference setting was Unknown.' This provides clear conditions for selection, though it does not explicitly contrast with the manual-reference alternative, slightly lowering the score.

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

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

The description adds value beyond the destructiveHint annotation by clarifying this is the 'final permitted transactional tool call' that posts data. It carefully explains that a routeToken 'is not permission to post' and that preview-before-posting and confirmWrite still apply. It doesn't explicitly mention audit logging or irreversibility, but given the annotation already flags destructiveness, the description adds solid context about the confirmation workflow.

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?

This is a 250+ word wall of text with no paragraph breaks, bullets, or prioritization. While every sentence carries meaning, the dense run-on structure makes it hard to parse. It repeats 'Requires' multiple times and buries the most critical workflow steps (route token, preview) in the middle. It over-explains the obvious ('Never invent a placeholder token') while the overall structure defeats readability.

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 — 25 params, 20 required, destructive action, 32% schema coverage, no output schema — the description does a solid job covering the workflow: prerequisites, routing, confirmations, and safety guards. It explains the counterparty confirmation rule and the analysis category requirement thoroughly. Gaps include: no explanation of return values (though no output schema exists to leverage), no date format guidance for entryDate/procDate, and no description of what happens when route validation fails.

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 only 32% schema coverage, the description carries responsibility for the most critical parameters. It explains saleRepId/saleRepCode must come from brc_list_sales_reps (sources them), analysisCategoryId/accountCode must come from a Sales Analysis category, and routeToken from brc_route_request with retention rules. However, entryDate/procDate formats, the difference between acCode/accountCode, and the relationship between netAmount/quantity/unitPrice remain unexplained, leaving a 68% gap mostly unaddressed.

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 BRC sales credit note using structured MCP fields' — a specific verb+resource. It even differentiates from the sibling brc_create_sales_credit_note_gen_ref by directing users to the alternative when the company uses auto-generated references. This is exactly what distinguishes it from siblings.

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

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

Exceptional guidance. It explicitly says 'otherwise prefer brc_create_sales_credit_note_gen_ref' (alternative), gives negative instructions ('Do not use default or demo sales rep values', 'Do not default to CR01/Customer'), and provides a step-by-step workflow (call brc_route_request first, then preview, then confirm). This is the gold standard for 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?

Annotations declare destructiveHint=true and readOnlyHint=false, and the description reinforces that this is a write operation with guardrails. It discloses that routeToken 'is not permission to post', that preview-before-posting and confirmWrite/confirmDelete still apply, and that counterparties must be explicitly confirmed in the current conversation. This adds substantial behavioral context beyond what annotations alone provide.

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

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

The description is roughly 200 words, but every sentence carries a distinct requirement: sales-rep validation, analysis-category guardrail, routeToken workflow, and confirmation flags. It is front-loaded with the core purpose before enumerating preconditions. Though dense, the structure is coherent for a tool with many workflow prerequisites.

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, multi-confirmation transactional tool, it covers the key contexts: when to use, expected payload fields, how to obtain and use routeToken, and the confirmation semantics. No output schema exists, and return values are not described — a minor gap balanced by the preview-before-posting workflow. The description is complete enough for correct agent 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 86%, and the description adds meaning beyond the schema. It specifies that the opaque 'payload' must contain saleRepId, saleRepCode, analysisCategoryId, and accountCode — fields entirely missing from the schema. It also extends confirmCrAnalysisCategory and confirmCounterpartyExplicit with 'only after user confirms' semantics that go deeper than their schema descriptions.

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

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

States 'Creates a BRC sales credit note with an auto-generated reference using a raw BRC payload' — a specific verb, resource, and the auto-generation differentiator. 'Use when the company is configured for auto-generated sales references' clearly contrasts with the non-gen-ref sibling brc_create_sales_credit_note. Purpose is unambiguous.

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

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

Provides explicit when-to-use guidance: 'Use when the company is configured for auto-generated sales references', implying the manual-reference alternative. Adds detailed preconditions (saleRepId/saleRepCode, analysisCategoryId/accountCode) and workflow ordering (call brc_route_request first, retain the same routeToken). Also states when to ask the user vs. infer values, which is strong usage guidance beyond the schema.

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

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

Beyond the destructiveHint true annotation, the description explains important restrictions: routeToken is not permission to post, preview-before-posting and confirmWrite/confirmDelete still apply, and counterparty confirmation cannot be 'inherited' from an earlier preview. This is valuable behavioral context, although the description does not describe the full effect or consequences after a confirmed posting.

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

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

The description is well-structured and front-loaded: it identifies the action, then lays out the required token workflow, confirmation, and additional preconditions. It is a bit longer than other descriptions, but most sentences earn their weight given the safety-sensitive and workflow-heavy context. There is minor repetition about the routeToken, but the overall style is 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?

The tool is a complex transactional tool with 17 parameters, 14 required, and no output schema, while the schema descriptions cover only a small slice. The description focuses mainly on routeToken and confirmation behavior; it does not tell the agent how to obtain/call fill required accounting, VAT, analysis, or date fields. Given the unsupported complexity, this leaves the description not complete enough for reliable invocation.

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

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

The schema description covers only 29% of the 17 parameters, and the description does not compensate for the remaining gap. It re-explains routeToken, confirmWrite, and counterparty confirmation, but provides no guidance about fields like acChapter, procDate, bookTranTypeId, analysisCategoryId, accountCode, netAmount, or vatPercentage. With low schema coverage and no additional evidence per for these parameters, the help is meaningfully incomplete.

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

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

The description opens with a clear verb and resource: 'Creates a BRC sales entry', so the agent can tell it writes a sales entry. It does not explicitly distinguish it from sibling tools like brc_create_sales_invoice or brc_batch_sales_entries, but the named resource is specific enough for a human/AI to identify its primary role.

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 strong workflow guidance: call brc_route_request first, keep the same routeToken across lookup/preview/confirmation, pass it on the final transactional call, and never invent a placeholder. It also clearly sets confirmation expectations for preview and counterparty confirmation. It does not explicitly say when to choose this controller over relevant siblings such as invoice creation or batch entry tools, so it is not a full 5.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, and the description compliments this by stating 'Nothing is written to Big Red Cloud until you confirm' and explaining preview-before-posting plus confirmWrite semantics. It also discloses blocking rules for productId, VAT rates, and CR account codes. It doesn't explicitly say what the return value looks like, but for a mutation tool with this much safety context, this is strong 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 and uses newline-separated blocks for optional fields, but it packs a large amount of critical safety and routing guidance into what is otherwise a single mega-paragraph. Although ordered logically, it lacks headers or bullet structure. For a high-stakes 28-parameter tool, the density is understandable, but readability suffers.

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 (28 params, destructive side effect, multiple gating conditions), the description covers prerequisites (routeToken, saleRep, analysisCategory), constraints (VAT, priceBasis), explicit confirmation flags, and how to handle missing references or products. It leaves little unsaid about the intended usage order and safety guardrails.

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

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

Schema description coverage is 57%, and the description meaningfully supplements the schema by explaining the relationship between note/customerName, the meaning of productId vs productCode, priceBasis semantics, and the purpose of routeToken and confirmWrite. It does not merely repeat the schema—it adds behavioral context. It doesn't fully document every parameter, but the combination of schema and description is strong.

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 this creates a BRC sales invoice and explains the manual-reference variant vs. the gen_ref sibling. It names the sibling `brc_create_sales_invoice_gen_ref`, which immediately helps an agent distinguish when to use which. The verb+resource is precise, and the reference-handling detail explicitly differentiates it from the closely-named alternative.

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

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

The description repeatedly covers when and how to use this tool: 'Requires a reference when the company is configured for manual sales references; otherwise prefer brc_create_sales_invoice_gen_ref.' It also provides exclusionary guidance on calculating priceBasis, on when to set routeToken, confirmWrite, and confirmCounterpartyExplicit, and instructs calling `brc_route_request` first and listing sales reps if missing. This is exactly the kind of decision support an agent needs.

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

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

The description discloses many behavioral constraints beyond the annotations, including preview-before-posting, blocking of placeholders and non-sales VAT, and the requirement for explicit counterparty 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 extremely long and repetitive, with identical sentences repeated multiple times (e.g., about preview behavior and required fields), making it inefficient and not 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?

Despite verbosity, the description thoroughly covers all operational details, including route tokens, confirmation flags, product validation, VAT restrictions, and preview behavior, making it contextually 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?

Top-level parameter descriptions plus an extensive payload description clarify required fields, nested structures, enum meanings, and confirmation flags, exceeding basic schema information.

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 creates a BRC sales invoice with an auto-generated reference using a raw BRC payload, distinguishing it from other invoice-creation tools like brc_create_sales_invoice.

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

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

Explicitly states when to use (company configured for auto-generated references) and provides step-by-step guidance such as calling brc_route_request first, listing products, and requiring confirmations, making usage conditions clear.

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

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

The description discloses important behavioral traits beyond annotations: the necessity of an authentic routeToken, the exact routing sequence, and that 'A routeToken is not permission to post — preview-before-posting and confirmWrite/confirmDelete still apply.' This meaningfully supplements the annotations (readOnlyHint=false, destructiveHint=false) and gives agents safety-critical context for correct invocation.

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

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

The description is focused and front-loaded: the first sentence states purpose, followed by the routing workflow and key guardrails. Every sentence adds meaningful operational detail—no filler or redundant repetition of schema properties. It is appropriately sized for 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 absence of an output schema, the description does not need to detail return values. It provides sufficient context for the create workflow, including prerequisites, token handling, and confirmation requirements. It omits mention of connectionRef, but that parameter is fully described in the schema, so the description is not incomplete from a selection and invocation standpoint.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by clarifying the routeToken parameter's lifecycle and semantics: it must come from brc_route_request, be retained through the workflow, and is not a posting permission. This goes beyond the schema's 'Opaque routeToken... required for transactional tools' explanation, warranting 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 clearly states the tool's purpose: 'Creates a BRC sales rep using structured MCP fields.' It uses a specific verb and resource, and the routeToken workflow context helps distinguish it as a transactional create action. However, it does not explicitly differentiate from sibling tools like brc_batch_sales_reps, which may also create sales reps, so it falls just short of 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 usage guidance: call brc_route_request first, retain the returned routeToken through lookup, preview, and confirmation, and pass the same token on the final permitted transactional call. It also warns against inventing placeholder tokens. It does not explicitly compare against alternatives or state when not to use this tool, but the workflow steps are actionable and clear.

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

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

Annotations (readOnlyHint=false) confirm a write operation, and the description enriches this with safety and workflow caveats: a routeToken is not permission to post, preview-before-posting and confirmWrite still apply, and the token requirement is disclosed. No contradiction with annotations.

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

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

The description is dense but each sentence carries meaning, covering the action, negative behavior, edge case, and multi-step workflow. Could be broken into shorter paragraphs for scannability, but nothing is wasted.

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

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

Given the tool's complexity — a mutating transactional call with token-based workflow and nested payload — the description covers the action, prerequisites, error-avoidance (no placeholder token), and post-auth guardrails (preview/confirm still apply). No output schema exists, so nothing is lost there.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds valuable runtime semantics for routeToken (the full action workflow) and confirmWrite (never true on first call), going beyond the schema's attribute-level documentation, though some of this duplicates what's already 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 leads with a specific verb+resource ('Creates a BRC supplier') and differentiates from siblings by noting it uses a 'raw BRC payload' and explicitly does not handle opening balances. This clearly positions it against the ~160 sibling tools.

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

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

Provides explicit workflow guidance: call brc_route_request first, retain the token through lookup/preview/confirmation, and never invent a placeholder. Also gives an exclusion ('Does not create or update opening balance transactions') and a conditional instruction (warn users about opening balances).

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

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

Annotations already mark destructiveHint=true, but the description adds critical safety behavior: requiring explicit user confirmation before confirmWrite=true, retaining the same routeToken through lookup/preview/confirmation, and clarifying that routeToken does not grant posting permission. This meaningfully exceeds the structured annotations.

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

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

The description is front-loaded with the primary action and each sentence carries necessary workflow or safety information. It is dense but not verbose, with 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?

For a destructive transactional tool with a multi-step workflow, the description covers prerequisites (route_request, get_accrual), user confirmation requirement, and routeToken handling. Since there is no output schema, not describing return values is acceptable.

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 how to obtain the timestamp via brc_get_accrual and emphasizing routeToken lifecycle (from brc_route_request, reused across steps). It does not add much for companyName or connectionRef, but key parameters are enriched.

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 states 'Removes an existing parent Accrual by id' – a specific verb, resource, and scope. It clearly distinguishes this from sibling create/update/get/list accrual tools.

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

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

The description gives explicit workflow guidance: call brc_route_request first, use brc_get_accrual to retrieve the current timestamp, and do not set confirmWrite=true until user confirmation. It does not explicitly discuss when not to use the tool or alternatives, 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?

The description fully discloses the destructive nature ('Reverses/deletes') consistent with annotations (destructiveHint=true), and adds critical behavioral context: the need for explicit user confirmation via confirmWrite, the routeToken requirement, and that routeToken alone is not sufficient for posting. It also explains connectionRef reuse, providing beyond-annotation transparency about session handling. No contradictions with annotations.

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

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

The description is long but every sentence is informative and earns its place. It leads with the core action, then covers prerequisites (list first), safety (confirmWrite), the routing workflow (routeToken), and connectionRef handling. There is no fluff; each sentence addresses a specific aspect of using the tool.

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

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

Given the tool's complexity (destructive, requires routing, confirmation, and a multi-step workflow), the description is exceptionally complete. It explains the full flow: use list to get id, route request, get token, pass same token, confirm, and connectionRef reuse. With no output schema, it doesn't need to explain return values. This covers all necessary context for correct use.

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

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

Schema coverage is 100%, so the schema already fully describes all five parameters. The description does not add meaning beyond the schema for parameters themselves (e.g., it doesn't explain id beyond what's in schema, though it mentions how to obtain it). The contribution is workflow context rather than parameter semantics, so baseline 3 is appropriate.

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

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

The description clearly states the action ('Reverses/deletes a single allocation'), specifies the resource ('by allocation resolver id'), and distinguishes from siblings by explicitly directing the user to 'Use brc_list_allocated_transactions first to find the allocation id' and mentioning routeToken workflow. This differentiates it from other delete tools and provides specific verb+resource clarity.

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 and how to use: 'Use brc_list_allocated_transactions first', 'Do not call with confirmWrite=true until the user explicitly confirms', 'Requires routeToken from brc_route_request', 'Call brc_route_request first', and 'Never invent a placeholder token.' It also clarifies that routeToken is not permission to post and preview/confirm still apply. These are clear usage guidelines with prerequisites and safety exclusions.

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

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

Annotations already mark destructiveHint=true and readOnlyHint=false, but the description adds critical behavioral details: it requires explicit user confirmation, mandates a routed workflow from brc_route_request, and explicitly warns that a routeToken is not permission to post and that preview-before-posting and confirmWrite/confirmDelete still apply. No contradiction with annotations.

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

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

The description is dense and front-loaded, with each sentence addressing a necessary aspect (action, confirmation, routing, token handling, preview). While slightly long, every clause serves a purpose and there is no fluff. It is comprehensive rather than concise, but appropriately so for a destructive transactional tool.

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

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

For a destructive transactional tool with no output schema, the description covers all critical aspects: target identification, required user confirmation, routing prerequisites, and the persistence of preview/confirmation gates. It fully equips an agent to invoke the tool correctly, given the complexity of the workflow.

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

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

Schema coverage is high (83%), so the schema documents most parameters. The description adds meaningful context by explaining the routeToken lifecycle (retain through lookup/preview/confirmation) and emphasizing that confirmWrite/confirmDelete still apply, which complements the schema definitions beyond simple field descriptions.

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

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

The description uses a specific verb ('Deletes'), names the resource ('BRC bank account'), and specifies the scope ('by id'). It clearly distinguishes this from sibling delete tools by stating the exact target resource and the requirement for a routeToken.

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 'Only call this after the user has explicitly confirmed deletion,' providing a clear gate. It also specifies the required sequence: call brc_route_request first, retain the routeToken, and pass it on the final permitted transactional call. This is direct, actionable guidance on when and how 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?

Annotations already declare destructiveHint=true, so the destructive nature is established. The description adds important behavioral context: the routeToken requirement, that it is not permission to post, and that preview-before-posting and confirmation still apply. This goes beyond the annotation and explains the preconditions and safety steps. No contradiction with annotations.

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

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

The description is concise (about 4 sentences) and front-loaded with the core purpose. Every sentence adds necessary workflow or safety context without redundancy. Well-structured and easy to parse.

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 (required routeToken workflow, confirmation gates, destructive action) and the absence of an output schema, the description fully covers the necessary context: prerequisites, exact sequence, and safety constraints. It is complete for an agent to execute correctly.

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

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

Schema description coverage is 83%, so parameters are largely documented. The description adds semantic value by explaining the routeToken's role (opaque, from brc_route_request, not a permission) and reinforces the confirmWrite/confirmDelete requirement. This enhances understanding beyond the schema. It does not explicitly describe id or companyName, but those are already 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 'Deletes a BRC cash payment by id' – a specific verb and resource. It distinguishes from sibling delete tools (e.g., delete_cash_receipt, delete_payment) by naming the exact entity type (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 workflow instructions: call brc_route_request first, retain the returned routeToken through lookup/preview/confirmation, pass the same token on the final transactional call. Also gives clear 'never invent a placeholder token' and clarifies that routeToken is not permission to post, with confirmWrite/confirmDelete still applying. This fully guides when and how 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?

Annotations already indicate destructiveHint=true and readOnlyHint=false, so the destructive nature is known. The description adds meaningful behavioral context beyond annotations: the required routing workflow (routeToken), the need for preview/confirmation, and the distinction that routeToken is only routing permission. No contradiction with annotations. This adds valuable context about the operational 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 moderately sized but every sentence contributes to understanding the workflow and safety requirements. It is front-loaded with the action ('Deletes a BRC cash receipt by id') and then succinctly explains the routing and confirmation prerequisites. No filler or 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 complexity of the routing workflow and the destructive nature, the description covers essential operational steps (route request, token retention, preview, confirm). It is complete enough for an agent to know the required sequence. There is no output schema, but for a delete operation, output is likely minimal and not critical. The description adequately addresses 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 description coverage is 83%, so the schema already documents most parameters. The description adds emphasis on routeToken and confirmWrite, but this repeats what is already in the schema (e.g., 'Opaque routeToken from brc_route_request...' and confirmWrite's boolean semantics). No new parameter meaning is introduced, so it stays at the baseline of 3 for high coverage.

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

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

The description clearly states 'Deletes a BRC cash receipt by id,' which is a specific verb and resource. It distinguishes this from other delete tools by naming the exact entity (BRC cash receipt), though it does not explicitly contrast with sibling delete tools, the purpose is unambiguous.

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

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

The description provides explicit usage guidance: it instructs to call brc_route_request first, retain the returned routeToken, and never invent a placeholder. It also clarifies that routeToken is not permission and that preview-before-posting and confirmation still apply. However, it does not explicitly state when NOT to use this tool or compare it with alternatives like other deletes, so it lacks a direct alternative comparison.

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