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 already declare this is a non-read-only, non-destructive write operation. The description adds useful return context ('Returns the saved record with its SyncToken') but does not cover permissions, duplicate handling, or other behavioral traits beyond that.

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, front-loaded with the action and followed by the return value. There is no redundant or filler text.

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

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

For a create tool with rich schema coverage and annotations covering safety, the description supplies the essential action and return shape. It is mostly complete, though it omits routing guidance and any error or duplicate-behavior context.

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

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

Schema description coverage is 100%, and the schema itself explains the entity structure, AccountType requirement, sensitive-data warning, and optional company field. The description adds no parameter meaning beyond what the schema already 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: 'Create an account in QuickBooks Online.' The scope is clear, and the resource name distinguishes it from other create_* siblings such as create_customer 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 gives no when-to-use guidance, no alternatives, and no exclusions. It does not mention update_account, get_account, or search_accounts, so an agent must infer routing from the tool 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?

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 already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds one useful behavioral detail: it returns the saved record with its SyncToken, which matters for subsequent updates and deletes. However, it does not disclose validation errors, duplicate handling, or permission requirements.

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

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

The description is two short, front-loaded sentences with no redundant or filler content. The core operation is stated immediately, followed by the return value detail, which is efficient and easy to parse.

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

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

Given the tool's complexity (nested entity object) and the absence of an output schema, the description partially compensates by stating that the saved record and its SyncToken are returned. Yet it still lacks guidance on usage versus sibling create tools and omits behavioral context such as validation or side effects. With rich schema and annotations, this is adequate but with 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 schema itself documents both parameters thoroughly, including the complex entity object and company selection. The description adds no parameter-level meaning beyond what the schema provides, making the baseline 3 appropriate.

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

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

The description states a precise verb and resource: 'Create a bill in QuickBooks Online.' This clearly identifies the operation, but it does not differentiate the tool from other create operations like create_invoice, create_purchase_order, or create_journal_entry, so sibling ambiguity remains.

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 offers no guidance on when to use this tool versus alternatives such as create_invoice or create_purchase_order. It also omits prerequisites or context about when a bill is appropriate, leaving usage entirely implicit 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 declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so safety is partly covered. The description adds meaningful context beyond that: the operation has no external money-movement side effect and returns the saved record with its SyncToken, which is useful for follow-up update/void calls.

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

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

Three short sentences, zero filler, and the most decision-relevant fact (what it is not — no bank/card payment) is front-loaded before the return-value note.

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 exists, but the description compensates by stating the return shape (saved record with SyncToken). For a create tool with fully documented parameters and annotations, the remaining gap is minor; it could still note required permissions or whether the record can be edited afterward.

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

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

Schema description coverage is 100% and the schema itself is unusually rich, spelling out PayType, the matching account refs, and the LinkedTxn structure. The description adds nothing about parameters, so the baseline 3 applies.

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

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

States a specific verb and resource ("Create a bill payment") and immediately disambiguates from the crowded payment family by clarifying it is an accounting record that does not initiate a bank or card payment. That distinction is exactly what separates it from siblings 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 negative scoping ("does not initiate a bank or card payment") is an effective when-not cue and tells the agent this is not the tool for moving money. However, it never names the alternative tool to use instead for actual payment initiation, so routing is left partly to inference.

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 this as a non-read-only, non-destructive, closed-world write. The description adds genuine value beyond them by disclosing the return shape ('the saved record with its SyncToken'), which matters for chaining an update, and by reinforcing the one-entry-per-account-per-period constraint. It stops short of stating permission requirements or duplicate-budget behavior.

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

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

Three short sentences, each earning its place: the action, the shape constraint, and the return contract. Nothing is redundant and the core action 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 create tool with full schema coverage and a rich nested entity object, the description covers action, scope, and return value adequately; the SyncToken mention compensates for the absent output schema. What's missing is permission/precondition context and whether duplicate periods are rejected.

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 nested entity parameter is thoroughly documented in the schema itself, so baseline 3 applies. The description restates the ProfitAndLoss and one-entry-per-period constraints but adds no syntax or format detail 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?

States a specific verb and resource ('Create a budget in QuickBooks Online') and narrows scope with 'A profit-and-loss budget with one amount per account per period', which tells an agent exactly which budget shape this tool produces. It does not explicitly name sibling alternatives like update_budget or search_budgets, 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 create semantics make the primary usage self-evident, and the P&L-only constraint implicitly signals other budget types aren't creatable here. However there is no explicit when-to-use guidance, no note on whether a budget already exists for the period, and no pointer to update_budget for modifying an existing budget.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the agent knows this is a non-destructive write. The description adds that the saved record with SyncToken is returned, which is useful. It does not explain permissions, duplicate-name handling, or whether SyncToken is needed for subsequent updates.

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 waste. Purpose first, return value second.

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

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

For a write tool with a nested free-form entity object and no output schema, the description should clarify the entity shape or link to the Class object model, and mention that SyncToken must be preserved for later updates. The entity schema description is generic and mostly a compliance warning.

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 both parameters are documented in the schema. The description adds no detail about the entity structure or the company parameter beyond the return value note; 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?

