Workflow rules

Tools act on real business records. Resolve record names before writes, ask which record is intended when matches are ambiguous, and use the workspace timezone for relative dates. Get UUIDs for assignments from list_users.

Drafting and sending

create_quote and create_invoice create records. To deliver them, call send_notification with the record ID as module_id and type: "quote_to_customer" or "invoice_to_customer". Confirm customer-facing communication before sending.

Setting a status to sent is bookkeeping, not delivery. Initial sends move the status for you. Use reminder: true for reminders without an initial-send transition. Delivery uses workspace notification settings and SMS consent; the current notification endpoint also requires a contact email.

When creating a quote from a template, pass contact_id so it is addressed to the intended customer. Quote and invoice tool responses include a client URL when the record's public ID and workspace slug are available.

Recording money received

To settle an invoice, call create_payment with:

{
  "object_type": "invoice",
  "object_id": 101,
  "category": "payment",
  "settle_remaining": true
}

Omit amount. The server calculates the balance and records a completed payment. Use the payment method/date supplied by the user; otherwise omit them. Method defaults to Other. Pending payments block settlement.

This does not charge a card or send a receipt. A bare paid-status change is rejected while a balance remains. For a batch, report each invoice's outcome rather than claiming all succeeded after a partial failure.

Recurring work

Choose the tool based on the work:

Before setting up a recurring job, confirm the repeat pattern, end condition, and billing choice. per_visit automatically generates invoices when visits are completed; manual leaves billing to the business. Do not guess this choice.

Appointments cannot repeat on their own. Creating a job with type recurring is also insufficient: the schedule tool establishes the visit series and billing together. New recurring invoices are unsupported.

A custom weekly/monthly pattern needs selected days. A finite duration requires repeat_duration; use repeat_duration_unit: "occurrences" for a fixed count. For job/event schedules, only include repeat_frequency_schedule when repeat_frequency_unit is custom. Timed visits need start and end times unless all-day.

Use update_event with the intended update_scope when changing occurrences. Ask whether the change applies only to this visit or future work before selecting the scope.

Holding and resuming jobs

Use hold_job and confirm whether upcoming appointments should be kept or cancelled. Read the latest job and pass its held_at to resume_job as expected_held_at.

A recurring job needs a resume date only when appointments were cancelled and the schedule has not explicitly ended. Kept appointments continue generating. When all schedules have explicitly ended, omit resume_on: resuming clears the hold without restarting them. Holds do not support service-plan work.

Requests and follow-ups

For a new person asking for work, create_new_lead creates the contact, optional property, and linked request. For an existing request, use convert_request to create the job/quote/invoice and mark the request converted.

“Remind me to call this customer” is a contact task. Set reminders_enabled: true when a notification is wanted; it defaults to false. Use a timezone-bearing due timestamp and resolve the intended time with the user. Completing a recurring task completes that occurrence.

Service plans and subscriptions

A plan is an offering. Creating/editing it charges nobody, and archiving it does not cancel existing subscribers. A subscription represents an enrolled customer and may bill through Stripe.

Use cancel_service_plan_subscription to stop billing, after confirmation. Inspect billing_stopped / stripe_cancelled; never report that billing stopped when only the BlueSuite record changed. force: true can leave Stripe billing active. There is no MCP subscription-creation or per-subscriber price/cadence-edit tool.

Equipment and files

Company equipment is the business's own assets; installed equipment belongs at customer properties. Record company equipment service history with create_equipment_note, rather than only completing a task. Retire/sell assets when history should remain.

Installed equipment automatically schedules warranty/replacement reminders by default. Review auto_reminders_enabled before creating a unit with those dates.

Use upload_file for chat attachments, supported downloadable URLs, or base64 data. Use list_files to inspect existing files, and update_upload for metadata. Workspace line-item images require module_type: "workspace" and category: "line_item".