Predictive customer scores tools

search_predictions: List the ML prediction jobs in a project, or fetch one by ID.
get_customer_prediction_score: Get a customer's current score for a prediction.

search_predictions

Searches the ML prediction jobs in a project, or fetches one by ID. Predictions compute customer-level scores such as churn probability, customer lifetime value, or propensity for a particular action. Omit prediction_id to list all predictions — the response gives you the name, tags, archived flag, and initiative assignment. Pass prediction_id to fetch the full configuration of a single prediction job: model type (churn, lifetime value, or propensity), target event, training settings, and the customer attribute where the score is written.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`prediction_id`	`str`	No	The prediction job ID. Omit to list all predictions; provide to fetch one.

Response parameters

The tool returns a PredictionsResponse when prediction_id is omitted, or a PredictionResponse when it's provided.

When prediction_id is omitted, the PredictionsResponse object has the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[PredictionSummary]`	The prediction jobs defined in the project.
`error`	`str \| null`	Error message if the request failed.

The PredictionSummary object has the following fields:

Field	Type	Description
`id`	`str`	The prediction job's unique ID.
`name`	`str`	The prediction job's display name.
`archived`	`bool`	Whether the prediction has been archived.
`tags`	`list[str]`	User-defined tags.
`initiative_id`	`str \| null`	The initiative this prediction belongs to, if any.
`created`	`any \| null`	Unix timestamp of when the prediction was created.
`created_by_display_name`	`str`	Display name of the creator.
`edited`	`float \| null`	Unix timestamp of the last edit.
`edited_by_display_name`	`str`	Display name of the last editor.

When prediction_id is provided, the PredictionResponse object has the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`Prediction \| null`	The full prediction job definition.
`error`	`str \| null`	Error message if the request failed.

The Prediction object adds the following field on top of the summary record:

Field	Type	Description
`definition`	`any \| null`	The prediction model configuration: model type (churn, lifetime value, or propensity), target event, training settings, and the output customer attribute.

get_customer_prediction_score

Returns the current prediction score for one customer in one prediction job. The tool reads the prediction's output attribute name from the job definition and then looks up that attribute on the customer's properties. The response includes the score value, the last update timestamp, the prediction's name, and the model type.

If the score is null, the model has not yet written a score for this customer. That can happen when the model has not run since the customer was created, or when the customer didn't meet the model's training criteria.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`prediction_id`	`str`	Yes	The prediction job ID returned by `search_predictions`.
`customer_id`	`str`	Yes	The internal customer ID returned by `list_customers`.

Response parameters

The tool returns a CustomerPredictionScoreResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`prediction_name`	`str \| null`	The prediction job's display name.
`model_type`	`str \| null`	The model type, for example `churn`, `ltv`, or `propensity`.
`output_attribute`	`str \| null`	The customer property where the prediction score is stored.
`score`	`any \| null`	The customer's current prediction score. Null if the score hasn't been computed yet.
`last_update`	`float \| null`	Unix timestamp of when the score was last updated. Null if the score has never been set.
`error`	`str \| null`	Error message if the request failed.