States a specific verb and resource ('Create a class in QuickBooks Online') and notes the return value. It doesn't differentiate itself from siblings like search_classes or update_class, but 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 guidance on when to create a class versus searching existing ones or updating. No prerequisites such as the need for a connected company 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?

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the bar is lower. The description goes beyond them by disclosing the return payload ('the saved record with its SyncToken'), which matters because the SyncToken is needed for subsequent updates, and by repeating the multicurrency prerequisite.

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 the core action front-loaded and no filler. The middle sentence is a fragment ('The currencies the company transacts in; only meaningful with multicurrency enabled'), which is slightly awkward but costs no real clarity.

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

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

For a create tool with annotations covering safety, a fully described schema, and no output schema, the description is nearly complete: action, prerequisite, and return shape are all present. It could have noted required fields inside the free-form entity object or typical validation failures, but nothing essential is missing.

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

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

Schema description coverage is 100% and the entity schema already documents the QBO object, the Code field as ISO 4217, the multicurrency requirement, and the PII fields to omit. The description adds nothing parameter-specific beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Create a company currency in QuickBooks Online'), which cleanly separates it from update_company_currency, delete_company_currency and search_company_currencies. It does not name a sibling explicitly, but the create/read/update/delete split is unambiguous from the verb.

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 supplies one real precondition — 'only meaningful with multicurrency enabled' — which is genuine usage context. However it gives no when-not guidance and never points to update_company_currency or search_company_currencies as the alternative when the currency already exists.

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

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

