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

With no annotations, the description discloses the two-phase commit process, the need for explicit counterparty confirmation, and the 5-item limit. It does not explicitly state that the tool performs writes or mention error handling, but the workflow is well explained.

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

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

The description is concise with five sentences, each adding value. It is front-loaded with the main action. Could be improved with bullet points or clearer separation of steps, but effective as is.

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

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

Covers essential aspects: batch limits, preview confirmation, counterparty confirmation. Lacks details on error handling or partial success, but for a batch tool with no output schema, it provides sufficient context 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 coverage is 100%, but the description adds critical context for confirmWrite, confirmCounterpartyExplicit, and priceBasis beyond the schema descriptions. The items parameter is merely restated, but overall the description enhances understanding.

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

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

The description clearly states it processes a batch of BRC cash payments with a maximum of 5 items, distinguishing it from single-item create tools and other batch tools for different entities.

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

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

Provides explicit step-by-step workflow: first call without confirmWrite returns a preview, then retry with confirmWrite: true only after user confirmation. Also mandates confirmCounterpartyExplicit after explicit naming, and warns against preflight or reused drafts.

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

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

No annotations provided, so description carries full burden. It discloses the two-call confirmation flow, maximum 5 items, and the requirement for explicit counterparty confirmation. It also warns against reusing counterparties from earlier drafts. This is thorough for a write operation, though it does not mention idempotency or error 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 a single paragraph that packs essential information without redundancy. It front-loads the purpose and limit. While it could be broken into bullet points for easier scanning, it remains concise and every sentence adds value.

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

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

Given no output schema and the tool's complexity (multi-step confirmation), the description adequately covers the interaction flow, preflight request, and confirmation flags. It does not describe return values or error scenarios, but for a batch tool with good annotations this 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. Description adds significant value by explaining the two-call pattern for confirmWrite, the condition for confirmCounterpartyExplicit, and the net vs gross distinction for priceBasis. It also clarifies the items parameter as 'batch items to process'. This goes beyond 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 explicitly states 'Processes a batch of BRC cash receipts' with a clear verb and resource. It distinguishes itself from sibling tools like 'brc_create_cash_receipt' by being a batch operation, and from other batch tools by specifying 'cash receipts'.

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

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

Provides a detailed step-by-step usage flow: first call without confirmWrite, show preview, get user confirmation, then retry with confirmWrite. Also specifies when to set confirmCounterpartyExplicit. However, it does not explicitly mention that for a single receipt the user should use brc_create_cash_receipt instead, which would improve 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?

Describes the confirmation flow and batch limit but does not specify whether 'processes' means create, update, or both. No annotations provided, so description carries full burden; missing side-effect clarity.

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

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

Four sentences, front-loaded with purpose and limit, then concise workflow instructions. Every sentence adds essential information 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?

Covers confirmation workflow well but lacks description of output (e.g., preview format, response structure) and doesn't clarify mutation type (create vs update). Given complexity of batch tools, more detail needed.

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

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

Schema coverage is 100% with parameter descriptions. Description adds value by explaining the confirmWrite two-step flow beyond schema, though other parameters are not further elaborated.

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

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

Description clearly states verb 'Processes a batch of customers', distinguishing from sibling batch tools for other entities. Explicitly mentions batch size limit (5 items), making purpose precise.

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 for the two-step confirmation workflow: first call without confirmWrite returns preview, user must confirm explicitly. Warns that passing preflight is not confirmation, preventing misuse.

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

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

No annotations are provided, so the description fully discloses behavioral traits. It reveals the two-phase commit: first call returns a preview without writing, then requires explicit user confirmation. It also details the counterparty confirmation requirement and batch size limit. This is thorough for a mutation tool.

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

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

The description is well-structured and front-loaded with the main purpose. It is moderately long but every sentence adds value. Minor redundancy with schema descriptions could be trimmed, but overall it is clear and efficient.

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

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

Given the lack of an output schema, the description mentions that the first call returns confirmation_required and a payload preview, instructing to show a plain-English draft. It covers the essential workflow and constraints. It could be more explicit about error scenarios or the structure of the preview, but it is sufficient for correct agent usage.

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

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

The input schema has 100% description coverage for all 6 parameters. The description largely restates or summarizes the schema descriptions (e.g., confirmWrite rules). It does not add significant new meaning beyond what the schema already provides. 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 begins by clearly stating the tool processes a batch of BRC payments. This distinguishes it from sibling batch tools like brc_batch_purchases or brc_batch_cash_receipts that handle different entities. The verb 'process' combined with 'BRC payments' is specific and unambiguous.

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

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

The description provides explicit step-by-step instructions: first call without confirmWrite yields a preview, then retry with confirmWrite only after explicit user confirmation. It also mandates confirmCounterpartyExplicit when the counterparty is explicitly named. It warns against misusing confirmWrite (e.g., never on first call) and against reusing counterparty from earlier drafts. This is comprehensive guidance for correct usage.

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

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

No annotations provided, but the description discloses the two-step confirmation workflow, including the return of a 'confirmation_required' response and a payload preview. It also clarifies that passing preflight is not confirmation. However, it does not detail error conditions or side effects beyond the confirmation flow.

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

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

The description is concise (three sentences) and front-loaded with the core purpose. Every sentence provides essential information 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 description covers the confirmation workflow and key parameters. However, it lacks details about the output of the second call (e.g., success response or errors). Given no output schema, this would be helpful for the agent to understand the result.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds significant context beyond the schema: it explains the confirmWrite parameter's required usage pattern, the confirmCrAnalysisCategory parameter's purpose for CR analysis account confirmation, and the priceBasis parameter's condition and meaning (net vs gross).

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

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

The description clearly states 'Processes a batch of products' and specifies the maximum batch size (5 items). It distinguishes itself from sibling tools like brc_create_product by handling batches and requiring a confirmation step.

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

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

Explicitly instructs the agent to first call without confirmWrite to get a preview, then retry with confirmWrite: true only after explicit user confirmation. Warns against setting confirmWrite on the first call or assuming preflight is 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?

Since no annotations are provided, the description fully discloses the two-phase confirmation behavior, the need for explicit user confirmation for writing and counterparty, and warns against reusing counterparties from earlier drafts. This goes beyond schema details.

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

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

The description is concise yet comprehensive, with every sentence providing essential information. It is front-loaded with the main action and efficiently covers all critical behavioral aspects 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?

Given the tool's complexity (6 parameters, 2 required, no output schema), the description thoroughly explains the entire workflow, including batch limits, confirmation flags, counterparty requirements, and the draft preview step, making it complete for 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?

