Faraday

Create a propensity Outcome for questions such as who will churn, convert, buy again, donate, attend, upgrade, respond, or become high value. The platform learns from the account's person attributes and behavior, then scores people by how likely they are to attain the behavior represented by a Cohort. Required: `name` and `attainment_cohort_id`, the Cohort of people who attained it. Optional: `eligible_cohort_id` limits who can be scored, while `attrition_cohort_id` supplies clear counterexamples. After the model builds, inspect its analysis and add the Outcome to a Scope payload to publish scores for retention, acquisition, lead ranking, or other action. With `preview: true`, the configuration is saved but the model does not build; otherwise creation starts an asynchronous build whose progress appears in the returned resource's job state.

create_outcome

Create a Persona Set to discover distinct, data-driven groups within a customer, donor, lead, fan, or other Cohort. The platform clusters people by shared attributes, which answers questions such as 'what kinds of buyers do we have?' without requiring segment rules in advance. Required: `name` and `cohort_id`. Leave `number_of_clusters` unset to choose the cluster count automatically; set it only when the use case requires an exact count. `preview: true` saves the configuration without building it. After the asynchronous build finishes, use `get_persona_set_dimensions` to understand each group, rename its Personas with `update_persona`, and add the Persona Set to a Scope payload when each person should receive a segment assignment.

create_persona_set

Create a reusable Place for geographic questions such as people near stores, households inside a service area, or leads in a sales territory. Use the Place in a Cohort's place conditions to include or exclude people by location; that Cohort can then drive modeling, market analysis, or delivery. Required: `name` and exactly one location source: `geojson` or `addresses`. Address inputs are resolved asynchronously, so poll the Place's `status` before using it. The schema defines the accepted GeoJSON shapes and address fields.

create_place

Create a Recommender for per-person next-best products, content, offers, locations, courses, categories, or upgrades. It learns from one interaction Stream, such as transactions, views, plays, or visits, and the chosen Stream property names the item being recommended. Required: `name`, `stream_name`, and `stream_property_name`; inspect the Stream first to confirm that it has enough recent events and the item property is populated. After the model builds, inspect its analysis and add it to a Scope payload to publish ranked recommendations. `preview: true` saves the configuration without building it. This feature is experimental and may require plan access.

create_recommender

Create a Scope that selects people and produces person-level fields for delivery. Its population combines Cohorts and exclusions; its payload can include identity fields, predictions, Persona membership, recommendations, Traits, Attributes, Cohort membership, and proximity to Atlas locations via `payload.location`. A Scope computes this data but does not send it until a Target uses it. Required: `name`, `population`, `payload`, and `preview`. An empty `population.cohort_ids` can select the entire available US population. Start in preview and confirm the population and fields before turning off preview mode.

create_scope

Find or create a Stream, the typed event channel for a kind of customer behavior such as transactions, signups, cancellations, page views, donations, clicks, attendance, or support events. Datasets emit events into Streams; behavioral Cohorts query them, Outcomes learn from them, and Recommenders use them as interaction histories. Names are lowercase identifiers that start with a letter and may contain digits or underscores. If the name already exists, the existing Stream is returned unchanged. Dataset `output_to_streams` mappings usually create Streams automatically; invoke this tool only when the Stream must exist before its Dataset mapping is added.

create_stream

Create a Target that sends a Scope's person-level population and payload to a destination. The payload can include identity fields, predictions, Persona membership, recommendations, Traits, Attributes, and Cohort membership. Destinations include ad platforms, email and customer systems, warehouses, files, the Lookup API, and webhooks. Without a Target, a Scope computes context but does not send it anywhere. Required: `name`, `scope_id`, connector-specific `options`, and `representation`; destinations backed by a Connection also require `connection_id`. Creation may send customer data outside Faraday, so confirm the destination, population, payload, representation, filters, and limits with the user before calling this tool.

create_target

Find or create a field for a stable per-person value from the account's own data, such as loyalty tier, lifetime value, preferred category, internal score, or customer status. A Dataset populates it through `output_to_traits`; Cohorts can then select people by the value, models can use it, and Scopes can deliver it through Targets. This tool defines the field but does not upload or return person-level values. `name` must be lowercase snake case and unique within the account. Set `statistical_type` to match the field's meaning.