Annotations already declare write/safe (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the bar is lower, and the description still adds real value: 'It does not move money' clarifies the semantic effect of the write, and 'Returns the saved record with its SyncToken' discloses the return shape despite there being no output schema. It does not cover permissions, idempotency, or duplicate 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?

Four short sentences, front-loaded with the action, then scope, then behavioral caveat, then return value. Every sentence carries distinct 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 mutation tool with a rich nested schema and no output schema, the description covers what it creates, its semantic effect, and its return value. Remaining gaps (required permissions, what happens on conflicting/duplicate records) are minor given the strong schema coverage and annotations.

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

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

Schema description coverage is 100%, so the nested entity object and company parameter are already fully documented in the schema, including the required TxnDate/Amount/BankAccountRef/CreditCardAccountRef fields. The description adds no parameter-level meaning beyond that, 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?

States a specific verb+resource ('Create a credit card payment txn in QuickBooks Online') and adds a semantic gloss — 'an accounting record of a bank payment toward a credit card balance' — that separates it from generic payment/transfer siblings. It stops short of naming the alternative tools (create_payment, create_transfer), so it is clear but not fully 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?

'It does not move money' implicitly tells the agent when this is appropriate (recording a payment vs. actually transferring funds), which is genuinely useful routing context. However there is no explicit when-to-use/when-not statement and no named alternatives, so guidance remains implied rather than 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 declare readOnlyHint=false and destructiveHint=false, so the agent knows this is a mutating but non-destructive operation. The description adds that it returns the saved record with its SyncToken, which is useful behavioral context. However, it does not mention required permissions, idempotency, or side effects, and the absence of destructiveHint=true is consistent with creating a new record.

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, front-loaded with the action and resource, followed by the return value. No wasted words or redundancy.

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

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

Given the complexity of creating a QuickBooks CreditMemo object (nested entity with many fields), the description is minimal. It lacks details about required fields, data validation, or how the entity object maps to QuickBooks API v3, though the schema covers some of this. No output schema exists, so the description's mention of the return value is helpful but not exhaustive. The definition is adequate but incomplete for a tool of 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 description coverage is 100%, so the schema already documents both parameters thoroughly. The description adds no parameter-specific details beyond what the schema provides. 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?

States a specific verb and resource ('Create a credit memo in QuickBooks Online'), which is clear enough to distinguish from siblings like update_credit_memo, get_credit_memo, or send_credit_memo. However, it does not explicitly name those siblings, 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?

Provides no guidance on when to use this tool versus alternatives (e.g., create_invoice, create_refund_receipt, create_vendor_credit), nor any prerequisites or contextual conditions. The agent must infer usage entirely from the name and sibling list.

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 mutation safety profile is covered. The description adds one genuinely useful behavioral fact beyond them — that the call returns the saved record including its SyncToken, which matters for subsequent optimistic-concurrency updates — but says nothing about duplicate handling, required fields, or failure behavior.

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

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

Two short sentences, front-loaded with the action and followed by the return-value note. Zero filler, though it is thin enough that it reads more like a label than a guide.

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

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

There is no output schema, and the description does cover the return value, which is the main gap it needed to fill. However, for a create tool whose payload is a free-form nested object with additionalProperties, it leaves out what happens on duplicate names, whether entity fields are validated, and which fields are practically required.

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

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

Schema description coverage is 100%, and the schema itself carries strong parameter semantics (the QuickBooks API v3 Customer shape, the PII prohibition on SSN/tax IDs/birth dates/card data, and the optional company selector). The description adds nothing on top of that, so the baseline 3 applies.

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

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

States a specific verb+resource ('Create a customer in QuickBooks Online'), which cleanly separates it from create_vendor, create_employee and the other create_* siblings by resource. It stops short of any explicit sibling routing, but the resource 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 on when to use this versus search_customers (to check for an existing customer first) or update_customer (for existing records). The agent must infer that creation is appropriate purely 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 declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the agent knows this is a contained write operation. The description adds one genuinely useful behavioral fact — that the call returns the saved record with its SyncToken — which matters because no output schema exists. It says nothing about permissions, validation failures, or duplicate 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?

Two sentences, zero filler, verb+resource front-loaded and the return-value note placed second. Nothing could be cut without losing information.

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

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

For a simple create tool whose entity shape is well specified in the schema and whose safety profile is covered by annotations, this is adequate but thin. It omits what happens on failure (duplicate names, invalid fields) and does not explain the optional company-selection parameter, which is the only piece of non-obvious behavior an agent might need.

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 parameters, including the nested 'entity' object with its data-privacy warning about SSNs, tax IDs, birth dates and card details, are fully documented in the schema. The description adds nothing beyond that, 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 ("Create a department") and scopes it to QuickBooks Online, so an agent can distinguish it from the many other create_* siblings by resource alone. It stops short of explicitly contrasting with neighbors like create_class or search_departments, but the resource name leaves no real 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 on when to use this tool versus alternatives such as update_department or search_departments, and no prerequisites (e.g., needing an existing company connection) are mentioned. The optional 'company' parameter hints at a multi-company scenario, but the description never explains it.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the description does not need to establish that this is a write. It adds one useful fact, that the response carries the SyncToken. However, it omits validation failure modes and the fact that the schema itself flags forbidden PII 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?

Two sentences, zero padding, and the operation is front-loaded ahead of the return-value note. 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?

With no output schema, the description's SyncToken note partially covers return values, and the heavy nested-object requirements live in the schema. But for a mutation against a real accounting ledger, the absence of any guidance on company selection or when a deposit is the correct record type leaves a 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 both parameters and the nested Deposit requirements (DepositToAccountRef, DepositLineDetail.AccountRef, forbidden PII fields) are already fully documented. The description adds nothing beyond the baseline, so a 3 is appropriate.

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

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

States a specific verb and resource (create a deposit in QuickBooks Online) and even names the return shape. It is distinguishable from siblings by the 'deposit' resource, though it never explicitly contrasts with near-neighbors 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?

There is no when-to-use guidance, no prerequisites (e.g., a connected company or a bank account), and no routing to alternatives such as create_transfer for moving funds. The agent must infer everything about invocation 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 declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, covering the safety profile. The description adds one behavioral fact beyond annotations -- that the call returns the saved record with its SyncToken -- which matters since there is no output schema, but it omits auth/company-connection requirements and any guidance on what the SyncToken is used for.

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, front-loaded with the action and followed by the return behavior. Zero filler or redundancy.

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

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

With 100% schema coverage covering the nested entity and company selection, and annotations covering the safety profile, the main remaining gap was return behavior -- which the description addresses briefly via 'the saved record with its SyncToken' in the absence of an output schema. It could say more about the returned object's shape, but it is 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%: the 'entity' parameter carries a detailed warning against sending SSNs, tax IDs, birth dates, or card details, and 'company' explains the connected-company selection. The description adds nothing beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Create an employee in QuickBooks Online') and names the target system, so an agent can distinguish it from update_employee or search_employees. No explicit sibling differentiation is needed beyond the resource name, but none is provided.

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 offers no when-to-use guidance, prerequisites, or alternatives (e.g., when to use update_employee vs create_employee, or the need for a connected company). Usage is only implied by the verb.

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, so the safety profile is covered. The description adds one genuinely useful behavioral fact beyond the annotations — that the call returns the saved record including its SyncToken, which matters for chaining into update_estimate. It says nothing about validation failures, required entity fields, or duplicate 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?

Two short sentences, the action is front-loaded, and the return-shape note is the only second-sentence content. Nothing is redundant with the name or 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?

With no output schema, the description usefully compensates by stating what comes back (saved record + SyncToken). The entity and company semantics are fully covered in the schema, so the main remaining gap is error/precondition behavior, which is minor for a straightforward create.

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%: entity is documented as a QBO API v3 Estimate object with an explicit PII warning, and company explains the multi-company fallback. The description contributes no additional parameter meaning, so the baseline 3 applies.

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

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

States a specific verb+resource ("Create an estimate") scoped to QuickBooks Online, which cleanly separates it from get_estimate, search_estimates and update_estimate. It does not, however, explicitly name any sibling or contrast itself with them, so the differentiation comes only from the verb.

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 when-to-use guidance, no prerequisites, and no mention of alternatives such as update_estimate when the record already exists. An agent can infer 'this creates a new estimate' from the name, but the description adds nothing to that inference.

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. The description adds meaningful behavior beyond that: it changes on-hand quantities and books a valuation difference (side effects), constrains to US Plus/Advanced companies, and notes the returned record carries a SyncToken. This is solid added 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?

