Skills › Knowledge Work Plugins › business-pulse › data_sources.md
data_sources.md
173 lines · small-business/skills/business-pulse/reference/data_sources.md at 2574e29
Most marks come from matching words in the file, so treat them as pointers.
1# Data Sources
3Exact mapping from each pulse section to the MCP tool that produces it. **Dispatch all calls in a single parallel batch** — do not pull serially.
Data Sources
Exact mapping from each pulse section to the MCP tool that produces it. Dispatch all calls in a single parallel batch — do not pull serially.
Raw lines 1 to 4Uses an outside tool MCP :3
Starts an agent Dispatch :3
5## Cash & Finance (the ledger)
7Whichever ledger is connected feeds this section — MYOB, NetSuite, QuickBooks, Xero, or Zoho Books, as peers (`../../../shared/connector-neutrality.md`). The QuickBooks table is first only because it is the longest; the Xero, NetSuite, MYOB, and Zoho Books tables below map the same metrics. Amounts carry the business's currency code (`../../../shared/currency-and-locale.md`); thresholds are in that currency.
Cash & Finance (the ledger)
Whichever ledger is connected feeds this section — MYOB, NetSuite, QuickBooks, Xero, or Zoho Books, as peers (../../../shared/connector-neutrality.md). The QuickBooks table is first only because it is the longest; the Xero, NetSuite, MYOB, and Zoho Books tables below map the same metrics. Amounts carry the business's currency code (../../../shared/currency-and-locale.md); thresholds are in that currency.
9### QuickBooks
11| Metric | Tool | Notes |
12|---|---|---|
13| Cash / bank balance | `cash_flow_quickbooks_account` | Current balance; show delta vs. prior week if available |
14| MTD revenue | `profit_loss_quickbooks_account` | Current month vs. prior month. Read income and expenses from the report rows or `monthlyBreakdown`; the response's top-level `totalExpenses`, `grossProfit`, and `grossProfitMargin` report 0 / 100% against real rows (a defect in the response shape), so never read them |
15| Outstanding receivables | QuickBooks invoice list | Filter to open/unpaid |
16| AR aging | QuickBooks invoice list | Group by days since due: 0–30, 31–60, 61+ |
17| Overdue invoices | QuickBooks invoice list | Filter to due_date > 30 days past; name customer + amount + days overdue |
19**Ledger state handling**: if the ledger's cash read returns an error, empty response, or "not connected" state, mark the entire Cash section as "n/a — ledger unavailable" (naming which) and continue. Do not retry.
QuickBooks
| Metric | Tool | Notes |
|---|---|---|
| Cash / bank balance | cash_flow_quickbooks_account | Current balance; show delta vs. prior week if available |
| MTD revenue | profit_loss_quickbooks_account | Current month vs. prior month. Read income and expenses from the report rows or monthlyBreakdown; the response's top-level totalExpenses, grossProfit, and grossProfitMargin report 0 / 100% against real rows (a defect in the response shape), so never read them |
| Outstanding receivables | QuickBooks invoice list | Filter to open/unpaid |
| AR aging | QuickBooks invoice list | Group by days since due: 0–30, 31–60, 61+ |
| Overdue invoices | QuickBooks invoice list | Filter to due_date > 30 days past; name customer + amount + days overdue |
Ledger state handling: if the ledger's cash read returns an error, empty response, or "not connected" state, mark the entire Cash section as "n/a — ledger unavailable" (naming which) and continue. Do not retry.
Raw lines 9 to 2021### Xero
23| Metric | Tool | Notes |
24|---|---|---|
25| Cash / bank balance | `get_cash_position` | Same role as the QuickBooks cash read |
26| MTD revenue, P&L trend | `get_profit_and_loss` | Current month vs. prior |
27| Receivables, AR aging, overdue | `get_aged_receivables` | Name customer + amount + days overdue. (`get_contacts_and_receivables` is deprecated in the Xero server; do not call it) |
Xero
| Metric | Tool | Notes |
|---|---|---|
| Cash / bank balance | get_cash_position | Same role as the QuickBooks cash read |
| MTD revenue, P&L trend | get_profit_and_loss | Current month vs. prior |
| Receivables, AR aging, overdue | get_aged_receivables | Name customer + amount + days overdue. (get_contacts_and_receivables is deprecated in the Xero server; do not call it) |
29### NetSuite
31| Metric | Tool | Notes |
32|---|---|---|
33| Cash, receivables, P&L | `ns_runReport` / `ns_runCustomSuiteQL` | Same metrics, same section |
NetSuite
| Metric | Tool | Notes |
|---|---|---|
| Cash, receivables, P&L | ns_runReport / ns_runCustomSuiteQL | Same metrics, same section |
35### MYOB
37| Metric | Tool | Notes |
38|---|---|---|
39| MTD revenue, P&L trend | `myob_get_profit_loss` | Resolve the financial year first with `myob_get_financial_year_dates` |
40| Receivables, overdue | `myob_get_outstanding_customer_balances` | No cash balance exists in MYOB; leave the cash line as "not available from MYOB" |
MYOB
| Metric | Tool | Notes |
|---|---|---|
| MTD revenue, P&L trend | myob_get_profit_loss | Resolve the financial year first with myob_get_financial_year_dates |
| Receivables, overdue | myob_get_outstanding_customer_balances | No cash balance exists in MYOB; leave the cash line as "not available from MYOB" |
42### Zoho Books
44Every call takes `organization_id` from `list_organizations`.
46| Metric | Tool | Notes |
47|---|---|---|
48| Cash / bank balance | `list_bank_accounts` with `filter_by=Status.Active` | Sum `current_balance` across bank and cash accounts (`bcy_balance` is the same figure in base currency). No history endpoint, so the WoW delta needs the prior pulse's stored figure or is omitted |
49| MTD revenue | `list_invoices` with `date_start`/`date_end` for the month and `response_option=3` | Returns the count and the summed `total`; invoiced revenue, not a P&L — say so. Zoho Books exposes no P&L report endpoint |
50| Outstanding receivables | `list_invoices` with `status=unpaid` and `response_option=3` | Summed `balance` |
51| AR aging, overdue invoices | `list_invoices` with `status=overdue`, sorted by `due_date` | Each carries `due_days` ("Overdue by 323 days"), `customer_name`, `balance`, `email`; bucket by due date yourself |
53Zoho Desk is a separate connector and a separate organisation ID; it feeds the support section below, not this one.
Zoho Books
Every call takes organization_id from list_organizations.
| Metric | Tool | Notes |
|---|---|---|
| Cash / bank balance | list_bank_accounts with filter_by=Status.Active | Sum current_balance across bank and cash accounts (bcy_balance is the same figure in base currency). No history endpoint, so the WoW delta needs the prior pulse's stored figure or is omitted |
| MTD revenue | list_invoices with date_start/date_end for the month and response_option=3 | Returns the count and the summed total; invoiced revenue, not a P&L — say so. Zoho Books exposes no P&L report endpoint |
| Outstanding receivables | list_invoices with status=unpaid and response_option=3 | Summed balance |
| AR aging, overdue invoices | list_invoices with status=overdue, sorted by due_date | Each carries due_days ("Overdue by 323 days"), customer_name, balance, email; bucket by due date yourself |
Zoho Desk is a separate connector and a separate organisation ID; it feeds the support section below, not this one.
Raw lines 42 to 5455## Revenue & Sales (PayPal / Square / Stripe)
57| Metric | Tool | Notes |
58|---|---|---|
59| 7-day settlement total | PayPal transactions | Sum completed settlements in window |
60| Sales trend | PayPal transactions | This 7 days vs. prior 7 days; compute delta |
61| Failed / pending transactions | PayPal transactions | Flag any > 200 (business currency; `thresholds.md`) |
62| Square settlements | Square (if connected) | Same as PayPal — sum + trend |
63| Stripe revenue | Stripe `list_invoices` (if connected) | Paid invoices in window |
64| Stripe failed payments | Stripe API read — charges/payment intents (if connected) | Failed charges in window; flag any > 200 (business currency) |
65| Stripe disputes | Stripe API read — disputes (if connected) | Any dispute opened in window goes to the watch list, named |
67Use whichever payment connectors are available. If both PayPal and Square are connected, report combined and per-source.
Revenue & Sales (PayPal / Square / Stripe)
| Metric | Tool | Notes |
|---|---|---|
| 7-day settlement total | PayPal transactions | Sum completed settlements in window |
| Sales trend | PayPal transactions | This 7 days vs. prior 7 days; compute delta |
| Failed / pending transactions | PayPal transactions | Flag any > 200 (business currency; thresholds.md) |
| Square settlements | Square (if connected) | Same as PayPal — sum + trend |
| Stripe revenue | Stripe list_invoices (if connected) | Paid invoices in window |
| Stripe failed payments | Stripe API read — charges/payment intents (if connected) | Failed charges in window; flag any > 200 (business currency) |
| Stripe disputes | Stripe API read — disputes (if connected) | Any dispute opened in window goes to the watch list, named |
Use whichever payment connectors are available. If both PayPal and Square are connected, report combined and per-source.
Raw lines 55 to 6869## Pipeline (HubSpot)
71| Metric | Tool | Notes |
72|---|---|---|
73| Pipeline by stage | `search_crm_objects` type=deals (`get_crm_objects` needs explicit IDs; see `../../../shared/connector-call-shapes.md`) | Group by deal stage; sum amount |
74| Deals closed this week | `search_crm_objects` | Filter closedate in window, stage = closed-won |
75| Deals gone cold | `search_crm_objects` | Filter `notes_last_updated` > 7 days ago, open stage. That is HubSpot's "Last Activity Date" on deals — there is no `hs_last_activity_date` or `hs_lastactivitydate` property |
76| New leads this week | `search_crm_objects` | Filter createdate in window |
77| Stalled/slipped deals | `search_crm_objects` | Open deals where closedate < today |
Pipeline (HubSpot)
| Metric | Tool | Notes |
|---|---|---|
| Pipeline by stage | search_crm_objects type=deals (get_crm_objects needs explicit IDs; see ../../../shared/connector-call-shapes.md) | Group by deal stage; sum amount |
| Deals closed this week | search_crm_objects | Filter closedate in window, stage = closed-won |
| Deals gone cold | search_crm_objects | Filter notes_last_updated > 7 days ago, open stage. That is HubSpot's "Last Activity Date" on deals — there is no hs_last_activity_date or hs_lastactivitydate property |
| New leads this week | search_crm_objects | Filter createdate in window |
| Stalled/slipped deals | search_crm_objects | Open deals where closedate < today |
79## Commitments (Google Calendar)
81| Metric | Tool | Notes |
82|---|---|---|
83| This week's key items | `list_events` | Filter to current week; surface meetings with customers, deadlines, important holds |
84| Next 7 days | `list_events` | Forward-looking view; highlight anything with external parties |
Commitments (Google Calendar)
| Metric | Tool | Notes |
|---|---|---|
| This week's key items | list_events | Filter to current week; surface meetings with customers, deadlines, important holds |
| Next 7 days | list_events | Forward-looking view; highlight anything with external parties |
86## Watch List (Gmail or Microsoft 365)
88| Metric | Tool | Notes |
89|---|---|---|
90| Urgent threads | `search_threads` | Query: `is:important OR is:starred` in last 7 days |
91| Customer escalations | `search_threads` | Query: terms like "escalation," "complaint," "cancel," "refund," "urgent" in last 7 days |
92| Time-sensitive requests | `search_threads` | Query: `is:unread` + keywords like "deadline," "ASAP," "today" |
94**Gmail fallback**: if the Gmail call errors (auth flaky), skip Watch List silently and add "Gmail unavailable" to the appendix. Do not surface the error in the pulse body.
Watch List (Gmail or Microsoft 365)
| Metric | Tool | Notes |
|---|---|---|
| Urgent threads | search_threads | Query: is:important OR is:starred in last 7 days |
| Customer escalations | search_threads | Query: terms like "escalation," "complaint," "cancel," "refund," "urgent" in last 7 days |
| Time-sensitive requests | search_threads | Query: is:unread + keywords like "deadline," "ASAP," "today" |
Gmail fallback: if the Gmail call errors (auth flaky), skip Watch List silently and add "Gmail unavailable" to the appendix. Do not surface the error in the pulse body.
Raw lines 86 to 9596## Internal Signals (Slack / Teams)
98| Metric | Tool | Notes |
99|---|---|---|
100| Urgent threads | Slack search (if connected) | Threads with @mentions or urgency signals in owner-relevant channels |
101| Action items | Slack search | Messages directed at the owner or tagged for follow-up |
103Every section below this point follows the same rule: include only if the connector is available; omit the section entirely if not.
Internal Signals (Slack / Teams)
| Metric | Tool | Notes |
|---|---|---|
| Urgent threads | Slack search (if connected) | Threads with @mentions or urgency signals in owner-relevant channels |
| Action items | Slack search | Messages directed at the owner or tagged for follow-up |
Every section below this point follows the same rule: include only if the connector is available; omit the section entirely if not.
Raw lines 96 to 104105## Commerce (Shopify, if connected)
107| Metric | Tool | Notes |
108|---|---|---|
109| Orders, revenue, sales trend | `list-orders`, `run-analytics-query` | This 7 days vs. prior 7 |
110| Fulfillment issues | `list-orders` filtered to unfulfilled past promise | Named orders to the watch list |
Commerce (Shopify, if connected)
| Metric | Tool | Notes |
|---|---|---|
| Orders, revenue, sales trend | list-orders, run-analytics-query | This 7 days vs. prior 7 |
| Fulfillment issues | list-orders filtered to unfulfilled past promise | Named orders to the watch list |
112## Fulfillment (Square, if connected)
114| Metric | Tool | Notes |
115|---|---|---|
116| Fulfillment issues | Square orders API via `make_api_request` | Same watch-list treatment as Shopify |
Fulfillment (Square, if connected)
| Metric | Tool | Notes |
|---|---|---|
| Fulfillment issues | Square orders API via make_api_request | Same watch-list treatment as Shopify |
118## Payroll (Gusto, if connected)
120| Metric | Tool | Notes |
121|---|---|---|
122| Next payroll run | `list_payrolls` / `list_pay_periods` | Date and expected amount — the week's biggest cash commitment |
Payroll (Gusto, if connected)
| Metric | Tool | Notes |
|---|---|---|
| Next payroll run | list_payrolls / list_pay_periods | Date and expected amount — the week's biggest cash commitment |
124## Ads (TikTok Ads, if connected)
126| Metric | Tool | Notes |
127|---|---|---|
128| Ad spend, results, cost per result | TikTok reporting (`report_integrated_get`) | Last 7 days vs. prior 7; sits beside the sales trend |
Ads (TikTok Ads, if connected)
| Metric | Tool | Notes |
|---|---|---|
| Ad spend, results, cost per result | TikTok reporting (report_integrated_get) | Last 7 days vs. prior 7; sits beside the sales trend |
130## Card spend (Ramp / Expensify, if connected)
132| Metric | Tool | Notes |
133|---|---|---|
134| Week's card spend | Ramp `ramp_get_transactions` | Sum for window; call out any single transaction > 500 (business currency) |
135| Account balance | Ramp `ramp_get_ramp_business_account_balance` | Read-only |
136| Card spend + missing receipts | Expensify `Search` | Read-only; count expenses without receipts |
Card spend (Ramp / Expensify, if connected)
| Metric | Tool | Notes |
|---|---|---|
| Week's card spend | Ramp ramp_get_transactions | Sum for window; call out any single transaction > 500 (business currency) |
| Account balance | Ramp ramp_get_ramp_business_account_balance | Read-only |
| Card spend + missing receipts | Expensify Search | Read-only; count expenses without receipts |
138## Signatures (DocuSign, if connected)
140| Metric | Tool | Notes |
141|---|---|---|
142| Unsigned envelopes | `getEnvelopes` filtered to sent status | Flag any sitting unsigned > 3 days, named |
Signatures (DocuSign, if connected)
| Metric | Tool | Notes |
|---|---|---|
| Unsigned envelopes | getEnvelopes filtered to sent status | Flag any sitting unsigned > 3 days, named |
144## Internal signals (RingEx Chat, if connected)
146| Metric | Tool | Notes |
147|---|---|---|
148| Urgent team-chat posts | `read_team_chat` | Same role as Slack: escalation keywords, threads needing the owner. Chat only — no call data exists here |
Internal signals (RingEx Chat, if connected)
| Metric | Tool | Notes |
|---|---|---|
| Urgent team-chat posts | read_team_chat | Same role as Slack: escalation keywords, threads needing the owner. Chat only — no call data exists here |
150## Customer Support (Zoho Desk, if connected)
152| Metric | Tool | Notes |
153|---|---|---|
154| Open tickets, escalations | `getTickets` (`status`, `priority`, `sortBy=recentThread`) / `getTicketsMetrics` | Count open; flag any > 48h unresolved and any priority High, named. `getTickets` rejects an `include` parameter — request extra fields with `fields` |
Customer Support (Zoho Desk, if connected)
| Metric | Tool | Notes |
|---|---|---|
| Open tickets, escalations | getTickets (status, priority, sortBy=recentThread) / getTicketsMetrics | Count open; flag any > 48h unresolved and any priority High, named. getTickets rejects an include parameter — request extra fields with fields |
156## Risks scan
158Run these alongside the metric pulls — don't wait for metrics to finish first.
160| Risk | Source | Trigger condition |
161|---|---|---|
162| Overdue AR | Ledger invoices / aged receivables | due_date > 30 days past, unpaid |
163| Stalled deals | HubSpot | Open deal, no activity 7+ days |
164| Slipped deals | HubSpot | Open deal, closedate in past |
165| Urgent mail threads | Gmail or Microsoft 365 | `is:important` or escalation keywords |
166| Failed payments | PayPal / Square / Stripe | Failed or pending > 200 (business currency) |
167| New dispute | Stripe / PayPal | Any dispute opened in window — always a watch-list item |
168| Stale unsigned envelope | DocuSign | Sent envelope unsigned > 3 days |
169| Missing receipts piling up | Expensify | 5+ expenses without receipts in window |
Risks scan
Run these alongside the metric pulls — don't wait for metrics to finish first.
| Risk | Source | Trigger condition |
|---|---|---|
| Overdue AR | Ledger invoices / aged receivables | due_date > 30 days past, unpaid |
| Stalled deals | HubSpot | Open deal, no activity 7+ days |
| Slipped deals | HubSpot | Open deal, closedate in past |
| Urgent mail threads | Gmail or Microsoft 365 | is:important or escalation keywords |
| Failed payments | PayPal / Square / Stripe | Failed or pending > 200 (business currency) |
| New dispute | Stripe / PayPal | Any dispute opened in window — always a watch-list item |
| Stale unsigned envelope | DocuSign | Sent envelope unsigned > 3 days |
| Missing receipts piling up | Expensify | 5+ expenses without receipts in window |
171## Parallelization
173All of the above should fire in a single tool-call batch. A complete pulse is typically 8–15 parallel calls. If one errors, the rest proceed normally and the failed source appears in "Sources unavailable" at the bottom of the pulse.
Parallelization
All of the above should fire in a single tool-call batch. A complete pulse is typically 8–15 parallel calls. If one errors, the rest proceed normally and the failed source appears in "Sources unavailable" at the bottom of the pulse.
Raw lines 171 to 173