create_trait

Upload a UTF-8 flat file of customer, order, lead, donor, or event data to the account's Hosted CSV storage. The `content` argument is the raw file body. Use it only when the user asks to add the file to the account. A file with the same directory and filename is replaced, and matching Hosted CSV Datasets are queued to ingest it. This inline tool is for megabyte-scale files; use an S3 or GCS Connection for larger or recurring files. This tool is disabled in this MCP client by policy. Ask the user to complete this action in Faraday Enterprise at https://app.faraday.ai.

create_upload

Create a use case, the account's durable record of one customer problem and how the configured resources solve it. Use this for goals such as churn prevention, lead scoring, donor reactivation, audience delivery, or market expansion so later operators and agents can recover the intent behind the resource graph. Required: `title`. Optional `preface` fields record the background, problem, and solution; optional `technical_details` markdown records the machine-readable annex the reviewer and configuration auditor consume, and `draft` marks the use case a work in progress. There is no need to link resources to it: the configuration audit works out which resources serve each use case.

create_use_case

Create an HTTPS webhook endpoint so another system can react when asynchronous resource work fails or finishes with new output, such as refreshing a dashboard after Target delivery, starting work after Dataset ingestion, or alerting on a model error. Subscribe with `resource.errored` and/or `resource.ready_with_update`. The response returns the signing secret exactly once; store it before discarding the response so the receiver can verify later deliveries. If it is lost, delete and recreate the endpoint.

create_webhook_endpoint

Delete an unapproved migration owned by the current FIG v2 account. Approved migrations cannot be deleted, including ones support has rolled back, though a rolled-back migration stops blocking a new migration for the same accounts.

delete_migration

Delete a supported resource. By default the resource is soft-deleted and hidden while stored references remain; `hard_delete: true` removes it outright. Deletion is refused while blocking downstream dependencies remain, so inspect the dependency graph first. Archive the resource instead when a reversible pause is required. Accounts, Attributes, uploads, webhook endpoints, and use cases use other lifecycle tools.

delete_resource

Permanently delete one hosted CSV file. The call returns 404 when the file does not exist. Every Dataset for the same directory is queued to remove rows that came from the deleted file, and every Atlas for the same directory is rebuilt without it, which can change downstream populations and deliveries.

delete_upload

Permanently delete a webhook endpoint. Delivery stops and the signing secret cannot be recovered. Disable the endpoint instead when a reversible pause is required.

delete_webhook_endpoint

Ask Faraday: describe the BigQuery schema for aggregate analysis over the Faraday Identity Graph, so you can write a query against it. This is step one of Ask Faraday (also called Insights), the way to ask aggregate questions about this account's customers and markets; when the user says "Ask Faraday", start here. CALL THIS FIRST — before writing any insights query — then call `search_attributes` to get the exact column names and bucket boundaries for the attributes your question needs. Returns: the tables available to this account and their fully-qualified BigQuery names, every column with its meaning, which aggregate functions the privacy policy permits, the k-anonymity threshold, a worked example query in this account's own column names, and the caveats that change how results should be read. Use this for distribution and comparison questions — income distributions of customers vs. non-customers nearby, what differentiates two groups, how store catchments compare, how a customer base has shifted by acquisition quarter. These views return aggregates only and never person-level rows, so this is not a way to retrieve data about individuals; use a Scope delivered through a Target for that. Read-only, and costs nothing to call.

describe_insights_schema

Queue an immediate rebuild when fresh work is needed before the normal schedule, such as pulling new source rows, re-evaluating a Cohort, retraining an Outcome, recomputing a Scope, redelivering a Target, or refreshing Migration Lookup API metrics. The resource type determines the work: a Connection is re-read, a Dataset is ingested, an Atlas is rebuilt, a Cohort is evaluated, a model or Scope is rebuilt, a Target is published, and a Migration refreshes metrics (and performs the account move when already approved). The call returns after queuing; inspect the resource job state for completion. Repeated calls made before processing starts may collapse into one run. Confirm the intent before forcing a Target because it sends data to the external destination immediately.

force_update_resource

Get the account named by `account_id`, including its name, parent account, contract renewal date and monthly cost, job status, and identity-graph configuration.

