Assembled

Create one or more forecast adjustments layered on the master forecast. Each adjustment applies an 'add' or 'multiply' operation to the forecasted contact volume over a time range, optionally scoped to a single queue. Use this when the user wants to manually raise or lower the forecast (e.g. anticipating a marketing campaign, a holiday bump, or correcting a known under-forecast). Important constraints: - Timestamps may be Unix seconds, a date 'YYYY-MM-DD' (resolved in the company timezone; a bare end date is taken through the end of that day), or an ISO-8601 datetime, and must align to 15-minute boundaries (resolve to multiples of 900). end_time must be strictly greater than start_time. - 'add' values apply additively per 15-minute bucket and may be negative. - 'multiply' values apply as a multiplier and must be > 0 (1.0 is a no-op). - Submit all related adjustments in a single call when possible; the API regenerates downstream forecasts once per request. Args: create_adjustments_request: Adjustments to create. - adjustments (required, non-empty): list of adjustments. Each has start_time, end_time, channel, optional queue external ID, operation ('add' or 'multiply'), value, and optional name. - channel (required per adjustment): e.g. "phone", "email", "chat". To resolve a user-facing channel phrase (e.g. "calls", "voice") to the correct value, call `get_workforce_config()` first and match on `channels[].name` (case-insensitive). If no channel matches, ask the user for clarification instead of guessing. - queue (optional per adjustment) must be a queue external ID (UUID), not a name. To resolve a user-facing queue name (e.g. "Refunds") to an external ID, call `get_workforce_config()` first and match on `queues[].name`. If no queue matches, ask for clarification. Omit `queue` to adjust the channel-level master forecast. - name (optional per adjustment): a concise human-readable label (a handful of words) summarizing the user's intent, e.g. "Valentine's Day bump", "Holiday campaign", "Refunds staffing correction". This becomes the title shown in the UI's adjustments manager, so it should read well to a human, not be a restatement of the channel/queue/value. Strongly prefer to set `name` whenever the user's request gives you enough context to summarize it — adjustments without a name show up as unlabeled cards in the UI. Omit only when the user's intent is truly ambiguous. Returns CreateForecastAdjustmentsResult containing: - forecast_adjustments: the created adjustments as returned by the server, each with a server-assigned id and created_at. - error: populated if the request failed.

create_forecast_adjustments

Publish one overtime ('OT') or voluntary-time-off ('VTO') slot. What this does to staffing: - 'overtime' offers agents additional productive time. Opt-in lifts Capacity, so staffing_net (= Capacity − Required) moves up. Post OT when staffing_net is negative. - 'voluntary_time_off' offers agents unpaid time off. Opt-in lowers Capacity, so staffing_net moves down. Post VTO when staffing_net is positive. Always auto-published and auto-approved server-side. No draft or manager approval step. Args: request: Create parameters. - type (required): 'overtime' or 'voluntary_time_off'. - channel (required): canonical channel name from get_workforce_config().channels[].name (e.g. 'phone', 'email', 'chat'). - start_time / end_time (required): slot window as Unix seconds, a date 'YYYY-MM-DD' (resolved in the company timezone; a bare end date is taken through the end of that day; a bare start date equal to today starts the slot now, and one before today is rejected), or an ISO-8601 datetime. Must satisfy end_time - start_time >= 3600 (1 hour minimum); start_time must not be more than 60s in the past; end_time must be no more than 15 days out. - capacity (optional): max agent opt-ins the slot can absorb. OT stores positive, VTO stores negative (the tool forwards your value as-is). Omit for uncapped. - queue / site / team / skill (optional): external_id (UUID) or name from the matching list in get_workforce_config(). The client resolves names to external_ids before sending to apiserver. Value-column input is not supported. - id (optional): slot external_id UUID. Omit to auto-generate; pass an existing slot's id to overwrite it (replace semantics). - include_default_events (optional, VTO-only): when True, VTO replaces default productive events in the slot window even if the agent has no existing event there. Ignored for OT. - dry_run (optional, default False): when True, validate and return a preview of the slot without hitting the server. No row is persisted, no notifications fire, and no filter resolution runs (preview echoes your raw inputs). Recommended when the user's ask is ambiguous: call with dry_run=True, show the preview, confirm, then call again with dry_run=False and the preview's id (so the real call overwrites rather than creating a sibling row). Returns CreateOvertimeAndVoluntaryTimeOffResult with: - slot: persisted slot (or the preview on dry_run). On a real call, queue/site/team/skill are the external_id UUIDs apiserver stored. On dry_run, those fields echo your raw inputs (resolution is skipped) — treat the preview as a shape check, not a canonical identifier lookup. - dry_run: echoes the request flag. - error: populated on failure. FilterResolutionError errors (queue/site/team/skill name not found) include field + value so the LLM can self-correct via get_workforce_config. Notes: - Publishing a slot does NOT immediately move staffing_net in forecast_vs_actual — it moves only when agents opt in. Don't double-post while waiting; re-issue with the same id to resize. - Call get_overtime_and_voluntary_time_off first to check existing slots in the window before publishing a new one.

