Skip to main content
Glama
dnic-dev

bw-modeling-mcp

by dnic-dev
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

bw_update_ckf

Modify a reusable Calculated Key Figure by replacing its formula or appending/removing operands. Changes are applied in a single atomic save to avoid partial edits.

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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
formulaNoReplacement 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.
decimalsNoNumber of decimal places (0-9).
operationsNoTargeted edits on the existing formula, applied in order.
descriptionNoNew description.
component_nameYesTechnical name of the CKF.
transport_requestNoTransport request to record the change in.
exception_aggregationNoException 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.

  1. Changed1 schema field changedv1.7.1
    • 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"
+    }
+  }
+}
  2. Addedv1.5.0

TDQS

A4.2/5.0
Behavior4/5

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

With no annotations, the description does real work: it discloses mutation semantics and, importantly, atomicity — '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.' That single-save guarantee is a genuine behavioral trait not derivable from the schema. It still omits permission/lock prerequisites and transport implications, which matters for a write tool with a transport_request parameter.

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?

Front-loaded with the purpose, then the two call forms, then the atomicity guarantee. Every sentence carries information; no filler or restatement of the tool name.

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 mutation over nested formula trees, the description covers the two modes and write atomicity, and the rich schema and inline parameter docs carry the rest. It does not mention locking/transport prerequisites or return behavior, though no output schema exists to cover returns.

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%, so the schema already explains formula trees, operations, and exception_aggregation in depth; baseline is 3. The description adds the conceptual framing of formula-vs-operations and the 'leave the rest untouched' guarantee, but does not introduce syntax or semantics the schema lacks.

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 ('Change a reusable Calculated Key Figure'), and the qualifier 'reusable' separates it from sibling tools like bw_update_rkf (reusable RKF) and bw_update_query_key_figures (query-level key figures). An agent can route to it without opening the schema.

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?

It clearly distinguishes its two call forms — 'pass "formula" to replace the whole expression, or "operations" for targeted edits' — and names the canonical case ('add another summand to a sum without knowing the existing formula'). It stops short of naming alternatives such as bw_get_ckf or bw_create_ckf, or stating when not to use this tool, so it gets context but not full routing guidance.

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

Deploy Server

Other Tools