Three short sentences, front-loaded with the action, then the effect/constraint, then the return. No filler; each sentence carries distinct information.

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

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

For a mutation tool with a nested object schema and no output schema, the description covers purpose, side effects, eligibility, and the return value (saved record + SyncToken). Nothing essential to 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 description coverage is 100%, with the nested 'entity' object fully documented (TxnDate, DocNumber, AdjustAccountRef, ItemAdjustmentLineDetail, QtyDiff/NewQty). The description adds no parameter syntax beyond the schema, 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 gives a specific verb+resource ('Create an inventory adjustment in QuickBooks Online') and further states the effect ('Changes the quantity on hand of inventory items and books the valuation difference'). This clearly distinguishes it from update_inventory_adjustment, delete_inventory_adjustment, and get_inventory_adjustment.

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 states a concrete eligibility precondition: 'US companies on Plus or Advanced only.' That is useful when-to-use context, but it does not explicitly route the agent to alternatives or state when-not-to-use (e.g. use update vs 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 declare readOnlyHint=false and destructiveHint=false, so the write-but-non-destructive profile is covered. The description adds one genuinely useful behavioral fact beyond annotations — that it returns the saved record with its SyncToken — which is meaningful since there is no output schema, but it omits permissions/required-field/error behavior.

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

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

Two short sentences, front-loaded with the action and the return contract. No filler, no restating the title.

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

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

For a two-parameter write tool with 100% schema coverage and annotations covering safety, the description is nearly sufficient: it names the resource, the platform, and the return shape (SyncToken) despite no output schema. It stops short of the 5 because it says nothing about required fields or failure behavior for a mutation.

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

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

Schema description coverage is 100%, so both the 'entity' and 'company' parameters are already documented in the schema, including the PII restriction and the optional-company rule. The description adds no parameter-level meaning beyond that, which is the baseline 3 case.

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 invoice') plus the system context ('in QuickBooks Online'), so an agent knows exactly what the tool does. However, it does not differentiate itself from the many sibling create_* tools (create_estimate, create_sales_receipt, create_credit_memo), which share the same shape and would be the plausible confusions.

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 when-to-use guidance and names no alternatives such as create_estimate, create_sales_receipt, or update_invoice. The agent is left to infer from the tool name alone whether this or a sibling is the right entry point.

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, destructiveHint=false and openWorldHint=false, so the write-safety profile is already covered. The description adds genuinely useful information not in annotations: the call returns the saved record with its SyncToken. It does not mention permissions, error behavior, or duplicate-item 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?

Two short sentences, front-loaded with the action and followed by the return value. No waste, though the terseness borders on under-specification for a tool with a complex nested entity.

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 a deeply nested, polymorphic entity and no output schema, stating the return shape is helpful, but the description says nothing about usage context, failure modes, or the type-dependent requirements. The schema does the heavy lifting, leaving the description minimally 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% and the entity parameter's schema description is exceptionally detailed (type-specific required fields, guidance on excluded sensitive data). The description adds nothing about parameters, 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?

States a specific verb and resource (create an item in QuickBooks Online) and even names the return payload. It is clearly distinguishable from update_item, get_item and search_items, though it never explicitly differentiates itself from its siblings by 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 when-to-use guidance, no prerequisites, and no mention of alternatives such as update_item or search_items to check for an existing item first. The agent gets no routing help beyond 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 declare this as a non-read-only, non-destructive, closed-world create, so the safety profile is covered. The description adds genuinely useful behavioral context by stating the call returns the saved record including its SyncToken, which signals a follow-up token is available for updates. It stops short of describing failure behavior for unbalanced or invalid entries, which the schema partially covers.

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, and the core action is front-loaded before the return-value note. Nothing is repeated from the schema or annotations.

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

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

For a create tool with no output schema, the description plus the rich nested parameter documentation covers the essentials. The only gap is that it says nothing about the returned SyncToken's role or how validation errors (unbalanced lines) surface to the caller.

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 nested entity parameter is documented in depth (QBO v3 object shape, prohibited PII fields, debit/credit balancing rule). The description adds nothing beyond the schema, so the baseline of 3 is appropriate.

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

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

The description names a specific verb and resource ('Create a journal entry') and scopes it to QuickBooks Online, so the agent knows exactly what object is produced. It does not need to differentiate from siblings like create_invoice or create_bill since the resource itself is unambiguous, but it also never states how a journal entry differs from those other 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?

There is no when-to-use guidance, no mention of prerequisites (chart of accounts must exist, lines must reference valid accounts), and no routing to alternatives such as create_transfer or create_bill for cases where a manual journal entry is not appropriate. The agent must infer usage entirely from the name.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, closed-world), so the description only needs to add context; it does, by stating the return payload past tense-style ("Returns the saved record with its SyncToken"), which signals the concurrency token needed for follow-up updates. It stops short of noting failure modes, duplicate-payment behavior, or permission requirements.

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

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

