Skip to main content
Glama

Ziel ändern

update_business_goal
DestructiveIdempotent

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.

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": {
      "metric": "<metric>",
      "targetValue": "<targetValue>",
      "startsOn": "<startsOn>",
      "deadlineOn": "<deadlineOn>",
      "goalId": "<goalId>",
      "expectedRevision": "<expectedRevision>",
      "requestKey": "<requestKey>"
    },
    "name": "update_business_goal"
  }
}

Input Schema

NameRequiredDescriptionDefault
titleNoOptional display label; omitted derives a label from the goal. A label does not change measurement or source coverage.
goalIdYesExact opaque goalId returned by get_business_goals in this workspace; never a proposal ID or another tenant's identifier.
metricYesMeasurement: original paid revenue, inquiry count, booking count or booking rate. Money goals require Owner approval.
cadenceNoonce targets the entire date span; weekly repeats the full targetValue per business reporting week in that span. Omitted means once.once
startsOnYesFirst included valid UTC calendar day, YYYY-MM-DD.
comparatorNoMinimum to reach or maximum to stay within; omitted means at_least.at_least
deadlineOnYesLast included valid UTC calendar day, YYYY-MM-DD, on or after startsOn. Clarify ambiguous dates before a write.
requestKeyYesCaller-generated request UUID. Keep it with the same exact operation, actor and payload; a reused key with changed contents is rejected. After an uncertain result read the goal, never invent another key.
segmentKeyNoExisting segment identifier; omitted or null means tenant-wide. An invented identifier does not establish measurable source coverage.
targetValueYesSafe integer in EUR cents for paid_revenue, counts for inquiries/bookings, or basis points for booking_rate (100 = 1%; maximum 10000). No currency conversion.
segmentLabelNoDisplay label for segmentKey; omitted or null when no segment is selected. Not a source selector.
expectedRevisionYesExact revision from the same goalId read. A changed goal requires a fresh read and renewed user intent, not automatic revision replacement.

Output Schema

