# MCP server reference

Every tool PYLO's MCP server lists, generated from the server's own list.

PYLO runs a Model Context Protocol server, so Claude and other agents can read a workspace's figures and, with the right token, carry out setup actions. This reference is generated from the list of tools the server itself returns, so it always matches what an agent sees.

## Connecting

- Endpoint: `https://api.pylosystem.com/mcp`, streamable HTTP, JSON-RPC.
- Authentication: a PYLO API token sent as `Authorization: Bearer <token>`. An owner or admin creates one under Settings, then API tokens, with the MCP scope. The Claude plugin can sign in with OAuth instead; see [the Claude plugin](/docs/claude-plugin).
- A workspace token reads only its own workspace, and every tool refuses another. An agency token can read each workspace in its agency and names the one it wants with `workspaceId`.
- A member's own token lists different tools, which read only that member's own figures. They are listed at the end.

## Tools at a glance

| Tool | What it does |
|---|---|
| `list_workspaces` | Workspaces |
| `get_setup_status` | Setup status |
| `get_metric_definitions` | Metric definitions |
| `get_metric` | One metric |
| `get_call_kpis` | Call figures |
| `get_booking_outcomes` | Cancellations and reschedules |
| `get_payment_kpis` | Payment figures |
| `get_funnel` | Funnel |
| `list_leads` | Leads |
| `get_lead_journey` | Lead journey |
| `list_calls` | Calls |
| `list_payments` | Payments |
| `get_commission` | Commission |
| `get_eod_compliance` | End of day compliance |
| `get_webinar` | Webinars |
| `get_integration_health` | Integration health |
| `list_flow_runs` | Flow runs |
| `list_audit_events` | Audit log |
| `get_data_trust` | Data trust |
| `list_reconciliation_items` | Reconciliation items |
| `get_source_coverage` | Source coverage |
| `get_rep_activity` | Rep activity |
| `get_pickup_heatmap` | Pick-up heatmap |
| `list_cadence_violations` | Cadence violations |
| `get_ad_scorecard` | Ad scorecard |
| `get_kill_scale_list` | Kill or scale list |
| `get_content_scorecard` | Content scorecard |
| `get_posting_cadence` | Posting cadence |
| `get_booking_thread` | Booking thread |
| `get_show_rate_drivers` | Show-rate drivers |
| `list_unrecovered_no_shows` | Unrecovered no-shows |
| `get_outcomes` | Outcomes |
| `list_vault_keys` | Keys held |
| `get_speed_to_lead` | Speed to lead |
| `get_price_book` | Price book |
| `list_price_drift` | Price drift |
| `list_change_log` | Change log |
| `compare_before_after` | Before and after |
| `get_target_plan` | Target plan |
| `get_pace` | Pace to target |
| `get_capacity` | Calendar capacity |
| `get_allocation_suggestions` | Lead allocation suggestions |
| `get_attribution` | Attribution |
| `get_call_analysis` | Call analysis |
| `get_objection_report` | Objection report |
| `get_segment_report` | Segment report |
| `get_statement` | Statement |
| `get_client_economics` | Client economics |
| `get_operator_pnl` | Operator P&L |
| `list_unlinked_recordings` | Unlinked recordings |
| `plan_blueprint` | Plan a workspace |
| `get_plan` | A plan |
| `request_plan_approval` | Ask for approval |
| `apply_plan` | Apply a plan |
| `create_connect_link` | Connect link |
| `get_connect_status` | Connect status |
| `test_vault_key` | Test a key |
| `request_proxy_token` | Proxy token for a script |
| `run_test_lead` | Run a test lead |
| `get_test_run` | A test run |
| `void_call` | Void calls |

## Reading tools

### `list_workspaces`

**Workspaces**

The workspaces this token can read, each with its id, name, currency and tier. Call this first with an agency token, to find the workspaceId every other tool takes. A workspace token gets its one workspace.

No arguments.

### `get_setup_status`

**Setup status**

The eleven setup steps for a workspace, each done, waiting, in progress or not started, with what finishes it and, when it is waiting, on what. Use it to see what is left before a workspace is live. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `get_metric_definitions`

