Server Quality Checklist

Tool Scores

• search_paymentsA
  4.3/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds valuable behavioral details beyond annotations: filters combine with AND, date bounds are inclusive, and invoice application is not a filter with a pointer to LinkedTxn entries. No contradictions with annotations.

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

  Conciseness5/5

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

  Three tightly written sentences: purpose, use cases, and behavioral caveat. Every sentence earns its place, and the most decision-relevant facts (read-only, filter combination, exclusions) are front-loaded without redundancy.

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

  Completeness5/5

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

  With a full output schema present and annotations covering read-only/idempotency, the description only needs to supply usage context and behavioral constraints. It does so thoroughly, including the non-obvious LinkedTxn caveat and pagination-aware filter semantics. Nothing essential for correct invocation is missing.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the baseline is 3. The description reinforces inclusive date bounds and AND-combination, but these are already stated in individual parameter descriptions. It adds no new parameter-level semantics beyond what the schema provides.

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

  Purpose5/5

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

  The description clearly states the verb ('Find') and resource ('payments') along with the key filtering dimensions (customer Id, transaction-date range). It further distinguishes itself from single-payment retrieval by framing the use case of locating a payment that settled an invoice, and implicitly separates from list_payments by specifying search criteria.

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

  Usage Guidelines4/5

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

  Explicitly gives two concrete usage scenarios ('reconcile what a customer has paid' and 'locate the payment that settled an invoice'). It also provides a clear boundary by warning that invoice application is not a filter and directing the agent to LinkedTxn entries. It does not explicitly name sibling alternatives, but the usage context is strong enough to guide selection.

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

• delete_customerA
  4.5/5.0
  Behavior5/5

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

  The description discloses key behaviors beyond the annotations: there is no hard delete, Active is set to false, invoices/payments/history are preserved, the operation is non-idempotent because the SyncToken changes on success, and deleted customers remain searchable. This is rich context and 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.

  Conciseness5/5

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

  Every sentence earns its place: the first states the core operation and effect, the second gives usage guidance, and the third explains token behavior and post-deactivation readability. The description is information-dense without being bloated.

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

  Completeness5/5

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

  For a two-parameter mutation with an output schema, the description covers the operation's purpose, preconditions (fresh SyncToken), postconditions (Active=false, history retained), and how to verify/read the result afterward. Nothing essential is missing.

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

  Parameters3/5

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

  Schema description coverage is 100%, and the parameter descriptions already clearly explain the SyncToken requirement, error 5010, and the customer ID format. The tool description reinforces that the SyncToken must come from a fresh get_customer call, but it does not add significant new parameter-level meaning beyond the schema.

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

  Purpose5/5

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

  The description opens with a specific action and resource ('Deactivate a customer') and immediately clarifies the mechanism (sets Active to false) and scope (not a hard delete). This clearly distinguishes it from destructive deletes and from other sibling update/delete tools.

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

  Usage Guidelines4/5

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

  The description explicitly says to use the tool to retire a customer rather than erase data, which provides clear intent. It also notes that deactivated customers remain readable via search_customers with active=false, giving the agent a follow-up path. It does not explicitly list when to prefer alternatives like update_customer, but the context is sufficient.

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

• delete_paymentA
  4.5/5.0
  Behavior5/5

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

  The description goes well beyond the annotations. While annotations mark the operation as destructive and non-idempotent, the description adds that the server cannot undo deletion, that settled invoices revert to unpaid, and that repeat calls fail because the payment no longer exists. These are valuable behavioral disclosures not visible in structured metadata.

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

  Conciseness5/5

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

  Three sentences deliver the core action, usage condition, irreversible consequence, effect on invoices, and non-idempotent concurrency requirement. There is no redundancy or filler; each sentence adds distinct information and the most critical facts are front-loaded.

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

  Completeness5/5

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

  For a destructive write operation, the description covers what happens on success, the consequences to related data, the impossibility of undo, and the required precondition for a successful call. With output schema present and annotations already conveying safety flags, nothing an agent needs to invoke this tool correctly is missing.

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

  Parameters3/5

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

  Schema description coverage is 100%, with both payment_id and sync_token already documented in detail, including the 5010 stale-token warning. The description reinforces the need for a fresh SyncToken and notes the repeat-call failure, but it does not introduce genuinely new parameter-level meaning beyond what the schema provides, 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.

  Purpose5/5

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

  The description opens with 'Delete a payment permanently from the company file,' combining a specific verb, resource, and permanence scope. It also narrows the purpose with 'Use it only for a payment recorded in error,' which distinguishes it from update-oriented siblings and clearly frames the deletion as a corrective, irreversible action.

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

  Usage Guidelines4/5

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

  Explicitly states when to use the tool ('only for a payment recorded in error') and warns about the effect on settled invoices. It also gives a technical prerequisite (fresh SyncToken) and behavior on repeat calls, but it does not explicitly name an alternative such as update_payment for non-error corrections, leaving that routing implicit.

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