The schema has 100% description coverage for all 6 parameters, but the description adds workflow context for confirmWrite and confirmCounterpartyExplicit, explaining the two-step process and the requirement for explicit user confirmation, enhancing understanding beyond the schema.

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

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

The description clearly states 'Processes a batch of purchases' with a specific verb and resource, and distinguishes it from sibling batch tools like brc_batch_sales_invoices by mentioning purchases and the two-step confirmation workflow.

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

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

Explicitly instructs the agent to first call without confirmWrite: true to get a preview, then retry with confirmWrite: true only after user confirmation. Also requires confirmCounterpartyExplicit: true once the user explicitly names the counterparty, providing clear when-to-use and when-not-to-use guidance.

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

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

No annotations provided, so description carries full burden. It details the confirmation workflow, maximum batch size (5), preflight behavior, and explicit user confirmation requirements for both write and counterparty. Does not cover error handling or idempotency, but covers key behavioral expectations.

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

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

Single dense paragraph front-loads purpose, then concisely lists constraints with no redundant sentences. All information is directly useful for an agent deciding to invoke 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 complexity (6 params, 2 required, workflow) and no output schema, the description covers the main flow and constraints. Mentions return value (confirmation_required + preview) but doesn't detail response format or error cases. Still comprehensive enough for most agent decisions.

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%, baseline 3. Description adds significant value: explains the workflow for confirmWrite (two-step), confirmCounterpartyExplicit (requires explicit user naming in current conversation), and priceBasis (context for gross/net). Goes well beyond schema descriptions, especially for confirmWrite and confirmCounterpartyExplicit.

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

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

The description clearly states 'Processes a batch of quotes,' specifying the action (processes), resource (quotes), and batch context. It distinguishes from sibling tools like brc_create_quote (single quote) and other batch tools (e.g., brc_batch_sales_invoices) by focusing on quotes.

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 the two-step flow: first call without confirmWrite returns a preview, then retry with confirmWrite after user confirmation. Provides when-not-to-use for confirmWrite and confirmCounterpartyExplicit. No direct comparison to alternatives like brc_create_quote for single quotes, but the batch focus 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?

With no annotations, description fully discloses behavior: runtime blocking of placeholder productIds, preflight return of confirmation_required and payload preview, requirement for explicit user confirmation, and constraints on counterparty reuse. Very transparent.

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

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

Single paragraph is effective and front-loaded, but could be slightly improved with bullet points or section breaks for easier scanning. No redundant sentences, 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?

Despite no output schema and nested items, description covers all necessary context: workflow, validation rules, parameter usage, and expected responses. Leaves no obvious gaps for typical usage scenarios.

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

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

Schema coverage is 100%, but description adds significant meaning: explains when and how to set confirmWrite and confirmCounterpartyExplicit, details priceBasis usage for gross/net, and clarifies the confirmCrAnalysisCategory parameter context. Adds value beyond schema.

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

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

The description clearly states the tool processes a batch of sales credit notes, with specific verb and resource. It distinguishes from siblings by detailing unique validation rules and confirmation workflow, not seen in other tool descriptions.

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 brc_list_products to get real productIds, do not invent or use placeholder IDs, maximum 5 items, two-stage confirmWrite process with preflight, and counterparty confirmation requirements. Clearly differentiates from 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?

With no annotations, the description carries the full burden. It discloses the two-step confirmation process, the need for explicit counterparty confirmation, and the maximum batch size. However, it does not detail the exact system behavior (e.g., what validation occurs, error handling, or side effects of the write operation).

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

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

The description is three dense sentences that front-load the purpose and constraints. Every sentence provides essential guidance without extraneous information, achieving high efficiency.

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

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

The description covers the core workflow (confirmation flow, counterparty check, max items) well. It lacks details on error handling or the structure of the 'payload preview' and no output schema is provided, but the main usage scenarios are adequately addressed.

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

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

Schema coverage is 100%, but the description adds significant behavioral context: it explains the two-step usage of confirmWrite, the condition for confirmCounterpartyExplicit, and the meaning of priceBasis. This goes beyond the schema's descriptions.

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

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

The description clearly states 'Processes a batch of sales entries' and specifies a maximum of 5 items per batch. This distinguishes it from sibling tools like brc_batch_sales_invoices or brc_create_sales_entry, which handle different record types or single entries.

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 instructions: first call without confirmWrite returns a preview, then retry with confirmWrite after user confirmation. It also mandates confirmCounterpartyExplicit when the user names the counterparty. However, it does not explicitly contrast with alternatives like single-entry creation.

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

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

No annotations are provided, so the description carries the full burden. It thoroughly discloses behaviors: safety checks, placeholder blocking, VAT validation, priceBasis handling, CR analysis category confirmation, counterparty confirmation, note defaults, deliveryTo optionality, max items, and preflight not being confirmation.

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

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

The description is lengthy but well-structured, front-loaded with the purpose, and each sentence adds value. It could be more concise by grouping related rules, but given the complexity, it is appropriately detailed without 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?

The description covers most behaviors for a batch tool with complex rules, including the confirmation flow and blocking behaviors. It lacks explicit mention of the output after success, but that is partially inferred. With no output schema, it is fairly complete.

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

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

Schema coverage is 100%, yet the description adds significant meaning beyond the schema. It explains item-level fields (note, deliveryTo), the interplay between confirmWrite, confirmCrAnalysisCategory, and confirmCounterpartyExplicit, and provides context for priceBasis and companyName.

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

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

The description clearly states 'Processes a batch of sales invoices', which is a specific verb+resource. It distinguishes from siblings like 'brc_create_sales_invoice' (single) and 'brc_batch_sales_credit_notes' by mentioning batch-specific behaviors such as multiple customer confirmation and max items.

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 guidelines, including the confirmation flow (first call without confirmWrite, then with after user confirmation), maximum 5 items, and prerequisites like calling brc_list_products. It does not explicitly compare with other batch tools but clearly implies when to use this batch version.

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

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

No annotations provided, so description carries full burden. It discloses the two-step confirmation, max items, and that preflight is not confirmation. However, it omits details on final output after confirmWrite, error handling, idempotency, and side effects.

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

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

Two sentences cover purpose and workflow efficiently. Information is front-loaded: first sentence states purpose, second details the confirmation process. Could be improved with bullet points for clarity, 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?

Covers the core batch processing and confirmation flow. However, lacks information about return values (no output schema), error scenarios, or what happens after successful confirmWrite. More details on the final result would improve completeness.

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

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

Schema coverage is 100% so baseline is 3. The description adds value by explaining the confirmWrite workflow and preflight step, and clarifying that priceBasis applies to all items. This goes beyond the schema's individual parameter descriptions.

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

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