**Metric definitions**

What PYLO's metrics mean, from the metric registry: the definition, the numerator and the denominator by name, the exclusions and the period rule. Use it before quoting a figure, to say exactly what it counts. Pass metric for one, prefix for a family (rate., cash., calls.), or neither for every declared metric. Never returns a value: get_metric does. Refuses an id the registry has not declared.

| Argument | Type | Required | Description |
|---|---|---|---|
| `metric` | string | no | One registry id, for example rate.show. |
| `prefix` | string | no | Every declared id starting with this, for example rate. |

### `get_metric`

**One metric**

One metric for a period: the value, the numerator and denominator with their labels and counts, the exclusions and the period rule. A rate is a fraction, never a percentage. A figure PYLO cannot produce comes back as unavailable with the reason, never as zero. Use it to answer a question like "show rate, last 30 days". Refuses an id the registry has not declared. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `metric` | string | yes | The registry id, for example rate.show or cash.collected. |
| `from` | string | no | Start of the period, YYYY-MM-DD. Defaults to 30 days ago. |
| `to` | string | no | End of the period, YYYY-MM-DD. Defaults to today. |
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `get_call_kpis`

**Call figures**

Every call figure for a period in one answer: booked, live, qualified, closed, no-shows, cancellations, reschedules and disqualifications, with the show rate, the booked to held, booked to cancelled and booked to rescheduled rates beside it, the close rate, the qualified close rate and the disqualification rate, each with both sides. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `from` | string | no | Start of the period, YYYY-MM-DD. Defaults to 30 days ago. |
| `to` | string | no | End of the period, YYYY-MM-DD. Defaults to today. |
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `get_booking_outcomes`

**Cancellations and reschedules**

Of the calls booked into a period, how many were cancelled and, counted apart, how many were rescheduled, broken down by funnel, source, setter and closer. Every row carries both sides of both rates, for example 6 of 40 calls cancelled. A reschedule is never counted as a cancellation. A row labelled Not recorded holds the calls with no value for that breakdown, so each breakdown adds up to the workspace total. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `from` | string | no | Start of the period, YYYY-MM-DD. Defaults to 30 days ago. |
| `to` | string | no | End of the period, YYYY-MM-DD. Defaults to today. |
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `get_payment_kpis`

**Payment figures**

Cash collected, outstanding, after fees and by kind for a period, plus revenue booked, deals closed and the two averages, each in the workspace's currency. Use list_payments for the rows behind them. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `from` | string | no | Start of the period, YYYY-MM-DD. Defaults to 30 days ago. |
| `to` | string | no | End of the period, YYYY-MM-DD. Defaults to today. |
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `get_funnel`

**Funnel**

One funnel's stages for a period, with each stage's count and the conversion to the next, and whether each figure is counted, reported on an end-of-day form, or a gap PYLO cannot see. Refuses a funnel PYLO does not have. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `from` | string | no | Start of the period, YYYY-MM-DD. Defaults to 30 days ago. |
| `to` | string | no | End of the period, YYYY-MM-DD. Defaults to today. |
| `funnel` | string: vsl, dm, free_community, webinar | no | Which funnel. Defaults to vsl. |
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `list_leads`

**Leads**

Leads created in a period, newest first, with their source, status, owners (the assigned setter and closer) and UTMs. For one lead's whole history use get_lead_journey. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `from` | string | no | Start of the period, YYYY-MM-DD. Defaults to 30 days ago. |
| `to` | string | no | End of the period, YYYY-MM-DD. Defaults to today. |
| `limit` | number | no | How many to return. Defaults to 100, capped at 500. |
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `get_lead_journey`

**Lead journey**

Everything PYLO holds about one lead, in time order: how they arrived, every attribution touch, every call and its outcome, every payment with its currency, and every flow run. The tool to call in the thread of a booked call. Refuses without a leadId. A lead in another workspace is not found. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `leadId` | string | yes | The lead's PYLO id. |
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `list_calls`

