Look up historical pricing from the south Alabama contractor line item corpus.

USE WHEN: Generating estimates, validating pricing, comparing job costs, "what do we charge for X?". DO NOT USE WHEN: Looking up a specific job's line items (use hcp_list_job_line_items). GOTCHAS: Prices are south Alabama contractor historical (south Alabama market). Adjust for other regions.

Add a line item to a job. Price is in CENTS (e.g., 1500 = $15.00). Response prices converted from cents to dollars.

Add a note to a job. note_type: 'internal' (staff only) or 'customer' (visible to customer).

Add tags to a customer. Merges with existing tags via GET+PATCH to prevent data loss (HCP PATCH replaces the entire tags array). Tags are arbitrary strings, not tag_ IDs. Deduplicates before writing.

Apply a tag to a job. Idempotent — re-applying an existing tag is safe. Returns the full list of tags on the job after applying. Tag removal is available via hcp_remove_tag_from_job.

Create a new job. Requires customer_id (cus_ prefix). Prices converted from cents to dollars. Note: HCP API silently drops 'description' on POST /jobs. If description is provided, it is added as an internal note on the job after creation.

Create a new lead. customer_name is the only required field. HCP expects nested customer and address objects.

Create a new tag. Returns 422 if tag name already exists. Tag names are case-sensitive.

Get company profile for the authenticated API key. Returns company name, timezone, address, and settings. No parameters needed.

Get a single customer by ID (cus_ prefix).

Get a single estimate by ID (csr_ prefix). Prices converted from cents to dollars.

Get a single job by ID. Prices converted from cents to dollars.

List service addresses for a customer (cus_ prefix).

List customers with optional search. Auto-paginates unless explicit page is set.

List employees/technicians. Auto-paginates unless explicit page is set. Employee IDs use pro_ prefix.

List line items for a specific estimate option. Prices converted from cents to dollars.

List estimates with optional filters. Auto-paginates unless explicit page is set. Prices converted from cents to dollars.

List events with incremental polling. Auto-paginates unless explicit page is set. Max page_size is 50 (HCP limit). Use last_polled_at (ISO 8601) for incremental consumption.

List invoices. No server-side filtering available. For job-specific invoices, use hcp_list_job_invoices(job_id) instead. Invoice items are inline (no nested call needed). Prices converted from cents to dollars.

List all invoices for a specific job. Eliminates need to paginate full invoice list (29K+) and filter client-side. Prices converted from cents to dollars.

List line items for a job. Prices converted from cents to dollars. Note: HCP returns job line items in {object: 'list', data: [...]} format, normalized here to standard shape.

List jobs with optional filters. Auto-paginates unless explicit page is set. Prices converted from cents to dollars.

List leads. Auto-paginates unless explicit page is set.

List lead sources. Auto-paginates unless explicit page is set.

List material categories from HCP price book. Optionally filter by parent category UUID.

List all tags. Auto-paginates unless explicit page is set. Tag IDs use tag_ prefix.

Remove a tag from a job. Returns the remaining tags on the job after removal.

Update a job's schedule. Overwrites existing schedule — previous values are lost. Times must be ISO 8601 format.

Bucket overdue invoices by age for accounts receivable analysis.

USE WHEN: "How much money is owed?", AR review, collection priority, cash flow analysis. DO NOT USE WHEN: Looking for specific invoice (use hcp_list_invoices). GOTCHAS: Invoice endpoint has no server-side filters. For large accounts (29K+ invoices), results are capped at max_invoices. Check metadata.coverage_pct.

Classify a job into one of 13 plumbing service categories using tags, line items, description, and notes. Returns category, confidence level, all detected signals, and a suggested tag. USE WHEN need to categorize a job, auto-tag jobs, understand job mix, classify for reporting. DO NOT USE WHEN looking for job details (use hcp_get_job) or listing jobs (use hcp_list_jobs). GOTCHAS: regex-based, not AI; ~38.8% of jobs fall into general catch-all.

Comprehensive customer intelligence — 9 binary pattern flags for churn risk, payment health, value assessment, and service patterns. Returns all patterns that fire with human-readable explanations.

USE WHEN: "Tell me about this customer", customer history review, churn risk assessment, before sending an estimate, account health check. DO NOT USE WHEN: Looking up customer contact info only (use hcp_get_customer), listing all customers (use hcp_list_customers). GOTCHAS: Requires customer_id (cus_ prefix). Fetches all customer jobs + invoices — may take a few seconds for high-volume customers.

Scan estimates and flag those needing follow-up. Returns stale sent estimates (no customer response after threshold) and approved-but-unscheduled estimates (customer said yes but no job created). USE WHEN contractor asks about pending estimates, revenue at risk, stale quotes, or what needs attention. DO NOT USE WHEN looking for specific estimate details (use hcp_get_estimate).

Generate a Good/Better/Best three-tier estimate skeleton (language only).

USE WHEN: Contractor needs estimate scaffolding — scope language, line item structure, tier framing for a Good/Better/Best presentation. DO NOT USE WHEN: Creating an estimate record in HCP (no API write here), looking up raw historical pricing. GOTCHAS: v0.1.0 is language-only — every tier returns unit_price=null. The connected AI must NOT invent dollar amounts. To get grounded pricing, aggregate the contractor's own past HCP jobs of the same category at runtime. Per-job-type directive content (when present) goes in directive_guidance.

Historical revenue analysis with trend detection and simple projection.

USE WHEN: "How's business?", revenue trends, forecasting, seasonal analysis, "are we growing?", financial planning. DO NOT USE WHEN: Looking for specific job revenue (use hcp_get_job), invoice details (use hcp_list_invoices). GOTCHAS: Projection uses simple moving average -- not ML. Accuracy decreases with fewer months of data. Pipeline shows scheduled jobs only.

Per-technician performance metrics — revenue, job count, avg value, completion rate.

USE WHEN: "How are my techs doing?", performance review, revenue by tech, comparing technicians, identifying top performers. DO NOT USE WHEN: Looking up employee details (use hcp_list_employees), scheduling (use hcp_update_job_schedule). GOTCHAS: Default is last 30 days. Job type breakdown uses regex classification (v7 taxonomy, 25 categories with multi-label support). Uses first assigned tech per job — doesn't split multi-tech jobs.

Detect completed jobs with no invoice — unbilled revenue.

USE WHEN: End-of-day check, "did we invoice everything?", revenue leakage. DO NOT USE WHEN: Looking for job details (use hcp_get_job) or invoice details (use hcp_list_invoices). GOTCHAS: Default date range is today CT. Uses scheduled date filter (not completion date). $0 jobs still flagged.