Caribooks (QuickBooks Online)

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the agent knows this is a mutating operation. The description adds valuable context by noting that activation sets the next run from the schedule, and that depending on configuration the loop can change bookkeeping records or email invoice reminders to external recipients. It also mentions preview mode requiring approval, which is useful behavioral context. While it doesn't detail side effects like exactly what records change or email content, the annotations plus description sufficiently convey the risk profile.

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

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

The description is reasonably concise at about four sentences, with the core action front-loaded in the first sentence. Later sentences add relevant context about schedule, effects, and approval requirements. It is not overly verbose, though the last sentence about the Caribooks portal is somewhat tangential and could be trimmed without losing essential meaning.

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

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

For a tool with one parameter, no output schema, and clear annotations, the description covers the essential context: what it does, when it's appropriate, the approval requirement, and potential side effects. It doesn't describe the return value, but without an output schema, that's less critical. The main gap is that it doesn't explicitly state prerequisites like 'loop must be paused' (though implied by 'existing paused') or what happens if the loop is already active, but overall it's 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 description coverage is 100% and the single parameter loop_id is well described in the schema itself ('The loop's id, as create_task and list_loops show it.'). The description doesn't add much beyond the schema, but it does contextualize that the loop must be paused and existing, which implies the ID refers to an existing paused loop. Since the schema already handles the parameter description well, a baseline 3 is appropriate.

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

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

The description clearly states the tool activates an existing paused bookkeeping loop by id after user approval, which is a specific verb-resource pair. It mentions setting the next run from its schedule and distinguishes between preview mode requiring approval and normal activation, but doesn't explicitly differentiate it from sibling tools like 'list_loops' or 'create_task' that might be related to loop management.

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

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

The description gives clear context for when to use this tool: to activate a paused loop after user approval, and mentions preview mode requires approval of proposed actions. However, it doesn't explicitly state when not to use it or name alternative tools for managing loops (e.g., if the user wants to modify a loop instead of activating it), though the context implies activation is the specific purpose.

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 annotations already indicating mutability and destructiveness, the description adds valuable context: the 20 MB size limit, the full-access permission requirement, and the fact that this action does not create a transaction or transcription. This goes beyond the structured hints without contradicting them.

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

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

The description is dense but well organized: opening with the core action, then clarifying the three file sources, then constraints, permissions, and exclusions. Every sentence earns its place and no schema information is needlessly repeated.

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 9-parameter mutation tool with no output schema, the description covers the key invocation concerns: what files are accepted, how to supply them, size limits, permissions, and side-effect boundaries. The only minor gap is that it does not describe the call's return value or confirmation behavior.

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

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

The schema already covers all parameters, so the baseline is 3. The description adds meaningful extra semantics by explaining the three file-source modes: upload_id from the Caribooks document box, file for ChatGPT native descriptors, and content_base64 for small inline bytes. This helps agents choose the right mutually exclusive parameter.

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

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

The description clearly states a specific verb and resource: attach a file to an existing QuickBooks transaction, and enumerates supported file types. It also clarifies that it does not create a transaction or render a transcription, which separates it from the create_* family. However, it does not explicitly differentiate itself from the closely named sibling attach_receipt.

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

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

The description provides useful context: it targets existing transactions, requires full access, and explicitly excludes creating transactions or rendering transcriptions. It does not name alternative tools such as attach_receipt or state when to prefer them, so the usage guidance is implied rather than explicit.

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

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

Annotations only provide readOnlyHint=false and destructiveHint=false, so the description carries the behavioral burden and fulfills it well. It discloses that the PDF is 'visibly marked as a transcription, not an original document,' that it requires explicit confirmation, that it fails on duplicates unless confirmed, and that it never transfers original uploaded files. This far exceeds the minimal annotation signal.

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, each serving a distinct purpose: what it does, when to use it, behavioral caveat, and explicit non-transfer. It is front-loaded with the core action and wastes no words. The structure is tight and scannable.

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

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

For a tool with 7 parameters, a nested object, no output schema, and mutation semantics, the description covers all critical aspects: purpose, target scenario, prerequisites (confirmation and access), duplicate handling, and non-transfer of originals. Combined with the 100% schema descriptions, an agent has everything needed to decide and 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 100%, so the baseline is 3, but the description adds meaningful context for receipt fields: 'The receipt fields contain the original text and, when applicable, the actual email sender and subject.' It also clarifies the filename default and emphasizes the confirmation gates on confirmed_by_user and allow_duplicate. That extra guidance compensates for the nested-object 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 opens with a specific verb and resource: 'Render user-provided receipt text as a PDF transcription and attach it to a QuickBooks transaction.' It clearly distinguishes from siblings by narrowing to text-only receipts and explicitly stating 'Does not transfer original uploaded files,' which separates it from attach_file.

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

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

The description gives explicit when-to-use guidance ('Intended for receipts that exist only as text, such as an email body or copied order confirmation'), states prerequisites ('Requires confirmed_by_user: true... and full access on the connection'), and implies the alternative for original files with 'Does not transfer original uploaded files.' No ambiguity remains about when this tool is appropriate.

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

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

Annotations provide readOnlyHint=false and destructiveHint=false, which already establish that this is a mutating but non-destructive write operation. The description adds no behavioral traits beyond that, such as side effects, permissions, or impact on QuickBooks data. There is no contradiction with the annotations.

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

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

The description is a single, front-loaded sentence with no filler or redundant wording. It is concise, though it forgoes the opportunity to add useful context; still, it earns its place as a clear statement of the 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?

The description gives the core operation, and the schema's entity description covers the important field-level restrictions and the required AccountType. However, the overall definition is minimal: it doesn't clarify the exact kind of account, provide sibling differentiation, or describe what happens after creation. This is adequate but not rich.

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

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

Schema description coverage is 100%, so the schema already documents the required 'entity' object and optional 'company' parameter. The description adds no parameter-level meaning, but because the schema is thorough, a baseline score of 3 is appropriate.

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

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

The description states a clear verb and resource: 'Create an account in QuickBooks Online.' The word 'account' plus the surrounding sibling tools (get_account, update_account, search_accounts) makes the target resource identifiable. It is slightly less specific than it could be because it doesn't say 'chart of accounts account,' but it is not tautological or misleading.

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

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

There is no guidance about when to use this tool versus alternatives like update_account or search_accounts, nor any mention of prerequisites or setup. The description only states the action without contextual direction.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description doesn't need to restate those. It adds a useful boundary ('does not upload a file or render a PDF') but does not disclose auth requirements or side effects. Adequate for a create 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?

Two short, front-loaded sentences, zero filler. The description earns its place by stating the core function and the key exclusion in the first sentence.

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

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

With a detailed schema and the boundary note about file vs. PDF, the agent has everything needed to call this tool correctly. No output schema exists, but a create operation's return value is not necessary for correct invocation.

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

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

Schema description coverage is 100%, and the entity parameter description is rich enough to explain the required structure (Note plus AttachableRef). The tool description adds no extra parameter meaning, so the baseline of 3 applies.

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

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

The description states a specific action and resource: create a text note attached to a QuickBooks record, and explicitly differentiates from file upload and PDF rendering. This makes it immediately clear what the tool does and how it differs from attach_file and attach_receipt.

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

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

The description says 'Does not upload a file or render a PDF,' implying the alternatives, and the input schema explicitly names attach_file and attach_receipt as the tools for those actions. An agent gets clear routing guidance.

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

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

Annotations declare readOnlyHint=false (write) and destructiveHint=false (non-destructive), so the description doesn't need to restate that. The description adds critical behavioral context: it instructs to avoid sending government identifiers, birth dates, and card-processing details, and clarifies the constraint for ItemBasedExpenseLineDetail lines. These go beyond annotations and are valuable for safe usage.

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

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

The main description is a single, front-loaded sentence that delivers the core purpose immediately. It's concise, though it could incorporate a brief usage-hint or differentiation. The entity parameter description is embedded in the schema, so the main description itself is efficient.

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

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

Given the tool has a nested, complex parameter and no output schema, the description effectively covers the essential intent. The schema handles the detailed object structure. The description adds necessary guardrails about sensitive fields and line-detail conditions. No critical information for invoking the tool correctly seems missing.

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

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

Schema coverage is 100%, so baseline is 3. The entity parameter description in the schema already explains the object. The tool description adds meaning beyond the schema by warning about sensitive data and explaining the line-detail rule, which are not in the schema's generic description. This enriches the parameter 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?

Description clearly states the verb 'Create' and resource 'a bill' in 'QuickBooks Online.' This directly distinguishes it from siblings like create_bill_payment, create_purchase, and create_vendor_credit. The action is unambiguous.

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

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

No explicit when-to-use guidance is provided. The description does not mention alternatives or conditions for choosing this tool over create_purchase/invoice. However, the name and the singular resource strongly imply this is for creating a bill, and the parameter guidance implies the required structure. Usage is implied but not explicitly differentiated.

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

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

The annotations only indicate this is not read-only and not destructive. The description adds meaningful behavioral context by stating this is a bookkeeping record and does not trigger a real bank or card transfer, which is important for an agent to set user expectations correctly.

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 short sentences with no filler. The first states the action, the second gives context, and the third clarifies a key boundary. Every sentence earns its place and the key distinction is front-loaded.

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

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

For a nested-object creation tool, the description plus rich entity schema is largely sufficient for correct invocation. The only notable gap is that no return value or failure behavior is described, but this is minor given the clear schema and boundary clarification.

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

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

Schema description coverage is 100%, so the input schema already documents the entity and company parameters well. The entity description details PayType, bank/card references, and LinkedTxn requirements. The tool description itself adds no extra parameter-level meaning, so baseline 3 applies.

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

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

The description uses a specific verb and resource ('Create a bill payment in QuickBooks Online'), clarifies it is an accounting record of a payment to a vendor, and explicitly distinguishes it from actual payment initiation. This sets it apart from related tools like create_payment and create_credit_card_payment_txn.

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

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