Four short sentences, each front-loaded with a distinct fact: identity, definition, hard constraint, and return value. Nothing restates the tool name or the annotations, and the reader can stop after sentence two with a correct mental model.

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 no output schema, the description covers what gets created, the key restriction, and the return shape (record + SyncToken). It is nearly complete; only auth/prerequisite information (e.g., which connections or scopes are required) is absent, which is minor given the two-parameter surface.

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

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

Schema coverage is 100% and the entity parameter already documents LinkedTxn linking and prohibited data, so a 3 baseline applies. The description earns one extra point by documenting a field constraint not present in the schema ("ProcessPayment must be omitted or false"), which materially changes how the entity object must be built.

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

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

States a specific verb+resource ("Create a payment in QuickBooks Online") and immediately narrows scope: it is an accounting record of a payment already received, not payment processing. This distinguishes it from siblings like create_bill_payment, create_credit_card_payment_txn, and create_sales_receipt without the agent needing to open another 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?

It gives a clear when-not ("Payment processing is not supported; ProcessPayment must be omitted or false"), which steers the agent away from a mistaken processing use. However, it never routes to the alternatives an agent would actually want here – create_bill_payment for vendor payments, create_sales_receipt for point-of-sale, or send_payment/invoice for collections – so usage 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 declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds a useful return detail (the saved record including its SyncToken, which matters because there is no output schema), but says nothing about idempotency, duplicate handling, or what happens if the method already 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?

Two short sentences, zero filler, and the core action is front-loaded before the return-value note. Nothing is repeated from the title or annotations.

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

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

The entity parameter is an opaque object with no shape given in the schema, and the description does not mention that a payment method needs at least a name (or any other minimal required field inside the object). An agent can call the tool but must guess what to put in 'entity'. The SyncToken return note partially compensates for the missing output schema.

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

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

Schema coverage is 100%, and the schema already explains the QuickBooks API v3 PaymentMethod object and the PII prohibition better than the description does. The description adds no parameter meaning the schema lacks, so the baseline 3 applies.

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

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

States a specific verb and resource ('Create a payment method in QuickBooks Online'), which cleanly separates it from get_payment_method, search_payment_methods, and update_payment_method. It doesn't explicitly name any sibling as an alternative or counterpart, so it stops short of the top mark.

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 search_payment_methods (to check for an existing method first) or update_payment_method. Nothing is said about duplicate names, required prerequisites, or conditions under which creation would fail.

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 write/safety profile is covered. The description adds one genuinely useful behavioral fact beyond the annotations: the call returns the saved record including its SyncToken, which is needed for any follow-up update. It still says nothing about validation failures, PII rejection behavior mentioned in the schema, or whether duplicate submissions create duplicates.

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 the verb and result front-loaded; every clause carries information and nothing is padded or repeated from the title.

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

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

For a mutation tool whose annotations carry the safety profile and whose schema fully documents the entity payload, the description covers the essentials and even notes the returned SyncToken. The remaining gap is disambiguation from the other purchase-like create tools, which is the main thing an agent could get wrong 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?

Schema description coverage is 100%, so the entity parameter's required PaymentType/AccountRef fields and the PII prohibition are already documented in the schema. The description adds nothing about parameters, so the baseline 3 applies.

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

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

States a specific verb and resource ('Create a purchase') and scopes it to QuickBooks Online, so the agent knows exactly what entity is being created. However, it does nothing to distinguish a Purchase from the many easily-confused siblings (create_purchase_order, create_bill, create_expense-style tools, create_sales_receipt), which matters in this crowded namespace.

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 offers no when-to-use guidance, no prerequisites, and never names an alternative tool. With siblings like create_purchase_order and create_bill sitting right next to it, the absence of any routing hint leaves the agent to guess which create tool applies.

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 readOnlyHint=false, destructiveHint=false, and openWorldHint=false, covering the safety profile. The description adds useful return information ('Returns the saved record with its SyncToken'), which is valuable since there is no output schema, but it does not disclose permissions, error behavior, or side effects beyond what annotations already 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?

Two short sentences, both of which earn their place: one for purpose, one for return value. The purpose is front-loaded and there is no redundant or filler content.

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

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

Given the full parameter schema coverage and existing annotations, the description is nearly complete for a create tool: it states the action and the return shape. It does not mention alternatives or common preconditions, but those gaps are modest given that the schema itself carries detailed entity guidance and the annotations cover safety.

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 both parameters in detail, including the complex entity object and the company parameter. The description adds no additional meaning about parameter formats or constraints, which is the baseline expectation when schema coverage is full.

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 order in QuickBooks Online.' This clearly distinguishes the tool from most siblings by its resource name alone, though it does not explicitly differentiate from nearby siblings like 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 alternatives such as create_purchase, create_bill, or create_purchase (expense). There are no prerequisites, exclusions, or conditions given, leaving the agent to infer usage entirely.

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=true and openWorldHint=true, so the write/safety profile is covered. The description adds genuinely useful behavioral context beyond that: the record is a template whose downstream effect is producing transactions on a schedule or on request, and the call returns the saved record with its SyncToken. It still does not state permission/auth requirements or the consequences of creating an 'Automated' recurring entry.

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, front-loaded with purpose before the explanatory clause and the return note. Every sentence earns its place and nothing is padded.

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

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