NameRequiredDescriptionDefault
goalNoFlat stored goal definition and identity/revision metadata; no measured actual, progress or pace.
goalIdNoStored goal identity, present with active/archived results.
reasonNoRejection reason; no goal change was applied.
statusYesRead before reporting success: stored active/archived goal, unactivated Owner request, or rejected change.
replayedNoOriginal receipt replay, not proof of current goal or request state.
revisionNoRevision of the returned active/archived goal, not a measured-progress revision.
activatesYesTrue only for an active non-money result; an Owner request never activates the goal.
nextActionNoExact existing card/read continuation for an unactivated Owner request; models never confirm.
proposalIdNoStored Owner-request identity, present with owner_approval_required; not a goal ID.
presentationNoThe request receipt is retained even if its card could not be displayed. Read the same proposal; never prepare again.
lifecycleStatusNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "https://json-schema.org/draft/2020-12/schema",
      +  "additionalProperties": false,
      +  "properties": {
      +    "activates": {
      +      "description": "True only for an active non-money result; an Owner request never activates the goal.",
      +      "type": "boolean"
      +    },
      +    "goal": {
      +      "additionalProperties": false,
      +      "description": "Flat stored goal definition and identity/revision metadata; no measured actual, progress or pace.",
      +      "properties": {
      +        "accountId": {
      +          "type": "string"
      +        },
      +        "cadence": {
      +          "enum": [
      +            "once",
      +            "weekly"
      +          ],
      +          "type": "string"
      +        },
      +        "comparator": {
      +          "enum": [
      +            "at_least",
      +            "at_most"
      +          ],
      +          "type": "string"
      +        },
      +        "createdAt": {
      +          "type": "string"
      +        },
      +        "deadlineOn": {
      +          "type": "string"
      +        },
      +        "goalId": {
      +          "type": "string"
      +        },
      +        "id": {
      +          "type": "string"
      +        },
      +        "lifecycleStatus": {
      +          "enum": [
      +            "active",
      +            "archived"
      +          ],
      +          "type": "string"
      +        },
      +        "metric": {
      +          "enum": [
      +            "paid_revenue",
      +            "inquiries",
      +            "bookings",
      +            "booking_rate"
      +          ],
      +          "type": "string"
      +        },
      +        "revision": {
      +          "type": "string"
      +        },
      +        "segmentKey": {
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "segmentLabel": {
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "startsOn": {
      +          "type": "string"
      +        },
      +        "status": {
      +          "enum": [
      +            "active",
      +            "archived"
      +          ],
      +          "type": "string"
      +        },
      +        "targetValue": {
      +          "type": "number"
      +        },
      +        "title": {
      +          "type": "string"
      +        },
      +        "unit": {
      +          "enum": [
      +            "eur_cents",
      +            "count",
      +            "basis_points"
      +          ],
      +          "type": "string"
      +        },
      +        "updatedAt": {
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "id",
      +        "accountId",
      +        "goalId",
      +        "revision",
      +        "metric",
      +        "comparator",
      +        "targetValue",
      +        "unit",
      +        "startsOn",
      +        "deadlineOn",
      +        "cadence",
      +        "segmentKey",
      +        "segmentLabel",
      +        "title",
      +        "status",
      +        "lifecycleStatus"
      +      ],
      +      "type": "object"
      +    },
      +    "goalId": {
      +      "description": "Stored goal identity, present with active/archived results.",
      +      "type": "string"
      +    },
      +    "lifecycleStatus": {
      +      "enum": [
      +        "active",
      +        "archived"
      +      ],
      +      "type": "string"
      +    },
      +    "nextAction": {
      +      "additionalProperties": false,
      +      "description": "Exact existing card/read continuation for an unactivated Owner request; models never confirm.",
      +      "properties": {
      +        "arguments": {
      +          "additionalProperties": false,
      +          "properties": {
      +            "proposalId": {
      +              "type": "string"
      +            }
      +          },
      +          "required": [
      +            "proposalId"
      +          ],
      +          "type": "object"
      +        },
      +        "capability": {
      +          "description": "Exact server-provided continuation in this connection; copy it rather than infer another tool.",
      +          "type": "string"
      +        },
      +        "requiresHumanClick": {
      +          "const": true,
      +          "type": "boolean"
      +        }
      +      },
      +      "required": [
      +        "capability",
      +        "requiresHumanClick",
      +        "arguments"
      +      ],
      +      "type": "object"
      +    },
      +    "presentation": {
      +      "const": "unavailable_read_same_proposal",
      +      "description": "The request receipt is retained even if its card could not be displayed. Read the same proposal; never prepare again.",
      +      "type": "string"
      +    },
      +    "proposalId": {
      +      "description": "Stored Owner-request identity, present with owner_approval_required; not a goal ID.",
      +      "type": "string"
      +    },
      +    "reason": {
      +      "description": "Rejection reason; no goal change was applied.",
      +      "type": "string"
      +    },
      +    "replayed": {
      +      "description": "Original receipt replay, not proof of current goal or request state.",
      +      "type": "boolean"
      +    },
      +    "revision": {
      +      "description": "Revision of the returned active/archived goal, not a measured-progress revision.",
      +      "type": "string"
      +    },
      +    "status": {
      +      "description": "Read before reporting success: stored active/archived goal, unactivated Owner request, or rejected change.",
      +      "enum": [
      +        "active",
      +        "archived",
      +        "owner_approval_required",
      +        "rejected"
      +      ],
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "status",
      +    "activates"
      +  ],
      +  "type": "object"
      +}
  2. Added

TDQS

A4.8/5.0
Behavior5/5

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

Beyond the annotations, it discloses that omitted optional fields reset to defaults rather than retaining stored values, that archived goals cannot be edited or restored, that paid_revenue triggers owner_approval_required with activates=false, that models must not call confirm_business_change, and that rejection changes nothing. It also names required permissions and confirms no spending or provider action occurs, which is substantial behavioral context for a destructive mutation.

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?

It is front-loaded with the key distinction and organized into clear sections ('Build the replacement', 'Apply or hand off', 'Recover'), which is appropriate for a 12-parameter destructive tool. The density is justified, though some sentences are terse enough to require careful reading.

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 high-risk update with 12 parameters, annotations, and an output schema, the description covers the missing decision-critical context: overwrite semantics, approval behavior, replay and recovery, and permission requirements. Nothing essential for correct invocation appears 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 schema already carries most parameter definitions, but the description adds important cross-field semantics the schema cannot provide: replacement is a full overwrite rather than a patch, and changing metric changes the meaning of targetValue across units. That materially improves correct invocation beyond the baseline.

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?

It states a specific verb and resource ('Replace an active goal's definition') and immediately distinguishes the tool from create_business_goal and archive_business_goal. An agent can tell exactly what this tool does and what it is not for 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?

The description gives explicit when-to-use ('on explicit request') and names alternatives for creation and retirement. It also defines the replacement workflow, the approval path for paid_revenue, and recovery behavior after uncertainty, leaving little to inference.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources