AI Chat Tools

Overview

The AI chat assistant can now perform actions for you through natural language. Instead of clicking through forms, just tell the AI what you want - "create a ticket for Alice at 123 Main St for pipe repair" - and it handles the work. The AI automatically searches customers, finds items from your catalog, geocodes addresses, and creates complete records with proper accounting linkage.

What AI Can Do

Create Tickets

Tell the AI to create a ticket and it will:

• Search for the customer by name
• Find or verify the property address (with Google Maps geocoding)
• Search your catalog for matching items
• Create the ticket with proper items, pricing, and location stamping
• Assign to subcontractors if requested

Example: "Create a ticket for John Smith at 456 Oak Ave for outlet installation, assign to Beta Electric"

Create Jobs

The AI can schedule jobs from tickets or create new ones:

• Links to existing tickets or creates new ones
• Copies all ticket items as job tasks
• Sets date, time slot (AM/PM/specific time), and assigned tech
• Creates contacts and copies photos from tickets

Example: "Schedule a job for Alice tomorrow at 2pm for the pipe repair ticket"

Create Invoices

Generate invoices with proper accounting:

• Uses numbered invoice creation (auto-increments invoice numbers)
• Links items to your catalog via itemId for QuickBooks/Xero sync
• Calculates tax automatically based on item taxable flags
• Links to source tickets, jobs, or projects

Example: "Invoice John for 2 outlets at $150 each plus the service call"

Search Customers

Find customers across all types:

• Searches homeowners, businesses, and builders
• Server-side search (fast, handles large customer lists)
• Returns customer type, contact info, and IDs

Example: "Find customers named Smith"

Search Items

Look up catalog items before creating tickets:

• Searches by name, SKU, or description
• Returns price, cost, type, and itemId
• Helps AI pick the right items for tickets and invoices

Example: "What do we charge for HVAC tune-ups?"

Get Properties

Find properties for a customer:

• Works for homeowners and builders
• Returns address, city, state, and propertyId
• Supports builder subdivisions and lots

Example: "Show me Alice's properties"

Add Customers

Create new customers with address verification:

• Google Maps address verification (geocodes lat/lng, fills missing zip codes)
• Supports homeowners, businesses, and builders
• Database-first approach (saves to DB, then geocodes in background)

Example: "Add new customer Bob Johnson at 789 Pine St, Austin TX"

Geocode Addresses

Convert addresses to coordinates and parsed components:

• Returns lat/lng, formatted address, and placeId
• Parses street address, city, state, and zip code
• Useful for property creation and mapping

Example: "Geocode 123 Main Street, Dallas TX"

How It Works

Tool Chaining

The AI automatically chains tools together to complete complex requests:

"Create a ticket for Alice for pipe repair" becomes:

1. searchCustomers("Alice")
2. getPropertiesByCustomer(aliceId)
3. searchItems("pipe")
4. createTicket(propertyId, customerId, items, description)

"Schedule a job and invoice it" becomes:

1. createJob (or find existing ticket)
2. createInvoice(jobId, line items from job)

Manual UI Parity

Every AI tool produces the exact same result as using the manual UI:

• createTicket: requires items from catalog, supports sub assignment, location stamping, activity logging
• createJob: copies ALL ticket items as tasks, creates contacts, checks for duplicates
• createInvoice: uses numbered invoices, itemId for accounting sync, proper tax calculation
• All searches use proper server-side filters and indexes

Address Verification

When you add customers or create tickets with addresses:

• Google Maps verifies the address exists
• Missing zip codes are filled automatically
• Lat/lng coordinates are geocoded for mapping
• Database saves first (fast), geocoding happens after (background)

Testing & Verification

End-to-End Test Scripts

BlueClerk includes automated test scripts that verify AI tools work correctly:

test-ai-full-flow.ts - Tool-level test:

1. Alpha (GC) creates ticket with items, assigns to Beta (sub)
2. Beta schedules the job via sub workflow
3. Beta completes tasks
4. Alpha creates invoice

test-ai-chat-flow.ts - Real Claude natural language test:

• Uses actual Claude API with natural language prompts
• Tests the entire flow via conversational commands
• Verifies tool calls work in production

verify-sub-pickup.ts - Sub assignment verification:

• AI creates ticket assigned to sub
• Sub sees it in pending tickets
• Sub schedules manually
• Job created under GC's company

Tips

• Be specific: "Create a ticket for Alice at 123 Main St" works better than "make a ticket"
• Let AI search: You don't need exact customer IDs - just give names and the AI will find them
• Ask for catalog items first: "What do we charge for outlets?" before creating tickets
• Chain commands: "Create a ticket, schedule it tomorrow, then invoice it" works in one conversation
• Check the results: AI shows you what it created - verify before sending to customers

Questions

Q: Does AI create tickets without items? A: No - items are REQUIRED. AI will search your catalog and add matching items automatically.

Q: Can AI assign tickets to subcontractors? A: Yes - use "assign to [sub name]" and AI will search your subcontractor roster and assign correctly.

Q: Do AI-created invoices sync to QuickBooks? A: Yes - AI uses itemId linkage so invoices sync properly with your accounting software.

Q: Can AI create jobs from existing tickets? A: Yes - say "schedule a job for ticket #1234" and AI will create a job linked to that ticket with all items copied as tasks.

Q: How does address verification work? A: AI uses Google Maps to verify addresses, fill missing zip codes, and geocode lat/lng coordinates automatically.

Q: What if the AI can't find a customer? A: It will tell you "Customer not found" and suggest creating a new one with addCustomer.