The description clearly states the tool processes a batch of sales reps, with a specific verb and resource. It distinguishes from sibling batch tools (e.g., customers, products) by naming 'sales reps' directly. The two-step confirmation workflow is also explained.

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 the confirmation workflow: first call without confirmWrite returns preview, second with confirmWrite only after user confirmation. It mentions max batch size and that preflight is not confirmation. However, it does not explicitly exclude scenarios or compare to 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?

Without annotations, the description fully discloses the preflight/confirmation behavior, maximum items, and the requirement for explicit user confirmation. However, it does not describe error handling, side effects, or the nature of the return value beyond mentioning confirmation_required and preview.

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

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

Four sentences, front-loaded with purpose, no redundancy. Every sentence adds essential guidance (limit, confirmation workflow, non-confirmation clarification).

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

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

Given the complexity of batch processing with a preflight confirmation workflow and no output schema, the description adequately conveys the core behavior. It covers the confirmation protocol and parameter semantics. Slightly lacking on what the tool returns after successful write, but schema description fills some gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value by explaining the workflow around confirmWrite (two-step process) and confirmCrAnalysisCategory (intentional CR account). It also clarifies priceBasis for VAT-inclusive/exclusive. This goes beyond 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?

Clearly states the tool processes a batch of suppliers with a specific constraint (max 5 items). Distinguishes from sibling batch tools and single supplier creation tools through naming and context.

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 the two-step confirmation process: first call without confirmWrite, show plain-English draft, then retry with confirmWrite after explicit user confirmation. Provides critical guidance on what constitutes confirmation ('passing preflight is not confirmation'). Does not explicitly state when to use alternative tools like brc_create_supplier for single suppliers.

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

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

No annotations are provided, so the description must carry the behavioral burden. It states the tool returns warnings but does not specify the nature of warnings, side effects (none expected), or any other behavioral traits like rate limits or authentication needs. Acceptable but lacks depth.

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

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

The description is two concise sentences, front-loads the purpose, and contains no redundant information. Every sentence contributes value.

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

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

For a simple 2-param tool with no output schema, the description covers the main purpose but omits the return format of the warnings. It could be more complete by specifying the structure or content of the warnings.

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 adds only an example for companyName ('YOUR-COMPANY-NAME'), which adds marginal value beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool checks BRC company processing settings before VAT-sensitive or payment-terms-sensitive workflows, and returns warnings for pre-validation. It differentiates from sibling tools by specifying the context (VAT/payment-terms sensitive), though not perfectly distinct from other check 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 implies usage before creating or changing records in specific workflows, but does not explicitly state when not to use it or provide guidance on alternatives like brc_company_readiness_check. No explicit exclusions or comparisons.

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

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

No annotations provided; description only states action and scope. Does not disclose side effects, reversibility, authorization requirements, or what 'MCP server memory' means. Lacks behavioral depth.

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

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

Single, clear sentence with no unnecessary words. Front-loads key action and scope.

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?

Sufficient for a parameterless tool; describes what is cleared and scope. No output schema, so return values not required. Could mention confirmation or reversibility, but overall 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?

No parameters in schema (100% coverage). Baseline score of 4 for 0 parameters; description adds no param info since none exist.

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 verb 'clears', resource 'connection credentials for all company contexts', and location 'MCP server memory'. Differentiates from sibling brc_clear_company_api_key by specifying 'all company contexts'.

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?

Does not explicitly provide when to use or alternatives. The distinction from the singular clear tool is implied by name, but no explicit guidance on when to choose this over brc_clear_company_api_key.

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

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

Despite no annotations, the description fully discloses the destructive nature, the two-phase process (preview then confirm), and the necessity of user confirmation. Adds critical behavioral 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 clear and informative, though slightly verbose for a two-parameter tool. The step-by-step structure justifies the length for a destructive operation.

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

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

Given no output schema and two optional parameters, the description covers all necessary context: the preflight/preview behavior, the need for confirmation, and parameter usage. No gaps.

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

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

Schema coverage is 100% with descriptions, but the tool description adds significant semantics: explains the role of confirmWrite in the two-step confirmation flow and that confirmWrite must only be true after explicit user confirmation.

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 'Clear the Red audit log for this MCP server session,' specifying the action, resource, and scope. It distinguishes from sibling tools like brc_list_audit_log.

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

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

Provides explicit step-by-step instructions: first call without confirmWrite to get preview, then retry after user confirmation. Explains that passing preflight is not confirmation and sets clear conditions for setting confirmWrite true.

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

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

No annotations are provided, so the description carries full burden. It states 'clears ... from MCP server memory' indicating a destructive action. However, it does not disclose side effects, authorization needs, reversibility, or impact on ongoing operations.

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

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

The description is a single sentence of 12 words, front-loaded with the action verb. Every word is necessary, and it avoids any redundant or extraneous information.

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

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

For a simple one-parameter tool with no output schema, the description covers the essential purpose and context. It could hint at the return value (e.g., success/failure) or mention that it affects the current MCP session, but overall it is satisfactory.

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

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

Schema coverage is 100%, with the parameter already described in the schema. The tool description does not add additional meaning or usage guidance beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description uses the specific verb 'clears' and identifies the resource as 'API key for a named company context'. It clearly distinguishes from sibling tools like brc_clear_all_company_api_keys and brc_get_company_api_key_status.

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

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

The description implies usage for clearing a specific company's API key but does not explicitly state when to use this tool versus alternatives like brc_clear_all_company_api_keys. No exclusions or prerequisites are provided.

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?

Without annotations, the description fully explains the two-step behavior and the requirement for explicit user confirmation, adding significant value beyond a simple 'close' verb.

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 with three sentences, front-loading the purpose, and every sentence earns its place by explaining the critical usage pattern.

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

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

Given no output schema, the description adequately explains the confirmation process and return of a preview. It could be improved by stating the final response for the second call, but it is largely sufficient.

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

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

Schema coverage is 100%, but the description adds crucial semantics for the confirmWrite parameter, detailing the required flow. This goes beyond the schema's basic description.

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

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

The description clearly states 'Closes a BRC quote' with a specific verb and resource. It distinguishes itself from sibling tools like brc_reopen_quote by focusing on the close action.

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

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

The description provides explicit instructions on the two-step confirmation process, including when to set confirmWrite: true and that preflight is not confirmation. It does not mention 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?

With no annotations provided, the description carries full burden for behavioral disclosure. It does not explicitly state that the tool is non-destructive, requires specific authentication, or has side effects. The description only hints at checking readiness but lacks explicit safety or behavioral details.

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

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

