Samuelz® Business OS

Ausgabenlimit · Angaben ändern

update_business_budget

Replace a selected budget cap or definition. Use create_business_budget for a new frame, create_business_role_budget for a new role share, and archive_business_budget to retire either resource.

Change a General frame

Read get_business_budgets(budgetId), then build the complete requested definition from that frame. Retain reachKey+startsOn; changing the category label does not create a new identity. Supply the whole new cap: raising 10000 to 15000 EUR cents means limitCents=15000, not 5000. Current Owners can retain or lower it directly; increases return an unactivated human Owner card. Missing, archived or stale frames reject the change.

Read budgetId+allocationId together. Copy roleKey and parentAllocationId from that share, and goal/startsOn/endsOn/reachKey/reachLabel from its General frame. Change only the share’s limitCents; omit expectedRevision in this role mode. This cannot move a share to another role/parent, create a missing share or raise the General frame’s cap. Hierarchy, totals and allocation authority still apply.

Recover safely

General requestKey does not deduplicate a direct save. Role replay returns the original work-journal receipt, not current state. After uncertainty reread the exact resource/request; do not substitute keys or revisions.

Requires operator:prepare, accounting:read, operations:read and current module access. Role changes also require existing work:read/write and Workspace/allocation authority; Owners need work:manage/Workspace manage. No payment or provider action occurs.

Input Schema

Name	Required	Description
`goal`	No	Purpose of the selected spending frame.
`endsOn`	No	Last included UTC calendar day, on or after startsOn.
`roleKey`	No	Exact existing roleKey from get_business_context(view=roles). Requires budgetId, requestKey and the unchanged parent frame; excludes expectedRevision.
`budgetId`	No	Exact budgetId from this workspace's get_business_budgets; archive selects that frame, role mode selects its parent.
`reachKey`	No	Workspace-local spending category key, not a provider account or permission. Creation may introduce a key; updates and role allocations copy the selected frame’s key.
`startsOn`	No	First included UTC calendar day. Together with reachKey identifies a General frame.
`limitCents`	No	General/role limit in safe integer EUR cents. Zero blocks positive new spending; it does not archive. No currency conversion.
`reachLabel`	No	Display label for reachKey.
`requestKey`	No	Fresh caller UUID across this tenant's shared work-operation journal. Exact replay keeps every argument; changed contents or actor conflict.
`allocationId`	No	Exact existing allocationId from get_business_budgets(budgetId,allocationId). Update requires this selection; a missing allocation is never created. Keep its roleKey and parentAllocationId unchanged.
`expectedRevision`	No	Copy the selected General frame’s current revision. A stale revision rejects the entire replacement; reread and obtain renewed intent instead of retrying with a newer revision.
`parentAllocationId`	No	Role mode only: parent share for a child allocation; omitted/null means a root share. Immutable on updates.

Output Schema

Name	Required	Description
`budget`	No	Existing SpendLimitRow returned by a direct General change; this is not the measured read projection.
`reason`	No	Rejection reason; no requested change was applied.
`status`	Yes	Stored General limit/role share, unactivated human request, or rejected change. Archive preparation never reports an archived frame.
`roleKey`	No
`budgetId`	No
`replayed`	No	Original role/archive receipt replay, not proof of current resource or request state. General is not journal-idempotent.
`revision`	No	Work-journal revision on a fresh role allocation; absent on replay. Not a General frame revision.
`activates`	No	True for an applied General/role change; false for a human request or rejection when present.
`limitCents`	No
`nextAction`	No
`proposalId`	No	Existing stored human-request identity, not a budgetId or allocationId.
`allocationId`	No
`presentation`	No	The persisted receipt survives an unavailable card. Read the same proposal; never prepare another request.
`ownerAssigned`	No
`parentAllocationId`	No
`tenantLimitChanged`	No	Role allocation leaves the company limit unchanged.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedNov 2, 2026

