Skip to main content
Glama

Charming

by io.github.tambo-ai
OverviewDiscussionsAdmin

get_app

Read-only

Fetch an existing app by ID and render it inline. Use this to open, re-render, or continue working with an app the caller already has. Returns the live embedded UI plus its callable API operations, which another agent can invoke with query_app (read-only) or mutate_app (writes) to query or update saved app data. Unlike list_apps, which returns metadata including IDs and URLs, get_app renders the app; call list_apps first to find the ID. For synchronous results, give the user shareUrl to open or share the app; the url field is machine-only and embeds a write-capable access token.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
app_idYesThe app ID (UUID)

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
idYesUUID of the opened app.
okYesIndicates success. Errors arrive as content with isError:true.
apiYesFull API surface — same shape as `_meta.charming.api`, but model-facing.
urlYesMachine/API URL for the app (stable /app/<uuid> form). Embeds a write-capable ?t= access token — NEVER show, paste, or send it to the user. Append /api/<op> to its path for out-of-band operation calls. For anything user-facing, use shareUrl instead.
$schemaNoExact dated canonical manifest schema URL. Omitted for legacy apps.
appNameNoURL-safe slug for the app, unique per owner. Distinct from manifestId and displayName, and stable across edits — use rename_app to change it (the title changing does NOT change the slug).
revisionYesServer-owned app source revision. Historical null counters read as 0; new apps start at 1; each successful source write advances it once. Pass this value through `expected_revision` when guarding update_app.
shareUrlYesThe link to give humans whenever the user wants to open or share the app. Friendly /<handle>/<app-name> form when the OWNER has a live handle and the app a slug, /app/<uuid> otherwise. Always token-free — safe to show, paste, and send. Not an API base: appending /api/<op> to the friendly form 404s; use `url` for machine calls.
advisoriesNoStructured 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.
appVersionYesCanonical apps return decimal String(revision). Legacy apps return their stored effective SemVer.
manifestIdYesStable manifest identifier declared by the app module. Distinct from `id` (DB primary key) — surface this when discussing the app with the user.
descriptionYesSearch-friendly summary of what the app does. Null on apps created before descriptions existed; agents are nudged to backfill on the next update_app.
displayNameYesHuman-readable name shown in app listings and headers.
recentIssuesNoRuntime failures recorded against the current app revision since it was published (#1133): contract misses, runtime JS errors, CSP violations, and failed API calls. Present only when the current revision has at least one such event — absence means a clean render. The same summary is appended to the text content. Fetch full detail with GET /app/:id/activity.
manifestVersionYesDeprecated public contract marker. Canonical apps return null; legacy apps return their stored contract date.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • addedOutput schema / properties / api / properties / operations / items / properties / idempotent
      Added value: +{
+  "description": "True when repeating the call with the same input has no further effect.",
+  "type": "boolean"
+}
    • addedOutput schema / properties / api / properties / operations / items / properties / openWorld
      Added value: +{
+  "description": "True when the route may reach beyond the app, such as the network. Default true.",
+  "type": "boolean"
+}
    • changedOutput schema / properties / api / properties / operations / items / required
      Previous value: -[
-  "op",
-  "method",
-  "path",
-  "url",
-  "readOnly",
-  "destructive",
-  "public",
-  "tool",
-  "discoveredFrom"
-]New value: +[
+  "op",
+  "method",
+  "path",
+  "url",
+  "readOnly",
+  "destructive",
+  "idempotent",
+  "openWorld",
+  "public",
+  "tool",
+  "discoveredFrom"
+]
  2. Changed25 schema fields changed
    • addedOutput schema / properties / $schema
      Added value: +{
+  "description": "Exact dated canonical manifest schema URL. Omitted for legacy apps.",
+  "enum": [
+    "https://charm.ing/schema/app-manifest/2026-07-31.json",
+    "https://charm.ing/schema/app-manifest/2026-09-05.json"
+  ],
+  "type": "string"
+}
    • addedOutput schema / properties / advisories
      Added value: +{
+  "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"
+}
    • changedOutput schema / properties / api / description
      Previous value: -"Full API surface — same shape as `_meta.buildy.api`, but model-facing."New value: +"Full API surface — same shape as `_meta.charming.api`, but model-facing."
    • changedOutput schema / properties / api / properties / operations / items / properties / input / description
      Previous value: -"JSON Schema for the field. Same shape passed to `route.input`/`route.output`."New value: +"JSON Schema for the field. Canonical source declares it as `route.inputSchema` or `route.outputSchema`."
    • removedOutput schema / properties / api / properties / operations / items / properties / name
      Removed value: -{
-  "description": "Back-compat alias of `op`. Read either; prefer `op` for new consumers.",
-  "type": "string"
-}
    • changedOutput schema / properties / api / properties / operations / items / properties / output / description
      Previous value: -"JSON Schema for the field. Same shape passed to `route.input`/`route.output`."New value: +"JSON Schema for the field. Canonical source declares it as `route.inputSchema` or `route.outputSchema`."
    • removedOutput schema / properties / appName / anyOf
      Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
    • addedOutput schema / properties / appName / type
      Added value: +[
+  "string",
+  "null"
+]
    • changedOutput schema / properties / appVersion / description
      Previous value: -"Author-declared version string for the app (whatever the manifest source set as `manifest.version`, e.g. \"0.0.1\"). Distinct from the concurrency `version` int and from `manifestVersion` (Charming contract date)."New value: +"Canonical apps return decimal String(revision). Legacy apps return their stored effective SemVer."
    • removedOutput schema / properties / description / anyOf
      Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
    • addedOutput schema / properties / description / type
      Added value: +[
+  "string",
+  "null"
+]
    • changedOutput schema / properties / manifestVersion / description
      Previous value: -"Charming manifest contract date (`YYYY-MM-DD`) the app is pinned to. The runtime branches on this value to pick contract-specific behaviour."New value: +"Deprecated public contract marker. Canonical apps return null; legacy apps return their stored contract date."
    • changedOutput schema / properties / manifestVersion / type
      Previous value: -"string"New value: +[
+  "string",
+  "null"
+]
    • changedOutput schema / properties / recentIssues / description
      Previous value: -"Runtime failures recorded against the current app version since it was published (#1133): contract misses, runtime JS errors, CSP violations, and failed API calls. Present only when the current version has at least one such event — absence means a clean render. The same summary is appended to the text content. Fetch full detail with GET /app/:id/activity."New value: +"Runtime failures recorded against the current app revision since it was published (#1133): contract misses, runtime JS errors, CSP violations, and failed API calls. Present only when the current revision has at least one such event — absence means a clean render. The same summary is appended to the text content. Fetch full detail with GET /app/:id/activity."
    • addedOutput schema / properties / recentIssues / properties / counts / properties / externalResourceFailures
      Added value: +{
+  "description": "Failed external image requests, including failures caught by app code.",
+  "maximum": 9007199254740991,
+  "minimum": -9007199254740991,
+  "type": "integer"
+}
    • changedOutput schema / properties / recentIssues / properties / counts / required
      Previous value: -[
-  "contractMisses",
-  "runtimeErrors",
-  "cspViolations",
-  "apiFailures",
-  "appLoadErrors"
-]New value: +[
+  "contractMisses",
+  "runtimeErrors",
+  "cspViolations",
+  "apiFailures",
+  "externalResourceFailures",
+  "appLoadErrors"
+]
    • changedOutput schema / properties / recentIssues / properties / examples / items / properties / category / enum
      Previous value: -[
-  "contractMisses",
-  "runtimeErrors",
-  "cspViolations",
-  "apiFailures",
-  "appLoadErrors"
-]New value: +[
+  "contractMisses",
+  "runtimeErrors",
+  "cspViolations",
+  "apiFailures",
+  "appLoadErrors",
+  "externalResourceFailures"
+]
    • changedOutput schema / properties / recentIssues / properties / examples / items / properties / kind / description
      Previous value: -"Underlying durable event kind: `diag_report` (runtime errors and CSP violations, distinguished by category), `contract_validation` (contract misses), `api_proxy_result` (API failures), or `app_load_error` (caught load failures)."New value: +"Underlying durable event kind: `diag_report` (runtime errors and CSP violations, distinguished by category), `contract_validation` (contract misses), `api_proxy_result` (API failures), `app_load_error` (caught load failures), or `image_proxy_result` (external image failures)."
    • addedOutput schema / properties / recentIssues / properties / sinceRevision
      Added value: +{
+  "description": "The app revision the issues are attributed to (the current revision at call time). Legacy nulls normalize to 0.",
+  "maximum": 9007199254740991,
+  "minimum": 0,
+  "type": "integer"
+}
    • removedOutput schema / properties / recentIssues / properties / sinceVersion
      Removed value: -{
-  "anyOf": [
-    {
-      "maximum": 9007199254740991,
-      "minimum": -9007199254740991,
-      "type": "integer"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "description": "The app version the issues are attributed to (the current version at call time). Null on legacy rows that predate versioning."
-}
    • changedOutput schema / properties / recentIssues / properties / total / description
      Previous value: -"Issue events counted for the current version, capped at 500 — a value of 500 means 500 or more. Use GET /app/:id/activity for the exact, paginated list."New value: +"Issue events counted for the current revision, capped at 500 — a value of 500 means 500 or more. Use GET /app/:id/activity for the exact, paginated list."
    • changedOutput schema / properties / recentIssues / required
      Previous value: -[
-  "sinceVersion",
-  "total",
-  "counts",
-  "examples"
-]New value: +[
+  "sinceRevision",
+  "total",
+  "counts",
+  "examples"
+]
    • addedOutput schema / properties / revision
      Added value: +{
+  "description": "Server-owned app source revision. Historical null counters read as 0; new apps start at 1; each successful source write advances it once. Pass this value through `expected_revision` when guarding update_app.",
+  "maximum": 9007199254740991,
+  "minimum": 0,
+  "type": "integer"
+}
    • removedOutput schema / properties / version
      Removed value: -{
-  "description": "Monotonic int version of the app. 0 on truly-legacy rows that predate versioning (still editable — pass `expected_version: 0`); otherwise a positive int bumped on every successful update_app/PUT. Pass back as `expected_version` on edits-aware update_app and as `If-Match: \"v<N>\"` on PATCH /app/:id/source.",
-  "maximum": 9007199254740991,
-  "minimum": -9007199254740991,
-  "type": "integer"
-}
    • changedOutput schema / required
      Previous value: -[
-  "ok",
-  "id",
-  "url",
-  "shareUrl",
-  "displayName",
-  "description",
-  "manifestId",
-  "version",
-  "appVersion",
-  "manifestVersion",
-  "api"
-]New value: +[
+  "ok",
+  "id",
+  "url",
+  "shareUrl",
+  "displayName",
+  "description",
+  "manifestId",
+  "revision",
+  "appVersion",
+  "manifestVersion",
+  "api"
+]
  3. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already declare readOnly/destructive/openWorld, but the description goes well beyond them: it discloses that the response contains a live embedded UI plus callable API operations, and warns that the `url` field is machine-only and embeds a write-capable access token while `shareUrl` is the user-safe one. That token-handling caveat is a meaningful behavioral disclosure not available anywhere in structured fields.

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 the core action, and every subsequent sentence carries routing or safety information rather than filler. It is dense but slightly long, packing five distinct ideas into one paragraph where minor trimming would still preserve meaning.

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?

Although an output schema exists, the description still tells the agent what comes back (embedded UI plus invokable operations) and which return field is safe to hand to a user versus which is token-bearing. For a render tool with a downstream query/mutate workflow, nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is a single parameter with 100% schema description coverage, so the schema fully documents app_id including its UUID format and pattern. The description's 'by ID' adds no format or constraint detail beyond that, so the baseline 3 applies.

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 ('Fetch an existing app by ID and render it inline') and immediately distinguishes itself from the closest sibling by contrasting rendering against list_apps' metadata-only return. An agent can tell exactly what this does and what it is not.

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?

Gives explicit when-to-use ('open, re-render, or continue working with an app the caller already has'), names the prerequisite alternative ('call list_apps first to find the ID'), and points to the downstream alternatives query_app and mutate_app with their read/write split.

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

All Charming toolsInspect
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