The description is two sentences long, front-loaded with the primary purpose, and contains no redundant information. Every word serves a purpose.

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

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

For a simple tool with one parameter and no output schema, the description covers the essential function and considerations. However, it would benefit from mentioning the format of the output (e.g., a readiness status or list of issues) to be fully complete.

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

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

Schema coverage is 100% for the single parameter, and the schema description already provides clear guidance. The tool description does not add extra meaning beyond what the schema offers, so it meets the baseline of 3.

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

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

The description clearly states what the tool does: checks readiness for read-only and transaction workflows, and highlights specific considerations. It is distinct from sibling tools that perform batch operations, create/update, or other checks.

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

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

The description implies the tool should be used before performing read-only and transaction workflows, but does not explicitly state when to use it over alternatives like brc_check_transaction_settings or other readiness tools. No exclusions or conditions are provided.

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

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

With no annotations provided, the description carries full burden. It adds the behavioral note 'Never exposes connection credentials', which is helpful but does not detail other behaviors (e.g., side effects, idempotency, permissions). The description is somewhat transparent but lacks depth.

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

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

The description is three sentences, front-loaded with purpose, and every sentence adds value. No redundancy or 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 simple tool with one parameter and no output schema, the description is complete. It explains the prerequisite (user submitted connection page), the trigger (confirmation code), and a safety note. No missing essential 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?

Schema description coverage is 100% and the parameter's own description already explains the code. The tool description adds context about when the code is obtained (from success page) but does not add new parameter meaning beyond the schema. Baseline 3.

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

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

The description clearly states the tool claims a completed secure Red connection code for the current MCP session, specifying the verb 'Claims' and the resource (secure connection code). This distinguishes it from siblings like brc_start_company_connection, which likely initiates the process.

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

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

The description provides clear usage context: 'Use after the user has submitted the secure connection page and returns to this chat with the confirmation code shown on the success page'. It gives an example (MCP session changed after opening browser) but does not explicitly state when not to use or mention 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?

No annotations are provided, so the description carries the burden. It discloses that the API accepts only the parent transaction and relies on shared logic for the reversing child, which is key behavioral insight. It also mentions the confirmation flow.

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

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

Two sentences: first defines purpose, second provides crucial usage guideline. No wasted words; each sentence adds value.

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

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

Given no output schema and no annotations, the description covers creation behavior and the critical confirmation step. It could mention return value, but it's not essential. The context of many sibling create tools makes the purpose clear.

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 baseline is 3. The description adds meaning for confirmWrite (user confirmation requirement) but does not elaborate on other parameters beyond schema defaults.

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

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

The description clearly states 'Creates a new parent Accrual' and explains the API's behavior of generating a reversing child transaction. This is specific and distinguishes from siblings like brc_update_accrual or brc_list_accruals.

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 warns not to call with confirmWrite=true until user confirmation, providing clear usage guidance. However, it does not compare to other tools for when to use this one vs. alternatives like brc_update_accrual.

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

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

No annotations provided, so description carries full burden. It discloses automatic category creation when categoryId omitted, and requirement for nominalAcCode to exist. Does not cover authentication or response.

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

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

Single paragraph of 4 sentences, concise and to the point. Could be slightly more structured (e.g., bullet points for required fields).

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 18 parameters and no output schema, description covers core workflow and key constraints but lacks details on many parameters and return behavior. Sufficient for basic use but not fully comprehensive.

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

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

Schema coverage 50%. Description highlights required fields (acCode, details, lastChq, nominalAcCode) and explains categoryId optionality, but many parameters (address, balance, sortCode, etc.) remain unexplained.

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

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

The description clearly states 'Creates a BRC bank account', which is a specific verb+resource. Sibling tools are distinct create operations for other entities, so no confusion.

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

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

Explicitly warns against calling with confirmCreate=true before user confirmation, and lists required fields. However, no mention of when not to use or 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?

With no annotations provided, the description carries the full burden. It explains the two-phase confirmation flow, constraints on analysis categories, and counterparty confirmation needs. However, it does not describe the final success response or potential errors, which is a gap for a creation tool.

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

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

The description is relatively long but every sentence serves a purpose. It is front-loaded with the core purpose and usage patterns. Minor redundancy (e.g., 'Passing preflight is not confirmation' could be integrated) but overall well-structured.

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

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

Given the tool's complexity (18 parameters, three payment types, two-step confirmation), the description covers the essential workflow and constraints well. It lacks output schema details but mentions the preview response. Overall fairly complete for the complexity.

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

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

The description adds significant meaning beyond the input schema by explaining which parameter combinations to use for each payment type, the requirement that analysis categories be from CP01-CP03, and the semantics of confirmWrite and confirmCounterpartyExplicit. This is valuable given the tool's complexity.

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

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

The description clearly states it creates a BRC cash payment and distinguishes among three usage patterns (supplier payment, bank lodgement, analysed expenses). This differentiates it from sibling create tools like brc_create_cash_receipt and brc_create_sales_invoice.

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

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

The description provides explicit guidance on when to use each parameter combination (supplierId+ledger, bankAccountId+lodgement, analysisCategoryId+accountCode). It also details the two-step confirmation workflow and counterparty confirmation requirement, giving clear direction on how to invoke the tool correctly and safely.

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

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

With no annotations, the description fully describes behavioral traits: two-step confirmation process, defaults for entryDate/procDate, conditional VAT fields, counterparty confirmation. No contradictions.

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

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

Reasonably concise and front-loaded with main action. Contains useful details without excessive verbosity. Could be slightly tighter but well-organized.

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

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

Given 30 parameters and no output schema, description covers workflow and important constraints. Missing return value details beyond preflight. Fairly complete for usage 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?

Schema coverage is only 10%, so description should compensate. It explains confirmWrite, confirmCounterpartyExplicit, entryDate/procDate defaults, and VAT condition. However, many parameters (note, total, acCode, etc.) lack semantic description, leaving gaps.

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

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

The description clearly states it 'Creates a BRC cash receipt' with a specific verb and resource. It distinguishes from sibling create tools by specifying cash receipt, but does not explicitly compare to siblings like brc_create_cash_payment.

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

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

Provides detailed workflow: first call without confirmWrite for preview, then explicit user confirmation. Requires confirmCounterpartyExplicit for explicit counterparty confirmation. Notes conditional VAT fields based on company setting. Gives clear when-to-use instructions.

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

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

With no annotations, the description fully discloses key behaviors: no opening balance handling, preflight returns confirmation_required, email mismatch warning, and confirmation workflow. No contradictions. Missing auth or rate limit info, but these are not critical for basic usage.

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

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