create_overtime_and_voluntary_time_off

Get scheduled activities for agents matching a filter over a small time window. Use this when the user asks who is scheduled, what coverage looks like for a queue, or what an agent's day looks like. Required scoping ---------------- At least one of `queue`, `site`, `team`, or `skill` MUST be set; `channel` alone is rejected. To resolve a user-facing name to an external ID, call `get_workforce_config()` first and match on the appropriate `*[].name`. If nothing matches, ask the user to clarify rather than guessing. If the server rejects the request with 400, the rejection details from the upstream JSON body — `agent_count`, `filters_applied`, `tier_caps`, and a `suggested_action` string — arrive as keys on `error` itself; a non-JSON rejection arrives as text in `error["error"]` instead. **Read `suggested_action` and follow it verbatim on retry rather than guessing permutations.** Args: schedule_request: The request parameters. - filters (at least one required): external ID or value of the filters to apply. Resolve names to IDs via `get_workforce_config()`. - channel (optional): e.g. "phone", "email", "chat". Used to further narrow within a queue/site/team/skill filter; not accepted alone. - start_time / end_time (required): Unix seconds, a date 'YYYY-MM-DD' (resolved at midnight in the company timezone; a bare end date is taken through the end of that day), or an ISO-8601 datetime. Window must be at most 7 days; the server may impose a tighter cap based on resolved agent count. - schedule_id (optional): an alternate schedule's external ID. Omit for the company's master schedule. To enumerate non-master schedules (drafts, alternates, scenarios), call `get_workforce_config(filter_type="schedules")` first; each returned entry has an `id` (pass as `schedule_id` here) and a `live` flag identifying the master. Returns GetScheduleResult containing: - activities: list of {id, agent_id, type_name, type_id, start_time, end_time}. `type_name` is the human-readable event type label (e.g. "Shift", "Lunch") — use it for display; `type_id` is the stable external ID for that type, for passing to other tools. - agents: minimal {id, name} projection of agents whose activities are returned. - error: populated on failure. For tier-rule rejections (400) the upstream JSON body — including `suggested_action` — is merged into `error` as structured keys (a non-JSON body lands in `error["error"]` as text); read `suggested_action` to rectify and retry.

get_schedule

Get the current date and time, in both UTC and the company's timezone. Call this before constructing any date range from a relative phrase ("today", "yesterday", "last week", "last 30 days"). Use the company-local date so a "day" matches the Assembled UI. Do not guess the current date from memory — it is likely about a year out of date.

get_current_time

List existing forecast adjustments for the company. Forecast adjustments are manual overrides layered on top of the master forecast. Each adjustment has an operation ('add' or 'multiply') and a value applied over a time range for a given channel (and optionally queue). Args: adjustments_request: Filter and pagination parameters. - start_time / end_time (optional): Unix seconds, a date 'YYYY-MM-DD' (resolved in the company timezone; a bare end date is taken through the end of that day), or an ISO-8601 datetime. Adjustments overlapping this window are returned. If omitted, all times are returned. - channel (optional): e.g. "phone", "email", "chat". To resolve a user-facing channel phrase (e.g. "calls", "voice") to the correct value, call `get_workforce_config()` first and match on `channels[].name` (case-insensitive). If no channel matches, ask the user for clarification instead of guessing. - queue (optional): queue external ID to filter by. To resolve a user-facing queue name (e.g. "Refunds") to an external ID, call `get_workforce_config()` first and match on `queues[].name`. If no queue matches, ask for clarification. - limit / offset (optional): pagination controls. Returns GetForecastAdjustmentsResult containing: - forecast_adjustments: list of adjustments with id, start_time, end_time, channel, queue, operation, value, created_at. - count, limit, offset: pagination metadata. - error: populated if the request failed.