**Calls**

Calls scheduled in a period, newest first, with outcome, the closer, setter and SDR slots, and whether each was voided or filed as an internal booking. Voided calls are left out unless includeVoided is true. For figures rather than rows use get_call_kpis. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `from` | string | no | Start of the period, YYYY-MM-DD. Defaults to 30 days ago. |
| `to` | string | no | End of the period, YYYY-MM-DD. Defaults to today. |
| `limit` | number | no | How many to return. Defaults to 100, capped at 500. |
| `includeVoided` | boolean | no | Include voided calls, each marked with its reason. |
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `list_payments`

**Payments**

Payments and instalments paid or due in a period, with status, whether each is the initial payment, and verification. Amounts are as stored, in their currency, never converted. Read only: PYLO has no tool that refunds, pays out or edits a payment. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `from` | string | no | Start of the period, YYYY-MM-DD. Defaults to 30 days ago. |
| `to` | string | no | End of the period, YYYY-MM-DD. Defaults to today. |
| `limit` | number | no | How many to return. Defaults to 100, capped at 500. |
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `get_commission`

**Commission**

What each team member is owed for a period, in the workspace's currency, with every line behind it: the call, the slot held, the cash, the rate and the rule that set the rate. Read only: PYLO never pays anybody. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `from` | string | no | Start of the period, YYYY-MM-DD. Defaults to 30 days ago. |
| `to` | string | no | End of the period, YYYY-MM-DD. Defaults to today. |
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `get_eod_compliance`

**End of day compliance**

End-of-day reports filed against those expected, per team member and role, for a period. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `from` | string | no | Start of the period, YYYY-MM-DD. Defaults to 30 days ago. |
| `to` | string | no | End of the period, YYYY-MM-DD. Defaults to today. |
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `get_webinar`

**Webinars**

Webinar events with registrations, attendance, pitch and booking counts, and the show rate, booking rate and replay conversion rate, each with both sides. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `from` | string | no | Start of the period, YYYY-MM-DD. Defaults to 30 days ago. |
| `to` | string | no | End of the period, YYYY-MM-DD. Defaults to today. |
| `eventId` | string | no | One event, instead of every event in the period. |
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `get_integration_health`

**Integration health**

For each provider: whether it is connected, when PYLO last received data from it, what it can and cannot see, and what would fix it. Never returns a credential. Use it before trusting a figure that depends on a provider, or to find what an integration needs. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `list_flow_runs`

**Flow runs**

Runs of the workspace's flows (lead intake, booking, cancellation, outcome, payment, hand-off) in a period, newest first, with status and failures. Says so when flows are not built on this deployment. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `from` | string | no | Start of the period, YYYY-MM-DD. Defaults to 30 days ago. |
| `to` | string | no | End of the period, YYYY-MM-DD. Defaults to today. |
| `limit` | number | no | How many to return. Defaults to 100, capped at 500. |
| `flow` | string | no | One flow, for example lead_intake. |
| `status` | string | no | Only runs in this status, for example failed. |
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `list_audit_events`

**Audit log**

Audit log entries in a period, newest first: who or which token changed what, before and after. Says so when the audit log is not built on this deployment. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `from` | string | no | Start of the period, YYYY-MM-DD. Defaults to 30 days ago. |
| `to` | string | no | End of the period, YYYY-MM-DD. Defaults to today. |
| `limit` | number | no | How many to return. Defaults to 100, capped at 500. |
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `get_data_trust`

**Data trust**

Can this workspace's figures for a period be trusted? Every check (silent inbound streams against their four-week baseline, outcome filing, source coverage, cash reconciliation, connection identity) with its status, its reasons in plain sentences and the evidence behind them, and an overall trust flag: ok, or degraded with the reasons. Quote the reasons beside any figure from a degraded period. Days are UTC days. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `from` | string | no | Start of the period, YYYY-MM-DD. Defaults to 30 days ago. |
| `to` | string | no | End of the period, YYYY-MM-DD. Defaults to today. |
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `list_reconciliation_items`

**Reconciliation items**