With no output schema, the description correctly fills that gap by stating the return value (saved record with SyncToken). For a nested-object mutation tool, the deep schema documentation and the destructive/write annotations cover the remaining structured detail, so the description is nearly complete, though it omits any mention of prerequisites or failure modes.

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 carries an unusually rich description (RecurringInfo, RecurType values, ScheduleInfo shape). The description adds no parameter-level meaning of its own, so the baseline 3 applies — the schema, not the description, does the work here.

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 a recurring transaction in QuickBooks Online) and immediately clarifies what the resource actually is: 'a template QuickBooks uses to create a transaction on a schedule, or on request.' That second clause is what separates it from the many sibling create_* tools that make real transactions, so an agent can place it 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?

Usage is implied by the definition of the resource (create one when you want a scheduled/on-demand template), but there is no explicit when-to-use guidance, no exclusions, and no pointer to siblings such as search_recurring_transactions, get_recurring_transaction, or create_invoice. Adequate but leaves routing to inference.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the mutation nature is already declared. The description adds one genuinely useful behavioral fact absent from the annotations: that the call returns the persisted record with its SyncToken, which matters because there is no output schema. It says nothing about permissions, idempotency, or failure behavior.

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

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

Two short sentences with the operation stated first and the return value second; nothing is redundant. It is efficient, though the terseness leaves real gaps rather than being optimally sized for a create 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 create tool with a nested free-form entity object and no output schema, the description at least discloses the return shape (saved record plus SyncToken). It omits error semantics and any hint about required entity fields, but the 100% schema coverage carries most of that burden, making this minimally 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%, so the schema already documents both the entity payload (including the government-identifier restriction and DepositToAccountRef) and the optional company parameter. The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Create a refund receipt in QuickBooks Online'), which is clear enough to distinguish from read/update siblings. However, it does not differentiate from the near-neighbor create_sales_receipt, which an agent could easily confuse with a refund 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 contains no when-to-use guidance, no prerequisites, and no reference to alternatives such as create_sales_receipt or update_refund_receipt. An agent must infer everything about selection from the tool 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?

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the write/safety profile is covered. The description adds a useful return-value detail (saved record with SyncToken), which partly compensates for the missing output schema. It does not disclose failure/idempotency behavior or any permission requirements.

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

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

Two short, front-loaded sentences with zero filler: the action first, then the return payload. Nothing is wasted.

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

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

For a create tool with a nested free-form entity object and no output schema, the definition is minimally adequate: the schema carries the field-level detail and the description notes the returned SyncToken. It is missing the contextual routing information (when to prefer this over sibling create tools) that complexity here would warrant.

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 the nested 'entity' object and the 'company' parameter are already documented in the schema, including the caution about government identifiers. The description adds no parameter-level meaning beyond that, 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 ('Create a sales receipt in QuickBooks Online'), which is clearly understandable. However, it does nothing to differentiate this from the many adjacent create_* siblings (create_invoice, create_refund_receipt, create_credit_memo, create_estimate), so an agent must rely on external knowledge of QuickBooks object types to choose correctly.

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 create_invoice, create_refund_receipt, create_payment, or create_deposit, nor any prerequisites (e.g., customer/item must exist, company must be connected). The one relevant hint — the company parameter — is left to the schema only.

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?

Adds substantial behavior beyond the annotations: the loop is saved paused unless run_now is true, and new loops run in preview mode writing nothing to QuickBooks with every change awaiting approval. These are exactly the safety/state traits an agent needs and that readOnlyHint/destructiveHint alone do not 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?

Five sentences, front-loaded with the core action, then scope, then state behavior. Every sentence carries information, though the return-value and preview sentences could be tightened slightly.

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, so the description appropriately covers the return value ('the saved task and its proposed configuration for review') plus paused/preview behavior. Nothing needed to invoke 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 coverage is 100%, so the baseline is 3, but the description adds meaning not in the schema: the default paused state and the run_now trigger semantics, plus preview-mode consequences of running. This goes beyond the parameter docs rather than restating them.

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 a bookkeeping loop from a user-requested task') and defines what a loop is (data access, permitted actions, approval requirements). It clearly separates loops from plain transactions, but never names the nearest sibling (create_recurring_transaction) to disambiguate the overlap.

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

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