changedInput schema / oneOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "budgetId": {
-        "description": "Exact active General budgetId from get_business_budgets(budgetId). Never a role allocation or request ID.",
-        "maxLength": 160,
-        "minLength": 1,
-        "type": "string"
-      },
-      "endsOn": {
-        "description": "Last included UTC calendar day, on or after startsOn.",
-        "format": "date",
-        "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
-        "type": "string"
-      },
-      "expectedRevision": {
-        "description": "Copy the selected General frame’s current revision. A stale revision rejects the entire replacement; reread and obtain renewed intent instead of retrying with a newer revision.",
-        "pattern": "^[a-f0-9]{64}$",
-        "type": "string"
-      },
-      "goal": {
-        "description": "Purpose of the selected spending frame.",
-        "maxLength": 160,
-        "minLength": 1,
-        "type": "string"
-      },
-      "limitCents": {
-        "description": "General/role limit in safe integer EUR cents. Zero blocks positive new spending; it does not archive. No currency conversion.",
-        "maximum": 9007199254740991,
-        "minimum": 0,
-        "type": "integer"
-      },
-      "reachKey": {
-        "description": "Workspace-local spending category key, not a provider account or permission. Creation may introduce a key; updates and role allocations copy the selected frame’s key.",
-        "pattern": "^[a-z0-9][a-z0-9_-]{0,79}$",
-        "type": "string"
-      },
-      "reachLabel": {
-        "description": "Display label for reachKey.",
-        "maxLength": 120,
-        "minLength": 1,
-        "type": "string"
-      },
-      "requestKey": {
-        "description": "Optional legacy reference, not journal-idempotency. After uncertainty read the frame/request instead of repeating the write.",
-        "format": "uuid",
-        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
-        "type": "string"
-      },
-      "startsOn": {
-        "description": "First included UTC calendar day. Together with reachKey identifies a General frame.",
-        "format": "date",
-        "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
-        "type": "string"
-      }
-    },
-    "required": [
-      "goal",
-      "startsOn",
-      "endsOn",
-      "reachKey",
-      "reachLabel",
-      "limitCents",
-      "budgetId",
-      "expectedRevision"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "allocationId": {
-        "description": "Role mode only: exact existing allocation to revise limitCents; roleKey and parentAllocationId stay unchanged. Omit for initial allocation.",
-        "minLength": 1,
-        "type": "string"
-      },
-      "budgetId": {
-        "description": "Exact budgetId from this workspace's get_business_budgets; archive selects that frame, role mode selects its parent.",
-        "maxLength": 160,
-        "minLength": 1,
-        "type": "string"
-      },
-      "endsOn": {
-        "description": "Last included UTC calendar day, on or after startsOn.",
-        "format": "date",
-        "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
-        "type": "string"
-      },
-      "goal": {
-        "description": "Purpose of the selected spending frame.",
-        "maxLength": 160,
-        "minLength": 1,
-        "type": "string"
-      },
-      "limitCents": {
-        "description": "General/role limit in safe integer EUR cents. Zero blocks positive new spending; it does not archive. No currency conversion.",
-        "maximum": 9007199254740991,
-        "minimum": 0,
-        "type": "integer"
-      },
-      "parentAllocationId": {
-        "anyOf": [
-          {
-            "minLength": 1,
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "Role mode only: parent share for a child allocation; omitted/null means a root share. Immutable on updates."
-      },
-      "reachKey": {
-        "description": "Workspace-local spending category key, not a provider account or permission. Creation may introduce a key; updates and role allocations copy the selected frame’s key.",
-        "pattern": "^[a-z0-9][a-z0-9_-]{0,79}$",
-        "type": "string"
-      },
-      "reachLabel": {
-        "description": "Display label for reachKey.",
-        "maxLength": 120,
-        "minLength": 1,
-        "type": "string"
-      },
-      "requestKey": {
-        "description": "Fresh caller UUID across this tenant's shared work-operation journal. Exact replay keeps every argument; changed contents or actor conflict.",
-        "format": "uuid",
-        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
-        "type": "string"
-      },
-      "roleKey": {
-        "description": "Exact existing roleKey from get_business_context(view=roles). Requires budgetId, requestKey and the unchanged parent frame; excludes expectedRevision.",
-        "maxLength": 120,
-        "minLength": 1,
-        "type": "string"
-      },
-      "startsOn": {
-        "description": "First included UTC calendar day. Together with reachKey identifies a General frame.",
-        "format": "date",
-        "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
-        "type": "string"
-      }
-    },
-    "required": [
-      "goal",
-      "startsOn",
-      "endsOn",
-      "reachKey",
-      "reachLabel",
-      "limitCents",
-      "budgetId",
-      "requestKey",
-      "roleKey"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "budgetId": {
+        "description": "Exact active General budgetId from get_business_budgets(budgetId). Never a role allocation or request ID.",
+        "maxLength": 160,
+        "minLength": 1,
+        "type": "string"
+      },
+      "endsOn": {
+        "description": "Last included UTC calendar day, on or after startsOn.",
+        "format": "date",
+        "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+        "type": "string"
+      },
+      "expectedRevision": {
+        "description": "Copy the selected General frame’s current revision. A stale revision rejects the entire replacement; reread and obtain renewed intent instead of retrying with a newer revision.",
+        "pattern": "^[a-f0-9]{64}$",
+        "type": "string"
+      },
+      "goal": {
+        "description": "Purpose of the selected spending frame.",
+        "maxLength": 160,
+        "minLength": 1,
+        "type": "string"
+      },
+      "limitCents": {
+        "description": "General/role limit in safe integer EUR cents. Zero blocks positive new spending; it does not archive. No currency conversion.",
+        "maximum": 9007199254740991,
+        "minimum": 0,
+        "type": "integer"
+      },
+      "reachKey": {
+        "description": "Workspace-local spending category key, not a provider account or permission. Creation may introduce a key; updates and role allocations copy the selected frame’s key.",
+        "pattern": "^[a-z0-9][a-z0-9_-]{0,79}$",
+        "type": "string"
+      },
+      "reachLabel": {
+        "description": "Display label for reachKey.",
+        "maxLength": 120,
+        "minLength": 1,
+        "type": "string"
+      },
+      "requestKey": {
+        "description": "Optional legacy reference, not journal-idempotency. After uncertainty read the frame/request instead of repeating the write.",
+        "format": "uuid",
+        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+        "type": "string"
+      },
+      "startsOn": {
+        "description": "First included UTC calendar day. Together with reachKey identifies a General frame.",
+        "format": "date",
+        "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+        "type": "string"
+      }
+    },
+    "required": [
+      "goal",
+      "startsOn",
+      "endsOn",
+      "reachKey",
+      "reachLabel",
+      "limitCents",
+      "budgetId",
+      "expectedRevision"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "allocationId": {
+        "description": "Exact existing allocationId from get_business_budgets(budgetId,allocationId). Update requires this selection; a missing allocation is never created. Keep its roleKey and parentAllocationId unchanged.",
+        "minLength": 1,
+        "type": "string"
+      },
+      "budgetId": {
+        "description": "Exact budgetId from this workspace's get_business_budgets; archive selects that frame, role mode selects its parent.",
+        "maxLength": 160,
+        "minLength": 1,
+        "type": "string"
+      },
+      "endsOn": {
+        "description": "Last included UTC calendar day, on or after startsOn.",
+        "format": "date",
+        "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+        "type": "string"
+      },
+      "goal": {
+        "description": "Purpose of the selected spending frame.",
+        "maxLength": 160,
+        "minLength": 1,
+        "type": "string"
+      },
+      "limitCents": {
+        "description": "General/role limit in safe integer EUR cents. Zero blocks positive new spending; it does not archive. No currency conversion.",
+        "maximum": 9007199254740991,
+        "minimum": 0,
+        "type": "integer"
+      },
+      "parentAllocationId": {
+        "anyOf": [
+          {
+            "minLength": 1,
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Role mode only: parent share for a child allocation; omitted/null means a root share. Immutable on updates."
+      },
+      "reachKey": {
+        "description": "Workspace-local spending category key, not a provider account or permission. Creation may introduce a key; updates and role allocations copy the selected frame’s key.",
+        "pattern": "^[a-z0-9][a-z0-9_-]{0,79}$",
+        "type": "string"
+      },
+      "reachLabel": {
+        "description": "Display label for reachKey.",
+        "maxLength": 120,
+        "minLength": 1,
+        "type": "string"
+      },
+      "requestKey": {
+        "description": "Fresh caller UUID across this tenant's shared work-operation journal. Exact replay keeps every argument; changed contents or actor conflict.",
+        "format": "uuid",
+        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+        "type": "string"
+      },
+      "roleKey": {
+        "description": "Exact existing roleKey from get_business_context(view=roles). Requires budgetId, requestKey and the unchanged parent frame; excludes expectedRevision.",
+        "maxLength": 120,
+        "minLength": 1,
+        "type": "string"
+      },
+      "startsOn": {
+        "description": "First included UTC calendar day. Together with reachKey identifies a General frame.",
+        "format": "date",
+        "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+        "type": "string"
+      }
+    },
+    "required": [
+      "goal",
+      "startsOn",
+      "endsOn",
+      "reachKey",
+      "reachLabel",
+      "limitCents",
+      "budgetId",
+      "requestKey",
+      "roleKey",
+      "allocationId"
+    ],
+    "type": "object"
+  }
+]

changedInput schema / properties / allocationId / description

Previous value: -"Role mode only: exact existing allocation to revise limitCents; roleKey and parentAllocationId stay unchanged. Omit for initial allocation."New value: +"Exact existing allocationId from get_business_budgets(budgetId,allocationId). Update requires this selection; a missing allocation is never created. Keep its roleKey and parentAllocationId unchanged."

Changed16 schema fields changedNov 2, 2026

addedInput schema / oneOf

Added value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "budgetId": {
+        "description": "Exact active General budgetId from get_business_budgets(budgetId). Never a role allocation or request ID.",
+        "maxLength": 160,
+        "minLength": 1,
+        "type": "string"
+      },
+      "endsOn": {
+        "description": "Last included UTC calendar day, on or after startsOn.",
+        "format": "date",
+        "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+        "type": "string"
+      },
+      "expectedRevision": {
+        "description": "Copy the selected General frame’s current revision. A stale revision rejects the entire replacement; reread and obtain renewed intent instead of retrying with a newer revision.",
+        "pattern": "^[a-f0-9]{64}$",
+        "type": "string"
+      },
+      "goal": {
+        "description": "Purpose of the selected spending frame.",
+        "maxLength": 160,
+        "minLength": 1,
+        "type": "string"
+      },
+      "limitCents": {
+        "description": "General/role limit in safe integer EUR cents. Zero blocks positive new spending; it does not archive. No currency conversion.",
+        "maximum": 9007199254740991,
+        "minimum": 0,
+        "type": "integer"
+      },
+      "reachKey": {
+        "description": "Workspace-local spending category key, not a provider account or permission. Creation may introduce a key; updates and role allocations copy the selected frame’s key.",
+        "pattern": "^[a-z0-9][a-z0-9_-]{0,79}$",
+        "type": "string"
+      },
+      "reachLabel": {
+        "description": "Display label for reachKey.",
+        "maxLength": 120,
+        "minLength": 1,
+        "type": "string"
+      },
+      "requestKey": {
+        "description": "Optional legacy reference, not journal-idempotency. After uncertainty read the frame/request instead of repeating the write.",
+        "format": "uuid",
+        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+        "type": "string"
+      },
+      "startsOn": {
+        "description": "First included UTC calendar day. Together with reachKey identifies a General frame.",
+        "format": "date",
+        "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+        "type": "string"
+      }
+    },
+    "required": [
+      "goal",
+      "startsOn",
+      "endsOn",
+      "reachKey",
+      "reachLabel",
+      "limitCents",
+      "budgetId",
+      "expectedRevision"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "allocationId": {
+        "description": "Role mode only: exact existing allocation to revise limitCents; roleKey and parentAllocationId stay unchanged. Omit for initial allocation.",
+        "minLength": 1,
+        "type": "string"
+      },
+      "budgetId": {
+        "description": "Exact budgetId from this workspace's get_business_budgets; archive selects that frame, role mode selects its parent.",
+        "maxLength": 160,
+        "minLength": 1,
+        "type": "string"
+      },
+      "endsOn": {
+        "description": "Last included UTC calendar day, on or after startsOn.",
+        "format": "date",
+        "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+        "type": "string"
+      },
+      "goal": {
+        "description": "Purpose of the selected spending frame.",
+        "maxLength": 160,
+        "minLength": 1,
+        "type": "string"
+      },
+      "limitCents": {
+        "description": "General/role limit in safe integer EUR cents. Zero blocks positive new spending; it does not archive. No currency conversion.",
+        "maximum": 9007199254740991,
+        "minimum": 0,
+        "type": "integer"
+      },
+      "parentAllocationId": {
+        "anyOf": [
+          {
+            "minLength": 1,
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Role mode only: parent share for a child allocation; omitted/null means a root share. Immutable on updates."
+      },
+      "reachKey": {
+        "description": "Workspace-local spending category key, not a provider account or permission. Creation may introduce a key; updates and role allocations copy the selected frame’s key.",
+        "pattern": "^[a-z0-9][a-z0-9_-]{0,79}$",
+        "type": "string"
+      },
+      "reachLabel": {
+        "description": "Display label for reachKey.",
+        "maxLength": 120,
+        "minLength": 1,
+        "type": "string"
+      },
+      "requestKey": {
+        "description": "Fresh caller UUID across this tenant's shared work-operation journal. Exact replay keeps every argument; changed contents or actor conflict.",
+        "format": "uuid",
+        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+        "type": "string"
+      },
+      "roleKey": {
+        "description": "Exact existing roleKey from get_business_context(view=roles). Requires budgetId, requestKey and the unchanged parent frame; excludes expectedRevision.",
+        "maxLength": 120,
+        "minLength": 1,
+        "type": "string"
+      },
+      "startsOn": {
+        "description": "First included UTC calendar day. Together with reachKey identifies a General frame.",
+        "format": "date",
+        "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+        "type": "string"
+      }
+    },
+    "required": [
+      "goal",
+      "startsOn",
+      "endsOn",
+      "reachKey",
+      "reachLabel",
+      "limitCents",
+      "budgetId",
+      "requestKey",
+      "roleKey"
+    ],
+    "type": "object"
+  }
+]

addedInput schema / properties / allocationId

Added value: +{
+  "description": "Role mode only: exact existing allocation to revise limitCents; roleKey and parentAllocationId stay unchanged. Omit for initial allocation.",
+  "minLength": 1,
+  "type": "string"
+}

changedInput schema / properties / budgetId / description

Previous value: -"Exact active General budgetId from get_business_budgets(budgetId). Never a role allocation or request ID."New value: +"Exact budgetId from this workspace's get_business_budgets; archive selects that frame, role mode selects its parent."

addedInput schema / properties / parentAllocationId

Added value: +{
+  "anyOf": [
+    {
+      "minLength": 1,
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Role mode only: parent share for a child allocation; omitted/null means a root share. Immutable on updates."
+}

changedInput schema / properties / requestKey / description

Previous value: -"Optional legacy reference, not journal-idempotency. After uncertainty read the frame/request instead of repeating the write."New value: +"Fresh caller UUID across this tenant's shared work-operation journal. Exact replay keeps every argument; changed contents or actor conflict."

addedInput schema / properties / roleKey

Added value: +{
+  "description": "Exact existing roleKey from get_business_context(view=roles). Requires budgetId, requestKey and the unchanged parent frame; excludes expectedRevision.",
+  "maxLength": 120,
+  "minLength": 1,
+  "type": "string"
+}

removedInput schema / required

Removed value: -[
-  "goal",
-  "startsOn",
-  "endsOn",
-  "reachKey",
-  "reachLabel",
-  "limitCents",
-  "budgetId",
-  "expectedRevision"
-]

addedOutput schema / properties / allocationId
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / budgetId
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / limitCents
```
Added value: +{
+  "type": "number"
+}
```
addedOutput schema / properties / ownerAssigned
```
Added value: +{
+  "type": "boolean"
+}
```

addedOutput schema / properties / parentAllocationId

Added value: +{
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedOutput schema / properties / replayed

Added value: +{
+  "description": "Original role/archive receipt replay, not proof of current resource or request state. General is not journal-idempotent.",
+  "type": "boolean"
+}

addedOutput schema / properties / revision

Added value: +{
+  "description": "Work-journal revision on a fresh role allocation; absent on replay. Not a General frame revision.",
+  "type": "number"
+}

addedOutput schema / properties / roleKey
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / tenantLimitChanged

Added value: +{
+  "const": false,
+  "description": "Role allocation leaves the company limit unchanged.",
+  "type": "boolean"
+}

AddedNov 2, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations only supply readOnlyHint=false, destructiveHint=false and idempotentHint=false; the description goes far beyond by explaining that General requestKey does not deduplicate a direct save while a role replay returns the original work-journal receipt, and that stale revisions reject the entire replacement. It also discloses the side effect that cap increases return an unactivated human Owner card, and that no payment or provider action occurs.

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?

The three headed sections (General frame, role share, recover safely) are front-loaded and scannable, with the substantive constraint stated before the procedural detail. It is long, but nearly every sentence carries a distinct rule; only the trailing permission sentence overlaps slightly with mode-specific authority already implied earlier.

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

Completeness5/5

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

For a 12-parameter, oneOf-shaped mutation with an output schema, the description supplies the missing pieces the schema cannot: which branch to use, how to compose arguments from prior reads, revision semantics, failure modes, and required scopes. Nothing an agent needs in order to call it safely appears to be absent.

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 genuine meaning beyond the schema: the worked example clarifying that a raise to 15000 is limitCents=15000 'not 5000', the instruction to omit expectedRevision in role mode, and the rule that goal/startsOn/endsOn/reachKey/reachLabel are copied from the parent General frame while only limitCents changes. It does not restate format constraints that the schema already enforces, which is appropriate.

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?

The opening line names a specific verb and resource ('Replace a selected budget cap or definition') and immediately distinguishes the two replaceable resources (General frame vs. role share). It also names the three sibling tools that handle adjacent operations (create_business_budget, create_business_role_budget, archive_business_budget), so an agent can route 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 Guidelines5/5

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

Explicit when-to-use routing is present for every alternative: create for a new frame, create_business_role_budget for a new role share, archive to retire. It also states negative conditions ('cannot move a share to another role/parent, create a missing share or raise the General frame's cap') and rejection triggers ('Missing, archived or stale frames reject the change').

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

All Samuelz® Business OS tools Inspect

Try in Browser