Extremely concise at ~100 words, no filler. Front-loaded with purpose. Every sentence provides essential information. Excellent 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?

Covers workflow, constraints (no opening balance), and preflight behavior. No output schema, but description mentions what first call returns. Could elaborate on payload structure, but schema covers that. Adequate for a create tool with moderate 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 critical usage semantics for confirmWrite (workflow and when to set true) and clarifies payload as 'raw BRC payload'. This adds value beyond the schema.

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

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

The description clearly states the verb ('Creates') and resource ('BRC customer'). It distinguishes itself from sibling tools by explicitly noting what it does NOT do (opening balance transactions), which helps differentiate from other create tools.

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

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

Provides clear when-to-use guidance, including a detailed confirmation workflow (preflight, confirmWrite) and email mismatch check. Could be stronger on when to use alternatives, but the explicit workflow instructions serve as good 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?

No annotations are provided, so the description carries full burden. It discloses the creation action and the need for user confirmation, but does not specify permissions, side effects, or success response. The warning about confirmWrite is good, but more behavioral context (e.g., whether it automatically validates balance, if it can be undone) would improve transparency.

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

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

The description is extremely concise with two sentences. The first sentence states the primary purpose, and the second adds critical usage guidance. No wasted words, and the structure is optimal for quick comprehension.

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

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

Given no output schema, the description should hint at return values or status. It does not explain what the response contains (e.g., batch ID). While the schema documents the parameters, the description lacks completeness regarding the result of the operation. The balance and confirmation advice are helpful, but overall it could be more comprehensive for a complex creation tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema by stating that debit and credit lines must balance and that confirmWrite should only be true after user confirmation. This extra context for the parameters (especially confirmWrite and accountTransactions) elevates the score.

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

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

The description clearly states 'Creates a new Nominal Journal Batch' with a specific verb and resource, distinguishing it from siblings like update, delete, or list. It also adds essential constraints about balanced lines and confirmation flow.

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

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

The description provides explicit usage guidance: not to set confirmWrite=true until user confirms, and that journal lines must balance. It implies a two-step creation process. However, it does not compare this tool to potential alternatives for obtaining the same result, though the sibling set makes the purpose clear.

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

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

No annotations provided, so description carries full burden. It discloses the two-step creation process, that passing preflight is not confirmation, and the need for explicit counterparty confirmation. This makes the behavioral expectations clear.

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

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

Single paragraph, front-loaded with purpose, then explains two paths and confirmation process. Every sentence is necessary and informative without being verbose.

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

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

For 17 parameters and no output schema, description covers usage well but lacks details about return values (e.g., what the payload preview contains, what a successful response includes). Slightly incomplete 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?

Adds meaning beyond schema: explains the relationship between supplierId and analysisCategoryId+accountCode, details confirmation parameters, and notes that analysis categories must be from BP01-BP06. Schema coverage is 65%, but description compensates well.

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

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

The description clearly states it creates a BRC payment from the Payments book, specifying the resource and action. It distinguishes between supplier payments and analysed bank payments, differentiating from sibling tools like brc_create_cash_payment and brc_create_prepayment.

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 guidelines are given: use supplierId for supplier payments or analysisCategoryId + accountCode for analysed bank payments. The two-step confirmation process is detailed, including not setting confirmWrite on the first call and requiring explicit user confirmation. Also explains confirmCounterpartyExplicit requirement.

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

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

With no annotations, the description carries full burden. It discloses that the tool creates a parent Prepayment and relies on shared logic to generate a reversing child transaction. It also warns about the confirmWrite flag, giving important behavioral context beyond simple creation.

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 with no wasted words. The information is front-loaded and to the point.

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 creating a parent with an auto-generated child, the description and schema provide enough context for correct usage. No output schema exists, but description doesn't need to explain return values. The confirmWrite guidance fills a key gap.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds semantic value for confirmWrite by explaining when to set it true, but for other parameters it adds no additional meaning beyond 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 clearly states it creates a parent Prepayment, specifying the verb and resource. It distinguishes from sibling tools like brc_delete_prepayment, brc_get_prepayment, and other create tools by focusing on the prepayment entity and its parent-child aspect.

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

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

The description provides a critical usage guideline: 'Do not call with confirmWrite=true until the user has reviewed the draft and explicitly confirmed creation.' It does not explicitly compare to alternatives, but the resource name differentiates from other create tools.

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

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

With no annotations, the description must disclose behavioral traits. It effectively reveals the two-step confirmation mechanism and that the first call is non-destructive but returns a preview. It does not mention idempotency, destructive potential beyond the preflight, or error conditions, but the preflight disclosure is strong.

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

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

The description is extremely concise: two sentences plus a short warning. Every sentence adds essential information. The purpose is stated first, followed by the critical usage process. 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 the complexity of the preflight workflow and no output schema, the description adequately covers the behavior: first call returns confirmation and preview, second call creates. It lacks detail on success response or error states, but for a create tool with clear preflight steps, it is fairly complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value for the confirmWrite parameter by reinforcing its usage in the preflight flow, but does not add semantic detail beyond the schema for payload or companyName. The guidance on confirmWrite is helpful but does not significantly raise the score.

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

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

The description clearly states it creates a BRC product using a raw BRC payload. The verb 'creates' and resource 'BRC product' are specific. However, it does not explicitly differentiate from sibling tools like brc_update_product or other create tools, relying on the name for distinction.

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

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

Provides explicit step-by-step guidance: first call without confirmWrite returns preview, then show draft to user, then retry with confirmWrite only after explicit confirmation. Also warns that passing preflight is not confirmation. This leaves no ambiguity about 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?

No annotations are provided, so the description carries the full burden. It explains the two-phase commit behavior (preview then confirmation), clarifies that passing preflight is not confirmation, and requires explicit counterparty confirmation. It does not explicitly state the side effects (e.g., database creation), but the workflow details are sufficiently transparent. Could be slightly more explicit about success outputs.

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 appropriately sized for a complex tool with multi-step workflow. It front-loads the main purpose and key conditions, then structures the workflow. Every sentence serves a purpose, though it could be slightly more concise by combining some conditional statements.

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

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

Given 16 parameters (13 required) and no output schema, the description covers the essential workflow, confirmation steps, and counterparty confirmation. It does not explain return values or error handling, but for a creation tool with two-phase commit, the guidance is sufficiently complete to use the tool correctly.

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

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

Schema covers 100% of parameters with descriptions, but the description adds significant context for confirmWrite and confirmCounterpartyExplicit, explaining their workflow semantics. It also clarifies when reference is required. For other parameters like netAmount, schema descriptions suffice, but the tool's description adds value for the nuanced boolean params.

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

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

The description starts with 'Creates a BRC purchase using structured MCP fields', clearly stating the verb and resource. It also distinguishes from sibling tool brc_create_purchase_gen_ref by specifying when each should be used (manual reference vs auto-generated), ensuring 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?

Explicitly states when to use this tool (company configured for manual reference) and when to prefer brc_create_purchase_gen_ref. Provides a detailed multi-step workflow: first call without confirmWrite, then retry with confirmWrite only after explicit user confirmation. Also requires confirmCounterpartyExplicit after the user explicitly names or confirms the counterparty. This is clear and actionable guidance.

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

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

With no annotations, description carries full burden. Explains two-step confirmation process, preflight behavior, and counterparty confirmation requirement. Lacks error handling details but provides substantial behavioral context for a mutation tool.

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

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

Description is front-loaded with purpose and usage. Well-structured with clear sentences. Slightly verbose but every part contributes to understanding the tool's behavior and requirements.

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

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

Explains core workflow and confirmation requirements, but lacks return value details (e.g., structure of payload preview, error responses). No output schema, so description should cover this. Incomplete for a complex tool with 15 parameters.

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

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

Schema description coverage is only 20% (2 out of 15 parameters have descriptions in schema). Description adds meaning for confirmWrite and confirmCounterpartyExplicit by explaining when to set them, but provides no additional info for the other 12 parameters, partially compensating for low 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?

Description clearly states 'Creates a Purchases Book purchase with a generated reference using structured fields.' This specifies the verb (creates), resource (Purchases Book purchase), and differentiator (generated reference), distinguishing it from siblings like brc_create_purchase.

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

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

Explicitly states 'Use when the company is configured for auto-generated purchase references.' Provides detailed workflow: first call without confirmWrite, show draft, retry with confirmWrite only after explicit user confirmation. Also specifies confirmCounterpartyExplicit requirement, clearly differentiating from other tools.

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

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

No annotations are provided, but the description fully discloses behavioral traits: requires saleRepId and saleRepCode, requires analysisCategoryId and accountCode, warns against defaulting to CR01/Customer, describes the confirmation_required preview, and mandates explicit user 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 lengthy but densely packed with essential instructions. Every sentence adds value, though it could be slightly more structured (e.g., bullet points) for easier scanning. 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 28 parameters, no output schema, and no nested objects, the description is fairly complete. It covers the confirmation flow, prerequisites, and constraints. Missing explicit mention of success response structure, but the agent can infer from the confirmation flow.

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 (36%), so the description carries the burden. It clearly adds meaning for critical parameters like confirmWrite, confirmCounterpartyExplicit, confirmCrAnalysisCategory, and the reference parameter. However, not all 28 parameters are explicitly described in the main description, but key ones are covered.

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

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

The description clearly states it creates a BRC quote using structured MCP fields. It distinguishes from sibling tools like brc_create_quote_gen_ref by detailing quote reference requirements. However, it could explicitly name the sibling for contrast.

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

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

The description provides extensive usage guidance: when to require a quote reference, not to use with unknown settings unless reference provided, do not use default sales rep values, requires explicit user confirmations for write, counterparty, and analysis category. It even specifies the two-step confirmation workflow.

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

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

With no annotations provided, the description takes full responsibility for disclosing behavioral traits. It covers crucial behaviors: draft previews include warnings for missing fields without inventing values, confirmation flags must be set only after explicit user confirmation, the first call returns a payload preview rather than executing, and preflight is not confirmation. This level of detail ensures the agent understands the tool's behavior thoroughly.

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 efficient, with every sentence providing necessary guidance. It is front-loaded with the purpose and then systematically covers usage conditions, requirements, and the multi-step process. No superfluous content is present, though the length is justified by 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 explains the tool's behavior and usage constraints, but it lacks information about the return value on successful creation. Given the tool has 28 parameters, no output schema, and no annotations, this gap leaves the agent uncertain about what to expect after the final confirmWrite call. Additional context on the response format would improve completeness.

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

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

Schema description coverage is only 36%, so the description must compensate. It adds meaningful context for confirm booleans and sales rep parameters, describing when to set them true. However, many required parameters like acCode, entryDate, productId, unitPrice, etc., are left undocumented in the description, relying on the sparse schema descriptions. The description partially addresses the gap but does not fully cover all parameters.

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

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

The description starts with 'Creates a BRC quote with a generated reference using structured MCP fields,' which is a clear verb+resource combination. It also distinguishes from the sibling tool brc_create_quote by specifying auto-generated references, making the purpose unambiguous.

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

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

The description explicitly states when to use this tool ('when quote references are auto-generated' or after user confirmation of the setting) and includes detailed instructions on prerequisites (e.g., requires saleRepId, saleRepCode, analysisCategoryId, accountCode), prohibitions (e.g., do not use default sales rep values, do not default to CR01), and the two-call workflow with confirmWrite. This provides comprehensive guidance on usage context and 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?

No annotations are provided, so the description carries full behavioral burden. It transparently discloses the two-phase confirmWrite mechanism (first call returns confirmation_required and payload preview, retry with confirmWrite only after explicit user confirmation), the need for explicit counterparty confirmation, and that preflight is not confirmation. It does not, however, mention potential errors, rate limits, or destructive consequences of creating a credit note, but given the complexity, the disclosed behaviors are thorough.

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 somewhat verbose, containing multiple instructions in prose form without visual separation. It front-loads the purpose but then packs requirements in long sentences. While every sentence adds value, a more structured format (bullets or short paragraphs) would improve readability for an agent. It is concise relative to the complexity but could be better organized.

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

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

Given 23 parameters, 19 required, no output schema, and no annotations, the description covers the creation workflow, prerequisites, confirmation steps, and handling of missing data (e.g., listing sales reps). It is quite complete, but it doesn't describe the success response format or any post-creation steps. For a high-complexity tool, this is strong.

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

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

Schema description coverage is only 26%, but the description significantly compensates by explaining many key parameters: reference (conditionally required), saleRepId/saleRepCode (must be from brc_list_sales_reps and not default), analysisCategoryId/accountCode (must be from Sales Analysis category, not defaulted), and the three confirm parameters with precise conditions. This adds substantial meaning beyond the schema. However, some parameters like productId, customerId, etc. are not explained beyond basic type info.

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

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

The description clearly states it creates a BRC sales credit note using structured MCP fields. It distinguishes itself from the sibling 'brc_create_sales_credit_note_gen_ref' by explicitly noting when to use each based on manual reference configuration. The verb 'creates' and resource 'BRC sales credit note' are specific and unambiguous.

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

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

The description provides extensive usage guidance: when to prefer this tool over the gen_ref variant, requirements for saleRepId/saleRepCode (and not to use default/demo values), requirements for analysisCategoryId and accountCode, conditions for setting confirmCrAnalysisCategory, confirmWrite, and confirmCounterpartyExplicit. It also instructs the agent to list or ask for missing sales reps. This is exceptional context for correct tool invocation.

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?

Given no annotations, the description fully explains the two-call protocol, confirmation flags, and pitfalls. It does not explicitly state that the tool writes a record to the database or mention reversibility, but the creation nature is implied. Good transparency for a complex tool.

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

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

The description is lengthy but each sentence serves a purpose. It front-loads the core purpose and then details usage guidelines. A bit verbose but justified by the complexity of the tool. No wasted sentences.

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

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

Given the complexity (5 parameters, nested payload, no output schema), the description covers all necessary aspects: prerequisites, confirmation flags, preflight protocol, and common mistakes. It is complete enough for an agent to invoke correctly.

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

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

Schema coverage is 80% (high), but the description adds critical meaning beyond the schema: it explains the hidden requirements inside the payload object (saleRepId, saleRepCode, analysisCategoryId, accountCode), the two-call protocol for confirmWrite, and the semantics of confirmCrAnalysisCategory and confirmCounterpartyExplicit. This adds significant value.

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

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

The description clearly states it creates a BRC sales credit note with auto-generated reference using raw payload. It differentiates from the sibling tool 'brc_create_sales_credit_note' by specifying auto-generated reference, and the sibling list confirms both exist.

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: 'when company is configured for auto-generated sales references'. Provides thorough prerequisites, warnings against default/demo values, and detailed multi-step confirmation process. Clearly differentiates from preflight and write calls.

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

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

No annotations provided, but the description fully discloses the tool's behavioral traits: two-phase confirmation, return of confirmation_required and payload preview on first call, need for explicit user confirmation, and prohibition of reusing counterparty without explicit confirmation. This is comprehensive for a mutation tool.

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

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

The description is four sentences, front-loaded with the tool's purpose, then details the workflow. Every sentence adds value without redundancy. Highly concise and well-structured.

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

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

Given the complexity (15 parameters, no output schema, no annotations), the description covers the key workflow and constraints. It explains the two-phase confirmation and counterparty confirmation, which are the most complex aspects. It does not detail other standard parameters (e.g., netAmount, vatRateId) but the agent can infer from names. Overall, it provides sufficient context for correct tool usage.

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

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

Schema description coverage is low (20%), but the description adds critical semantic context for the two boolean parameters (confirmWrite, confirmCounterpartyExplicit), explaining their usage rules in the workflow. For other 12 parameters, no additional meaning is provided beyond schema names/types. However, the workflow context for the booleans is essential and compensates somewhat.

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

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

The description clearly states it creates a BRC sales entry using structured MCP fields. It distinguishes itself from numerous sibling tools like brc_create_sales_invoice, brc_create_sales_credit_note, etc., by specifying the exact resource (sales entry) and the unique two-phase confirmation workflow.

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

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

Provides explicit step-by-step guidelines: first call without confirmWrite: true yields preview, then retry with confirmWrite: true only after explicit user confirmation. Also requires confirmCounterpartyExplicit: true after user explicitly names counterparty. Clearly states when not to use (e.g., not on first call, not without explicit confirmation) and distinguishes from passing preflight.

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

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

With no annotations, the description fully discloses behavioral traits: productId 0/1 are blocked at runtime, purchase VAT rates are blocked, first call returns confirmation_required with payload preview, requires confirmCounterpartyExplicit, and addresses gross price entry behavior. All critical behaviors are transparent.

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

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

The description is very long and dense, lacking section breaks. While all information is valuable, it could be more concise. For a tool with 26 parameters, the length is somewhat justified, but improvement in structure would enhance 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 high complexity (26 params, no output schema), the description is remarkably complete. It covers prerequisites, workflows, confirmation steps, relationships with other tools (brc_list_products, brc_list_sales_reps), and edge cases. It even instructs on what to do when no suitable product exists. Only missing detail is the return value after posting, but that is acceptable without an output schema.

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

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

Schema coverage is 54%, and the description adds significant meaning beyond the schema. It explains constraints for note (default to customer name), deliveryTo (do not invent), priceBasis (required when Gross Price Entry enabled), confirmWrite (never true on first call), and clarifies that productId 0/1 are placeholders blocked at runtime.

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

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

The description clearly states 'Creates a BRC sales invoice using structured MCP fields.' It differentiates from the sibling brc_create_sales_invoice_gen_ref by specifying when each should be used (manual vs automatic reference generation). The verb 'creates' and resource 'sales invoice' are specific.

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

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

Extensive guidance on when to use this tool vs alternatives (e.g., prefer gen_ref when manual references not needed). Includes many 'do not' instructions (invent values, use default sales rep, default analysis category) and explicit workflow steps (first call without confirmWrite, show draft, retry with 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?

Despite no annotations, the description discloses many behavioral traits: creation mutation, preflight confirmation, blocked values (productId 0/1, purchase VAT), default behavior (note defaults to customer name), and the confirmation_required response. However, it does not describe the final success response structure, which is a notable omission.

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 overly verbose and repetitive (e.g., note and deliveryTo instructions repeated). It is a dense block of text lacking structure, which makes it harder for an AI agent to parse quickly. While front-loaded with purpose, conciseness is poor.

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 (6 parameters, nested payload, no output schema), the description covers most essential aspects: usage context, parameter semantics, behavioral rules, and confirmation flow. The only gap is the lack of output structure explanation, but overall it is quite complete.

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

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

The input schema covers 83% of parameters, but the description adds significant value for the payload parameter, detailing expected fields (note, deliveryTo, saleRepId, etc.) and constraints. For priceBasis and confirmation flags, the description reinforces and clarifies schema descriptions, making parameter semantics excellent.

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

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

The description clearly states it creates a BRC sales invoice with auto-generated reference, distinguishing it from the sibling brc_create_sales_invoice (which likely uses manual reference). The verb 'creates' and resource 'sales invoice' are specific, and the condition of auto-generated references is explicitly mentioned.

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 extensive usage guidance: when to use (auto-generated references), what to avoid (default values, placeholders, purchase VAT rates), and the precise confirmation workflow (preflight first, then confirmWrite, plus confirmCounterpartyExplicit). It explicitly states do's and don'ts.

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

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

Discloses the two-phase workflow (preflight returns confirmation_required and preview, actual write on second call) and warns that preflight is not confirmation. No annotations existed, so the description carries the burden well.

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

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

The description is two sentences, front-loaded with purpose. The workflow detail is necessary but could be slightly more concise (e.g., bullet points). 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, the description mentions 'payload preview' but does not specify its structure or indicate that the output likely contains the created rep's ID. Lacks mention of prerequisites like company context existence.

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

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

All parameters have schema descriptions (100% coverage), so baseline is 3. The description adds context for confirmWrite's preflight behavior but does not enhance understanding of other parameters beyond the schema.

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

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

The description explicitly states 'Creates a BRC sales rep', using a specific verb and resource. It distinguishes from sibling tools like batch creation and update tools by implying a single-entity creation with a confirmation workflow.

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

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

Provides clear step-by-step guidance on using confirmWrite: first call without, show preview, then retry with confirmation. However, it does not mention when to use batch creation (brc_batch_sales_reps) as an 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?

No annotations are provided, so the description carries the full burden. It discloses the two-step confirmation process, the preflight behavior, and that opening balance is not handled. This is detailed for a mutation tool, though it does not mention error states or idempotency.

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 and front-loaded with the purpose. It packs essential information without excess. A slight improvement could be structuring as bullet points for the two-step process, but it remains 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?

Given no output schema, the description does not explain return values or possible errors. The complex workflow is well-covered, but missing what the successful response looks like. Considering the many sibling tools, it is complete enough for its core usage.

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

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

Schema coverage is 100% but descriptions are minimal. The description adds crucial behavioral context for confirmWrite (when to set true/false) and clarifies that payload is a raw BRC payload. This goes beyond the schema's bare description.

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

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

The description clearly states it creates a BRC supplier using a raw BRC payload. It distinguishes from sibling tools like brc_batch_suppliers and brc_update_supplier by specifying that it does not handle opening balance transactions. The verb 'creates' and resource 'supplier' are specific.

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

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

The description provides explicit guidance on when to use confirmWrite: never on first call, only after user confirmation of a plain-English draft. It also warns about opening balance handling. However, it does not explicitly compare to other supplier-related tools like batch creation.

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?

Without annotations, the description bears full burden. It discloses the destructive nature, required timestamp format, and confirmation step. However, it omits information about side effects, irreversibility, or response 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?

Three concise sentences. The main action is front-loaded, with critical usage instructions following. No unnecessary 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 delete tool with no output schema and no annotations, the description lacks return value information and error conditions. It provides key prerequisites and safety steps but not a complete operational picture.

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

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

Schema descriptions cover all 4 parameters. The description adds context: timestamp must be retrieved from brc_get_accrual and confirmWrite should only be true after user confirmation. This exceeds what schema provides.

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

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

The description clearly states the action (removes) and the specific resource (existing parent Accrual by id). It distinguishes itself from sibling delete tools by specifying the resource and mentioning the prerequisite timestamp retrieval.

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 use brc_get_accrual first and warns not to set confirmWrite=true without explicit user confirmation. However, it does not mention when not to use the tool or compare to other deletion-related tools.

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

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

No annotations are provided, so the description carries the full burden. It discloses the destructive nature and the user confirmation requirement. However, it does not elaborate on potential side effects, reversibility, or error conditions.

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

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

The description is two sentences with no wasted words. First sentence states purpose and prerequisite, second sentence gives a critical rule. 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 description covers the action, prerequisite step, and safety rule. For a deletion tool with no output schema, it is fairly complete. However, it does not mention return values or behavior on invalid ids.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds minimal additional meaning beyond the schema, such as the context of 'allocation resolver id' and the need for user confirmation, but this is mostly redundant.

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

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

The description clearly states the verb 'reverses/deletes' and the resource 'allocation by allocation resolver id', and it distinguishes from siblings by specifying the unique resource type and prerequisite step (using brc_list_allocated_transactions).

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

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

The description provides explicit guidance on when to call the tool (after finding the allocation id) and a critical safety rule (do not call with confirmWrite=true without user confirmation). However, it does not mention alternatives or when not to use this tool compared to other delete tools.

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

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

No annotations provided, so description carries full burden. It discloses the confirmation flow, the preview, and the requirement for explicit user confirmation. However, it does not explicitly state irreversible nature or success effects, though implied.

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, followed by step-by-step instructions. Every sentence is necessary and well-organized.

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

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

Given no output schema, the description fully covers the workflow, including the confirmation requirement, preview, and preflight warning. It is complete for safe usage.

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

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

Schema coverage is high (75%), so baseline 3. The description adds significant context for confirmWrite parameter (first call false, then true after confirmation) and clarifies the two-step behavior beyond the schema's minimal description.

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

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

The description clearly states the verb 'Deletes' and the resource 'BRC bank account by id'. It is specific and distinguishes from sibling delete tools by focusing on bank accounts.

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: 'Only call this after the user has explicitly confirmed deletion.' Provides a two-step process with first call without confirmWrite and second call after confirmation, and warns against using preflight as confirmation.

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

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

With no annotations provided, the description carries full burden and excels. It explains the destructive nature (delete), the required two-step confirmation process, the return of confirmation_required and payload preview on initial call, and the critical warning that preflight is not confirmation. It fully discloses the behavioral pattern.

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

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

The description is a single paragraph that is concise and front-loaded with the main action. Every sentence adds important information: deletion action, two-step process including draft display, and a warning. 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 the tool is a delete operation with a confirmation pattern and no output schema, the description covers the essential process well. It explains the initial response and required next step. However, it could be more complete by mentioning potential error conditions or the behavior of the confirmDelete parameter, and by clarifying what happens on a successful delete.

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 (75%) with descriptions for id, companyName, and confirmWrite. The description adds value by explaining the multi-step usage of confirmWrite but does not mention confirmDelete, which is in the schema with default false. This omission is a gap, keeping the score at 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 'Deletes a BRC cash payment by id,' specifying the verb and resource. It distinguishes from sibling delete tools by the resource name and the unique two-step confirmation process, which is not described in other sibling descriptions.

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

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

Provides explicit step-by-step instructions for safe usage: first call without confirmWrite:true, show plain-English draft in chat, then retry with confirmWrite:true only after explicit user confirmation. Warns that preflight is not confirmation. However, it does not compare to alternatives like other delete tools or specify when not to use this tool.

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

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

With no annotations, the full burden is on the description. It thoroughly explains the two-step behavior, the necessity of user confirmation, and the preview feature. It doesn't mention error states or impacts of deletion, but the core behavior is well-transparent.

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