The description provides clear context: use this when recording an accounting payment to a vendor, not when disbursing funds. It does not name sibling alternatives explicitly, but the 'does not initiate a bank or card payment' boundary gives useful when-not guidance.

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

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

Annotations already indicate this is a mutation (readOnlyHint=false), and the description/schema add useful behavioral constraints: the budget must be P&L with one amount per account per period, and sensitive data like SSNs, tax IDs, birthdays, and card-processing details must not be sent. It does not describe response shape or duplicate-handling behavior, but the added constraints go beyond what annotations convey.

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

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

The main description is two concise sentences with the core action first and the qualifying scope second. The longer entity parameter description is dense but every phrase contributes required field, enum, array-shape, or privacy 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?

The definition provides enough information to construct a valid request: entity fields, acceptable enum values, company selection, and a privacy warning are all covered. There is no output schema and the nested AccountRef/date formats are not fully spelled out, leaving a small gap, but nothing essential for invoking the tool correctly is missing.

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

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

Both parameters have schema descriptions (100% coverage), and the entity parameter description adds substantial meaning beyond the bare object type. It enumerates the required budget fields, allowed BudgetType and BudgetEntryType values, the BudgetDetail array shape, and a clear privacy restriction.

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

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

The description uses a specific verb and resource: "Create a budget in QuickBooks Online." The second sentence narrows the scope to "a profit-and-loss budget with one amount per account per period," which clearly distinguishes this from the get/search/update/delete budget siblings and from other create_* entity 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 intended use is explicit: call this when creating a new QuickBooks budget, specifically a profit-and-loss budget. It does not explicitly mention when not to use it or point to update_budget/search_budgets as alternatives, but the create verb and the P&L constraint make the selection context unambiguous.

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

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

The description adds no behavioral detail beyond what the annotations already convey (readOnlyHint=false, destructiveHint=false). It does not disclose return behavior, idempotency, validation, or effects on QuickBooks data. The sensitive-data warning appears only in the schema, not in the description.

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, front-loaded sentence with no filler or redundant wording. It is efficient, though so minimal that it leaves usage and behavioral context to other 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?

For a straightforward create operation, the description plus a fully documented schema gives an agent the essential action and parameters. However, with no output schema and no mention of return values, duplicate handling, or how this relates to update_class/search_classes, the definition is adequate but not rich.

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

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

Schema description coverage is 100%, and both parameters ('entity' and 'company') are documented in the input schema, including the restriction on sending government identifiers and card-processing details. The description itself adds no parameter-level meaning, but the high schema coverage justifies the baseline 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 states a specific verb ('Create') and resource ('a class') in the QuickBooks Online context, making the primary function clear. It does not explicitly differentiate from sibling tools like update_class or search_classes, but the verb and resource are specific enough to avoid core ambiguity.

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

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

There is no guidance about when to choose this tool over update_class, search_classes, get_class, or other create_* tools. The verb 'Create' implies the use case, but the description provides no explicit context, prerequisites, or exclusions.

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

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

The annotations already signal this is not read-only (readOnlyHint=false) and not destructive (destructiveHint=false), so the 'Create' wording is consistent rather than additive. The description adds the multicurrency prerequisite and clarifies what a company currency represents, but it does not disclose behaviors like duplicate-currency errors, idempotency, or required permissions.

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 short, direct sentences with no filler. The primary action is front-loaded, and the additional context about multicurrency and the resource meaning earns its place.

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

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

For a simple create-with-nested-object tool, the combination of description and rich schema covers the prerequisite, the object shape, and the sensitive-data restriction. It does not describe return values or error conditions, but no output schema exists and the create action is predictable enough that this is a minor gap.

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

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

Schema description coverage is 100%, so the schema already documents the entity object, the company selector, and the ISO 4217 Code requirement. The main description adds little parameter-level detail, but that is acceptable because the schema carries the semantic load.

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

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

The description states a specific action ('Create a company currency') and a specific resource ('in QuickBooks Online'), which is unambiguous. It also distinguishes itself from sibling tools like update_company_currency, delete_company_currency, get_company_currency, and search_company_currencies by being the create operation.

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

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

The description gives clear context about when this is applicable: 'only meaningful with multicurrency enabled' and the schema reinforces the prerequisite. It does not explicitly name alternatives or exclusion cases, but the multicurrency precondition is a useful and clear usage signal.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, meaning the tool writes but is not destructive. The description adds a key behavioral detail: 'It does not move money,' clarifying that this is purely an accounting record with no real-world fund movement. This is beyond what annotations provide.

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

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

Three short sentences, each earning its place. The first names the action and target, the second defines the concept, and the third negates a common misunderstanding. No filler.

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

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

Given the simple two-parameter schema with exhaustive parameter descriptions and the behavioral note about money not moving, the description is complete enough for an agent to invoke correctly. It does not describe return values, but no output schema is provided and none is required for this kind of 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 description coverage is 100%, and the entity parameter description already details required fields (TxnDate, Amount, BankAccountRef, CreditCardAccountRef) and restrictions on sensitive data. The tool description adds no parameter-level information; baseline 3 applies.

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

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

States the verb 'Create' and the resource 'credit card payment txn in QuickBooks Online'. Clarifies the concept with 'accounting record of a bank payment toward a credit card balance' and distinguishes it from money movement with 'It does not move money.' This is specific enough to separate from sibling tools like create_payment or create_transfer.

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 use case: recording a bank payment toward a credit card balance. It does not explicitly name alternatives or state when to use vs create_payment/create_bill_payment, but the 'does not move money' clause gives a hint that it is not for actual transfers. This is implicit guidance, not explicit.

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

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

Annotations indicate this is not read-only and not destructive, but the description adds no behavioral context beyond the basic 'create' action. It does not disclose effects on QuickBooks, required permissions, validation behavior, or what response to expect, so the description contributes little beyond what the annotations already imply.

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 clear sentence with no filler, tautology, or redundant detail. It is appropriately front-loaded and easy to parse quickly.

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

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

The schema covers parameters well, but the overall definition lacks sibling differentiation, usage context, and behavioral expectations. An agent can likely invoke the tool in a straightforward case, but it is not fully equipped to choose this tool correctly or understand side effects without additional inference.

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

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

Schema description coverage is 100%, so the input schema fully documents the entity object and the optional company parameter. The description adds no parameter-level detail, but the baseline of 3 applies because the structured schema carries the burden.

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

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

The description names a specific verb ('Create'), a clear resource ('a credit memo'), and the platform ('QuickBooks Online'), so an agent can identify what the tool does. It does not, however, differentiate this from closely related create_* siblings such as create_refund_receipt or create_vendor_credit, so it stops short of full sibling differentiation.

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

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

The description gives no guidance on when to use this tool versus alternatives like send_credit_memo, update_credit_memo, create_refund_receipt, or create_credit_card_payment_txn. There is no mention of prerequisites, when a credit memo is the right transaction type, or when to choose another create tool.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false, so the description aligns by stating 'create'. However, the description adds no behavioral details beyond that—no mention of side effects, required permissions, or what happens on creation. It does not contradict annotations, but it provides no extra value beyond the annotation fields.

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

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

The description is a single sentence, which is concise, but it is under-specified rather than appropriately sized. It lacks any structuring or front-loading of key info. While it is short, it does not earn its place because it provides minimal 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 create tool with two parameters and no output schema, the description is incomplete. It doesn't mention what the return value will be (likely the created customer object), any constraints on the entity, or how to select the company. The schema covers parameters, but the description provides no additional context that would help an agent call the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters (entity and company) in detail. The description itself adds no parameter information, so the baseline of 3 is appropriate. It does not compensate for any gaps because there are none.

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 (create) and resource (customer) with the context 'in QuickBooks Online'. It is distinct from other create_* tools because the resource is customer, and it is not a tautology since it adds context. However, it doesn't mention alternatives like update_customer or search_customers, but that's not required for this dimension.

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

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

There is no guidance on when to use this tool versus alternatives. No mention of prerequisites, when to use update_customer instead, or any conditions. The description is solely a statement of purpose, providing zero direction for tool selection.

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

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

Annotations indicate a non-read-only write operation (readOnlyHint=false), and the description adds no further behavioral detail about side effects or permissions. However, the entity parameter description includes a useful compliance caveat—do not send government identifiers, birth dates, or card-processing details—which goes beyond the annotations by warning about data handling.

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 front-loaded sentence with no wasted words, stating the verb, resource, and target system immediately. It is appropriately terse, though it omits usage guidance that would make it fully self-sufficient.

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 definition is minimally viable: it names the operation clearly and the schema covers parameters, but the entity is a freeform object with no documented required fields. With no output schema, the expected result is undisclosed, and the agent must rely on external QuickBooks API knowledge to construct a valid Department object. The compliance warning helps, but overall the context is incomplete.

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

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

Schema description coverage is 100%, so the baseline is 3. The entity description identifies the expected QuickBooks API v3 Department object and adds a compliance warning, while the company parameter is clearly described with an optional-when-single-company note. The tool description itself adds no parameter meaning beyond what the 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 states a specific verb ('Create'), resource ('department'), and target system ('QuickBooks Online'), making it clear what the tool does. It is easily distinguished from update_department, get_department, and search_departments, though it does not explicitly contrast with sibling 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?

No guidance is provided on when to use this tool versus alternatives like update_department or create_class. There is no mention of prerequisites, such as checking whether the department already exists, or any exclusions that would route an agent to another tool.

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

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

Annotations already establish that this is a mutation (readOnlyHint=false) and not destructive. The description adds a useful compliance constraint by warning against sending SSN/tax IDs, birth dates, or card-processing details, but it does not disclose return behavior, side effects, or failure modes. Transparency is partial.

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

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

The description is one front-loaded sentence with no filler, immediately naming the action and target system. Every word earns its place, though the brevity does rely on the schema for additional detail.

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

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

