Custom KPI Tools Query Custom KPI data — user-defined indicators organized into datasets , collected through campaigns , and assigned to facilities via assignments . Each dataset groups related KPIs (e.g. “ESG Social Metrics”), campaigns are time-boxed data collection rounds sent to assigned facilities, and values are the submitted responses.
All Custom KPI tools are read-only . Campaign management, value submission, and invite sending are not exposed through MCP.
list_custom_kpisList Custom KPI definitions for an organization. Returns each KPI with its parent dataset context flattened in.
Parameters: Parameter Type Required Default Description organization_idstring No default org Organization UUID facility_idstring No — Filter KPIs assigned to a specific facility dataset_idstring No — Filter KPIs from a specific dataset
Example response: { "items" : [ { "id" : "kpi-1a2b3c4d-..." , "dataset_id" : "ds-5e6f7a8b-..." , "dataset_name" : "ESG Social Metrics" , "dataset_description" : "Core social indicators for annual reporting" , "name" : "Employee Turnover Rate" , "description" : "Percentage of employees who left during the reporting period" , "unit" : "%" , "value_type" : "percentage" , "required" : true , "sort_order" : 0 , "created_at" : "2025-01-15T10:00:00" , "updated_at" : null }, { "id" : "kpi-9c0d1e2f-..." , "dataset_id" : "ds-5e6f7a8b-..." , "dataset_name" : "ESG Social Metrics" , "dataset_description" : "Core social indicators for annual reporting" , "name" : "Training Hours per Employee" , "description" : null , "unit" : "hours" , "value_type" : "number" , "required" : true , "sort_order" : 1 , "created_at" : "2025-01-15T10:00:00" , "updated_at" : "2025-03-01T14:30:00" } ], "total" : 2 }
Key response fields: Field Description dataset_id / dataset_nameParent dataset context, flattened into each KPI value_typeExpected answer type (see below) unitMeasurement unit (%, hours, kg, etc.) — null for text/boolean/select KPIs requiredWhether a response value is mandatory in campaigns facility_idOnly present when filtering by facility_id
Type Description numberNumeric value (integer or decimal) textFree-form text percentagePercentage value (0–100) dateDate (YYYY-MM-DD) booleanTrue/false selectSingle choice from predefined options
get_custom_kpiGet one Custom KPI definition with full detail — formula, unit, value type, and linked dataset. Use list_custom_kpis first to discover available KPI IDs.
Parameters: Parameter Type Required Default Description dataset_idstring Yes — UUID of the KPI dataset kpi_idstring Yes — UUID of the KPI organization_idstring No default org Organization UUID
Example response: { "id" : "kpi-1a2b3c4d-..." , "dataset_id" : "ds-5e6f7a8b-..." , "dataset_name" : "ESG Social Metrics" , "dataset_description" : "Core social indicators for annual reporting" , "name" : "Employee Satisfaction Score" , "description" : "Overall satisfaction rating from annual survey" , "unit" : null , "value_type" : "select" , "required" : true , "sort_order" : 2 , "created_at" : "2025-01-15T10:00:00" , "updated_at" : null }
list_kpi_datasetsList Custom KPI dataset containers — each dataset groups related KPIs together.
Parameters: Parameter Type Required Default Description organization_idstring No default org Organization UUID
Example response: { "items" : [ { "id" : "ds-5e6f7a8b-..." , "organization_id" : "a1b2c3d4-..." , "name" : "ESG Social Metrics" , "description" : "Core social indicators for annual reporting" , "created_by" : "u1a2b3c4-..." , "updated_by" : null , "created_at" : "2025-01-15T10:00:00" , "updated_at" : null }, { "id" : "ds-3g4h5i6j-..." , "organization_id" : "a1b2c3d4-..." , "name" : "Water & Waste Tracking" , "description" : null , "created_by" : "u1a2b3c4-..." , "updated_by" : null , "created_at" : "2025-03-20T08:30:00" , "updated_at" : null } ], "total" : 2 }
list_kpi_campaignsList data collection campaigns for a specific KPI dataset. Each campaign represents a time-boxed reporting period with a submission deadline.
Parameters: Parameter Type Required Default Description dataset_idstring Yes — UUID of the KPI dataset organization_idstring No default org Organization UUID
Example response: { "items" : [ { "id" : "camp-1a2b3c4d-..." , "dataset_id" : "ds-5e6f7a8b-..." , "name" : "Q1 2025 ESG Collection" , "period_start" : "2025-01-01" , "period_end" : "2025-03-31" , "deadline" : "2025-04-15" , "locked_at" : null , "created_by" : "u1a2b3c4-..." , "updated_by" : null , "created_at" : "2025-01-10T09:00:00" , "updated_at" : null } ], "total" : 1 }
Key response fields: Field Description period_start / period_endThe reporting period this campaign covers deadlineSubmission deadline for assigned facilities locked_atIf set, the campaign is locked and no more submissions are accepted
get_kpi_campaign_valuesGet submitted values/responses for a specific campaign — the actual data collected from facilities.
Parameters: Parameter Type Required Default Description dataset_idstring Yes — UUID of the KPI dataset campaign_idstring Yes — UUID of the campaign organization_idstring No default org Organization UUID pageinteger No 1 Page number sizeinteger No 50 Results per page
Example response: { "items" : [ { "id" : "val-1a2b3c4d-..." , "campaign_assignment_id" : "ca-5e6f7a8b-..." , "assignment_id" : "asgn-9c0d1e2f-..." , "kpi_id" : "kpi-1a2b3c4d-..." , "value_numeric" : 12.5 , "submitted_at" : "2025-04-10T14:30:00" , "submitter_email" : "maria@acme.com" , "submitter_user_id" : "u-3g4h5i6j-..." , "kpi_name" : "Employee Turnover Rate" , "kpi_unit" : "%" , "data_owner_email" : "hr@acme.com" , "organization_name" : "ACME Spain" , "facility_name" : "Barcelona Office" } ], "total" : 15 }
Key response fields: Field Description value_numericThe submitted numeric value (null for text/date/select KPIs) kpi_name / kpi_unitKPI context flattened into each value row data_owner_emailThe person responsible for this assignment facility_nameThe facility that submitted this value (null if org-level) submitted_atWhen the value was submitted
list_kpi_assignmentsList facility/user assignments for a Custom KPI dataset — which facilities and data owners are responsible for reporting.
Parameters: Parameter Type Required Default Description dataset_idstring Yes — UUID of the KPI dataset organization_idstring No default org Organization UUID
Example response: { "items" : [ { "id" : "asgn-9c0d1e2f-..." , "dataset_id" : "ds-5e6f7a8b-..." , "organization_id" : "a1b2c3d4-..." , "facility_id" : "fac-1a2b3c4d-..." , "data_owner_user_id" : "u-3g4h5i6j-..." , "data_owner_email" : "hr@acme.com" , "created_at" : "2025-01-15T10:00:00" , "updated_at" : null } ], "total" : 1 }
Key response fields: Field Description facility_idThe assigned facility (null for org-level assignments) data_owner_emailContact email for the person responsible for data submission data_owner_user_idPlatform user ID of the data owner (null if external)
Example prompts: "List all our KPI datasets" "What KPIs are assigned to our Barcelona factory?" "Show me the KPI definitions in the ESG Social Metrics dataset" "Show submitted values for the Q1 2025 ESG campaign" "Which facilities are assigned to report on dataset ds-456?" "What's the employee turnover rate submitted by each facility?"
Workflow
Discover datasets — list_kpi_datasets to see available KPI dataset containersExplore definitions — list_custom_kpis to see individual KPI definitions (filter by facility_id or dataset_id)Find campaigns — list_kpi_campaigns to see data collection rounds and their deadlinesRead submitted data — get_kpi_campaign_values to retrieve the actual values submitted by facilitiesCheck assignments — list_kpi_assignments to see which facilities and data owners are responsible
Elastic Data Custom datasets with flexible schemas — a different way to track custom data
Facilities Facilities that KPI datasets are assigned to
Emissions GHG emissions data — standard environmental metrics
API Reference REST API endpoints for custom KPIs