Samuelz® Business OS

Rolle · Ausgabenlimit · Neu anlegen

create_business_role_budget

Idempotent

Create a new role’s share of an existing General budget, without increasing that budget’s cap. Use update_business_budget with allocationId for an existing share, or archive_business_budget to retire one. This tool assigns money limits to existing roles; it does not create roles or grant access.

Build from existing records

Read get_business_budgets and get_business_context(view=roles). Choose the frame’s budgetId and that role’s roleKey; copy the frame’s goal, dates and reach. Omit parentAllocationId for a root share, or select an existing parent share for a child. That choice changes where hierarchy and sibling totals constrain the allocation.

Set limitCents to this share’s complete EUR-cent cap, not an increment or the frame’s cap. An active share for the selected role must not already exist; creation neither replaces it nor restores archived records.

Save and recover

Current allocation authority, hierarchy and totals apply. requestKey identifies this create intent in the existing work journal. Exact replay returns its original receipt, not current state; other arguments or intents conflict. After uncertainty reread the frame/share rather than changing the key. No payment or provider action occurs.

Requires operator:prepare, accounting:read, operations:read, existing work:read/write and current Workspace/allocation authority. Owners also need work:manage/Workspace manage.

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": {
      "goal": "<goal>",
      "startsOn": "<startsOn>",
      "endsOn": "<endsOn>",
      "reachKey": "<reachKey>",
      "reachLabel": "<reachLabel>",
      "limitCents": "<limitCents>",
      "budgetId": "<budgetId>",
      "requestKey": "<requestKey>",
      "roleKey": "<roleKey>"
    },
    "name": "create_business_role_budget"
  }
}

Input Schema

Name	Required	Description
`goal`	Yes	Purpose of the selected spending frame.
`endsOn`	Yes	Last included UTC calendar day, on or after startsOn.
`roleKey`	Yes	Exact existing roleKey from get_business_context(view=roles). Requires budgetId, requestKey and the unchanged parent frame; excludes expectedRevision.
`budgetId`	Yes	Exact budgetId from this workspace's get_business_budgets; archive selects that frame, role mode selects its parent.
`reachKey`	Yes	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`	Yes	First included UTC calendar day. Together with reachKey identifies a General frame.
`limitCents`	Yes	General/role limit in safe integer EUR cents. Zero blocks positive new spending; it does not archive. No currency conversion.
`reachLabel`	Yes	Display label for reachKey.
`requestKey`	Yes	Fresh caller UUID across this tenant's shared work-operation journal. Exact replay keeps every argument; changed contents or actor conflict.
`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
`status`	Yes
`roleKey`	Yes
`budgetId`	Yes
`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`	Yes
`limitCents`	Yes
`allocationId`	Yes
`ownerAssigned`	Yes
`parentAllocationId`	Yes
`tenantLimitChanged`	Yes	Role allocation leaves the company limit unchanged.

Schema Changelog

Changes observed during successful MCP inspections.

AddedNov 2, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Goes well past the annotations: it discloses that the budget cap is not raised, that archived records are not restored, that no payment or provider action occurs, and it spells out requestKey replay semantics beyond the bare idempotentHint=true (exact replay returns the original receipt rather than current state; conflicting arguments conflict). Required authorities (operator:prepare, accounting:read, operations:read, work:manage for owners) are listed, which is exactly the recovery/permission context annotations cannot carry.

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?

Front-loaded with purpose, siblings, and the no-access caveat before the procedural sections, and the 'Build from existing records' / 'Save and recover' headers make a dense block navigable. Every sentence carries information, though the run-on compression (e.g. the authority list) costs some readability.

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 9-required-parameter mutation with an output schema, the description supplies what the structured fields cannot: prerequisite reads, the active-share conflict rule, idempotent-replay recovery guidance ('reread the frame/share rather than changing the key'), and full permission requirements. Nothing an agent needs to invoke this safely is missing.

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 baseline is 3, but the description adds real meaning: limitCents is 'this share's complete EUR-cent cap, not an increment or the frame's cap', and parentAllocationId's root-vs-child choice 'changes where hierarchy and sibling totals constrain the allocation'. goal/dates/reach are covered via 'copy the frame's goal, dates and reach'. It stops short of schema-level detail on requestKey formatting, which the schema already handles.

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 new role's share of an existing General budget') plus a hard constraint ('without increasing that budget's cap'), and immediately disambiguates from siblings by name: 'This tool assigns money limits to existing roles; it does not create roles or grant access.' An agent can distinguish this from create_business_budget and update_business_budget without opening any 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?

Explicitly routes alternatives: 'Use update_business_budget with allocationId for an existing share, or archive_business_budget to retire one.' Adds a documented pre-call workflow ('Read get_business_budgets and get_business_context(view=roles)') and an exclusion ('An active share for the selected role must not already exist'), covering both when to use and when not to.

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

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?