Faraday

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 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 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 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.

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 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.

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.

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 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 `guide` markdown records the implementation. After creation, link each Cohort, Outcome, Scope, Target, Recommender, or other resource that implements the use case with `link_resource_to_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.

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.

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.

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

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, or redelivering a Target. 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, and a Target is published. 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.

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

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.

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.

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.

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.

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.

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.

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.

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 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.

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 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.

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.

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.

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, to look up the reference keys to filter on downstream, or to see which rows failed to geocode (they are absent — compare against the Atlas's `counts`). Pagination is `limit` (capped at 100) + `offset`; `total_count` is included in the response envelope.

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.

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.

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 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.

Retrieve a single Persona Set by ID, with each persona's id/name and the source Cohort (as an ID reference).

For every trait, the distribution per persona (over- and under-indexed values, summary stats). Use this to answer 'what makes each persona different?' and to drive a renaming pass that gives each cluster a real name ('the suburban repeat-buyer', 'the price-sensitive lapser', etc.) via `update_persona`. Same data the Faraday UI renders on the persona-set dimensions page.

Retrieve a single Place by ID with its full resolved geometry. Use this to verify a store footprint, service area, territory, or drive-time boundary before using it in a Cohort or changing the source locations.

Retrieve one Recommender by ID, including its interaction Stream, item property, predictor settings, preview state, report URL, and latest build metadata. Use this to confirm what behavior and item the model learns from before reusing or changing it.

Retrieve a Recommender's cross-validation analysis: feature importance plus top-N accuracy, average true-item rank, item distribution, ROC AUC, and ROC curve, with available splits for new or repeat and recognized or unrecognized people. Use this to judge model quality and choose a useful recommendation count before attaching the Recommender to a Scope.

Get one Scope's population and person-level payload configuration, including any Atlas `payload.location` proximity settings, which attach either each person's nearest matching location or every matching location. The response contains configuration, status, columns, and aggregate counts, not person rows or values. Attached Targets can send those rows and values to external systems.

Get score distributions for each Outcome and Recommender in a Scope, comparing the Scope population with each model's eligible population. Use this to see whether the selected population is concentrated in higher or lower score bands and to choose or review Target score thresholds; read the Scope record itself for population counts and output columns.