Samuelz Business OS

Request retirement of a selected budget frame or role share through its human Owner card. Use update_business_budget to change a cap. Setting a cap to zero blocks positive new spending but does not retire the resource.

Select what retires

Read get_business_budgets for the exact resource. For a whole frame, use its budgetId and revision. For one share, keep the parent budgetId, add its allocationId and use that share’s revision as expectedRevision. The frame revision and numeric work-journal receipt revision cannot replace the share’s revision.

Resolve blockers before preparing

A frame cannot retire with Workspace/ads_* identity, another active overlap, active shares or bound advertising exposure. A share cannot retire with active children. Zero-valued shares/children are still active; retiring a parent never silently retires them. Share retirement leaves the parent cap unchanged.

Preparation retires nothing. Human confirmation irreversibly removes future spending authority, retaining identity, consumption and history without cancelling provider work. Exact replay keeps the original key/revision and returns an old receipt. After uncertainty read get_business_change(proposalId) and the resource; never prepare another request to probe success.

Requires current Owner authority, operator:prepare, accounting:read and operations:read. Role retirement also needs existing work:read/write and Workspace write authority.

Archive one explicitly selected goal from active tracking. These lifecycle tools cannot restore an archived goal. Read get_business_goals(goalId) first; use update_business_goal for definition changes.

Request:

• A new intent needs the current expectedRevision and a fresh requestKey, unique across this actor/workspace’s goal create/update/archive operations, not merely per goal.

• An exact replay keeps its original requestKey and expectedRevision even after the stored revision changes. Substituting a newer revision under that key is a conflict.

• A receipt describes the original result, not current goal/proposal state. After uncertainty or replay, read get_business_goals(goalId), which includes archived records.

Results:

• Non-money: status=archived and activates=false; the output schema describes the retained goal/revision.

• Money goal: owner_approval_required and the existing human-card continuation; never call confirm_business_change.

• Rejected: no change; read the reason.

Requires current operator:prepare, accounting:read and operations:read authority. History and references remain; archiving does not delete the goal or cancel work orders, steering baselines, budgets or provider actions.

Commit exactly the change on a trusted human Owner card. App-only: models must never invoke this tool, construct proof or request hidden metadata in chat. A chat “yes” is not the card’s human confirmation; present the existing card instead.

Keep one card intact

The trusted UI returns that card’s kind and approvalToken together. For kind=goal, pass its proposalId: this covers stored goal and General/role-budget requests. For kind=policy, pass its exact signed candidate instead. Never combine two cards, supply both selectors, patch the displayed change or alter signed revision/deadline data.

Authority remains current

Requires policy:write and current Owner/module access; policies also need policy:read. Role-budget retirement additionally needs existing work:read/write, accounting:read and Workspace/Accounting write authority. Each workflow validates signature, tenant, principal, grant and expiry. Goal changes, budget archives and policies also validate revision.

Read the result without retrying

approved records a goal/budget commit; confirmed records a policy commit with revision/policyVersion. not_applied caused no new effect. not_verified or a lost reply may still mean a commit occurred. pending_owner, expired or not_found do not prove success.

Never retry confirmation. Read get_business_change(proposalId), then the goal/budget by resource ID. For policies use the separately authorized Policy connection to read get_policy(kind=policy,moduleKey,policyKey). Receipts do not prove current state, and current state alone cannot attribute this attempt’s effect.

Request a new General spending limit for one category and period through its human Owner card. Use update_business_budget to change an existing frame, create_business_role_budget to divide it among roles, and prepare_policy_change for advertising policy.

Build the new frame

Read every get_business_budgets(view=frames,includeArchived=true) page before choosing reachKey+startsOn. That pair identifies a frame: a different label or end date does not make it new. Update an existing pair; an archived overlap cannot be restored.

Choose reachKey as the workspace category identity and reachLabel as its readable name; neither selects a provider account or grants permission. Set limitCents to the whole requested EUR-cent cap, not an addition or available cash. Renaming a category changes its label, not its identity.

Human handoff and recovery

owner_approval_required/activates=false means no spending authority yet. Only a human confirms. requestKey is not journal-idempotency here: repeating the call may create another pending request. After uncertainty, read the same proposalId via get_business_change and check the frame rather than creating again.