Gives clear context for when to use it: 'recurring work on a schedule or after documents reach the Caribooks document box.' The schedule enum logic (recurring vs once) is also echoed. However, it offers no explicit when-not guidance or named alternatives such as create_recurring_transaction.

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, readOnlyHint=false, and openWorldHint=false, so the safety profile is largely covered. The description adds only the return shape (saved record plus SyncToken), and is silent on the irreversibility, permission requirements, and side-effect account creation that the schema's entity description warns about.

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 tight sentences with the action front-loaded and the return value second; every sentence earns its place. It is slightly under-scaled for a destructive, irreversible operation, but there is no filler or redundancy.

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

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

With no output schema, the description usefully states what is returned, and the schema's entity description carries the destructive/irreversible warnings and PII constraints. For a two-parameter tool with nested object input and full schema coverage, this is nearly complete; only permission/prerequisite context for the calling company is 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%, so the baseline is 3. The description supplies no parameter detail at all; the meaningful semantics (QBO v3 TaxAgency shape, PII restrictions, irreversibility) come entirely from the schema's entity 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 gives a specific verb+resource ("Create a tax agency in QuickBooks Online") and states the return value, so the agent knows exactly what is produced. It does not, however, distinguish itself from nearby siblings like create_tax_service or create_tax_code, so an agent must infer the boundary from the entity type alone.

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 body contains no when-to-use or when-not-to-use guidance. The critical "Only create one when the user has asked for it" caveat lives in the schema's entity field description, not in the tool description, and no alternative tools (e.g. search_tax_agencies, get_tax_agency) are referenced.

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 declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds a genuinely useful behavioral detail not in the annotations — that the response includes the saved record with its SyncToken — but says nothing about permission requirements, duplicate handling, or what happens on validation failure.

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, verb-and-resource front-loaded, no filler or restatement of the title.

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

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

With no output schema, the description partially compensates by naming SyncToken in the return value, and the schema carries rich parameter detail. However, for a mutation tool it omits error/failure behavior and any indication of whether the Term object shape can be validated client-side, leaving a few real 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%: the entity parameter is documented as a QuickBooks Online API v3 Term object with an explicit prohibition on government identifiers, birth dates and card-processing details, and company is documented with its optional-when-single-company rule. The description adds no parameter meaning beyond that, 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?

States a specific verb and resource ('Create a term') plus the system context ('in QuickBooks Online'), which cleanly separates it from the get_term/update_term/search_terms siblings operating on the same resource. It does not, however, differentiate itself from the many other create_* entity tools beyond the noun.

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 when-to-use guidance: it never says that update_term should be used for existing terms, that search_terms/get_term exist for lookup, or what prerequisites apply. The agent must infer usage entirely from the verb.

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 non-read-only, non-destructive, closed-world. The description adds the useful behavior that the saved record is returned with its SyncToken (needed for subsequent updates), but it doesn't mention required permissions, validation behavior, or duplicate handling – beyond safe to add, the record lifecycle is not described.

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, front-loaded with the action and resource, with no filler. 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?

For a create tool with no output schema, the return-value note is helpful, but the description does not compensate for missing mutation guidance (permissions, when to use, alternatives) even though annotations cover the safety profile. Adequate but with clear gaps for a 2-parameter nested-object 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%, so the entity and company parameters are already documented in detail, including the NameOf/EmployeeRef/VendorRef requirement and PII exclusions. The description adds nothing beyond that schema baseline, so 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') and adds the return value. It is clearly distinct from create-invoice/create-bill siblings, but does not explicitly differentiate from create_task or update_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?

No guidance on when to use this versus update_time_activity or search_time_activities, and no prerequisites or exclusions. The 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 declare the safety profile (readOnly=false, destructive=false, openWorld=false), so the bar is lower. The description still adds real value beyond them: it discloses the return payload ('the saved record with its SyncToken'), which matters for chaining into update_transfer, and warns against sending government identifiers, birth dates, or card-processing details.

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

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

Three short sentences, front-loaded with the core action, and each carries information. The second sentence lightly restates the first ('recording a transfer between accounts'), so it is efficient but not maximally tight.

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

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

There is no output schema, so the description correctly covers the return value (saved record plus SyncToken), and the nested entity object's required fields and the sensitive-data restriction are covered in the schema text. For a create tool whose annotations cover the mutation profile, this is close to complete; only explicit alternative-tool guidance 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 both parameters are fully documented in the schema, including the required FromAccountRef/ToAccountRef/Amount subfields and the constraint that the accounts must differ. The description adds nothing further about parameters, 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?

States a specific verb and resource ('Create a transfer in QuickBooks Online') and defines the domain concept ('An accounting entry recording a transfer between accounts'). It also draws a useful negative boundary ('It does not move money between bank accounts'), though it never names the nearby siblings (create_deposit, create_journal_entry, create_payment) an agent might confuse it with.

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 only implied: the negative clarification about not moving money hints at when this is and isn't appropriate, but there is no explicit when-to-use, no prerequisites, and no routing to an alternative tool (e.g., journal entry vs. transfer). Adequate but with clear gaps.

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 mutation/safety profile is covered structurally. The description adds that the saved record plus SyncToken is returned, which is useful since there is no output schema, but it says nothing about duplicate handling, required fields, permissions, or error behavior.

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

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

