bw-modeling-mcp

bw_create_ckf

Create a reusable Calculated Key Figure on an InfoProvider from an operator/operand formula tree, with optional exception aggregation, transport recording, and validation.

Instructions

Create a reusable Calculated Key Figure (CKF) on an InfoProvider. The formula is passed as an operator/operand tree in the same node syntax bw_update_query_key_figures uses for "add_formula", so a tree read back from bw_get_ckf (field formula_tree) can be written again unchanged. Records to a transport when package and transport_request are given, and reports in "recorded_in" where the entry actually landed.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "provider_name": "<provider_name>",
      "technical_name": "<technical_name>",
      "description": "<description>",
      "formula": "<formula>"
    },
    "name": "bw_create_ckf"
  }
}

Input Schema

Name	Required	Description
`formula`	Yes	Formula tree. A node is one of: {"type":"operator","code":"+","operands":[...]} (codes as in the BW formula editor: + - * / , NDIV0, IF, MAX, %A, …); {"type":"component","component_name":"..."} for a reusable CKF/RKF; {"type":"key_figure","name":"..."} for a basic key figure InfoObject; {"type":"variable","variable_name":"..."} for a formula variable; {"type":"constant","value":100}. Operand counts are checked against the operator catalog before anything is written.
`package`	No	Development package (default "$TMP").
`decimals`	No	Number of decimal places (0-9). Server default when omitted.
`info_area`	No	InfoArea the CKF is filed under.
`description`	Yes	Description of the CKF.
`provider_name`	Yes	InfoProvider the CKF is defined on (e.g. a CompositeProvider).
`technical_name`	Yes	Technical name of the new CKF.
`transport_request`	No	Transport request to record the CKF in.
`exception_aggregation`	No	Exception aggregation of the CKF itself, e.g. { "type": "SUM", "reference_characteristic": "IOBJ_NAME" }. Needed for a weighted average: a helper CKF "unit value * quantity" with SUM over the finest characteristic, divided by the quantity in a second CKF. Without it the product is formed from values already summed up — numerically plausible and wrong. Standard aggregation when omitted.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.8.1Oct 16, 2026

changedInput schema / properties / formula / description

Previous value: -"Formula tree. A node is one of: {\"type\":\"operator\",\"code\":\"+\",\"operands\":[...]} (codes as in the BW formula editor: + - * / , NDIV0, IF, MAX, %A, …); {\"type\":\"component\",\"component_name\":\"...\"} for a reusable CKF/RKF; {\"type\":\"key_figure\",\"name\":\"...\"} for a basic key figure InfoObject; {\"type\":\"constant\",\"value\":100}. Operand counts are checked against the operator catalog before anything is written."New value: +"Formula tree. A node is one of: {\"type\":\"operator\",\"code\":\"+\",\"operands\":[...]} (codes as in the BW formula editor: + - * / , NDIV0, IF, MAX, %A, …); {\"type\":\"component\",\"component_name\":\"...\"} for a reusable CKF/RKF; {\"type\":\"key_figure\",\"name\":\"...\"} for a basic key figure InfoObject; {\"type\":\"variable\",\"variable_name\":\"...\"} for a formula variable; {\"type\":\"constant\",\"value\":100}. Operand counts are checked against the operator catalog before anything is written."

Changed1 schema field changedv1.7.1Oct 1, 2026

addedInput schema / properties / exception_aggregation

Added value: +{
+  "description": "Exception aggregation of the CKF itself, e.g. { \"type\": \"SUM\", \"reference_characteristic\": \"IOBJ_NAME\" }. Needed for a weighted average: a helper CKF \"unit value * quantity\" with SUM over the finest characteristic, divided by the quantity in a second CKF. Without it the product is formed from values already summed up — numerically plausible and wrong. Standard aggregation when omitted.",
+  "properties": {
+    "exclude": {
+      "description": "Aggregate over all characteristics except the reference characteristics. Default false.",
+      "type": "boolean"
+    },
+    "reference_characteristic": {
+      "description": "Reference characteristic the exception aggregation runs over (e.g. \"IOBJ_NAME\").",
+      "type": "string"
+    },
+    "reference_characteristics": {
+      "description": "Several reference characteristics (up to five). Takes precedence over reference_characteristic.",
+      "items": {
+        "type": "string"
+      },
+      "maxItems": 5,
+      "type": "array"
+    },
+    "type": {
+      "description": "Aggregation type: SUM, MAX, MIN, AVG (all values), AV0 (average of non-zero values), AV1 / AV2 (average weighted by calendar / working days), CNT (count all), CN0 (count non-zero), FIR / LAS (first / last value), NO1 / NO2 / NOP (no aggregation if more than one record / value / non-zero value), STD, VAR. Any other literal is refused, because the backend would silently store standard aggregation instead.",
+      "enum": [
+        "SUM",
+        "MAX",
+        "MIN",
+        "AVG",
+        "AV0",
+        "AV1",
+        "AV2",
+        "CNT",
+        "CN0",
+        "FIR",
+        "LAS",
+        "NO1",
+        "NO2",
+        "NOP",
+        "STD",
+        "VAR"
+      ],
+      "type": "string"
+    }
+  },
+  "required": [
+    "type"
+  ],
+  "type": "object"
+}

Addedv1.5.0Sep 19, 2026

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations the description carries the full burden, and it delivers non-obvious behavior: transport recording is conditional on package + transport_request, and the result reports where the entry landed in "recorded_in". It omits activation requirements, error/failure handling, and permission needs, so it is strong but not complete.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the create action, then the formula contract, then transport behavior. Efficient with no filler, though the middle sentence is slightly dense.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, but the description covers the key return signal ("recorded_in") and the formula input contract, which is enough to call the tool correctly. Minor gaps remain around activation and error behavior for a creation tool with no annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real value beyond the schema by documenting the formula tree's round-trip interchangeability with bw_get_ckf's formula_tree field. It still leaves the transport/package interaction largely to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Create a reusable Calculated Key Figure (CKF) on an InfoProvider") and situates it among related tools, naming bw_get_ckf and bw_update_query_key_figures. An agent can distinguish this from bw_create_rkf and bw_update_ckf without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains the formula syntax interoperates with bw_update_query_key_figures' "add_formula" and that a tree from bw_get_ckf can be reused, which implies the workflow. However it never states explicit when/when-not conditions or how to choose this over bw_create_rkf for a different key-figure type.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server