Predictive customer scores tools

list_predictions: List the ML prediction jobs in a project.
get_prediction: Get the full configuration of a prediction job.
get_customer_prediction_score: Get a customer's current score for a prediction.

list_predictions

Lists every ML prediction job defined in a project. Predictions compute customer-level scores such as churn probability, customer lifetime value, or propensity for a particular action. The response gives you the name, tags, archived flag, and initiative assignment.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.

Response parameters

The tool returns a PredictionsResponse object with 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.

get_prediction

Returns the full configuration for 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`	Yes	The prediction job ID returned by `list_predictions`.

Response parameters

The tool returns a PredictionResponse object with 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 `list_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.