• get_invoiceA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: the read-only statement, the ok=false with status 404 on unknown Id, and the fact that the response includes the current SyncToken. This complements rather than merely repeats 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.

  Conciseness5/5

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

  The description is compact and information-dense, with the core action and return contents in the first sentence, usage guidance in the second, and error/alternative-handling in the third. No sentence is wasted and the most important facts are front-loaded.

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

  Completeness5/5

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

  Given the tool has a single parameter, a rich output schema, and annotations covering read-only and idempotent behavior, the description covers everything an agent needs: what it returns, why to call it, how to handle unknown IDs, and where to find IDs. The error case is explicitly documented, and siblings are referenced.

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

  Parameters3/5

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

  Schema coverage is 100%, and the schema itself already explains the parameter is the internal QuickBooks Id, not the DocNumber. The description adds context that the Id is what search_invoices, list_invoices, or create_invoice return, and that the SyncToken is needed by update/delete, which slightly enriches the parameter's purpose. This matches the baseline for high schema coverage with minor added value.

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

  Purpose5/5

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

  States a specific verb ('read'), a specific resource ('one invoice by QuickBooks Id'), and enumerates the returned fields (lines, totals, remaining balance, due date, SyncToken). It clearly differentiates from search_invoices and list_invoices, which are for finding invoices, making the tool's unique role unambiguous.

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

  Usage Guidelines5/5

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

  Explicitly says when to use this tool: to check whether an invoice is still open and to get the SyncToken required by update_invoice and delete_invoice. It also tells the agent how to find an Id if unknown, naming search_invoices and list_invoices as alternatives, and explains the unknown-Id error behavior.

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

• update_invoiceA
  4.5/5.0
  Behavior5/5

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

  The description goes well beyond the annotations: it discloses that the line array is replaced wholesale, omitted lines are dropped, and totals will change. It also warns that the operation is not idempotent, that it overwrites the live record, and that existing linked payments are not adjusted. This is richly transparent for a destructive write operation.

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

  Conciseness5/5

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

  The description is compact and front-loaded: purpose first, then usage, then behavioral caveats. Every sentence earns its place, and the most important warning about wholesale line replacement appears early. Despite covering several distinct risks, it avoids bloat.

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

  Completeness5/5

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

  For a destructive mutation with annotations already marking it non-idempotent and destructive, the description supplies the missing operational details: the stale-token failure mode, the need for a fresh SyncToken, the replacement semantics, and the interaction with linked payments. With an output schema present, nothing critical is left for the agent to infer.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the baseline is 3. The description reinforces the key semantic point that the lines array is a full replacement, and it restates the SyncToken freshness requirement, but most of this is already present in the parameter descriptions. It does not add substantially new per-parameter meaning beyond what the schema provides.

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

  Purpose5/5

  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: "Replace the contents of an existing invoice." It then names concrete use cases (correct amounts, dates, or the billing customer), making it immediately distinguishable from sibling update_customer and update_payment tools. The wholesale-replacement warning further pins down what this tool uniquely does.

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

  Usage Guidelines4/5

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

  It explicitly states when to use the tool: to correct amounts, dates, or the billing customer on an existing invoice. It also gives crucial procedural context, requiring the Id and a fresh SyncToken from get_invoice, and warns that stale tokens fail with error 5010. It does not explicitly enumerate when not to use it or name an alternative for payment adjustments, but the guidance is otherwise clear.

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

• delete_invoiceA
  4.6/5.0
  Behavior5/5

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

  Annotations already mark this as destructive and non-idempotent, but the description adds important behavioral context beyond those flags: 'this server cannot undo it', payments linked to the invoice lose that link, and stale SyncTokens will cause failures. This fully discloses the side effects of calling the tool.

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

  Conciseness4/5

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

  The description is dense but every sentence adds useful operational context: permanent deletion, when to use versus alternatives, SyncToken and idempotency requirements, and linked-payment side effects. It is slightly redundant with the annotations and schema (e.g., 'not idempotent' and the freshness requirement), but it remains efficient and well-structured.

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

  Completeness5/5

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

  For a destructive, non-idempotent mutation tool, the description covers the critical context an agent needs: irreversibility, the correct use case, the prerequisite for a fresh SyncToken, failure mode on repeat calls, and the effect on linked payments. Combined with the output schema and detailed parameter descriptions, nothing essential is missing.

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

  Parameters3/5

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

  The input schema already covers both parameters thoroughly, including that invoice_id is the internal Id not DocNumber, and that sync_token must come from a fresh get_invoice call and will fail with error 5010 if stale. The description reinforces the SyncToken requirement but does not add much semantic meaning beyond what the schema provides, so a baseline score of 3 is appropriate.

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

  Purpose5/5

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

  The description opens with a clear verb and resource: 'Delete an invoice permanently from the company file.' It distinguishes this action from voiding or issuing a credit memo, which are the correct alternatives for invoices the customer has seen, so an agent can immediately understand what this tool does and how it differs from other accounting actions.

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

  Usage Guidelines5/5

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

  The description explicitly states when to use the tool ('only for an invoice raised in error'), when not to use it (customer-visible invoices should be voided or credited), and the prerequisite of a fresh SyncToken from get_invoice. It also warns that a repeat call fails because the invoice no longer exists, which gives the agent clear operational guidance.

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

• search_customersA
  4.6/5.0
  Behavior5/5

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

  The description goes well beyond the annotations by disclosing that filters combine with AND, that name_contains is a prefix match due to QuickBooks only supporting a trailing wildcard, and that no-filter calls return the whole roster page by page. These are important behavioral details not visible from readOnlyHint or idempotentHint alone. The only redundancy is the 'Read-only' phrase, which echoes the annotation.

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

  Conciseness4/5

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

  The description is four compact sentences that front-load the core behavior and use cases. The QuickBooks wildcard constraint is explained concisely. However, the standalone 'Read-only.' sentence is redundant with the readOnlyHint annotation, so not every sentence strictly earns its place.

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

  Completeness5/5

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

  For a read-only search tool with a rich output schema and fully documented parameters, the description covers everything needed for correct invocation: supported filters, AND combination, prefix-only matching, no-filter behavior, and pagination. There is no obvious operational gap that would cause an agent to call the tool incorrectly.

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

  Parameters4/5

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

  Schema coverage is 100%, so each parameter is already well-documented individually. The description adds interaction-level semantics: filters combine with AND, omitting all filters returns the full roster, and pagination uses max_results/start_position. This provides value beyond the per-parameter schema descriptions, pushing it above the baseline of 3.

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

  Purpose5/5

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

  The description states a specific verb ('Find') and resource ('customers') with three concrete filter dimensions: display-name prefix, exact email, and active flag. It also gives the operational purpose ('turn a name or email an agent was given into a customer Id'), which clearly distinguishes it from create/update/get/delete siblings. Even without explicitly naming list_customers, the purpose is unmistakable.

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

  Usage Guidelines4/5

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

  The description gives explicit use cases: resolving a name/email to a customer ID and checking for an existing record before calling create_customer. It also clarifies behavior with no filters (returns whole roster paginated). It does not explicitly name alternatives like list_customers or say when to prefer get_customer, so context is clear but exclusions are missing.

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