Requires operator:prepare, accounting:read, operations:read and current module access; confirmation retains Owner checks. No payment or provider action occurs.

Create an additional goal on explicit request. First check every active get_business_goals page: overlapping goals are not merged or replaced. Use update_business_goal to change a goal and archive_business_goal to retire it.

Translate the requested target

Choose metric, targetValue and cadence together. “20 bookings each week” uses bookings/20/weekly; “20 bookings by the deadline” uses once for the entire inclusive UTC-day span. Weekly repeats the full target in each Europe/Berlin reporting week, even a clipped first/last week; do not divide or prorate it. Resolve ambiguous dates or cadence before creating.

The target’s units follow the metric. A display title or segment label cannot establish missing measurement coverage. Select only an existing, evidenced segment rather than inventing one from the wording.

Check the outcome

Non-money goals become active. Paid revenue instead returns owner_approval_required/activates=false with proposalId/nextAction for a human Owner card; models never confirm. rejected changes nothing—read its reason. A stored definition is not measured progress, and creation spends nothing or triggers a provider action.

Use a fresh requestKey for each new intent across this actor/workspace’s goal create/update/archive operations. Replay returns its old receipt; keyless legacy calls are non-idempotent. After uncertainty read stored goals instead of creating again. Requires operator:prepare, accounting:read, operations:read and current authority.

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.

Read budget definitions, spending limits and recorded consumption. Use get_business_change to find changes across resources or recover approval requests; this tool reads the selected budget’s evidence.

Pick the question

• How much may be spent now? Call without arguments. Advertising, roles and questions report availability separately.

• Which stored frame should change? List view=frames, then take that row’s budgetId into an exact read.

• Which role share should change? Read its budgetId+allocationId together.

• What changed in a known budget? Use view=history with its budgetId. To trace one share, match kind/allocationId within that parent’s history.

Finish the read

Follow hasMore even if a history page has no matching share: unrelated events still consume limit. Frame pages seek by ID, not date; history follows newest-recorded append order. Keep the returned continuation with its original selection.

Consumption is not available cash; missing historical revisions stay unknown. Missing frames yield budgets=[]; unavailable role data stays null; storage failures are errors. Requires accounting:read and operations:read. Read current state before update_business_budget/archive_business_budget. New frames use create_business_budget; new shares use create_business_role_budget.

Find a recorded change across resources or recover a goal/budget approval request. This is an activity index and request reader, not the detailed history for a known resource; use get_business_goals/get_business_budgets(view=history) or get_policy_history for that evidence.

Start from the question

• “Who changed what?” Select activity and search record content. Follow a hit’s exact nextRead to its source history until receiptId matches.

• “Which requests were applied?” Filter the request list with status=approved. query=approved only searches words; it does not select that lifecycle state.

• “What happened to this request?” Supply its proposalId alone. Read status and the original expiresAt. A valid pending human card can be displayed without saving or approving it; if unavailable, reread the same request instead of preparing another.

Continue without changing the question

Keep each returned continuation with its original mode and filters. Activity is source-grouped, not globally chronological. Follow hasMore even after an empty filtered page. A receipt does not establish current state or progress; missing evidence is unverified, unrecorded history unknown. Unsaved policy previews are absent.

Requires operator:prepare, accounting:read, operations:read and current module access; policy evidence also needs policy:read/Owner access. insufficient_scope/retryAllowed=false requires the indicated consent before another call. Module/role denials are errors, not empty results.

Read the connected workspace identity, discover the available Business core or find existing role positions. For records use get_business_funnel, get_business_goals or get_business_budgets.

Choose view=identity for current context/profile without catalog reads; omit names, domain and detail. Discovery is the default: names and domain intersect, detail=summary returns names/access and full adds descriptions/schemas without expanding permissions. Empty filtered results do not prove absence. This profile covers overview, goals and budgets. Use the separate CRM, Marketing, Policy, Sales or Accounting connection for those domains.

view=roles returns minimal live roleDirectory keys/titles, requires current work:read and Workspace read authority and accepts no catalog filters. Follow nextRoleKey as afterRoleKey while hasMore. Role discovery grants no allocation authority. profile.id is workspace-bound and opaque. missingScopes/access.nextAction identify unmet prerequisites. Authentication failure is an error; this read cannot sign in, switch tenants or grant access. Later actions recheck authority.

