@@ -21,6 +21,17 @@ import { quickbooksReadMasterDataTool } from '@/tools/quickbooks/read_master_dat
 import { quickbooksReadPurchasingTransactionsTool } from '@/tools/quickbooks/read_purchasing_transactions'
 import { quickbooksReadSalesTransactionsTool } from '@/tools/quickbooks/read_sales_transactions'
 import type { QuickBooksAttachmentTargetType } from '@/tools/quickbooks/types'
+import {
+  buildQuickBooksMasterDataQueryUrl,
+  buildQuickBooksQueryUrl,
+  buildQuickBooksSalesQueryUrl,
+} from '@/tools/quickbooks/utils'
+import {
+  parseQuickBooksAddress,
+  quickBooksDisplayName,
+  quickBooksEmailAddress,
+  quickBooksItemName,
+} from '@/tools/quickbooks/values'
 
 describe('QuickBooks credential authority', () => {
   it('declares both credential-derived routing parameters on every tool', () => {
@@ -332,3 +343,115 @@ describe('QuickBooks locale-dependent item accounts', () => {
     ).toEqual({ Name: 'Conseil', Type: 'Service' })
   })
 })
+
+describe('QuickBooks documented query language', () => {
+  const auth = {
+    accessToken: 'token',
+    realmId: '123',
+    quickBooksEnvironment: 'sandbox',
+  } as const
+
+  function getQueryStatement(url: URL): string {
+    return url.searchParams.get('query') ?? ''
+  }
+
+  it('percent-encodes spaces rather than using the form-encoded plus', () => {
+    const url = buildQuickBooksQueryUrl(auth, 'Customer', 1, 25)
+
+    expect(url.search).not.toContain('+')
+    expect(url.search).toContain(
+      'query=SELECT%20*%20FROM%20Customer%20STARTPOSITION%201%20MAXRESULTS%2025'
+    )
+  })
+
+  it('emits one-based STARTPOSITION and MAXRESULTS in the documented order', () => {
+    expect(getQueryStatement(buildQuickBooksQueryUrl(auth, 'Invoice', 26, 25))).toBe(
+      'SELECT * FROM Invoice STARTPOSITION 26 MAXRESULTS 25'
+    )
+  })
+
+  it('renders a boolean Active filter unquoted', () => {
+    expect(
+      getQueryStatement(
+        buildQuickBooksMasterDataQueryUrl({
+          ...auth,
+          recordType: 'vendor',
+          readMode: 'list',
+          activeStatus: 'inactive',
+        })
+      )
+    ).toBe('SELECT * FROM Vendor WHERE Active = false STARTPOSITION 1 MAXRESULTS 25')
+  })
+
+  it('omits the WHERE clause when no filter is requested', () => {
+    expect(
+      getQueryStatement(
+        buildQuickBooksMasterDataQueryUrl({ ...auth, recordType: 'item', readMode: 'list' })
+      )
+    ).toBe('SELECT * FROM Item STARTPOSITION 1 MAXRESULTS 25')
+  })
+
+  it('escapes backslashes before apostrophes in a filter value', () => {
+    expect(
+      getQueryStatement(
+        buildQuickBooksSalesQueryUrl({
+          ...auth,
+          transactionType: 'invoice',
+          readMode: 'list',
+          customerId: "a\\b'c",
+        })
+      )
+    ).toBe("SELECT * FROM Invoice WHERE CustomerRef = 'a\\\\b\\'c' STARTPOSITION 1 MAXRESULTS 25")
+  })
+
+  it('accepts the documented maximum page size of 1000', () => {
+    expect(getQueryStatement(buildQuickBooksQueryUrl(auth, 'Customer', 1, 1000))).toBe(
+      'SELECT * FROM Customer STARTPOSITION 1 MAXRESULTS 1000'
+    )
+    expect(() => buildQuickBooksQueryUrl(auth, 'Customer', 1, 1001)).toThrow(
+      'maxResults must be an integer from 1 through 1000'
+    )
+  })
+})
+
+describe('QuickBooks documented field constraints', () => {
+  it('writes back every address line QuickBooks returns', () => {
+    expect(
+      parseQuickBooksAddress(
+        { Line1: '1', Line2: '2', Line3: '3', Line4: '4', Line5: '5' },
+        'billingAddress'
+      )
+    ).toEqual({ Line1: '1', Line2: '2', Line3: '3', Line4: '4', Line5: '5' })
+    expect(parseQuickBooksAddress({ line3: '3' }, 'billingAddress')).toEqual({ Line3: '3' })
+  })
+
+  it('rejects an item name QuickBooks documents as invalid', () => {
+    expect(() => quickBooksItemName('Parent:Child')).toThrow(
+      'name cannot include tabs, new lines, or colons'
+    )
+    expect(() => quickBooksItemName('a'.repeat(101))).toThrow('name cannot exceed 100 characters')
+    expect(quickBooksItemName('Consulting')).toBe('Consulting')
+  })
+
+  it('rejects a display name past the documented 500-character maximum', () => {
+    expect(() => quickBooksDisplayName('a'.repeat(501), 'displayName')).toThrow(
+      'displayName cannot exceed 500 characters'
+    )
+    expect(quickBooksDisplayName('a'.repeat(500), 'displayName')).toHaveLength(500)
+  })
+
+  it('rejects an email address QuickBooks cannot store', () => {
+    expect(() => quickBooksEmailAddress('not-an-email')).toThrow(
+      'Email address must be a valid address such as name@example.com'
+    )
+    expect(() => quickBooksEmailAddress('a@b@c.com')).toThrow(
+      'Email address must be a valid address such as name@example.com'
+    )
+    expect(() => quickBooksEmailAddress(`${'a'.repeat(95)}@example.com`)).toThrow(
+      'Email address cannot exceed 100 characters'
+    )
+    expect(quickBooksEmailAddress('billing@example.com')).toEqual({
+      Address: 'billing@example.com',
+    })
+  })
+})
@@ -19,6 +19,7 @@ import {
 import {
   optionalQuickBooksString,
   parseQuickBooksAddress,
+  quickBooksDisplayName,
   quickBooksEmailAddress,
   quickBooksPhoneNumber,
 } from '@/tools/quickbooks/values'
@@ -129,7 +130,7 @@ export const quickbooksCreateCustomerTool: ToolConfig<
     method: 'POST',
     headers: (params) => getQuickBooksToolHeaders(params.accessToken, 'application/json'),
     body: (params) => {
-      const displayName = optionalQuickBooksString(params.displayName)
+      const displayName = quickBooksDisplayName(params.displayName, 'displayName')
       const givenName = optionalQuickBooksString(params.givenName)
       const familyName = optionalQuickBooksString(params.familyName)
       if (displayName === undefined && givenName === undefined && familyName === undefined) {
 
@@ -19,6 +19,7 @@ import {
 import {
   optionalQuickBooksString,
   parseQuickBooksAddress,
+  quickBooksDisplayName,
   quickBooksEmailAddress,
   quickBooksPhoneNumber,
 } from '@/tools/quickbooks/values'
@@ -129,7 +130,7 @@ export const quickbooksCreateEmployeeTool: ToolConfig<
         throw new Error('At least one of givenName or familyName must be supplied')
       }
       return filterUndefined({
-        DisplayName: optionalQuickBooksString(params.displayName),
+        DisplayName: quickBooksDisplayName(params.displayName, 'displayName'),
         GivenName: givenName,
         FamilyName: familyName,
         PrimaryEmailAddr: quickBooksEmailAddress(params.primaryEmail),
 
@@ -14,6 +14,7 @@ import {
 } from '@/tools/quickbooks/utils'
 import {
   optionalQuickBooksString,
+  quickBooksItemName,
   quickBooksReference,
   quickBooksWritableItemType,
   requiredQuickBooksString,
@@ -52,7 +53,7 @@ export const quickbooksCreateItemTool: ToolConfig<
       type: 'string',
       required: true,
       visibility: 'user-or-llm',
-      description: 'Unique item name',
+      description: 'Unique item name, up to 100 characters, without tabs, new lines, or colons',
     },
     itemType: {
       type: 'string',
@@ -128,7 +129,7 @@ export const quickbooksCreateItemTool: ToolConfig<
       const incomeAccountId = optionalQuickBooksString(params.incomeAccountId)
       const expenseAccountId = optionalQuickBooksString(params.expenseAccountId)
       return filterUndefined({
-        Name: requiredQuickBooksString(params.name, 'name'),
+        Name: quickBooksItemName(requiredQuickBooksString(params.name, 'name')),
         Type: type,
         IncomeAccountRef:
           incomeAccountId === undefined
 
@@ -16,6 +16,7 @@ import {
 import {
   optionalQuickBooksString,
   parseQuickBooksAddress,
+  quickBooksDisplayName,
   quickBooksEmailAddress,
   quickBooksPhoneNumber,
 } from '@/tools/quickbooks/values'
@@ -132,7 +133,7 @@ export const quickbooksCreateVendorTool: ToolConfig<
     method: 'POST',
     headers: (params) => getQuickBooksToolHeaders(params.accessToken, 'application/json'),
     body: (params) => {
-      const displayName = optionalQuickBooksString(params.displayName)
+      const displayName = quickBooksDisplayName(params.displayName, 'displayName')
       const givenName = optionalQuickBooksString(params.givenName)
       const familyName = optionalQuickBooksString(params.familyName)
       if (displayName === undefined && givenName === undefined && familyName === undefined) {
 
@@ -68,6 +68,39 @@ describe('QuickBooks fault handling', () => {
     expect(formatQuickBooksFaultDetail(elementOnly!)).toBe('element: SyncToken')
   })
 
+  it.each([
+    ['ValidationFault', 'ValidationFault'],
+    ['Validation', 'ValidationFault'],
+    ['AuthenticationFault', 'AuthenticationFault'],
+    ['Authentication', 'AuthenticationFault'],
+    ['AuthorizationFault', 'AuthorizationFault'],
+    ['SystemFault', 'SystemFault'],
+  ])('reports the documented fault classification for type %s', (type, expected) => {
+    const fault = sanitizeQuickBooksFaultData({
+      Fault: { type, Error: [{ code: '6240', Message: 'Duplicate Name Exists Error' }] },
+    })
+
+    expect(fault?.Fault.type).toBe(expected)
+    expect(formatQuickBooksFaultDetail(fault!)).toBe(
+      `${expected}: 6240: Duplicate Name Exists Error`
+    )
+  })
+
+  it('preserves the classification across repeated sanitization', () => {
+    const first = sanitizeQuickBooksFaultData({
+      Fault: { type: 'AuthenticationFault', Error: [{ Message: 'message' }] },
+    })
+
+    expect(sanitizeQuickBooksFaultData(first)?.Fault.type).toBe('AuthenticationFault')
+  })
+
+  it('omits the classification when Intuit does not send one', () => {
+    const fault = sanitizeQuickBooksFaultData({ Fault: { Error: [{ Message: 'message' }] } })
+
+    expect(fault?.Fault).not.toHaveProperty('type')
+    expect(formatQuickBooksFaultDetail(fault!)).toBe('message')
+  })
+
   it.each([null, [], {}, { Fault: {} }, { Fault: { Error: [] } }])(
     'does not claim malformed fault payloads: %j',
     (payload) => {
 
@@ -12,6 +12,22 @@ const QUICKBOOKS_MAX_FAULT_FIELD_CHARS = 500
 /** Documented Intuit fault fields retained during sanitization. */
 const QUICKBOOKS_FAULT_FIELDS = ['code', 'Message', 'Detail', 'element'] as const
 
+/**
+ * Documented `Fault.type` classifications, which separate a rejected payload
+ * from an expired or unauthorized token. Intuit's own pages render these both
+ * with and without the `Fault` suffix — `type="ValidationFault"` in one sample,
+ * `type="Validation"` in another — so they are matched by prefix and reported
+ * under a single spelling.
+ */
+const QUICKBOOKS_FAULT_TYPES = ['Authentication', 'Authorization', 'Validation', 'System'] as const
+
+function normalizeQuickBooksFaultType(value: unknown): string | undefined {
+  const type = typeof value === 'string' ? value.trim() : ''
+  if (!type) return undefined
+  const known = QUICKBOOKS_FAULT_TYPES.find((candidate) => type.startsWith(candidate))
+  return known ? `${known}Fault` : truncate(type, QUICKBOOKS_MAX_FAULT_FIELD_CHARS, '')
+}
+
 /**
  * Intuit error code and message for an outdated `SyncToken`.
  * @see Fault sample `{"Message": "Stale Object Error", "code": "5010"}`
@@ -25,6 +41,8 @@ const QUICKBOOKS_STALE_OBJECT_GUIDANCE =
 export interface SanitizedQuickBooksFault {
   Fault: {
     Error: Array<Record<string, string>>
+    /** Documented Intuit fault classification, normalized by prefix. */
+    type?: string
     /**
      * Count of `Error` entries dropped by {@link QUICKBOOKS_MAX_FAULT_ERRORS}.
      * Preserved across repeated sanitization so a value that round-trips
@@ -72,9 +90,12 @@ export function sanitizeQuickBooksFaultData(data: unknown): SanitizedQuickBooksF
   const carriedOmitted = typeof priorOmitted === 'number' && priorOmitted > 0 ? priorOmitted : 0
   const omittedErrorCount = carriedOmitted + Math.max(0, usableErrorCount - sanitizedErrors.length)
 
+  const type = normalizeQuickBooksFaultType((fault as Record<string, unknown>).type)
+
   return {
     Fault: {
       Error: sanitizedErrors,
+      ...(type ? { type } : {}),
       ...(omittedErrorCount > 0 ? { omittedErrorCount } : {}),
     },
   }
@@ -91,7 +112,8 @@ function hasQuickBooksStaleObjectError(fault: SanitizedQuickBooksFault): boolean
 /**
  * Renders a sanitized fault as a single human-readable detail string.
  *
- * Each entry becomes `code: Message: Detail (element)`. Entries dropped by the
+ * The documented fault classification leads, then each entry becomes
+ * `code: Message: Detail (element)`. Entries dropped by the
  * sanitizer are reported as a trailing count, and a stale-`SyncToken` fault
  * gains explicit remediation guidance because retrying is never correct.
  */
@@ -110,6 +132,7 @@ export function formatQuickBooksFaultDetail(fault: SanitizedQuickBooksFault): st
 
   const omitted = fault.Fault.omittedErrorCount ?? 0
   return [
+    details.length > 0 && fault.Fault.type ? `${fault.Fault.type}:` : '',
     details.join('; '),
     omitted > 0
       ? `(${omitted} additional QuickBooks error${omitted === 1 ? '' : 's'} omitted)`