Cash that does not reconcile in a period: collected payments with no deal behind them, and closed deals whose cash has no payment behind it, largest first, each with its currency. Also the open items waiting on the reconciliation screen. Both sides are PYLO's own records; the processors' ledgers are not read. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `from` | string | no | Start of the period, YYYY-MM-DD. Defaults to 30 days ago. |
| `to` | string | no | End of the period, YYYY-MM-DD. Defaults to today. |
| `limit` | number | no | How many to return. Defaults to 100, capped at 500. |
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `get_source_coverage`

**Source coverage**

How many leads, bookings and closes in a period have a known source, by entry point (form, CRM, calendar, DM close form, import), with both counts. Use it to find where UTMs are being dropped. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `from` | string | no | Start of the period, YYYY-MM-DD. Defaults to 30 days ago. |
| `to` | string | no | End of the period, YYYY-MM-DD. Defaults to today. |
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `get_rep_activity`

**Rep activity**

Per rep per day: dials, connects (by call length, not the dialler's answered flag), pick-up rate, conversations over 3 minutes and talk time, with the EOD's reported dials beside the system's and the activity alerts, callbacks kept (the next call within the workspace's window of the promised time) and the leads that went dead with no connect. Give a teamMemberId for one rep. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `from` | string | no | Start of the period, YYYY-MM-DD. Defaults to 30 days ago. |
| `to` | string | no | End of the period, YYYY-MM-DD. Defaults to today. |
| `teamMemberId` | string | no | One rep's team member id. |
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `get_pickup_heatmap`

**Pick-up heatmap**

Dials and pick-up rate by London hour and weekday, and by the number each rep dialled from, with a number flagged as burned when it picks up at under half the rep's average on at least 20 dials. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `from` | string | no | Start of the period, YYYY-MM-DD. Defaults to 30 days ago. |
| `to` | string | no | End of the period, YYYY-MM-DD. Defaults to today. |
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `list_cadence_violations`

**Cadence violations**

Follow-ups to a lead that had not picked up sooner than the workspace's minimum gap, and leads called more times in a day than its rules allow, with the rules used. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `from` | string | no | Start of the period, YYYY-MM-DD. Defaults to 30 days ago. |
| `to` | string | no | End of the period, YYYY-MM-DD. Defaults to today. |
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `get_ad_scorecard`

**Ad scorecard**