For a create mutation with no output schema, the description is thin: it does not state what a successful call returns, how errors surface, or prerequisites such as an existing deposit account. The rich schema and mutation annotations make the tool callable, but the description leaves important operational context unstated.

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 entity property already documents the required Deposit object shape, DepositToAccountRef, per-line DepositLineDetail.AccountRef, and sensitive-data restrictions. The tool description itself adds no parameter meaning, so it stays at the high-coverage 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 states a specific action and resource, 'Create a deposit in QuickBooks Online,' so an agent can tell it apart from sibling create_* tools at the resource-name level. It does not elaborate on what a deposit involves or why it differs from similar transaction-creation tools, so it is clear but not maximally informative.

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

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

There is no guidance on when to use create_deposit versus alternatives such as create_payment, create_credit_card_payment_txn, or update_deposit. No exclusions, prerequisites, or routing hints are provided, leaving the agent to infer usage solely from the tool name.

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

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

Annotations already indicate readOnlyHint=false, so the write behavior is known. The description adds no behavioral context beyond that: no mention of required permissions, idempotency, duplicate handling, or what effects creation has in QuickBooks. With minimal annotations, the description shoulders more burden but does not carry it.

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

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

A single, front-loaded sentence with no filler. It is concise and easy to parse, though its brevity comes at the cost of informative substance. As far as structure and economy, it earns a high score.

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

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

No output schema and no mention of return values, success criteria, or post-create state. The nested entity object is documented in the schema, but the description provides no completeness for what an agent should expect after calling this tool. For a mutation with only sparse annotations, this is a meaningful 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?

The description itself adds no parameter details, but the input schema covers 100% of parameters with meaningful descriptions, including the entity object restrictions and company selection. With full schema coverage, the baseline of 3 applies; the description does not need to compensate.

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

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

States a specific verb and resource: 'Create an employee in QuickBooks Online.' This distinguishes it from sibling create_customer, create_vendor, and other create_* tools. However, it lacks any additional scoping or differentiation beyond the resource name, so it is clear but not strongly differentiated.

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

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

Provides no guidance on when to use this tool versus alternatives, when not to use it, or any prerequisites. The single sentence implies the obvious use case but offers no decision support for an agent choosing among the many create_* siblings.

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

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

The description only says 'Create an estimate' and does not disclose any side effects, permissions, or data handling behavior. The annotations are minimal (readOnlyHint=false, destructiveHint=false) and do not add context. Although the entity parameter warns against sending sensitive data, that is a parameter constraint, not a tool behavioral trait. The description carries the burden and does not satisfy it.

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

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

The description is a single sentence with no redundant phrases or extra details. It is concise and front-loaded with the core operation, making it easy for an agent to parse quickly.

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

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

Given the tool's complexity (nested entity object, no output schema), the description is minimal but the schema carries substantial detail including required fields and data constraints. However, there is no guidance on expected return values or when to use this over related tools, leaving some gaps. Still, the overall definition is enough for a competent agent to invoke correctly with the schema alone.

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%: both entity and company parameters have descriptive text, with the entity description warning about government identifiers and card-processing details. The tool description adds no parameter information beyond what the schema already provides, which meets the baseline for full coverage.

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

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

The description states 'Create an estimate in QuickBooks Online', which is a clear, specific verb+resource statement. It distinguishes this from the many other create_* tools in the sibling list by naming 'estimate' as the resource. It is not a tautology and is unambiguous.

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

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

The description gives no guidance on when to use this tool versus alternatives like create_invoice, create_sales_receipt, or the related search_estimates/update_estimate. There are no prerequisites, exclusions, or conditions stated, so the agent must infer usage from the resource name alone.

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

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

The annotations already indicate this is a write operation (readOnlyHint false) and not destructive (destructiveHint false). The description adds the specific behavioral detail that it books a valuation difference, and the plan/region constraint, which are not covered by annotations. It does not disclose potential side effects like requiring specific permissions or creating an irreversible transaction, but the added context is meaningful.

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 that front-loads the action and then efficiently adds the effect and the usage constraint. There is no redundancy or fluff; every part earns its place.

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

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

The description includes the critical region/plan constraint, and the schema thoroughly covers the complex nested entity parameter. There is no output schema, so no return-value details are needed. It does not mention prerequisites like having inventory items set up, but the core information an agent needs to decide and invoke the tool is present.

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

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

Schema description coverage is 100%, so both parameters are fully documented in the schema. The entity parameter has a detailed description explaining the structure and required fields. The tool description does not add any parameter-specific guidance beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description clearly states the action (create an inventory adjustment), the resource (inventory adjustment in QuickBooks Online), and the specific effect (changes quantity on hand and books valuation difference). It also includes a scope constraint (US companies on Plus or Advanced only), which distinguishes it from other create tools and clarifies its applicability.

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 concrete usage condition (US companies on Plus or Advanced) and implies the purpose of adjusting inventory quantities. It does not explicitly mention alternatives like update_inventory_adjustment, but the create vs. update distinction is implicit. The constraint is a strong usage guideline, though exclusions are not stated.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the agent knows this is a mutating operation. The description adds no behavioral details beyond 'create' – no mention of required permissions, side effects, or what happens on success/failure. The entity parameter description does add a useful constraint (do not send government identifiers, birth dates, card-processing details), which is a behavioral guardrail. However, the core description itself is minimal.

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, clear sentence that front-loads the core purpose. It is appropriately concise. The schema's entity description is longer but earns its place by providing critical data-handling constraints. No fluff or redundancy.

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

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

For a create operation with a nested object parameter and no output schema, the description is adequate but not rich. It tells the agent what to create and warns about sensitive fields, but doesn't describe the expected response, error conditions, or any prerequisites (e.g., customer must exist). Given the complexity of a QuickBooks Invoice object, more guidance on required sub-fields or common pitfalls 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 100%, so the schema already documents both parameters. The entity parameter description adds meaningful guidance beyond the schema: it explicitly warns against sending sensitive data (SSN, tax IDs, birth dates, card-processing details) and directs managing those fields in QuickBooks. The company parameter is also clearly explained. This exceeds the baseline 3 for full coverage.

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

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

The description states a specific verb and resource: 'Create an invoice in QuickBooks Online.' This clearly identifies the operation and target system. It doesn't explicitly differentiate from sibling tools like create_credit_memo or create_sales_receipt, but the resource 'invoice' is distinct enough among the create_* siblings.

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

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

The description implies usage: use this when you need to create an invoice in QuickBooks. It doesn't explicitly state when not to use it or mention alternatives like create_sales_receipt or create_credit_memo. The schema's entity description adds some context about what to send, but no explicit routing guidance is 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?

Annotations already indicate this is a write operation (readOnlyHint=false) and not destructive, so the description correctly stays consistent. It adds meaningful behavioral context by instructing the agent not to send government identifiers, birth dates, or card-processing details and to manage those fields directly in QuickBooks.

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 main description is a single clear sentence, and the entity parameter description is dense but every clause earns its place. It packs type-based requirements and a privacy warning into a compact, readable format without filler.

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

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

For a complex nested create operation, the definition covers the entity shape, required references, confidential-data restrictions, and how to target a company. It does not mention return values or error/validation behavior, and there is no output schema, leaving a minor gap for the agent to infer.

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

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

Although schema description coverage is 100%, the description adds substantial meaning beyond the field names. It enumerates type-specific required fields (Service/NonInventory, Inventory, Category, Group) and explains what company identifiers are accepted, giving an agent enough detail to construct a valid entity without external lookups.

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

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

The description states a specific verb ('Create') and resource ('an item in QuickBooks Online') without ambiguity. It does not explicitly differentiate from the many sibling create_* tools, but the QBO Item resource is well-defined enough that an agent can tell it from create_account, create_invoice, etc.

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

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

There is no guidance about when to use this tool versus alternatives such as update_item, get_item, or search_items. No conditions, prerequisites, or exclusions are provided; any usage signal is only implicit in the tool name.

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

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

Annotations already indicate this is a write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds no further behavioral context, such as side effects, idempotency, posting behavior, or result handling.

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, front-loaded sentence with no filler. It is appropriately concise given the input schema carries the detailed parameter guidance.

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

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

The description is adequate for a simple create tool but omits what a successful call returns and any operational context (e.g., whether the journal entry is posted or saved as a draft). The schema covers parameters, so the main gap is the lack of invocation-level detail beyond creation.

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

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

Schema description coverage is 100%, with detailed parameter descriptions for entity and company. The tool description itself adds no parameter-level meaning, so the baseline of 3 applies.

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

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

The description states a specific action ('Create') and a specific resource ('journal entry') in a named context ('QuickBooks Online'), which clearly distinguishes it from sibling create_* tools. It goes beyond a bare tautology by specifying the platform.

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

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

The description gives no guidance on when to use this tool versus alternatives such as create_invoice, create_bill, or update_journal_entry. Any usage signal is purely inferred from the tool name, not explicitly described.

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

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

Annotations already establish that this is a write operation that is not destructive. The description adds a meaningful behavioral boundary: this tool records a payment rather than executing payment processing. It does not detail side effects or idempotency, but the key non-obvious behavior is disclosed.

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

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

Two sentences with no filler. The core action is front-loaded, and the critical caveat about payment processing is stated immediately afterward.

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, combined with the fully documented schema, covers the essential semantics and the most important restriction for this create operation. It does not explicitly describe the return value or side effects after creation, but the annotations clarify the write/non-destructive profile.

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 `entity` and `company`. The description adds one actionable field-level constraint beyond the schema—`ProcessPayment` must be omitted or false—and clarifies the semantic meaning of the payment object as an accounting record rather than a processing action.

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

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

The description states a specific verb and resource: 'Create a payment in QuickBooks Online.' It further clarifies that this is an accounting record of an already-received customer payment, which distinguishes it from payment-processing or payment-method creation tools among the siblings.

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

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

The phrase 'customer payment already received' gives clear context for when to use this tool, and 'Payment processing is not supported; ProcessPayment must be omitted or false' is an explicit when-not. However, it does not name an alternative tool for payment processing, so it stops short of full alternative routing.

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

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

The tool description adds no behavioral nuance beyond the annotations (readOnlyHint=false, destructiveHint=false). It simply restates the action. Notably, the rich data-handling warning ('Do not send government identifiers...') lives in the schema property description, not in the tool description, so it does not count toward behavioral disclosure here.

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?