Read inquiry-to-paid-work progression and evidenced bottlenecks. Use get_business_goals for target progress and get_business_budgets for spending controls; neither reconstructs an unavailable funnel.

Choose a comparison

Use explicit boundaries for a repeatable reporting question. For example, from=2026-10-08T00:00:00Z and until=2026-10-15T00:00:00Z cover October 8–14; the comparison covers October 1–7. An inclusive end date therefore needs the following midnight. Changing either boundary changes both interval length and its immediately preceding equal-length baseline.

Interpret the evidence

Reports are live, so corrections can alter earlier results. Embedded goal progress is the current observation, not a historical snapshot. Inquiry creation, scheduled service and payment use different dates and populations; these are not one conversion cohort. Missing progression is not rejection, and reach counts are not people.

Original gross can include later refunds; it is neither retained cash nor profit. Payment can precede fulfillment. Keep unavailable-source reasons rather than inventing zeros or reconstructing them from another tool.

Requires accounting:read, operations:read and a supported tenant source adapter. Optional provider reach uses existing reports under current read rights and consent.

Read a goal’s definition, current progress or recorded definition changes. Use get_business_change to locate activity across resources or recover approval requests; use this tool once the goal is known.

Choose the evidence

• To find active goals, call without selectors. includeArchived extends discovery to retired goals.

• To inspect one goal before editing, copy its goalId into an exact read; that read also finds archived goals.

• To compare recorded definitions, use view=history with goalId. A historical target is not a stored historical progress measurement.

Complete the task

For a duplicate check, traverse every active page while hasMore. For inspecting a known goal, use its ID rather than repeatedly listing. Smaller list pages calculate progress for fewer goals, so a partial page cannot prove no other goal exists. Live inserts can shift pages.

Progress is recomputed within the reporting span. Missing sources or unsupported segments leave started periods unknown. Additive metrics read zero before the span begins, meaning no in-period events yet. Storage/evidence failures are errors.

Read the current revision before update_business_goal/archive_business_goal; create_business_goal creates a separate goal. get_business_funnel supplies source evidence and get_business_budgets spending controls. Requires accounting:read, operations:read and current access.

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.

Change a role share

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.

Replace an active goal’s definition on explicit request. Use create_business_goal to create a separate goal and archive_business_goal to retire one. Archived goals cannot be edited or restored.

Build the replacement

Read get_business_goals(goalId), then construct a complete flat draft from that definition. For “change only the target,” keep its metric, dates, cadence, comparator, title and segment choices while changing targetValue. Omitted optional fields take defaults, a derived title or null segments; they do not retain stored values.

Changing metric also changes the target’s meaning: 500 is 5% for booking_rate but EUR 5 for paid_revenue. Decide the new metric and target together rather than carrying a number across units blindly.

Apply or hand off

If either old or new metric is paid_revenue, the result is owner_approval_required/activates=false with a human card. Models never call confirm_business_change. Otherwise active contains the stored definition/revision, not measured progress. rejected changes nothing—read its reason. No spending or provider action occurs.

Recover

requestKey spans this actor/workspace’s goal create/update/archive intents. Exact replay retains the original expectedRevision after success and returns the old receipt. Reread the goal after replay or uncertainty before another change. Requires operator:prepare, accounting:read, operations:read and current authority, rechecked at the write.

Withdraw your own pending goal/budget approval request on explicit instruction. Read get_business_change first and select the pending request’s proposalId, not the active resource ID. Applied work belongs to its resource’s update/archive operation; an unsaved policy preview has no request to withdraw.

Bind the withdrawal

Create a separate withdrawal requestKey. Do not reuse the key that created or prepared the request: withdrawal is a different intent. Keep that new key paired with the selected proposalId for exact replay; changed intent conflicts.

Interpret the effect

Withdrawal invalidates the old human Owner card while retaining the original request and immutable receipt. It changes no active resource, money, provider work or permissions. Other actors’ requests and approved, expired or missing requests remain untouched.

withdrawn proves this withdrawal was recorded; it does not report current resource state. not_applied means this attempt recorded no withdrawal—read its reason. After replay or an uncertain reply, read get_business_change(proposalId) instead of writing again, changing the key or treating the preparation receipt as a withdrawal receipt.

The transaction rechecks operator:prepare, accounting:read, operations:read and existing module/grant authority.