Pack 09 3.7. Per ad in a period: spend, impressions, clicks, the leads whose utm_content is the ad's id or name, their booked calls and cash, cash return on spend and cost per booked call, each with its numerator and denominator. Also each hook's share of spend and the majority hook, and fatigue (frequency, and click-through against the ad's first 3 days). Money is per currency and never converted. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `from` | string | no | Start of the period, YYYY-MM-DD. Defaults to 30 days ago. |
| `to` | string | no | End of the period, YYYY-MM-DD. Defaults to today. |
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `get_kill_scale_list`

**Kill or scale list**

Pack 09 3.7. Which ads to scale (cash return above 4x) and which to kill (below 1x on meaningful spend, or cost per booked call more than twice the account's, including no bookings after 7 days), each with the reason and the spend a kill would recover. A list only: PYLO never pauses or edits an ad. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `from` | string | no | Start of the period, YYYY-MM-DD. Defaults to 30 days ago. |
| `to` | string | no | End of the period, YYYY-MM-DD. Defaults to today. |
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `get_content_scorecard`

**Content scorecard**

Pack 09 3.7. YouTube and Instagram posts in a period: views, outlier score against the channel average (2x or more is an outlier), and the buyers and cash each post converted, with how each buyer was tied to it (UTM, DM keyword, the buyer's own answer, first touch). Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `from` | string | no | Start of the period, YYYY-MM-DD. Defaults to 30 days ago. |
| `to` | string | no | End of the period, YYYY-MM-DD. Defaults to today. |
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `get_posting_cadence`

**Posting cadence**

Pack 09 3.7. Posts per channel per complete week against the workspace's commitment, the share of weeks that met it, and an alert for every committed week with nothing published. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `from` | string | no | Start of the period, YYYY-MM-DD. Defaults to 30 days ago. |
| `to` | string | no | End of the period, YYYY-MM-DD. Defaults to today. |
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `get_booking_thread`

**Booking thread**

One booking from first booked to its final state: each reschedule (who moved it and why), a cancellation with who cancelled and the reason, the pre-call touches, and the lead time. Give a threadId or any callId on it. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `threadId` | string | no | The booking thread's id. |
| `callId` | string | no | Any call on the thread. |
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `get_show_rate_drivers`

**Show-rate drivers**

Show rate with and without each driver (a setter confirming, the prospect replying, a group chat, a reminder, a setter booking it, booking within 3 days), counts on both sides, and "too few to compare" below the minimum sample. Also the booked to held, cancel, reschedule and no-show recovery rates. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `from` | string | no | Start of the period, YYYY-MM-DD. Defaults to 30 days ago. |
| `to` | string | no | End of the period, YYYY-MM-DD. Defaults to today. |
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `list_unrecovered_no_shows`

**Unrecovered no-shows**

No-shows in the period whose lead has not booked again since. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `from` | string | no | Start of the period, YYYY-MM-DD. Defaults to 30 days ago. |
| `to` | string | no | End of the period, YYYY-MM-DD. Defaults to today. |
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `get_outcomes`

**Outcomes**

How the calls in a period ended, counted by outcome. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `from` | string | no | Start of the period, YYYY-MM-DD. Defaults to 30 days ago. |
| `to` | string | no | End of the period, YYYY-MM-DD. Defaults to today. |
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `list_vault_keys`

**Keys held**

The keys PYLO holds for the workspace's key-based tools, as metadata only: the tool, the account behind the key, whether its last test passed, when it was last used, when it expires and when it is due for rotation. Never a key or any part of one. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `get_speed_to_lead`

**Speed to lead**

Leads that arrived recently and have no call yet, longest wait first, each with minutes waiting and a link to open it in PYLO. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `withinMinutes` | number | no | How far back to look, in minutes. Defaults to 120, capped at a week. |
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `get_price_book`

**Price book**

Each programme's versions: price, payment plan options, deposit rule, bonuses and the date each took effect, with the close rate while each was in force (both sides). Plus, for the period, the discount rate, pay in full share and price realisation, each with both sides. Says so when offer versions are not switched on. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `from` | string | no | Start of the period, YYYY-MM-DD. Defaults to 30 days ago. |
| `to` | string | no | End of the period, YYYY-MM-DD. Defaults to today. |
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `list_price_drift`

**Price drift**

Deals in a period whose price drifted: sold at an earlier version's price, or at a price different from the version in force with no reason recorded. Each with the list price, the price agreed and the version. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `from` | string | no | Start of the period, YYYY-MM-DD. Defaults to 30 days ago. |
| `to` | string | no | End of the period, YYYY-MM-DD. Defaults to today. |
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `list_change_log`

**Change log**

Dated changes in a workspace, newest first: price or offer, team, script, funnel or page, ad or social account restrictions, integration outages, launches and promos. Some PYLO records itself, the rest people and agents add. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `from` | string | no | Start of the period, YYYY-MM-DD. Defaults to 30 days ago. |
| `to` | string | no | End of the period, YYYY-MM-DD. Defaults to today. |
| `limit` | number | no | How many to return. Defaults to 100, capped at 500. |
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `compare_before_after`

**Before and after**

Key figures in equal windows either side of a moment or a change log entry (14 days each by default): show rate, close rate, average cash per deal, discount rate, pay in full share and price realisation, each with both sides for both windows. A side under the minimum sample (20 by default) comes back as too few to compare, with its counts. It shows what changed alongside the entry, never what the entry caused. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `at` | string | no | The moment, YYYY-MM-DD or a timestamp. Or pass changeId. |
| `changeId` | string | no | A change log entry's id, whose date is the moment. |
| `days` | number | no | Days each side. Defaults to 14, capped at 90. |
| `minSample` | number | no | The smallest side worth a rate. Defaults to 20. |
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `get_target_plan`

**Target plan**

Works back from a cash target to the closes, held calls, bookings, leads and daily dials it needs, in a best, average and worst case from the last three months' rates. Every input rate comes with its numerator, denominator and month; where the workspace's own data is too thin, the workspace's stated rate is used and the plan says so. Uses the month's cash target, or the monthly cash goal, unless cashTarget is given. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `cashTarget` | number | no | A cash figure to plan for, instead of the month's target. |
| `month` | string | no | YYYY-MM. Defaults to this month. |
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `get_pace`

**Pace to target**

Actual to date against each target pro-rated for the month so far, with a projected finish and the rate behind it, for the workspace and for each closer and setter against their own target or personal goal. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `get_capacity`

**Calendar capacity**

How full the closers' calendars are over the next two weeks, from their real Calendly availability, how many weeks remain until they are full at the current booking growth, and whether to consider adding a closer (projected over the threshold, 85% by default, for two weeks). Says what is missing when availability cannot be read. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `get_allocation_suggestions`

**Lead allocation suggestions**

Closers ranked by cash per booked call and close rate over 90 days, and suggested priority changes under the workspace's rules. Suggestions only: routing stays in the calendar or the CRM. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `get_attribution`

**Attribution**

Leads and closes by campaign, with the close rate over LEADS, which is not comparable with the close rate over live calls. Covers the workspace's whole history, which the answer says in its notes. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `get_call_analysis`

**Call analysis**

One call's analysed fields (objections, stated budget, decision-maker, next step, phases and the rest), each with the quote and timestamp it rests on and whether a rep confirmed, edited or rejected it. Cash is never among them. Says so when call analysis is not built on this deployment. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `callId` | string | yes | The call. |
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `get_objection_report`

**Objection report**

Objections on analysed calls in a period: the share of calls raising each type, by closer, and a topic signal when one reaches 30% of 20 or more calls. Also next steps on no-close calls, median pitch and discovery minutes and the discount rate. Confirmed fields only unless includeUnconfirmed, and then labelled. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `from` | string | no | Start of the period, YYYY-MM-DD. Defaults to 30 days ago. |
| `to` | string | no | End of the period, YYYY-MM-DD. Defaults to today. |
| `closerId` | string | no | One closer's calls. |
| `funnel` | string | no | One lead source, for example vsl_funnel. |
| `includeUnconfirmed` | boolean | no | Count fields no rep has confirmed yet. The answer says how many. |
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `get_segment_report`

**Segment report**

Close rate, AOV and cash per booked call by stated budget band, decision-maker present and country, stated budget against what was paid, and each scorer's lead scores against outcomes. Cash from payments only. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `from` | string | no | Start of the period, YYYY-MM-DD. Defaults to 30 days ago. |
| `to` | string | no | End of the period, YYYY-MM-DD. Defaults to today. |
| `funnel` | string | no | One lead source, for example vsl_funnel. |
| `includeUnconfirmed` | boolean | no | Count fields no rep has confirmed yet. The answer says how many. |
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `get_statement`

**Statement**

A client workspace's statement for one month under its agency's deal terms: every line, the base and rate each is worked on, the amount, its currency, and whether an operator marked it sent or paid. PYLO works amounts out; it never invoices or moves money. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `month` | string | no | YYYY-MM. Defaults to this month. |
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `get_client_economics`

**Client economics**

What the agency has earned from one client workspace: income per month, lifetime, tenure, trend and any post-launch slide (a month under half of the peak before it). Per currency, never combined. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `from` | string | no | First month, YYYY-MM. Defaults to twelve months ago. |
| `to` | string | no | Last month, YYYY-MM. Defaults to this month. |
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

### `get_operator_pnl`

**Operator P&L**

The agency's income by client and deal shape, less the agency's own costs, per month and currency. Needs an agency token; a workspace token is refused.

| Argument | Type | Required | Description |
|---|---|---|---|
| `from` | string | no | First month, YYYY-MM. Defaults to twelve months ago. |
| `to` | string | no | Last month, YYYY-MM. Defaults to this month. |

### `list_unlinked_recordings`

**Unlinked recordings**

Recordings from Fathom, Fireflies, Gong or Grain that PYLO could not place on a call, newest first, each with why and the calls that day it could belong to. Refuses a workspace the token was not issued for (refused.cross_workspace).

| Argument | Type | Required | Description |
|---|---|---|---|
| `workspaceId` | string | no | Which workspace. Leave it out with a workspace token, which reads only its own. An agency token names one of the ids list_workspaces returns. Any other id is refused. |

## Action tools

These change PYLO, so each needs a token carrying its scope. A plan is shown before anything is applied.

### `plan_blueprint`

**Plan a workspace**

Plans a new or existing workspace from a template and the client's overrides, or from a whole blueprint, and returns every change (create, update, no-op or blocked with the reason) without doing any of it. Needs config:plan. Only an agency token can plan a new workspace. A workspace or member token acts on its own workspace only.

Changes PYLO. Needs a token with the `config:plan` scope.

| Argument | Type | Required | Description |
|---|---|---|---|
| `newWorkspace` | boolean | no | True to plan a new workspace. Otherwise pass workspaceId. |
| `workspaceId` | string | no | Which workspace. An agency token names one of its agency's; a workspace or member token acts on its own and may leave it out. |
| `template` | string | no | A template key, from the agency's templates. |
| `version` | number | no | The template version. Defaults to its latest. |
| `overrides` | object | no | The client's intake, merged over the template: workspace, team, rates, SMS bodies and the rest. |
| `blueprint` | object | no | A whole blueprint, instead of a template and overrides. |

### `get_plan`

**A plan**

A plan's state and every change in it, with each change's result once it is applied. Needs config:plan.

Changes PYLO. Needs a token with the `config:plan` scope.

| Argument | Type | Required | Description |
|---|---|---|---|
| `planId` | string | yes | The plan's id, from plan_blueprint. |

### `request_plan_approval`

**Ask for approval**

Sends a plan to the workspace's owners and admins to approve in the app. Use it when this token has no config:apply, or when a person should approve in the app rather than in the conversation. Needs config:plan.

Changes PYLO. Needs a token with the `config:plan` scope.

| Argument | Type | Required | Description |
|---|---|---|---|
| `planId` | string | yes | The plan's id, from plan_blueprint. |

### `apply_plan`

**Apply a plan**

Applies a plan a person has approved, with an idempotency key: the same key never applies twice. A plan older than a day, or one whose workspace changed since it was made, is refused: plan again. Needs config:apply. Names any API tokens it issued but never returns their values.

Changes PYLO. Needs a token with the `config:apply` scope.

| Argument | Type | Required | Description |
|---|---|---|---|
| `planId` | string | yes | The plan's id, from plan_blueprint. |
| `idempotencyKey` | string | yes | 8 to 200 characters, fresh per apply. Reuse it only to retry the same apply. |

### `create_connect_link`

**Connect link**

Creates one link the client opens to connect their own tools (OAuth or a write-only key field, never through the conversation). Returns the URL once. Needs connect:links. A workspace or member token acts on its own workspace only.

Changes PYLO. Needs a token with the `connect:links` scope.

| Argument | Type | Required | Description |
|---|---|---|---|
| `workspaceId` | string | no | Which workspace. An agency token names one of its agency's; a workspace or member token acts on its own and may leave it out. |
| `providers` | array | no | Provider keys to connect. Defaults to the plan's or the workspace's missing ones. |
| `optional` | array | no | Providers offered but not required. |
| `planId` | string | no | The plan the link belongs to, if any. |
| `expiresInDays` | number | no | 1 to 30. Defaults to 7. |

### `get_connect_status`

**Connect status**

Each provider on a connect link: pending, connected, failed or unavailable, with the reason. Connected is read back from the connection itself. Needs connect:links. A workspace or member token acts on its own workspace only.

Changes PYLO. Needs a token with the `connect:links` scope.

| Argument | Type | Required | Description |
|---|---|---|---|
| `workspaceId` | string | no | Which workspace. An agency token names one of its agency's; a workspace or member token acts on its own and may leave it out. |
| `linkId` | string | yes | The link's id, from create_connect_link. |

### `test_vault_key`

**Test a key**

One cheap read at the tool with the saved key, on PYLO's server: does it still work, and for which account. Records the result, notices a replaced key or a changed account, and returns what it found. Never the key. Needs config:plan. A workspace or member token acts on its own workspace only.

Changes PYLO. Needs a token with the `config:plan` scope.

| Argument | Type | Required | Description |
|---|---|---|---|
| `workspaceId` | string | no | Which workspace. An agency token names one of its agency's; a workspace or member token acts on its own and may leave it out. |
| `provider` | string | yes | The key's provider, from list_vault_keys. |

### `request_proxy_token`

**Proxy token for a script**

A short-lived token (15 minutes by default, 60 at most) an operator's own script uses to read (GET only) from Close or the GoHighLevel private integration through PYLO, which adds the key on its server. For scripts, not for agents: an agent reads through PYLO's tools. Shown once. Needs admin:tokens. A workspace or member token acts on its own workspace only.

Changes PYLO. Needs a token with the `admin:tokens` scope.

| Argument | Type | Required | Description |
|---|---|---|---|
| `workspaceId` | string | no | Which workspace. An agency token names one of its agency's; a workspace or member token acts on its own and may leave it out. |
| `provider` | string | yes | close or ghl_private. |
| `ttlMinutes` | number | no | Minutes it lasts, 1 to 60. Defaults to 15. |

### `run_test_lead`

**Run a test lead**

Starts a simulated test lead: PYLO drives its own intake and stops before anything reaches a person. Returns the run and its trace so far. Needs test:run. A live run files a real CRM lead and sends real messages, so it needs a person to confirm it: mode live is refused here, and the operator starts it in the app under Settings, Test lead. A workspace or member token acts on its own workspace only.

Changes PYLO. Needs a token with the `test:run` scope.

| Argument | Type | Required | Description |
|---|---|---|---|
| `workspaceId` | string | no | Which workspace. An agency token names one of its agency's; a workspace or member token acts on its own and may leave it out. |
| `mode` | string: simulated, live | no | Defaults to simulated. Live is refused through this tool: a person starts it in the app. |
| `funnel` | string: typeform, dms | no | Simulated only. Defaults to typeform. |
| `email` | string | no | Live only: the address the test submission uses. |
| `waitMinutes` | number | no | Live only: how long PYLO waits for the booking. |

### `get_test_run`

**A test run**

A test lead run's trace, step by step, each passed, failed or skipped with its timing and reason. Leave runId out for the latest. Needs test:run. A workspace or member token acts on its own workspace only.

Changes PYLO. Needs a token with the `test:run` scope.

| Argument | Type | Required | Description |
|---|---|---|---|
| `workspaceId` | string | no | Which workspace. An agency token names one of its agency's; a workspace or member token acts on its own and may leave it out. |
| `runId` | string | no | The run's id. Defaults to the latest. |

### `void_call`

**Void calls**

Voids calls that should not count (a test, a duplicate, spam), with a reason. Refused for a call with money collected or commission paid on it. A voided call can be restored in the app. Needs config:apply. A workspace or member token acts on its own workspace only.

Changes PYLO. Needs a token with the `config:apply` scope.

| Argument | Type | Required | Description |
|---|---|---|---|
| `workspaceId` | string | no | Which workspace. An agency token names one of its agency's; a workspace or member token acts on its own and may leave it out. |
| `callIds` | array | yes | The calls, by id, from list_calls. |
| `reason` | string: test, duplicate, spam, other | yes | Why. |
| `note` | string | no | Required when the reason is other. |

## A member's own tools

### `pylo_my_board`

Your own board: your figures for this month, the same ones PYLO shows you on My Board. Use it for questions about your own calls, closes and cash. It refuses anything about other members or the workspace as a whole.

No arguments.