A single sentence with no filler: 'Create a payment method in QuickBooks Online.' It is appropriately front-loaded and compact for a simple create operation, with zero 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?

The input side is thoroughly covered by the schema, but the description omits expected return behavior (no output schema exists) and fails to disambiguate from create_payment. For a simple create with no annotations beyond readOnly/destructive hints, this is adequate but leaves clear gaps.

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

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

Schema description coverage is 100%, so the baseline is 3. The entity parameter description is strong: it identifies the object type, references QuickBooks Online API v3, and warns against sensitive fields. The company parameter is also well explained. The tool description itself adds no additional parameter meaning, so it does not exceed 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?

States a clear verb and resource: 'Create a payment method in QuickBooks Online.' This identifies the operation unambiguously at a glance. However, it does not explicitly distinguish itself from the similarly named sibling create_payment, so the differentiation burden falls on the tool name.

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

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

No guidance is provided about when to use this tool versus alternatives like create_payment, update_payment_method, or search_payment_methods. The general purpose is implied by the name, but no explicit context or exclusion criteria are given to prevent misuse.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the agent knows this is a mutation that is not read-only. The description adds no behavioral context beyond the act of creating, such as side effects on company books, irreversibility, permission requirements, or response behavior. It does not contradict the annotations, but it also does not disclose anything beyond them.

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

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

The description is a single direct sentence with no filler or redundancy. Every word contributes to stating the action and target system, and the most important information is front-loaded. This is an appropriately concise definition.

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 schema carries substantial parameter context, covering the nested entity structure and company parameter. However, the tool operates on a complex object with no output schema, and the description offers no high-level context about return behavior or how purchase differs from related transaction types. It is minimally viable but would benefit from a brief note on what a purchase represents in QuickBooks.

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 input schema already provides detailed meaning for both parameters, including the required fields, PII handling warning, and company selection behavior. The description itself adds no parameter-level information, so the baseline score of 3 applies.

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

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

The description states a specific verb and resource: 'Create a purchase in QuickBooks Online.' This clearly identifies the operation and the target system, and the noun 'purchase' distinguishes it from sibling tools like create_bill, create_purchase_order, or create_vendor_credit. It lacks explicit sibling differentiation, but the core purpose is unambiguous.

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

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

No guidance is given for when to use this tool versus alternatives such as create_bill, create_purchase_order, or create_payment. The description simply names the action without explaining its typical use case, prerequisites, or exclusions. An agent must infer which financial document is intended.

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

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

Annotations already signal that this is a mutating operation (readOnlyHint=false, destructiveHint=false), and the description adds no behavioral context beyond that. It does not mention prerequisites, whether duplicate POs are allowed, or what side effects occur in QuickBooks.

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, front-loaded sentence with no filler. It is appropriately sized for a tool whose detailed parameter guidance already lives in the schema.

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 schema covers entity complexity and company selection well, and annotations cover the basic safety profile. However, the overall definition omits what the tool returns, prerequisites, and when to choose a purchase order over sibling purchase/bill tools, leaving some gaps for a create operation with no 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 description coverage is 100%, and the entity parameter description is unusually detailed, including sensitive-data warnings and a specific QuickBooks error scenario. However, the tool description itself adds no additional parameter meaning, so the baseline of 3 is appropriate.

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

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

The description names a specific verb and resource: it creates a purchase order in QuickBooks Online. This is unambiguous and distinguishes it from get/search/update/delete siblings, though it does not explicitly contrast it with similar create tools such as create_purchase or create_bill.

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

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

The description provides no guidance on when to use this tool versus create_purchase, create_bill, or create_vendor_credit. There are no alternatives, exclusions, or contextual conditions, so the agent must infer usage solely from the tool name.

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

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

Annotations already indicate that this is a write operation (readOnlyHint: false) and potentially destructive (destructiveHint: true). The description adds no behavioral context beyond that—no mention of side effects, permission requirements, or what happens to existing data. With annotations present, the bar is lower, but the description still offers no added 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 concise—two sentences that front-load the purpose and define the term 'recurring transaction'. It is efficiently written with no wasted words, though it could benefit from more context without harming conciseness.

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

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

The tool is complex (nested RecurringInfo structure, multiple fields), and there is no output schema. The description does not explain what the response looks like, what errors might occur, or any prerequisites (like company selection). The agent is left to infer behavior from the schema alone, which is insufficient for a create operation with this 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 the schema documents both parameters. However, the description adds valuable semantics beyond the schema: it provides a concrete example of the RecurringInfo structure and explicitly warns against sending sensitive data (SSN, tax IDs, birth dates, card-processing details). This enhances the agent's understanding of the entity parameter beyond the schema's generic description.

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

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

The description states a specific verb and resource ('Create a recurring transaction in QuickBooks Online') and further clarifies that it's a template used to create transactions on a schedule or on request. This clearly distinguishes it from sibling tools like create_invoice or create_bill, which create actual transactions rather than recurring templates.

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 does not provide any guidance on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or suggest when to prefer other create_* tools. The purpose is implicit but no explicit usage context is given.

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

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

