bw-modeling-mcp

bw_update_ckf

Edit a reusable Calculated Key Figure by replacing its formula or appending and removing operands, leaving the rest untouched in one save.

Instructions

Change a reusable Calculated Key Figure. Two call forms: pass "formula" to replace the whole expression, or "operations" for targeted edits that leave the rest of the formula untouched — the usual case being "add another summand to a sum" without having to know or rebuild the existing formula. All operations are applied to one document and written in a single save, so a rejected operation leaves the stored formula unchanged rather than half edited.

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": {
      "component_name": "<component_name>"
    },
    "name": "bw_update_ckf"
  }
}

Input Schema

Name	Required	Description
`formula`	No	Replacement formula tree (mutually exclusive with "operations"). 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.
`decimals`	No	Number of decimal places (0-9).
`operations`	No	Targeted edits on the existing formula, applied in order.
`description`	No	New description.
`component_name`	Yes	Technical name of the CKF.
`transport_request`	No	Transport request to record the change in.
`exception_aggregation`	No	Exception aggregation of the CKF itself, e.g. { "type": "SUM", "reference_characteristic": "IOBJ_NAME" }, or false (null is accepted too) to return to standard aggregation. Independent of "formula" / "operations": the formula stays as it is. Takes back unchanged what bw_get_ckf reports in exception_aggregation.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv1.8.1Oct 16, 2026

changedInput schema / properties / formula / description

Previous value: -"Replacement formula tree (mutually exclusive with \"operations\"). 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: +"Replacement formula tree (mutually exclusive with \"operations\"). 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."

changedInput schema / properties / operations / items / properties / operand / description

Previous value: -"Operand to add (append_operand). 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: +"Operand to add (append_operand). 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\" }, or false (null is accepted too) to return to standard aggregation. Independent of \"formula\" / \"operations\": the formula stays as it is. Takes back unchanged what bw_get_ckf reports in exception_aggregation.",
+  "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"
+    }
+  }
+}

Addedv1.5.0Sep 19, 2026

TDQS

A4/5.0

Behavior4/5

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

No annotations exist, so the description carries the full burden, and it delivers the key trait: all operations are written in a single save, so a rejected operation leaves the stored formula unchanged rather than half-edited. It omits permissions/transport-locking requirements and any note that a change may need a subsequent activation step.

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

Conciseness5/5

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

Three sentences, front-loaded with purpose then the two call forms then the atomicity guarantee. Every sentence adds information and nothing is repeated.

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?

For a complex nested-object mutation tool with no output schema, it explains the two modes and the write semantics well. It leaves a minor gap around whether activation, transport recording, or locking is required for the change to take effect.

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

Parameters3/5

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

Schema description coverage is 100% and the schema already documents formula/operations mutual exclusivity, operand trees, and defaults thoroughly. The description paraphrases the same formula-vs-operations split but adds no syntax, format, or edge-case detail beyond the schema, so the baseline 3 applies.

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

Purpose4/5

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

States a specific verb ('Change') and resource ('reusable Calculated Key Figure'), making clear it is the mutation counterpart to bw_create_ckf / bw_get_ckf. It does not, however, explicitly name a sibling or disambiguate against e.g. bw_update_rkf, so it sits at a clear-but-not-routing 4.

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

Usage Guidelines4/5

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

Explicitly splits behavior into two call forms and says which to pick: 'formula' to replace the whole expression vs 'operations' for targeted edits, with the typical case called out. It gives no exclusions or sibling alternatives (e.g. read the current formula first via bw_get_ckf), so it stops short of a 5.

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

Deploy Server