get_forecast_adjustments

Get forecasted vs actual comparison metrics from Assembled. Returns bucketed comparisons of forecasted vs actual values for a given channel (and optional queue) over the requested time range. This covers volume (contacts/cases), handle time, service level, staffing (required/scheduled/net) and related metrics. Use this tool when the user wants to understand how actuals compared to the forecast, rather than raw forecasts alone. The bucket interval and schedule are chosen automatically: bucket size is picked from the window length (15m for <1 day, 1h for 1 day to 1 week, 1 day for >1 week) and the company's master schedule is always used. These are intentionally not exposed as tool arguments. Windows longer than ~6 months (184 days) are rejected: forecasted vs actual is intended for operational analysis. For year-plus historical trend analysis, use the analytics/metrics tool instead, or split the question into several shorter windows and call this tool per window. Args: forecasted_vs_actual_request: The request parameters. - channel (required): e.g. "phone", "email", "chat". The aggregate "all" channel is not supported. To resolve a user-facing channel phrase (e.g. "calls", "voice") to the correct value, call `get_workforce_config()` first and match on `channels[].name` (case-insensitive). If no channel matches, ask the user for clarification instead of guessing. - start_time / end_time (required): Unix seconds, a date 'YYYY-MM-DD' (resolved in the company's timezone, so a day matches the Assembled UI; a bare end date is taken through the end of that day), or an ISO-8601 datetime. - queue (optional): queue external ID to filter by. To resolve a user-facing queue name (e.g. "Refunds") to an external ID, call `get_workforce_config()` first and match on `queues[].name`. If no queue matches, ask for clarification. - limit / offset (optional): pagination controls. Leave unset in most cases; the tool pages the full window in one call by default. `limit` is capped at 500 (the server's max page size); larger values are clamped to 500 rather than requesting more buckets. Check `total` vs `len(forecasted_vs_actual)` in the response to detect truncation and re-invoke with `offset`. Returns GetForecastedVsActualResult containing: - forecasted_vs_actual: list of buckets with start_time, end_time, channel, queue, and forecasted/actual metric pairs. Fields present per bucket depend on the channel's configuration; unavailable metrics are None. - total, limit, offset: pagination metadata. - effective_start_time / effective_end_time: the window actually queried after snapping to the bucket interval grid; may differ from the requested start_time/end_time by up to one bucket on each side. Use these (not the request) when describing the window covered by the response. - bucket_seconds: bucket interval used for this response. - error: populated if the request failed.

get_forecasted_vs_actual

Get the catalog of available metrics and instructions for using the query_metrics() tool. Use this to determine available namespaces, metrics, and dimensions.

get_metrics_catalog_and_query_usage

List existing overtime ('OT') and voluntary-time-off ('VTO') slots. Use this before posting a new OT/VTO offer to avoid duplicates, or to verify uptake on a slot you previously posted (capacity vs. how many agents have opted in). Each row includes 'remaining_capacity = max(0, abs(capacity) - num_approved_requests)' as a derived convenience — the number of additional agent opt-ins the slot can still accept. Works for both OT (positive capacity) and VTO (negative capacity); remaining_capacity is None for uncapped slots. Args: request: Filter parameters. - start_time / end_time (optional): Unix seconds, a date 'YYYY-MM-DD' (resolved in the company timezone; a bare end date is taken through the end of that day), or an ISO-8601 datetime. If both omitted, defaults to now → now + 1 day. If one is omitted, the other is filled by ±1 day. The resolved window must not exceed 15 days. - channel (optional): canonical channel name from get_workforce_config().channels[].name (e.g. 'phone', 'email', 'chat'). ABAC scoping still applies when omitted. - queue / site / team / skill (optional): external_id (UUID) or name from the matching list in get_workforce_config(). Prefer the id when the user already supplied one; otherwise look up by name. Value-column input is not supported — resolve names via get_workforce_config first. - type (optional): 'overtime' or 'voluntary_time_off' to restrict results. Applied client-side after fetch. Returns GetOvertimeAndVoluntaryTimeOffResult with: - slots: matching slots ordered by start_time. Each slot's queue / site / team / skill fields hold the external_id (UUID) that matches get_workforce_config().*.id. - count: number returned (after type filter). - truncated: True if results were capped at 500; narrow the window. - error: populated if the request failed. Notes: - Both drafts ('is_published': false) and published slots are returned; ignore drafts unless the user explicitly asks about them. - Posting a new OT/VTO slot does not immediately move 'staffing_net' in forecast_vs_actual — agents must accept first. Don't double-post while waiting for opt-ins.

get_overtime_and_voluntary_time_off

Per-agent totals (in seconds, clipped to the requested window) of: - approved overtime (`overtime_seconds`), - approved paid time off (`pto_seconds`), - accepted voluntary time off (`vto_seconds`). Use this when the user asks "how much OT / PTO / VTO is each agent scheduled for next week" or similar workforce-management questions. Each row is one agent in the resolved filter scope, including agents with zero activity (their buckets are 0). Scope rules: - At least one of `queue`, `site`, `team`, or `skill` is required. Channel alone is not a sufficient scope. - The window must be > 0 and <= 366 days. - Filter scope is capped at 2000 active agents. If your filter resolves above that, the response's `error` field will contain a structured `suggested_action` string telling you which filter to add (e.g. "add a team, site, or skill filter to scope queue=..."). Read it and retry. Args: request: Filter / window / pagination parameters. - start_time / end_time (required): Unix seconds, a date 'YYYY-MM-DD' (resolved at midnight in the company timezone; a bare end date is taken through the end of that day), or an ISO-8601 datetime. - queue / site / team / skill (optional): pass external_id (UUID) or name from get_workforce_config(). Names resolve client-side. - channel (optional): adds a channel sub-scope (does not count toward the at-least-one-non-channel-filter requirement). - include_pending (optional, default false): also count status='pending' rows alongside 'approved'. Use when planning capacity *before* approval cycles close; otherwise omit so the totals reflect what's actually on the schedule. Returns GetAgentTimeSummariesResult with: - summaries: one row per agent (`agent_id`, `agent_name`, `overtime_seconds`, `pto_seconds`, `vto_seconds`). - start_time / end_time: the window the server actually used. - included_pending: echoes the request flag. - error: populated on failure. For 400 cap rejections, contains the server's structured body verbatim (`error`, `agent_count`, `filters_applied`, `suggested_action`). For filter-name resolution failures, `error_type='FilterResolutionError'` plus the offending field and value.

get_agent_time_summaries

Queues, sites, skills, teams, channels, and schedules for the company (bounded responses). Always returns `summary` (total counts per dimension) and the full `channels` list (usually small). Entity rows are either a **browse page** for one dimension, **search hits**, or empty when `summary_only` is true. **Browse (no `query`)** — paginate one dimension at a time: - Omit `filter_type` to default to `queues` (page through queue names). - Use `filter_type` = `sites`, `skills`, `teams`, or `schedules` to list those instead. The `schedules` dimension returns the company's active schedules sorted master-first; each entry has a `live` flag (true for the master) and an `id` that can be passed as `schedule_id` to `get_schedule` to read a non-master schedule. - Use `page` (1-based) and `page_size` (max 500; default 100). - Check `has_more` for additional pages. **Search (`query` set)** — substring match on names (case-insensitive): - Omit `filter_type` to search **all** of queues, sites, skills, teams, and schedules (each type capped at 50 matches to keep payloads small). - Set `filter_type` to a single type to search only that list (up to `page_size` matches, capped at 500). - Use this to resolve a user phrase (e.g. "support", "draft") to an external `id` before calling tools that require UUIDs. **Summary only** — set `summary_only=true` to get counts plus `channels` only (no queue/site/skill/team/schedule rows). Use for "how many queues do we have?" Note: `query_metrics` uses names directly; use this tool when another tool needs external IDs or you need to confirm an entity exists. Returns GetWorkforceConfigResult with `summary`, `channels`, pagination metadata (`page`, `page_size`, `filter_type`, `has_more`, `summary_only`), optional echoed `query`, and typed lists (`queues`, `sites`, `skills`, `teams`, `schedules`).

get_workforce_config