The description is minimal, providing no behavioral details beyond the fact that it creates a refund receipt. Even though annotations indicate readOnlyHint=false (so the agent knows it's a write operation), the description adds no information about what happens on creation (e.g., whether it affects inventory, requires specific account settings, or if it triggers any side effects). For a mutation tool, this is insufficient.

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

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

The description is a single, concise sentence that front-loads the primary action. It wastes no words and is easily scannable. However, it could have been slightly more informative without losing conciseness.

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

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

The tool involves a nested object parameter ('entity') and has no output schema, but the description doesn't explain what response to expect or any validation constraints. It also doesn't mention required fields within the entity object (though that's partly covered in the schema description, but not fully). Given the complexity of QuickBooks entities, the description is thin and omits important context like what constitutes a valid refund receipt.

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

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

The input schema provides detailed descriptions for both parameters. The 'entity' parameter is well-explained, including what to include or exclude (government identifiers, birth dates, etc.) and naming the DepositToAccountRef field. The 'company' parameter is also adequately described. Because schema coverage is 100%, the description itself doesn't need to add much, but the schema's rich descriptions 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 the verb and resource ('Create a refund receipt in QuickBooks Online'). It is specific and distinct from tools like create_sales_receipt or create_credit_memo by naming the specific receipt type. However, it doesn't explicitly differentiate it from the sibling create_sales_receipt, which might be confused, but the name itself is clear.

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

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

No guidance is provided on when to use this tool versus alternatives like create_sales_receipt or create_credit_memo. The description doesn't mention any prerequisites, such as having an existing customer or the appropriate permissions. An agent would have to infer usage from the tool name and context.

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

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

Annotations already indicate this is a mutating operation (readOnlyHint=false, destructiveHint=false), and the description merely restates that by saying 'Create'. It adds no detail about side effects, required permissions, idempotency, or how the created receipt is returned, so it contributes no behavioral transparency beyond structured data.

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, efficient sentence with no filler, and the key verb and resource are front-loaded. While very short, it is structurally clean and easy to parse.

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

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

For a tool with a nested entity and many create_* siblings, the description is too sparse to be contextually complete: it does not mention the document type's typical use, what happens after creation, or any relationship to send_sales_receipt. The structured schema fills parameter details, but selection context and workflow are missing.

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

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

Schema description coverage is 100% and the entity property is richly documented in the schema, including the warning about government identifiers. The tool description adds no parameter-level meaning of its own, so the baseline score of 3 applies.

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

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

The description clearly identifies the operation as creating a sales receipt in QuickBooks Online, giving a specific verb and resource. However, it makes no reference to sibling tools like create_invoice or create_credit_memo, so it does not help an agent distinguish when a sales receipt is the right document type.

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

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

The description provides no guidance on when to choose this tool over alternatives such as create_invoice, create_credit_memo, or create_refund_receipt, nor any prerequisites or exclusions. The only usage signal is the tool name itself, which is not enough for correct selection.

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

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

The description discloses useful behaviors beyond the annotations (paused, no QuickBooks write, preview mode, returns configuration for review). However, it states 'Creating a task does not start it' without qualification, yet the run_now parameter can start the loop immediately. This overgeneralization is misleading and could cause an agent to ignore run_now when the user asks for work now. The annotations (readOnlyHint=false, destructiveHint=false) do not contradict, but the internal inconsistency reduces 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 six sentences, each carrying meaningful information: purpose, suitability, internal behavior, return value, safety, and preview mode. It is front-loaded with the main purpose and avoids fluff, though the final two sentences could be tightened. Overall, it is efficient for the amount of context it provides.

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 return value ('Returns the saved task and its proposed configuration') and safety, which helps given there is no output schema. However, the absolute claim that creating a task does not start it conflicts with the run_now parameter, leaving a gap for agents handling immediate-execution requests. It also doesn't elaborate on when company selection is needed, though the schema covers that. These gaps prevent full 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?

The input schema already provides 100% coverage with parameter descriptions, so the baseline is 3. The description adds semantic value by framing the sentence as the user's own words and language, and by explaining the loop is paused and returns a configuration for review. This extra context helps an agent understand the intent behind the parameters, especially sentence and run_now.

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

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

The description states a specific verb and resource: 'Create a paused bookkeeping loop from a user-requested task'. It also explicitly distinguishes this tool from the many sibling create_* tools for QuickBooks entities by noting it does not write to QuickBooks. The title 'Create a task or a standing loop' further clarifies it handles both one-off and recurring work, making its purpose unmistakable.

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

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

The description gives a clear when-to-use signal: 'Suitable for recurring work on a schedule or after documents reach the Caribooks document box.' It also implies safety constraints (paused, no QuickBooks write, preview mode). However, it does not explicitly name alternatives like activate_loop or mention run_now as the path for immediate execution, and it lacks an explicit 'when not to use' against other create_* tools, though the loop concept is distinct enough.

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

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

Even though destructiveHint=true already signals destructiveness, the description adds valuable behavioral context: creating a tax agency cannot be undone and automatically creates payable and suspense accounts that can never be deleted. It also warns against sending government identifiers, birth dates, and card-processing details, which is critical safety information beyond the annotation.

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

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

The main description is a single efficient sentence, and the parameter descriptions pack important warnings into a compact, front-loaded structure. Every sentence earns its place without repetition or filler.

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

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

The definition covers the irreversible consequences, sensitive data exclusions, and the one required complex object. It does not describe the return value, but there is no output schema and the safety-critical context is sufficiently complete for an agent to invoke the tool responsibly.

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 thoroughly, including the entity object shape and the optional company field. The tool description itself adds no parameter-level semantics, so the baseline of 3 is appropriate.

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

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

The description names a specific verb and resource: 'Create a tax agency in QuickBooks Online.' It is clear and unambiguous about the core action. However, it does not explicitly differentiate from the sibling create_tax_service, so an agent must infer the distinction from the resource name.

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

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

The only usage guidance is buried in the entity parameter: 'Only create one when the user has asked for it.' This implies the tool should not be used casually, but there is no explicit mention of when to prefer search_tax_agencies/get_tax_agency or how to distinguish this from create_tax_service.

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

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

Annotations already mark this as destructive, and the description reinforces that with 'Cannot be undone' and 'only on an explicit request.' This adds meaningful behavioral context beyond the generic destructiveHint flag. No contradiction with annotations.

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

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

Two sentences, both purposeful. The core action is front-loaded and the irreversible side effect and authorization condition are stated immediately afterward with no filler.

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

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

For a create operation with a nested object, the entity schema supplies the necessary structural detail, and the description supplies the key caveats: irreversibility and explicit-request-only usage. It does not describe the return value, but no output schema exists and this gap is minor for a create action.

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 entity parameter is richly documented, including privacy restrictions, required fields, and inactive-vs-delete semantics. The tool description itself does not need to add parameter detail, so the baseline of 3 applies.

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

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

The description states a clear verb and resource: 'Create a sales tax code in QuickBooks Online, with new or existing tax rates attached to it.' This differentiates it from the sibling create_tax_agency and from read-only tax tools like get_tax_code and search_tax_codes.

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

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

The description gives clear context for when invocation is appropriate: 'only on an explicit request' and 'Cannot be undone.' It lacks an explicit mention of alternatives, but the purpose is unambiguous enough that an agent can decide when 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?

Annotations already signal a write operation (readOnlyHint: false) and non-destructive intent (destructiveHint: false). The description adds little beyond restating the mutation: it does not mention persistence, side effects, validation behavior, or any other operational traits that the annotations do not already cover. There is no annotation contradiction.

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

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

The description is very short and free of filler, but it is under-specified to the point of being barely informative. It is concise but not well-rounded; it earns its place only as a minimal restatement of the tool's name.

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

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

With no output schema and an open nested object parameter, the agent needs more context about what a Term contains and what a successful creation returns. The description does not provide that context, nor does it reference related tools like get_term or update_term that could help. It is incomplete for a tool that creates a domain-specific object.

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

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

Schema description coverage is 100%, and the schema provides robust parameter detail: the entity is described as a 'QuickBooks Online API v3 Term object' with explicit warnings about sensitive data, and the company parameter is explained. The tool description itself adds no parameter meaning, but the schema carries the burden adequately.

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

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

The description states a clear verb and resource: 'Create a term in QuickBooks Online.' It unambiguously identifies the target resource, distinguishing it from sibling create_* tools. However, it does not explain what a QBO 'term' actually is, leaving some ambiguity for an agent unfamiliar with QuickBooks terminology.

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

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

The description gives no guidance on when to use this tool versus alternatives such as update_term, get_term, or search_terms. There is no context about prerequisites, exclusions, or conditions that would help an agent select this tool over a sibling. The usage context is only implied by the verb 'create.'

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the agent knows this is a mutating but non-destructive operation. The description adds no behavioral context beyond that – nothing about side effects, required related entities, permissions, or rate limits. Since it discloses nothing beyond what annotations already convey, it earns a low score without constituting a contradiction.

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

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

The description is a single, front-loaded sentence with zero wasted words. It efficiently states the core operation and the system context. It is slightly too terse to earn a 5, as it omits any additional value-add, but it is well-structured for its brevity.

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 creation tool with a nested entity object and no output schema, the description is minimal. The schema compensates with rich parameter documentation, but the description itself does not mention prerequisites (e.g., existing employee/vendor), the NameOf distinction, or what a successful response contains. This is adequate for basic selection but leaves gaps for correct invocation.

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

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

Schema description coverage is 100%, so the schema fully documents both parameters: entity (with detailed guidance on TimeActivity structure and sensitive-field restrictions) and company. The description adds no parameter-level meaning, but because the schema carries the burden, the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource ('Create a time activity in QuickBooks Online'), which clearly identifies the operation and the object type. It is distinguishable from sibling tools like update_time_activity or get_time_activity by the verb and resource. However, it does not explicitly call out sibling alternatives, so it falls short of a 5.

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

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

The description provides no guidance on when to use this tool versus alternatives, such as update_time_activity for modifying existing entries or search_time_activities for retrieval. There are no prerequisites, exclusions, or context to help the agent decide. The only implied usage is the literal meaning of 'create'.

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

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

The description adds a key behavioral fact beyond the annotations: that the tool creates an accounting entry rather than moving money. This is crucial because the name alone might suggest a bank transfer. The annotations already indicate a non-read-only, non-destructive write operation, so the description's contribution is valuable but not comprehensive (e.g., no mention of permissions or side effects).

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

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

The description is short and front-loaded with the main action. The three sentences each add essential information: what it does, what kind of entry it is, and what it does NOT do. There are no wasted words, though it could be slightly more compact by merging the first two sentences.

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

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

The description, combined with the schema, provides enough information for an agent to invoke the tool correctly. It covers the crucial non-obvious behavior (not moving money) and the schema covers parameter constraints. It omits any mention of permissions or the response format, but for a simple create operation with full schema coverage, 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?

The input schema has 100% description coverage, with detailed documentation of the entity object (required FromAccountRef, ToAccountRef, Amount; accounts must differ) and the company parameter. The tool description adds no additional parameter-level information, so it relies fully on the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the action ('Create') and resource ('transfer in QuickBooks Online'), and adds a clarifying definition ('An accounting entry recording a transfer between accounts'). It explicitly distinguishes itself from actual bank transfers, which is a common source of confusion and helps differentiate it from other tools. This is a specific, unambiguous purpose statement.

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

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

The description includes an explicit exclusion: 'It does not move money between bank accounts.' This tells the agent when NOT to use this tool and implies the tool is for accounting entries only. However, it doesn't name a specific alternative tool for actual bank transfers, so the guidance is clear but incomplete.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description correctly implies a mutation. It adds important context about not sending government identifiers and managing those fields directly in QuickBooks, which is valuable beyond annotations.

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

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

The description is a single, direct sentence with no wasted words. The crucial note about government identifiers is left to the schema, but the description itself is appropriately terse.

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 simplicity (2 params, no output schema) and the rich schema descriptions, the description is complete enough for an agent to use it. However, it lacks any note about prerequisites like company connectivity, which might be inferred from the schema but could be more explicit.

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

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

The schema provides full descriptions for both parameters, including the structure of the 'entity' object and the 'company' parameter. The description adds no additional parameter-level information, so the baseline of 3 applies.

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

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

The description clearly states the action (create) and resource (vendor) in QuickBooks Online. It is distinct from siblings like create_customer or create_bill, but doesn't explicitly differentiate from create_vendor_credit, which is a related but different 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 implies usage for creating a vendor but doesn't provide context on when to prefer this over create_vendor_credit or other vendor-related tools. No explicit exclusions or alternatives are mentioned.

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

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

The description adds no behavioral context beyond what the annotations already convey: it simply says 'Create,' matching the readOnlyHint=false annotation. It does not disclose side effects on accounting records, whether the operation is reversible, idempotency, or error conditions. No contradiction with annotations exists.

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

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

The description is a single, clear sentence with no filler. It communicates the essential operation and platform efficiently, and every word contributes to the meaning.

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

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

For a simple create operation with a detailed input schema, this is minimally adequate. The description lacks usage guidance, expected return behavior, and side-effect awareness, but the schema covers the critical entity details. Given no output schema and a nested object parameter, more context would help an agent invoke it correctly.

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

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

The tool description provides no parameter-level meaning, but the input schema has 100% coverage and already describes the VendorCredit entity and the optional company parameter. The entity schema adds useful context about prohibited sensitive fields, so the baseline of 3 is appropriate.

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

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

The description clearly states the operation: 'Create a vendor credit in QuickBooks Online.' It identifies a specific verb and resource and adds the platform context. However, it does not differentiate this tool from related create tools like create_credit_memo or create_bill, so it stops short of full differentiation.

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

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

There is no guidance on when to use this tool versus alternatives, no prerequisites (e.g., vendor must exist), and no mention of related read/update/delete operations. An agent must infer usage solely from the tool name and generic create pattern.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is covered. The description adds valuable behavioral context by stating the deletion is permanent and that explicit user confirmation is required. This goes beyond the structured annotations.

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

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

Two sentences, each earning its place: one states the action and scope, the other the required confirmation. There is no redundancy or filler.

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

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

For a simple destructive operation with a rich sibling list and clear annotations, the description is sufficient. It communicates irreversibility and the safety requirement. It could mention what happens to associated file relationships, but this is not essential for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, so all parameters are already documented. The description reinforces that confirmation must be provided but does not add new parameter details. Baseline 3 is appropriate since the schema carries the semantic burden.

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

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

The description states a specific action ('Permanently delete'), a specific resource ('an attachable'), and the system ('QuickBooks Online'). The word 'permanently' disambiguates from update or detach operations. It clearly distinguishes this from siblings like create_attachable, update_attachable, and search_attachables.

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 makes clear what the tool does and that it deletes (not creates or updates) an attachable, so usage context is implied. However, it does not explicitly state when not to use it or name alternatives such as update_attachable for reversible changes. Guidance is adequate but not explicit.

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

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

Annotations already mark destructiveHint=true and readOnlyHint=false. The description adds value by stating 'Permanently delete' and 'Requires explicit user confirmation', which are behavioral traits beyond the annotations. There is no contradiction.

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

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

The description is a single, front-loaded sentence that states the action and the key prerequisite. Every word earns its place with no redundancy.

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

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

For a simple deletion tool with a fully documented schema and no output schema, the description provides sufficient context: it names the action, the target, and the confirmation requirement. No critical information is missing for an agent to call it correctly.

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

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

Schema description coverage is 100%, so all parameters (id, company, confirm) are already documented. The description does not add extra semantics beyond what the schema provides, so the baseline of 3 applies.

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

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

The description clearly states the verb 'delete', the resource 'bill', and the system 'QuickBooks Online'. It is specific enough to distinguish from other delete_* tools (e.g., delete_bill_payment, delete_credit_memo) by explicitly naming 'bill'.

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

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

The description includes the usage requirement 'Requires explicit user confirmation', which tells the agent when it is appropriate to invoke the tool. It does not explicitly contrast with alternatives, but given the resource-specific naming and the presence of many delete tools, the intended use case is clear.

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

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

Annotations already flag destructiveHint=true, but the description adds meaningful behavioral context: the deletion is permanent and requires explicit user confirmation. This tells the agent this is irreversible and gated on user consent, going beyond the annotation alone.

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

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

Two short sentences with no filler. The primary action and key safety requirement are front-loaded, and every word earns its place.

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

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

For a simple, destructive operation with three well-documented parameters, the description is nearly complete. It conveys irreversibility and the confirmation safeguard; only minor details about response behavior or effects on related records are omitted.

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 id, company, and confirm. The description's confirmation requirement reinforces the confirm parameter but does not add meaning beyond what the 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 states a specific verb and resource: 'Permanently delete a bill payment from QuickBooks Online.' The word 'permanently' also helps distinguish this from the sibling void_bill_payment, making the tool's purpose immediately clear.

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

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

The description conveys that this is for permanent deletion and requires explicit user confirmation, which implies appropriate usage. However, it does not explicitly compare against alternatives like void_bill_payment or state when one should be preferred over the other.

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

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

Annotations already declare destructiveHint=true, and readOnlyHint=false, establishing the operation as destructive. The description adds the important behavioral details that the deletion is permanent and requires explicit user confirmation, which goes beyond the annotation. There is no contradiction with the annotations.

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

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

The description consists of two tight sentences with no filler. The first sentence front-loads the core action and resource, and the second adds a critical safety prerequisite. Every word earns its place.

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

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

For a straightforward delete operation with fully documented parameters and a destructiveHint annotation, the description is complete. It conveys the essential context: permanence, the need for explicit consent, and the target system. The absence of an output schema is acceptable because delete operations typically don't require return-value documentation.

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 fully documents all three parameters (id, company, confirm) with 100% coverage, so the baseline is 3. The description's mention of 'explicit user confirmation' mirrors the confirm parameter's schema description but adds no new parameter semantics. The description does not elaborate on id or company beyond the schema.

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

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

The description states a specific verb ('delete'), resource ('budget'), and system ('QuickBooks Online'), with the key qualifier 'permanently'. This clearly distinguishes it from sibling delete tools and from update_budget. The confirmation requirement adds further semantic precision.

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

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

The description provides a clear usage context: use when a budget must be permanently removed, and only after explicit user confirmation. It does not explicitly name alternatives like update_budget for non-destructive changes, but the confirmation prerequisite and the delete semantics make the intended use unambiguous.

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

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

Annotations already indicate destructiveHint: true and readOnlyHint: false, so the safety profile is known. The description adds useful behavioral nuance beyond that: 'Existing transaction references remain intact' and the requirement for explicit user confirmation. It does not contradict the annotations.

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

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

Three short sentences with no filler. The core action is front-loaded, and each sentence earns its place: what it does, a key behavioral consequence, and the required precondition.

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 three-parameter deletion tool, the description covers the action, the key behavioral effect on existing references, and the required user confirmation. No output schema exists, so return-value details are not described, but that is not a significant gap for this operation.

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

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

Schema description coverage is 100%, so all three parameters are already documented. The description's confirmation requirement is largely redundant with the schema's confirm parameter description ('Must be true. Only set after the user has explicitly confirmed this deletion.'). Thus the description adds little 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 identifies a specific action ('Deactivate a company currency') and a specific resource, clearly distinguishing this tool from siblings like create_company_currency, get_company_currency, search_company_currencies, and update_company_currency. 'Deactivate' also clarifies the semantic difference from a hard delete.

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

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

The description states the core use case and adds a critical precondition: 'Requires explicit user confirmation.' It does not explicitly enumerate when to avoid using it or name alternatives, but the operation is distinct enough from sibling tools that 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?

Annotations already declare destructiveHint=true, but the description adds the crucial context that deletion is permanent and requires explicit user confirmation. This goes beyond the annotation by informing the agent of irreversibility and the need for human consent, which is vital for a destructive 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 a single sentence that conveys the core action, scope, and critical prerequisite (confirmation) with no unnecessary words. It is front-loaded with the verb and object.

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

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

For a destructive delete operation, the description covers permanence and confirmation, and the schema covers all parameters. It does not mention cascading effects or prerequisites (e.g., whether the transaction must be voidable first), but given the annotations and simple parameter set, this is largely sufficient. The lack of an output schema is not an issue here.

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

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

The schema already provides full descriptions for all three parameters (100% coverage), including the confirm flag's requirement to be true. The tool description reinforces the confirmation requirement but does not add new meaning beyond the schema. Baseline of 3 is appropriate given high schema coverage.

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

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

The description states a specific action (permanently delete) on a specific resource (credit card payment txn) within QuickBooks Online, which clearly distinguishes it from other delete tools for different entities. The addition of the confirmation requirement further clarifies the scope.

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

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

The purpose is clear, and the resource type is unambiguous. However, it does not explicitly mention alternatives or exclusions, though the name and description make it evident this tool is for credit card payment transactions only. There is no need to list every other delete tool, but a note like 'for other transaction types, use the corresponding delete tool' would be explicit. It's adequate but not fully explicit.

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

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

Annotations already mark this as destructive and non-read-only, and the description consistently reinforces this with 'permanently delete' and 'requires explicit user confirmation.' It adds context beyond the annotations by emphasizing irreversibility and the need for consent, though it does not detail cascade effects or recovery limitations.

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 short sentences with no filler. The core action and the critical confirmation requirement are front-loaded, and every sentence adds value.

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

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

For a destructive tool with no output schema, the description provides the essential behavioral facts: permanent deletion, target system, and user-confirmation requirement. It could mention side effects or prerequisites for deletion, but the annotations plus description cover the main safety-critical 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%, so the parameters (id, company, confirm) are already fully documented. The description adds no new parameter-level meaning beyond restating the confirmation requirement already present in the confirm field.

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

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

The description states a specific verb ('delete'), resource ('credit memo'), and system ('QuickBooks Online'), clearly distinguishing it from sibling delete_* tools like delete_invoice or delete_vendor_credit. The word 'permanently' adds important scope beyond the title.

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

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

No guidance is given about when to choose this tool versus alternatives such as voiding, updating, or searching credit memos. The only condition mentioned is explicit user confirmation, which is a prerequisite rather than a usage-vs-alternative guideline.

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

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

Annotations already signal destructiveHint=trueaine, but the description adds meaningful context by emphasizing that deletion is permanent and requires explicit user confirmation. This goes beyond the annotation's binary destructive flag and helps the agent treat the operation as irreversible.

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 short sentences with no wasted words. The core action is front-loaded, and the safety-critical confirmation requirement is stated immediately afterward.

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 operation, the essential contextual information is the permanence of the action and the need for user confirmation, both explicitly stated. With full schema coverage for parameters and destructiveHint annotations, nothing else is needed 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 description coverage is 100%, so the input schema already documents all three parameters. The description reinforces the confirm requirement but does not add new meaning beyond what the schema 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 states a specific verb and resource: 'Permanently delete a deposit from QuickBooks Online.' This clearly distinguishes delete_deposit from the many other delete_* siblings and identifies both the target entity and the system.

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

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

The description clearly communicates the key usage precondition: 'Requires explicit user confirmation.' This gives the agent actionable guidance about when it is appropriate to invoke the tool, though it does not name alternatives or explicitly state when not to use it.

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

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

The annotations already declare destructiveHint=true, so the description's 'permanently delete' reinforces that. But the description adds critical behavioral context: the deletion is permanent (irreversible), and explicit user confirmation is required. This is exactly the kind of high-stakes behavior an agent needs to know before invoking. It also implies real-world consequences (data loss) that annotations alone don't convey. No contradiction with annotations; the description aligns with destructiveHint=true.

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

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

Two sentences with no filler. The most important facts — permanent deletion and user confirmation — are front-loaded. Could potentially add more behavioral context, but for what it contains, it's efficient 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?

The description is complete enough for a destructive operation: it states permanent deletion and the confirmation requirement. The output schema is absent, but for a delete operation the return value is usually a success indicator, which the agent can infer. The sibling list includes void_* tools (void_bill_payment, void_invoice, void_sales_receipt) which are alternative non-permanent operations, and the description doesn't explicitly guide the agent to them; that's a minor gap but not critical for a permanent delete tool.

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

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

Schema description coverage is 100% — the schema already thoroughly documents 'id' as the QuickBooks Id, 'company' as which connected company, and 'confirm' as must be true. The description doesn't add much parameter-level meaning beyond the schema. The 'require explicit user confirmation' in the description adds slight emphasis to the 'confirm' parameter's importance, but the schema already covers it. Baseline 3 is appropriate when schema does the heavy lifting.

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

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

The description states a specific verb ('permanently delete'), a specific resource ('an estimate from QuickBooks Online'), and includes the key requirement of explicit user confirmation. The title is just 'delete estimate', but the description adds the permanent, irreversible nature and the QuickBooks context, making the tool's purpose unambiguous. The sibling list includes many delete_* tools, but the description names the exact resource (estimate), which distinguishes it from delete_bill, delete_invoice, etc.

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

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

The description says the delete is permanent and requires explicit user confirmation, which gives clear guidance on when NOT to call it (without user confirmation) and implies it should only be used after user consent. It doesn't name an alternative (e.g., void vs delete), but the context signals are clear enough — this is a permanent delete, versus void_* siblings which might be the non-permanent alternative. The 'requires explicit user confirmation' is a strong usage guideline even though it doesn't enumerate alternatives.

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

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

Annotations already mark destructiveHint=true, and the description adds value by stating the deletion is permanent and that explicit user confirmation is required. This extra context reinforces the confirm parameter's role and warns the agent that the action is irreversible, which is important behavioral guidance beyond the annotation alone.

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

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

Two short sentences, both informative and front-loaded. The first names the operation and its scope; the second provides the critical safety condition. There is no filler or repetition.

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

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

For a simple single-entity delete tool with 100% schema coverage, destructive annotation, and no nested objects, the description covers the essential operational and safety context. It could add detail about what the response contains or how to confirm success, but the tool is simple enough that this is not a critical 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 all three parameters (id, company, confirm) are already documented in the schema. The description's statement that the action 'Requires explicit user confirmation' aligns with the confirm parameter but adds little new semantic meaning beyond what the schema already states.

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

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

The description states a specific verb ('delete'), a specific resource ('inventory adjustment'), and the target system ('QuickBooks Online'), and makes the destructive nature explicit with 'Permanently'. This clearly distinguishes it from the many sibling delete_* tools, which act on different resources.

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

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

Usage is implied: use this tool when the user wants to delete an inventory adjustment. However, the description does not explicitly say when not to use it or mention any alternative such as void_inventory_adjustment or get_inventory_adjustment for verification. The confirmation requirement hints at the decision gate but does not provide deeper routing guidance.

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

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

Annotations already declare destructiveHint: true and readOnlyHint: false, so the destructive nature is covered. The description adds 'Permanently' and 'Requires explicit user confirmation,' which go beyond the annotation flags. This informs the agent that the deletion is irreversible and requires explicit user consent, adding meaningful 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 extremely concise, consisting of two short sentences with no unnecessary words. It front-loads the core action and includes the critical requirement of confirmation. 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 delete tool with a simple schema and no output schema, the description is adequate but not complete. It omits any mention of alternatives (like void_invoice) or potential side effects on linked records. Given the destructive nature and the existence of a void alternative, the description could be more informative. It meets the minimum viability but leaves gaps.

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

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

Schema description coverage is 100%, so all three parameters (id, company, confirm) have their own descriptions. The tool description does not add any additional parameter semantics beyond what the schema already provides. Baseline of 3 is appropriate because the schema carries the full burden.

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

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

The description clearly states the verb 'delete' and the resource 'invoice', and adds 'Permanently' to convey irreversibility. This distinguishes it from the sibling void_invoice, which likely voids rather than deletes. The purpose is unambiguous and specific.

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

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

The description does not provide guidance on when to use this tool versus alternatives. It does not mention void_invoice or update_invoice as alternatives for less permanent actions. The only requirement mentioned is user confirmation, which is a precondition, not a usage guideline. No when-not or alternative routing is 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?

The description adds 'permanently delete' and 'requires explicit user confirmation,' which are meaningful behavioral traits beyond the annotations' destructiveHint and readOnlyHint. It reinforces irreversibility and user-consent requirements, though it does not mention potential side effects or permission prerequisites.

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

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

Two concise sentences front-load the core purpose ('Permanently delete a journal entry') and then state the confirmation requirement. No filler words or redundant information; every sentence earns its place.

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

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

For a simple deletion tool with full schema coverage and destructiveHint annotation, the description adequately covers purpose and key behavioral requirements. It does not explain return values or error behavior, but the lack of an output schema and the simplicity of the operation make this a minor gap.

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

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

Schema description coverage is 100%, so all three parameters (id, company, confirm) are already documented. The description's mention of explicit user confirmation essentially mirrors the schema's confirm parameter description and adds no additional parameter-specific meaning.

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

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

The description states the specific verb 'delete', the resource 'journal entry', and the system 'QuickBooks Online', with 'permanently' clarifying the destructive nature. This clearly distinguishes it from siblings like create_journal_entry, update_journal_entry, get_journal_entry, and search_journal_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?

No guidance is given on when to use this tool versus alternatives such as update_journal_entry for modifications or void operations for reversible actions. The only hint is the verb 'delete', which implies purpose but does not explicitly state selection criteria or exclusions.

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

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

Annotations already declare destructiveHint=true, and the description reinforces and extends this by stating the deletion is permanent and requires explicit user confirmation. It adds the human-consent guardrail beyond what the annotations alone convey, with no contradiction.

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

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

Two short, information-dense sentences. The core action is front-loaded, and the safety requirement follows immediately. Every word contributes to the agent's understanding.

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

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

For a destructive single-resource delete operation, the description, combined with full schema coverage, covers the essential facts: what is being deleted, that it is permanent, and that confirmation is mandatory. The lack of usage-vs-alternative guidance is the main 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%, and each parameter already has a clear meaning in the schema. The description's mention of explicit user confirmation aligns with the 'confirm' parameter but adds no new semantic detail beyond what the schema documents.

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

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

The description names a specific verb ('delete'), a specific resource ('a payment'), and a specific environment ('QuickBooks Online'). The word 'Permanently' distinguishes it from sibling tools like void_payment, and the payment resource distinguishes it from delete_bill_payment.

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

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

The description does not explain when to choose this tool over alternatives such as void_payment or search_payments. It mentions the confirmation requirement, but that is a safety prerequisite, not guidance about when this tool should be used versus its siblings.

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

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

Annotations already indicate destructiveHint: true, and the description adds 'Permanently delete,' which clarifies irreversibility beyond the annotation's generic destructiveness. It also states the confirmation requirement, adding behavioral context. This aligns with annotations and adds meaningful detail, so the description adds value beyond what annotations provide.

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

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

The description is two sentences, front-loaded with the primary action and scope, followed by the critical confirmation requirement. Every word contributes value; there is no redundancy or fluff.

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

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

For a simple delete operation with three parameters and no output schema, the description covers the essential purpose and a key prerequisite (confirmation). It does not specify return values, but that is not expected without an output schema. It is sufficiently complete for an agent to invoke correctly, though it could mention the irreversibility explicitly (it does via 'permanently').

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 each parameter (id, company, confirm) is documented. The description mentions 'explicit user confirmation,' which reinforces the confirm parameter but does not add new semantic meaning for id or company. The baseline for 100% coverage is 3, and the description provides marginal additional context about 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 states a specific verb and resource: 'Permanently delete a purchase from QuickBooks Online.' This is precise, identifies the target entity (purchase), and includes the scope (QuickBooks Online). It clearly distinguishes from other delete_* tools by naming the resource type, so an agent can select it without 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?

The description gives one key prerequisite: 'Requires explicit user confirmation.' This is a clear condition for usage. However, it does not provide guidance on when to use this tool versus alternatives (e.g., void vs. delete for other entities) or mention any exclusions. The usage context is implied by the purpose, but not explicitly differentiated from siblings.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, and the description adds that the deletion is permanent and requires explicit user confirmation. This is valuable behavioral context beyond the structured annotations, and there is no contradiction with destructiveHint.

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

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

The description is two short sentences with no filler. The core action and target are front-loaded, and the confirmation requirement is stated immediately after, so an agent can parse the essential information quickly.

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

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

For a simple three-parameter destructive tool with fully documented parameters and a destructiveHint annotation, the description provides everything needed to select and invoke it: the action, resource, platform, permanence, and required user confirmation. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema description coverage is 100%, so id, company, and confirm are already fully explained in the schema. The tool description's mention of user confirmation mirrors the confirm parameter's schema description but adds no new parameter-level detail, so the 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 names a specific verb, a concrete resource ('a purchase order'), and the platform ('QuickBooks Online'), so there is no ambiguity about the operation. The resource is named exactly as in the tool, which distinguishes it from sibling delete tools for other object types.

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

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

It clearly implies when the tool is appropriate: when a purchase order must be permanently removed in QuickBooks Online. The explicit-confirmation requirement is a concrete precondition that tells the agent to gate the call on user approval. It does not explicitly contrast with alternatives, but the resource-specific name makes the primary alternative choice obvious.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description is not burdened by stating basic safety. It adds valuable behavioral context by emphasizing permanence and requiring explicit user confirmation, which are important for an irreversible mutation.

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 short, direct sentences with no filler. The key information (permanence and confirmation requirement) is front-loaded and every clause earns its place.

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

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

For a simple destructive operation with full schema coverage and strong annotations, the description captures the essential prerequisites (permanence, user confirmation). It does not describe success/error outcomes, but no output schema exists and the operation's core behavior is sufficiently communicated.

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

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

Schema description coverage is 100%, so the schema fully documents id, company, and confirm. The description's mention of 'explicit user confirmation' reinforces the confirm parameter's requirement, but it does not add new parameter-level meaning beyond what the schema already provides.

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

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

The description uses a specific verb ('delete') and resource ('recurring transaction from QuickBooks Online'), clearly distinguishing it from the many sibling delete_* tools. Adding 'Permanently' clarifies the operation's scope and irreversibility.

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

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

The description clearly states the operation targets a recurring transaction and that explicit user confirmation is required before deletion. However, it does not explicitly mention alternatives (e.g., deactivating rather than deleting, or using search/get tools first) or give when-to-use versus when-not-to-use guidance among the sibling tools.

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

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

Annotations already signal destructiveHint=true and readOnlyHint=false. The description adds valuable context beyond the annotations: the deletion is permanent and requires explicit user confirmation. This enriches the safety profile for the agent without contradicting the structured hints.

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

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

Two short sentences with zero filler. The action is stated first, followed by the key safety constraint. Every word earns its place, making it easy to parse quickly.

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

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

For a simple tool with full schema coverage, destructive annotations, and no output schema, the description covers the essential operational facts: permanent deletion, the entity, and the confirmation requirement. Nothing needed for correct invocation is missing.

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

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

Schema coverage is 100%: id, company, and confirm all have descriptive text in the schema. The description adds no additional parameter-level meaning, so the baseline of 3 is appropriate.

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

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

Description uses a specific verb ('delete') and resource ('refund receipt') and adds the critical qualifier 'permanently'. This clearly distinguishes the operation from send/void/update variants and makes the tool's purpose unambiguous even without opening the schema.

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 states the core condition for use: the user must have explicitly confirmed deletion. It also communicates that this is a permanent removal. However, it does not explicitly name alternatives (e.g., voiding) or state when not to use the tool, so it falls short of full exclusion guidance.

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

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

Annotations already declare destructiveHint=true, so the description adds value by specifying 'permanently' and emphasizing 'requires explicit user confirmation'. This goes beyond the annotation by disclosing the irreversibility and the confirmation requirement, which is not captured elsewhere. No contradiction with annotations.

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

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

The description is two sentences with no redundant information. The action and key constraint (permanence and confirmation) are front-loaded. Every word earns its place.

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

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

The description is adequate for a simple delete operation given the annotations and full schema coverage. However, it lacks any reference to the alternative void_sales_receipt and does not explain the consequences of deleting (e.g., impact on linked transactions). This is a notable gap for a destructive action with a closely related sibling.

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

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

The schema provides 100% description coverage for all parameters, so the description adds little beyond that. The phrase 'explicit user confirmation' hints at the confirm parameter but does not elaborate on its semantics beyond what the schema already states. This meets the baseline for well-documented schemas.

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

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

The description clearly states the verb 'delete' and resource 'sales receipt', and adds 'permanently' to indicate severity. However, it does not explicitly distinguish from the sibling void_sales_receipt, which is a common alternative for sales receipts. The purpose is clear but lacks explicit differentiation.

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

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

The description provides no guidance on when to use this tool versus alternatives like void_sales_receipt. It only states a requirement (explicit user confirmation) but does not explain the conditions under which deletion is appropriate or when voiding is preferred. There is no mention of alternatives or exclusions.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds value by specifying that deletion is permanent and requires explicit user confirmation, which goes beyond the mere destructive hint and clarifies the irreversible nature of the 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?

Two short sentences, no filler. The primary action is front-loaded, and the confirmation requirement is stated immediately. Every word earns its place.

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

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

For a delete tool with annotations and fully described parameters, the description covers the essential behavior: what is deleted, that it is permanent, and that confirmation is required. It does not explain return values, but no output schema exists and it is not critical for a delete operation. It is adequate but could mention potential side effects, though 'permanently' largely covers that.

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 three parameters, so the baseline is 3. The description does not add extra meaning beyond the schema; it simply reiterates the confirmation requirement, which is already documented in the confirm parameter description.

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

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

The description states a specific verb ('delete'), a specific resource ('time activity'), and the context ('from QuickBooks Online'). It also adds 'Permanently' and 'Requires explicit user confirmation,' which distinguishes it from update or void operations and from sibling tools like update_time_activity and create_time_activity.

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 (when you want to permanently delete a time activity) and includes a precondition ('Requires explicit user confirmation'), but it does not explicitly compare with alternatives or state when not to use it. There is no mention of when to prefer delete over update or void, so guidance is only implied.

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

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

Annotations already mark destructiveHint=true and readOnlyHint=false, and the description adds meaningful beyond-annotation context by stating the deletion is permanent and requires explicit user confirmation. This gives the agent crucial operational framing without contradicting the annotations.

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

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

The description consists of two short sentences with no filler. The core behavior and the critical confirmation precondition are front-loaded, and every word contributes to the agent's ability to invoke the tool safely.

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 three-parameter destructive operation, the description, combined with the full schema coverage and annotations, is sufficiently complete. It covers the essential deletion semantics and the confirmation gate, though it does not describe success/failure response behavior since no output schema is present.

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

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

Schema coverage is 100%, with clear descriptions for id, company, and confirm. The description reinforces the confirmation requirement but adds no syntax, format, or parameter-specific details beyond what the schema already 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 states a specific action ('Permanently delete') on a specific resource ('a transfer from QuickBooks Online'), making the tool's purpose unmistakable. It distinguishes the tool from create_transfer, update_transfer, and search_transfers by focusing on deletion and permanence. No tautology or ambiguity.

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

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

The description implies the appropriate usage context: when a transfer must be permanently removed and the user has confirmed the action. However, it does not explicitly name alternatives or state when this tool should not be used. The confirmation requirement provides useful procedural context but not full alternative-routing guidance.

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

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

The destructiveHint annotation already marks the tool as destructive, and the description adds meaningful context beyond it: the deletion is permanent and requires explicit user confirmation. This gives an agent important behavioral information about irreversibility and the need for a confirmation step.

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 short sentences with zero wasted words. The primary action and permanence are front-loaded, and the confirmation requirement is stated immediately after.

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

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

For a simple destructive operation with three well-documented parameters and the destructiveHint annotation, the description is largely complete. It states the resource, permanence, and confirmation prerequisite; a fully complete description might also note that the deletion cannot be undone, but 'Permanently' already implies this.

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 each parameter already has a clear description, especially `confirm`, which states it must be true and only set after explicit user confirmation. The tool description itself adds no additional parameter-level meaning beyond what the schema already provides.

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

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

The description states a specific verb ('delete'), a specific resource ('vendor credit'), and a clear scope ('from QuickBooks Online'). The word 'Permanently' adds an important precision that distinguishes this destructive action from a void or reversible operation.

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

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

The description provides a clear, explicit prerequisite: this should only be invoked after the user has explicitly confirmed the deletion. It does not enumerate alternatives or exclusions, but the resource-specific naming and confirmation gate make the intended usage clear.

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

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

Beyond the destructiveHint annotation, the description discloses that removal is permanent, that the filing-history row is retained and marked discarded, and that user confirmation via confirm: true is required. This gives the agent meaningful behavioral context for a destructive 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?

Three sentences front-load the core action, then add use cases, the confirmation requirement, and the retention side effect. Every sentence contributes useful information with no filler.

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

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

For a simple two-parameter destructive tool, the description is complete: it explains what is removed, when to use it, what must be provided, and what residual record remains. The schema covers parameter source for upload_id, and no output schema is needed for this operation.

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

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

Schema description coverage is 100%, so the schema already documents both upload_id and confirm. The description repeats the confirm requirement but adds no parameter-specific detail beyond what the schema provides, so the baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Permanently remove a user-selected file from the Caribooks document box.' It also distinguishes itself from related flows by noting it happens 'without attaching it to QuickBooks' and by naming the intended cases: unwanted documents, duplicates, and unrelated files.

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

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

The description gives clear context for when to use the tool ('Intended for unwanted documents, duplicates and unrelated files') and the required approval gate ('Requires confirm: true after the user's approval'). It does not explicitly name alternatives or when-not-to-use conditions, so it stops short of a 5.

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

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

Annotations already mark this as read-only and non-destructive, and the description adds substantial behavioral detail: it compares against all attachments, returns compact rows with a specific field list, orders newest first, reports documented/undocumented counts, and truncates oversized windows from the oldest end. This goes well beyond the annotation baseline.

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-organized: purpose first, then methodology, output shape, a practical caveat, and truncation behavior. Every sentence adds distinct value and there is no redundant or fluffy wording.

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

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

Given that there is no output schema, the description compensates by enumerating returned fields, ordering, counts, and truncation behavior. It also warns about legitimate receipt-free categories. Combined with complete schema parameter docs and safety annotations, nothing essential is missing for an agent to invoke this 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?

The input schema already describes all four parameters with 100% coverage. The description adds only that 'from' and 'to' limit the date range, which is already implied by the schema descriptions. It does not introduce new parameter meaning, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: 'List purchases and bills with no document attached in QuickBooks.' It clearly distinguishes itself from sibling search tools like search_purchases and search_bills by focusing on missing attachments across two transaction types.

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 makes the tool's context clear: it is for finding expenses without receipts, and it adds a caveat that some categories may not require receipts. It does not explicitly name alternatives or say when not to use it, but the unique attachment-filtering purpose is evident from the description and name.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds no further behavioral context (e.g., auth requirements, error behavior, or return shape), but for a simple read-only get operation, it does not contradict the annotations. It meets the baseline but adds no extra value.

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

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

One concise sentence that is front-loaded with the verb and resource, then the identifier criterion. Zero waste, ideal structure for a simple get tool.

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

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

For a simple two-parameter read-only tool with full schema coverage and safety annotations, the description is complete. It could mention the return object explicitly, but that is implicit in a 'get' operation. Minor gap: no mention of not-found behavior, but that is likely handled by the platform. 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?

Schema description coverage is 100%, with both id and company already described. The description merely repeats 'by Id' without adding syntax, format, or interplay details beyond the schema. Per the rubric, baseline 3 applies when schema does the heavy lifting.

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

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

The description states a specific verb ('Get'), a specific resource ('account'), and a specific criterion ('by Id'), which clearly distinguishes it from sibling tools like get_account_list (list all) and search_accounts (search). No ambiguity about what this tool does.

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

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

The description implies the tool is used when you have a specific account Id, but it does not explicitly mention alternatives like get_account_list or search_accounts, nor when to avoid this tool. The distinction is inferable from the name and description, but not stated outright, so guidance is present but not explicit.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral detail beyond that: row types, depth, column alignment, label vs value id alignment, omission and counting of all-zero rows, filter confirmation semantics, and the no_data flag. This gives an agent an unusually clear model of what the tool returns and how it behaves.

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

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

The description is dense but every clause earns its place, covering purpose, output structure, edge cases, and behavioral nuances. It is front-loaded with the primary action and contains no filler or repetition of schema content.

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

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

With no output schema, the description fully compensates by detailing the return object, row semantics, id alignment, hidden-zero handling, filter confirmation, and no_data behavior. Combined with the input schema and annotations, an agent has everything needed to call the tool and interpret its response correctly.

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