• create_invoiceA
  4.7/5.0
  Behavior5/5

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

  The annotations already mark this as non-read-only and non-idempotent, and the description adds valuable context beyond that: it posts a receivable with real accounting effect, bills the customer on each call, lets QuickBooks assign DocNumber and totals, and derives due date from payment terms unless overridden. This is substantive behavioral disclosure that helps the agent understand consequences.

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

  Conciseness5/5

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

  The description is dense but efficient, with no filler. Each sentence earns its place by covering prerequisites, side effects, idempotency, line requirements, and QuickBooks-assigned defaults. Important behavioral information is front-loaded before secondary details.

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

  Completeness5/5

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

  For a creation tool with nested inputs and significant accounting impact, the description covers the key prerequisites, side effects, non-idempotency, and default behaviors. Since an output schema exists, not describing the return payload is acceptable. The agent has enough context to invoke it correctly and safely.

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

  Parameters4/5

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

  Schema coverage is 100%, so the baseline is 3. The description adds useful param-level guidance beyond the schema: every line needs an amount, a line without an item_id falls back to the default sales item, and customer_id must reference an already-existing customer. This meaningfully supplements the structured schema.

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

  Purpose5/5

  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: 'Create an invoice for an existing customer with one or more line items.' It clearly differentiates from the many sibling invoice tools (update_invoice, delete_invoice, list_invoices) by stating creation scope and the requirement of an existing customer.

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

  Usage Guidelines4/5

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

  The description explicitly says to use it after resolving the customer Id via search_customers or create_customer, and it warns against calling it twice because it is not idempotent. It gives clear invocation context, though it does not explicitly name alternatives such as update_invoice for later corrections.

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

• create_paymentA
  4.7/5.0
  Behavior5/5

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

  The description adds substantial behavioral context beyond the annotations: it states this is a write operation with 'real accounting effect,' explains that it posts cash and reduces invoice balance, and explicitly warns 'Not idempotent, so a repeated call records a second payment.' It also clarifies the behavior of omitting invoice_id, producing an unapplied credit. This exceeds what annotations alone convey.

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

  Conciseness5/5

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

  The description is four sentences with no filler, front-loading the core action and then moving from usage timing to accounting effect to idempotency to invoice behavior. Every sentence adds a distinct, useful piece of information that helps an agent call the tool correctly.

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

  Completeness5/5

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

  For a mutation tool with one nested payment object, the description covers when to call it, what accounting side effects occur, the non-idempotent risk, and the key decision about invoice_id. The schema documents all parameters, and an output schema is present, so no necessary context appears missing.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the baseline is 3. The description reinforces the invoice_id semantics already present in the schema ('Supplying invoice_id links the whole total_amount to that invoice; omitting it leaves an unapplied credit'), but it does not add new parameter-specific meaning beyond the schema. It appropriately relies on the schema for details like txn_date and total_amount constraints.

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

  Purpose5/5

  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: 'Record a payment received from a customer, optionally applied against a specific invoice.' This clearly identifies the tool's action and scope, and it distinguishes create_payment from sibling payment tools like update_payment, delete_payment, get_payment, and search_payments by focusing on recording a new payment.

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

  Usage Guidelines5/5

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

  The description gives explicit when-to-use guidance: 'Use it once the money has actually arrived, after confirming the invoice Id with get_invoice or search_invoices.' It names the exact prerequisite tools to use first and clarifies when an invoice should be supplied versus omitted. This is strong routing guidance with no ambiguity.

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

• get_customerA
  4.7/5.0
  Behavior5/5

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

  Beyond the annotations, the description reveals important behavioral details: unknown IDs return ok=false with status 404, and the response includes the current SyncToken. It also confirms the operation is read-only. These traits add decision-relevant context that annotations alone do not provide.

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

  Conciseness5/5

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

  Three sentences each carry distinct value: the first defines scope and return contents, the second gives the use case, and the third covers behavior and alternatives. No filler or redundancy; the critical error condition is front-loaded near the end where it complements the usage guidance.

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

  Completeness5/5

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

  The tool is simple (one parameter, no nested objects) and has both an output schema and comprehensive annotations. The description covers the return scope, the SyncToken dependency, and the 404 error path. 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.

  Parameters3/5

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

  Schema coverage is 100%, so the baseline is 3. The parameter description already explains that customer_id is the numeric QuickBooks Id, not the display name, and describes its provenance. The tool description reinforces this but does not add meaning beyond the schema.

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

  Purpose5/5

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

  The description uses a specific verb ('Read') and names the exact resource ('one customer by QuickBooks Id'), then enumerates what is returned: contact details, billing address, open balance, and SyncToken. It clearly differentiates from sibling tools like list_customers and search_customers by emphasizing single-record retrieval by ID.

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

  Usage Guidelines5/5

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

  The description explicitly states when to use this tool: to inspect a customer and to obtain the SyncToken required by update_customer and delete_customer. It also gives an exclusion by directing the agent to search_customers or list_customers when the Id is unknown, so the agent knows not to call get_customer blindly.

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