get_account

One configuration audit of the account named by `account_id`, in full. `changes` lists what would bring the account in line with its use cases — resources to `create`, and resources to `update` with the attributes that differ; a change with `appliable: false` needs a person (it sets a credential, or would require replacing the resource). An empty `changes` list means the account is aligned. `orphaned_resources` are resources no use case asks for — advisory only. `conflicts` are resources that use cases disagree about, for the knowledgebase owner to reconcile. `use_cases` says whether the account serves each use case. After an apply, each change carries `applied_at` or `apply_error`; a change with neither was not attempted.

get_account_audit

Billing detail for the account named by `account_id`: paid/outstanding QuickBooks invoices, recorded payments, and the per-feature usage rows that drive overage billing. Subaccounts of a parent are billed at the parent, so calling this on a subaccount typically returns empty invoice/payment arrays.

get_account_billing

Retrieve the full dependency graph for the account — every edge between Connections, Datasets, Atlases, Streams, Cohorts, Outcomes, Persona Sets, Recommenders, Scopes, Targets, Places, Traits, Attributes, and Market Opportunity Analyses. Use this to orient on an existing account, understand how a use case is assembled, answer what a change or lifecycle action would affect, or plan an unblocking sequence before deletion. Each edge has `upstream_*` and `downstream_*` fields with id, literate name, type, status, archive timestamp, and the timestamps of last config edit, input read, and output write.

get_graph

The foundational context for the account named by `account_id`: who the client is, what they do, the challenges they face, and the future state Faraday is helping them reach. It is the account-level framing that the individual use cases sit within. The overview is markdown and can be empty (a fresh account with nothing written yet returns `{ content: "" }` and no `revision_id`). The returned `revision_id` is the optimistic-locking witness — pass it back to `update_account_overview` to detect concurrent edits.

get_account_overview

Retrieve a specific saved revision of the account overview by `revision_id`. Returns the full `content` markdown along with the revision's `created_at`. Use this to inspect history surfaced by `list_account_overview_revisions` — pair it with `update_account_overview` (passing the LIVE revision_id) to roll the overview back to a prior phrasing.

get_account_overview_revision

Most recent usage-metrics snapshot for the account named by `account_id`, sourced from the latest 'metrics_dashboard' usage event. Per-metric `limit` is intentionally null here — contractual limits live at the parent and are only emitted by get_account_usage_all. Use this for a quick 'how much has been consumed this period' read.

get_account_usage

Usage-metrics snapshot rolled up across the account named by `account_id` and every direct subaccount. Per-metric values are summed; contractual limits come from the parent account only (subaccounts do NOT raise the limit). Use this when checking whether a customer is approaching their plan ceiling.

get_account_usage_all

Retrieve a single Atlas by ID, including its `output_to_locations` column mapping, the columns detected in the source data, connection options (with secrets concealed), and the row/locatable counts from its most recent build. `counts.rows` is how many source rows were read and `counts.locatable` how many produced a location — a gap between them means rows could not be placed. Use `get_locations` to read the locations themselves, and `get_atlas_unplaced_rows` to see which rows could not be placed and why.

get_atlas

Page through an Atlas's build logs, newest first: one entry per build that re-read the Atlas's source or re-derived its locations from it, including builds that failed. A build that found nothing to do has no entry. Each log has its status, any error, when it started and finished, and a row funnel in `metrics`: rows in the source, rows that could not be parsed (malformed), rows placed as locations, and rows dropped per reason. A metric is absent when the build did not reach that stage. Use this to see why an Atlas has fewer locations than its source has rows, or why a build failed, then `get_atlas_unplaced_rows` to read the dropped rows. Pagination is `limit` (capped at 100) + `offset`; `total_count` is included in the response envelope.

get_atlas_ingress_logs

Page through the source rows one Atlas build could not place as a location, each with its mapped source values as they appeared in the file and a `reason` naming what went wrong with the row's locator — for example an address that could not be geocoded, a missing or non-numeric latitude, or a geometry that could not be read. Reads the most recent build that has finished, successfully or not, unless `log_id` names another from `get_atlas_ingress_logs`; a build still running is skipped because it may not have written its rows yet and has not stored its counts. Each build keeps at most 1,000 rows, and only the Atlas's 10 most recent builds keep theirs, so `total_count` is at most 1,000 and an older build returns none; the build's log `metrics` hold the true count per reason. Returns `{log_id, unplaced_rows, total_count}`, where `log_id` is the build read — null, with no rows, when no build of the Atlas has finished yet. Pagination is `limit` (capped at 100) + `offset`.