Two short sentences, front-loaded with the action and followed by the return value. No filler or redundancy.

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

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

For a create tool with a nested entity object and no output schema, the description covers the action and the return value but omits duplicate-prevention guidance, required-field expectations, and failure modes. Combined with the schema's full parameter documentation, it is adequate but has 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%: the schema documents both 'entity' (including the sensitive-data warning about SSNs, tax IDs, birth dates, card details) and 'company'. The description adds no parameter-level meaning beyond that, 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 ('Create a vendor in QuickBooks Online'), which cleanly separates it from update_vendor, search_vendors, and create_customer in the sibling list. It is clear but does not explicitly name an alternative or clarify edge cases such as duplicate vendors.

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 when-to-use or when-not-to-use guidance. The agent is not told to search_vendors first to avoid duplicates, nor what preconditions (e.g. a connected company) are needed. Only the purpose is 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 write-but-non-destructive profile is covered. The description adds one genuinely useful behavioral fact beyond annotations: it returns the saved record including its SyncToken (relevant for subsequent update calls). It does not cover auth/connection requirements or whether the call is retry-safe.

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 tight sentences with zero filler; the core action is front-loaded and the return-value note is secondary. Nothing is wasted or buried.

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 correctly picks up the slack by naming the returned record and SyncToken. However, for a tool whose sole required parameter is a free-form nested QBO object, it gives no hint about the minimum fields needed to construct a valid VendorCredit (e.g., vendor reference and amount/line items), leaving 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?

Schema description coverage is 100%: the 'entity' param is documented as a QBO API v3 VendorCredit object with an explicit data-privacy warning, and 'company' explains accepted identifiers. The description adds nothing beyond the schema, which is the baseline expectation at 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?

States a specific verb and resource ('Create a vendor credit in QuickBooks Online') plus a second sentence on the return payload. The resource is unambiguous enough to separate it from the many other create_* siblings, but the description never explicitly distinguishes it from create_bill, create_purchase, or the update/delete vendor-credit 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?

No guidance on when to use this versus create_bill or create_purchase, no prerequisites (e.g., a vendor must already exist), and no note that search_vendor_credits/update_vendor_credit exist for other operations. The agent must infer all of this from the tool 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?

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 declare the safe read-only profile, but the description adds real behavioral substance: the five-day/same-amount-and-direction matching heuristic, that it also counts booked and pending transactions, and the default window. 'Read-only' merely repeats the annotation, so this is strong but not maximally informative.

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

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

Front-loaded with the core comparison, then supporting detail. Slightly run-on, and the trailing 'Read-only' partially duplicates annotations, but nearly 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 multi-source comparison tool with no output schema, the description explains what is returned (unmatched bank transactions plus booked/pending counts) and the default scope. It lacks guidance on empty/edge results or the required bank-feed connection, but is otherwise sufficient to invoke correctly.

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

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

Schema description coverage is 100%, so from/to/account/company are fully documented there. The description restates the 60-day default (consistent with the schema) but adds no new syntax or format detail, so the baseline 3 applies.

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

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

States a specific operation: comparing each connected bank account's posted transactions against the mapped ledger and listing the ones with no matching line. The matching rule ('same amount and direction within five days') makes the intent unambiguous and distinct from a plain transaction listing.

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?

Implies a reconciliation use case ('often waiting in QuickBooks' bank feed to be accepted') and notes the 60-day default, but never states when to reach for this over siblings like list_bank_transactions or find_expenses_without_attachments, nor any preconditions such as needing a connected bank feed.

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 readOnlyHint annotation it discloses ordering (newest first), the exact returned fields, documented/undocumented counts, exclusion of charges flagged said_no_receipt, and truncation-from-the-oldest-end behavior. That is unusually rich behavioral context for a read tool.

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

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

Purpose is front-loaded and most sentences carry distinct information (exclusions, return fields, truncation). It is somewhat dense with one long comma-separated sentence enumerating return columns, but little is wasted.

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

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

With no output schema, the description does the heavy lifting by enumerating returned rows and counts, exclusions, ordering and truncation. Complete enough to call correctly; a note on pagination/limits would make it airtight.

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 to, from, types and company fully. The description only adds that from/to limit the date range and ties truncation to window width, which is marginal over the schema 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 specific verb (List) and a precise scope (purchases and bills with no document attached in QuickBooks). This cleanly differentiates it from siblings like search_purchases, search_bills, search_attachables and list_purchases_without_payee.

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

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

Gives clear context on the job (surfacing transactions missing receipts) and notes implicit exclusions such as payroll, tax remittances, transfers and bank fees that may not require receipts. It never names an alternative sibling or states an explicit when-not-to-use, so it stops short of the top score.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered and the description carries a lighter burden. It adds no return-shape, not-found behavior, or permission context beyond the annotation baseline, so it is merely adequate.

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

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

A single front-loaded sentence with no padding; the key action and lookup key come first. The trailing routing clause is slightly cryptic but short enough to earn its place.

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