Mutate App

Use this to save or change data in one of the caller's Charming apps, such as adding an expense to a budget app.

MCP name: mutate_app

Tool contract

{
  "annotations": {
    "destructiveHint": true,
    "openWorldHint": true,
    "readOnlyHint": false,
    "title": "Mutate App"
  },
  "description": "Use this to save or change data in one of the caller's Charming apps, such as adding an expense to a budget app. `op` names one of the routes the app's author wrote into the app, which get_app lists; this tool runs no code the caller supplies and adds no access beyond the caller's permission to use the app. To only read data, use query_app.",
  "execution": {
    "taskSupport": "forbidden"
  },
  "inputSchema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "properties": {
      "app_id": {
        "description": "UUID of the caller's app whose data to change, from list_apps.",
        "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"
      },
      "op": {
        "description": "Name of a route defined in this app (see get_app).",
        "type": "string"
      },
      "params": {
        "additionalProperties": {},
        "description": "Input for that route: a JSON object matching the route's `input` schema from get_app. Omit it when the route takes no input.",
        "propertyNames": {
          "type": "string"
        },
        "type": "object"
      }
    },
    "required": [
      "app_id",
      "op"
    ],
    "type": "object"
  },
  "name": "mutate_app",
  "outputSchema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false,
    "properties": {
      "advisories": {
        "description": "Structured non-fatal advisories, including authoring issues and unread staff feedback responses. Each advisory.summary is also appended to the text content for the LLM path.",
        "items": {
          "additionalProperties": false,
          "properties": {
            "data": {
              "additionalProperties": {},
              "description": "Kind-specific structured payload. Shape varies per advisory kind.",
              "propertyNames": {
                "type": "string"
              },
              "type": "object"
            },
            "doc_url": {
              "description": "Optional docs pointer for this advisory kind.",
              "type": "string"
            },
            "kind": {
              "description": "Stable advisory identifier (e.g. \"legacy-bridge\").",
              "type": "string"
            },
            "severity": {
              "description": "Severity; omitted advisories are treated as 'info'.",
              "enum": [
                "info",
                "warn"
              ],
              "type": "string"
            },
            "summary": {
              "description": "Agent-facing summary. Self-sufficient; no extra context required.",
              "type": "string"
            },
            "userSummary": {
              "description": "End-user-facing summary. Set when the advisory should render in-app.",
              "type": "string"
            }
          },
          "required": [
            "kind",
            "summary"
          ],
          "type": "object"
        },
        "type": "array"
      },
      "error": {
        "additionalProperties": false,
        "description": "Set when ok=false. Always inspect kind before retrying.",
        "properties": {
          "details": {
            "additionalProperties": {},
            "description": "Handler-supplied structured context for the error. Present on kind=\"handler_error\" when the route handler attached details.",
            "propertyNames": {
              "type": "string"
            },
            "type": "object"
          },
          "errors": {
            "description": "Validation issues from the route input/output schema. Present on kind=\"invalid_input\" and kind=\"invalid_output\".",
            "items": {},
            "type": "array"
          },
          "kind": {
            "description": "Error kind from the app envelope (e.g. \"operation_failed\", \"invalid_input\", \"invalid_output\", \"handler_error\") or a transport-level fallback.",
            "type": "string"
          },
          "message": {
            "description": "Human-readable error message. Secrets are redacted.",
            "type": "string"
          }
        },
        "required": [
          "kind",
          "message"
        ],
        "type": "object"
      },
      "ok": {
        "description": "True if the operation handler returned a successful envelope. False when the app reported an operation error — distinct from a transport/protocol error.",
        "type": "boolean"
      },
      "value": {
        "description": "Operation return value when ok=true. Shape depends on the app and op called."
      }
    },
    "required": [
      "ok"
    ],
    "type": "object"
  }
}