get_atlas_unplaced_rows

Get one Attribute definition by ID, including its source Stream, aggregation, value property, interpretation, categories or breaks, status, and effective permissions. The definition can describe a person-level customer fact, behavior, interest, score, or other value. This response returns metadata about the field, not any person's value or the source records used to derive it. A Scope can still include person-level values for delivery through a Target.

get_attribute

Retrieve a single Cohort by ID, including its Trait, Attribute, Stream-event, Place, Atlas `location_conditions`, and recency conditions plus the latest `population_count`. Use this to understand exactly who a model or Scope refers to before reusing or changing the Cohort.

get_cohort

Get cohort membership counts over time, bucketed by day, week, and month. Useful for sanity-checking that a freshly-edited Cohort behaves as intended (spot step-changes after a config edit), charting how a customer base / churn cohort / lead pool is trending, or confirming a 'recent activity' cohort is the expected size before wiring it into an Outcome's training population.

get_cohort_membership

Retrieve a single Connection by ID, including the configured `options` (with secrets like passwords / private keys concealed) and the latest job state. The connection's `directionality` field indicates whether it can be used for ingress, egress, or both.

get_connection

Get one Dataset configuration by ID, including its column-to-Trait mappings, identity fields, place mapping, event Stream outputs, connection options with secrets concealed, and row counts.

get_dataset

Page through every time Faraday pulled from this Dataset's upstream, with row counts, byte counts, durations, and any errors. Useful for debugging 'why didn't my new rows show up?', charting ingestion volume over time, or spotting a sudden cliff that points at an upstream issue. Pagination is `limit` (capped at 100) + `offset`; `total_count` is included in the response envelope.

get_dataset_ingress_logs

Page through the locations an Atlas build produced — each with its geometry, its `reference_key`, and the properties its Atlas defines. Pass `atlas_id` to read one Atlas's locations, or omit it to read every location in the account. Use this to confirm a build placed the locations you expected, or to look up the reference keys to filter on downstream. Rows a build could not place are not locations; read them with `get_atlas_unplaced_rows`. Pagination is `limit` (capped at 100) + `offset`; `total_count` is included in the response envelope.

get_locations

Retrieve one Market Opportunity Analysis by ID, including its Outcome, Scope, optional Persona, job state, overall opportunity summary, and Google Sheets or Slides report URLs once ready. Use the completed report artifacts to inspect market size and location in detail.

get_market_opportunity_analysis

Retrieve one migration by ID, including the linked FIG v1 and FIG v2 accounts, dataset and target pairs, Lookup API pull counts, approval time, finish time, and job status. Read `account_tree_relationship` before concluding anything about the account hierarchy: when it is `siblings`, the move leaves every parent alone, so a finished migration is expected to leave the FIG v2 account under the same parent it always had, next to the now-suspended FIG v1 account. Only a FIG v2 account created underneath its FIG v1 account changes parent.

get_migration

Retrieve one Outcome by ID, including its attainment, eligibility, and optional attrition Cohort references, predictor and bias settings, preview and build status, summary performance values, and report URL when available. Use `get_outcome_analysis` for feature importance and full validation metrics.

get_outcome

Retrieve a trained Outcome's structured analysis: feature importance and direction, lift curves and tables, ROC curve and AUC, metrics tables, modeling strategies, available tenure splits, and bias measurements. Use this to answer whether the model performs well, which inputs drive it, and how much lift its highest-ranked people provide. Use `get_outcome_report` when a ready-to-read HTML report is wanted instead of structured data.

get_outcome_analysis

Get a 1-hour signed URL pointing at the Outcome's HTML report — the standalone page Faraday generates with the model's marketing-grade summary, feature importances, and validation plots. Returns `{ url, expires_at, filename }`. MCP tools can't stream HTML, so fetch the URL separately when the body is needed.

get_outcome_report