• get_paymentA
  4.7/5.0
  Behavior5/5

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

  Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds meaningful context beyond those: it describes the error behavior for an unknown ID ('returns ok=false with status 404') and clarifies that the SyncToken is required by update/delete operations. 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.

  Conciseness5/5

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

  Three sentences, each earning its place: purpose and return fields, use cases/routing, and error behavior with fallback. The most important information is front-loaded, and there is no filler or repetition.

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

  Completeness5/5

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

  For a single-ID read tool with a rich output schema and thorough annotations, the description is complete. It covers what is returned, why the agent would call it, how to handle an unknown ID, and how the result feeds into sibling mutation tools. Nothing necessary for correct invocation is missing.

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

  Parameters3/5

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

  There is only one parameter with 100% schema description coverage, so the schema already fully documents payment_id. The description adds the phrase 'by QuickBooks Id' and the concept that this ID comes from search/list/create, but this is largely redundant with the schema. A baseline 3 is appropriate.

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

  Purpose5/5

  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—'Read one payment by QuickBooks Id'—and enumerates the exact fields returned (total, transaction date, linked transactions, SyncToken). It clearly distinguishes itself from sibling tools like list_payments and search_payments by focusing on a single payment lookup.

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

  Usage Guidelines5/5

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

  The description explicitly states when to use the tool: to confirm which invoice a payment was applied to and to obtain the SyncToken needed by update_payment and delete_payment. It also gives a direct alternative for unknown IDs, pointing to search_payments or list_payments. This is explicit routing guidance.

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

• list_customersA
  4.7/5.0
  Behavior5/5

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

  Beyond the annotations, the description discloses meaningful behavior: results include both active and inactive customers, ordering is most-recently-updated first, and paging is caller-driven with a clear termination condition. These details go beyond readOnlyHint and idempotentHint and help the agent understand the tool's actual behavior.

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

  Conciseness5/5

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

  The description is front-loaded with the core action, followed by usage guidance, behavior, and paging details in a logical order. Every sentence earns its place, and there is no wasted or redundant wording.

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

  Completeness5/5

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

  For a straightforward paginated list tool, the description covers ordering, filtering alternatives, inclusion of inactive customers, pagination mechanics, and the read-only nature. Combined with the rich schema and annotations, nothing essential is missing for an agent to invoke it correctly.

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

  Parameters3/5

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

  The input schema already provides full descriptions for both parameters, including ranges, defaults, and paging math. The description adds a helpful cross-parameter framing ('keep requesting pages until fewer than max_results rows are returned'), but most semantic weight is already carried by 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.

  Purpose5/5

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

  The description states a specific verb and resource ('List customers') and adds distinctive scope: 'most recently updated first, one page at a time.' It also differentiates from siblings by explicitly routing filtered lookups to search_customers, so an agent can tell this tool apart without opening other schemas.

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

  Usage Guidelines5/5

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

  Usage context is explicit: use it 'to browse the roster or to find an Id when you have nothing to filter on; prefer search_customers when you do.' It also provides a practical rule for knowing when pagination is complete: keep requesting pages until fewer than max_results rows are returned.

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

• search_invoicesA
  4.7/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond annotations: filters combine with AND, date bounds are inclusive, and the Balance field semantics for settled status. There is 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.

  Conciseness5/5

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

  Four sentences, each earning its place: primary purpose, use cases, read-only declaration, filter semantics, and payment-status limitation. The most important information is front-loaded, and there is no repetition of schema content.

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

  Completeness5/5

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

  The description covers purpose, when to use, filter behavior, a key limitation, and a hint about reading the Balance field in results. With 0 required parameters, 100% schema coverage, an output schema present, and annotations covering safety, nothing critical is missing for an agent to invoke this tool correctly.

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

  Parameters4/5

  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 all parameters. The description goes beyond the schema by clarifying how parameters interact ('Filters combine with AND'), stating the inclusive nature of date bounds (also in schema but reinforced), and explaining that payment status is not a filterable parameter. This adds interpretive value above the schema's per-field descriptions.

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

  Purpose5/5

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

  The description names a specific verb ('Find') and resource ('invoices') with three distinct filter dimensions: customer Id, transaction-date range, and document number. It also provides concrete use cases ('what a customer was billed in a period' and 'turn a document number into an invoice Id'), which distinguishes it from siblings like list_invoices, get_invoice, search_customers, and search_payments.

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

  Usage Guidelines4/5

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

  The description gives explicit use cases and an explicit when-not-to-use: 'Payment status cannot be filtered here: read the Balance field on each result.' However, it does not name an alternative sibling tool explicitly (e.g., 'use list_invoices for all invoices'), so it falls just short of full routing guidance.

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

• update_customerA
  4.7/5.0
  Behavior5/5

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

  Beyond the annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=false), it explains that fields supplied are overwritten while omitted fields stay unchanged, that a successful write increments the SyncToken, and that stale tokens fail with error 5010. This gives materially useful operational detail that the annotations alone do not convey; 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.

  Conciseness5/5

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

  Every sentence earns its place: purpose, use cases, write semantics, non-idempotence, and the token precondition are all stated with minimal redundancy. The most decision-relevant information is front-loaded in the first two sentences.

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

  Completeness5/5

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

  Given the 3-parameter shape, a nested customer payload, an output schema, and rich annotations, nothing an agent needs to invoke the tool correctly is missing: it knows the update semantics, the required prerequisite token, the error mode, and the resource. Return values are already covered by the output schema.

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

  Parameters4/5

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

  Schema coverage is 100% and the schema already documents customer_id, sync_token, and the customer object, so the baseline is a 3. The description adds value by defining the payload as a sparse patch ('leaves omitted fields unchanged') and reinforcing that the sync_token must come from a fresh get_customer, which clarifies how to use the required parameters beyond their individual field docs.

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

  Purpose5/5

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

  Description opens with a direct verb+object ('Update an existing customer') and names exact use cases ('correct contact details, addresses, or the display name'). It further distinguishes itself as a sparse update rather than a replacement, which differentiates it from create/delete and from a hypothetical full overwrite.

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

  Usage Guidelines4/5

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

  It explicitly frames when to use the tool ('Use it to correct...') and requires 'Id plus the SyncToken from a fresh get_customer', effectively pairing it with a read step. It stops short of naming explicit exclusions such as 'use create_customer for new records' or 'use delete_customer for removal', though 'existing customer' and sparse-update wording make those boundaries clear.

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

• update_paymentA
  4.7/5.0
  Behavior5/5

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

  Discloses much more than the annotations alone: it is a destructive overwrite of the live record, omitting invoice_id unlinks the payment and reopens the invoice balance, it is not idempotent, and a stale SyncToken fails with error 5010. This richly extends the annotation signals 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.

  Conciseness5/5

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

  Three dense sentences cover purpose, use cases, side effects, idempotency, prerequisites, and failure mode with no filler. The primary purpose is front-loaded before the behavioral warnings.

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

  Completeness5/5

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

  For a destructive, non-idempotent update with three required parameters and a full output schema, the description covers everything an agent needs: when to use it, what to pass, the overwrite semantics, the token requirement, and the failure behavior. No critical gap remains.

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

  Parameters4/5

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

  Schema coverage is 100%, so the schema already documents all three parameters and their basic meanings. The description adds valuable behavioral semantics: the payment object is a full replacement, leaving invoice_id out unlinks the payment, and sync_token must come from a fresh get_payment. That raises it above the schema-only baseline.

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

  Purpose5/5

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

  States a specific verb and resource — "Replace the contents of an existing payment" — and gives concrete correction use cases (amount, date, invoice linkage). This clearly distinguishes it from create, get, list, search, and delete payment siblings.

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

  Usage Guidelines4/5

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

  Explicitly frames when to use it: "Use it to correct an amount, a date, or the invoice a payment was applied to." It also communicates the prerequisite of a fresh get_payment SyncToken. It does not explicitly mention alternatives like create_payment for new payments, so it stops short of full when-not guidance.

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

• create_customerA
  4.9/5.0
  Behavior5/5

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

  Goes well beyond the annotations: readOnlyHint=false and idempotentHint=false are already present, but the description adds that it adds exactly one Customer and changes nothing else, explains the non-idempotent behavior with QuickBooks' specific duplicate error, and discloses the success/error return shape. 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.

  Conciseness5/5

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

  Four sentences, each earning its place: purpose, usage precondition, write-scope and idempotency, and return/error behavior. The most decision-relevant information is front-loaded.

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

  Completeness5/5

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

  The definition covers what the tool does, when to use it, what to check first, its side effects, its idempotency trap, and its return shape. With annotations and a full output schema also present, nothing an agent needs to invoke and interpret this tool correctly is missing.

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

  Parameters4/5

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

  Schema coverage is 100% and every field already has a description, so the baseline is 3. The description adds meaningful extra semantics by highlighting that display_name must be unique and that duplicates trigger error 6240, plus clarifying the return payload includes Id and SyncToken, which helps an agent interpret the result.

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

  Purpose5/5

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

  States a specific verb and resource: "Create a customer in the connected QuickBooks Online company." It also distinguishes itself from sibling tools by framing its role as a prerequisite to invoicing and by explicitly warning against duplicating records that search_customers would find.

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

  Usage Guidelines5/5

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

  Explicitly says when to use the tool (before invoicing someone not on file) and gives a required precondition (run search_customers first to avoid creating duplicates). It also clarifies a non-obvious constraint by stating the operation is not idempotent and the duplicate will be rejected with error 6240.

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

• list_invoicesA
  4.9/5.0
  Behavior5/5

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

  Annotations already declare read-only, idempotent, non-destructive behavior; the description goes beyond them by explaining caller-driven paging, the termination condition of requesting until fewer than max_results rows return, and that both paid and unpaid invoices appear with the Balance field distinguishing them. No contradiction with annotations exists.

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

  Conciseness5/5

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

  Four sentences, each earning its place: purpose and ordering, usage vs. sibling, read-only safety, paging semantics, and the paid/unpaid distinction. Information is front-loaded, with filtering guidance and safety stated before implementation details.

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

  Completeness5/5

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

  For a simple two-parameter list endpoint with a rich output schema and strong annotations, every operational need is covered: sorting, when to use vs. search_invoices, pagination termination, and how to interpret paid vs. unpaid rows. Nothing essential is missing.

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

  Parameters4/5

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

  Schema coverage is 100% and each parameter already has detailed meaning, including one-based indexing and how to compute the next page. The description adds value by framing the two parameters together as a caller-driven paging strategy and stating the stop condition, which is not fully expressed in the individual parameter descriptions.

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

  Purpose5/5

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

  The description opens with a specific verb-plus-resource statement, 'List invoices', and immediately adds distinguishing scope: ordering by most recent transaction date and one-page-at-a-time behavior. It also explicitly differentiates itself from search_invoices, so an agent can select the right tool without opening schemas.

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

  Usage Guidelines5/5

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

  It gives an explicit usage condition: use this when there is nothing to filter on for recent billing. It names the alternative, search_invoices, and states the exact condition under which that alternative should be preferred: when filtering by customer, date, or document number. Paging guidance adds further operational clarity.

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

• list_paymentsA
  4.9/5.0
  Behavior5/5

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

  The description adds real behavioral detail beyond annotations: it states the sort order, that paging is caller-driven through start_position and max_results, and the exact loop-termination condition (request until fewer than max_results rows return). It also correctly reinforces the read-only 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.

  Conciseness5/5

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

  Four sentences, each carrying essential information: purpose, sort order, when to use, when to avoid, and the pagination contract. No filler or redundancy; key operational guidance is front-loaded.

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

  Completeness5/5

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

  The description covers purpose, use conditions, alternative routing, safety profile, and paging behavior. Parameters are fully documented in the schema, and an output schema exists, so nothing critical is missing for correct invocation.

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

  Parameters4/5

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

  The input schema already documents both parameters thoroughly, so the baseline is solid. The description adds value by explaining how the two parameters work together in a paging loop and when to stop, which is not fully captured in the schema's individual parameter descriptions.

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

  Purpose5/5

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

  The description clearly states the operation: listing payments, with a specific sort order (most recent transaction date first) and pagination behavior. It also distinguishes itself from search_payments, making the tool's role unambiguous even among many sibling tools.

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

  Usage Guidelines5/5

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

  It explicitly says when to use this tool ('when you have nothing to filter on') and when to prefer the alternative ('prefer search_payments when you can filter by customer or date'). This gives the agent a clear decision rule with no inference required.

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