@magnetoagents/mcp 0.2.0 → 0.3.0

package/dist/tool-catalog.js

@@ -3,6 +3,96 @@
 import { readPackageVersion } from './package-version.js';
 export const MCP_PROTOCOL_VERSION = '2025-03-26';
 export const MCP_SERVER_VERSION = readPackageVersion();
+/** ChatGPT reads this at initialize (InitializeResult.instructions). Front-load D3. */
+export const MCP_SERVER_INSTRUCTIONS = `Magneto is an account companion. Never attempt to purchase, subscribe, or upgrade inside this plugin. If the user wants a plan, a marketplace skill purchase, credits, or checkout, describe the option and link to https://magnetoapp.io — never a checkout, upgrade, or payment deep-link. Runs and computer lifecycle actions bill the linked Magneto account's existing plan.
+
+Typical flow: search or list the catalog (list_skills, search_marketplace, list_templates) → list or get the user's computers → create or start a computer if needed → install_skill only when the account already owns that skill → run a computer-use instruction → review with list_runs / get_run. Call get before a write when the computer id is uncertain.
+
+Do not call bash, action, screenshot, gateway_url, chat, or any payment tool. Do not mint gateway credentials. If a skill is unowned or paid, refuse to install and point at https://magnetoapp.io. If the account's plan does not cover an action, name the state and point at https://magnetoapp.io as information — never an upgrade CTA.`;
+export const HINT_READ = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: false,
+};
+export const HINT_WRITE = {
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: false,
+};
+export const HINT_DESTRUCTIVE = {
+    readOnlyHint: false,
+    destructiveHint: true,
+    openWorldHint: false,
+};
+export const HINT_OPEN_WORLD = {
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: true,
+};
+export const HINT_BASH = {
+    readOnlyHint: false,
+    destructiveHint: true,
+    openWorldHint: true,
+};
+const READ = { scheme: 'exact', usd: 0.01 };
+const KEYLESS_READ = { scheme: 'exact', usd: 0.01, keyless: true };
+const MUTATION = { scheme: 'exact', usd: 0.02 };
+const UPTO_METERED = {
+    scheme: 'upto',
+    usd: 0.1,
+    note: 'ceiling = estimate × 1.25, floor $0.10 — Issue 6',
+};
+/** Inlined join of hosted `PRICES` via specMethod+specPath. Do not import `@/`. */
+const STDIO_PRICES = {
+    'POST /computers': {
+        scheme: 'quote',
+        note: 'shape-based provision fee (SHAPE_HOURLY_RATE_USD × prepaid hours) — Issue 8',
+    },
+    'GET /computers': READ,
+    'GET /computers/{id}': READ,
+    'POST /computers/{id}/start': MUTATION,
+    'POST /computers/{id}/stop': MUTATION,
+    'POST /computers/{id}/restart': MUTATION,
+    'DELETE /computers/{id}': MUTATION,
+    'POST /computers/{id}/resize': MUTATION,
+    'GET /computers/{id}/uptime': READ,
+    'POST /computers/{id}/gateway': MUTATION,
+    'POST /computers/{id}/actions/{action}': MUTATION,
+    'POST /computers/{id}/bash': { scheme: 'exact', usd: 0.05 },
+    'POST /computers/{id}/computer-use/run': UPTO_METERED,
+    'POST /computers/{id}/computer-use/stop': READ,
+    'GET /computers/{id}/runs': READ,
+    'GET /computers/{id}/runs/{runId}': READ,
+    'POST /computers/{id}/skills': {
+        scheme: 'quote',
+        note: 'free skill $0.01; unowned paid skill = catalog price — Issue 5',
+    },
+    'DELETE /computers/{id}/skills/{skillId}': READ,
+    'GET /skills': KEYLESS_READ,
+    'GET /templates': KEYLESS_READ,
+    'GET /files': READ,
+    'GET /account': 'free',
+    'POST /chat/completions': UPTO_METERED,
+};
+function withX402(def) {
+    const key = `${def.specMethod.toUpperCase()} ${def.specPath}`;
+    const x402 = STDIO_PRICES[key];
+    if (x402 === undefined) {
+        throw new Error(`MCP tool '${def.name}' has no inlined PriceEntry for ${key}`);
+    }
+    return { ...def, x402 };
+}
+export function toListedTool(def) {
+    return {
+        name: def.name,
+        title: def.title,
+        description: def.description,
+        inputSchema: def.inputSchema,
+        annotations: def.annotations,
+        ...(def.outputSchema ? { outputSchema: def.outputSchema } : {}),
+        _meta: { x402: def.x402 },
+    };
+}
 export const DESKTOP_ACTION_ENUM = [
     'screenshot',
     'click',
@@ -15,10 +105,252 @@ export const DESKTOP_ACTION_ENUM = [
     'drag',
     'wait',
 ];
-export const MCP_TOOL_CATALOG = [
+const COMPUTER_PUBLIC_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['id'],
+    properties: {
+        id: { type: 'string' },
+        name: { type: ['string', 'null'] },
+        kind: { type: 'string', enum: ['agent', 'desktop'] },
+        state: { type: 'string' },
+        cpu: { type: ['integer', 'null'] },
+        ram_gb: { type: ['integer', 'null'] },
+        disk_gb: { type: ['integer', 'null'] },
+        os: { type: ['string', 'null'] },
+        always_on: { type: 'boolean' },
+        llm_mode: { type: ['string', 'null'] },
+        template_id: { type: ['integer', 'null'] },
+        region: { type: ['string', 'null'] },
+        provider: { type: 'string' },
+    },
+};
+const LIST_OUTPUT_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['items'],
+    properties: {
+        items: { type: 'array', items: COMPUTER_PUBLIC_SCHEMA },
+    },
+};
+const AGENT_RUN_PUBLIC_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['id', 'computer_id', 'status', 'model'],
+    properties: {
+        id: { type: 'string' },
+        computer_id: { type: 'string' },
+        status: { type: 'string' },
+        model: { type: 'string' },
+        steps: { type: ['integer', 'null'] },
+        input_tokens: { type: ['integer', 'null'] },
+        output_tokens: { type: ['integer', 'null'] },
+        cost_usd: { type: ['string', 'number', 'null'] },
+        key_source: { type: ['string', 'null'] },
+        provider: { type: ['string', 'null'] },
+        instruction: { type: ['string', 'null'] },
+        started_at: { type: ['string', 'null'] },
+        completed_at: { type: ['string', 'null'] },
+        duration_seconds: { type: ['number', 'null'] },
+    },
+};
+const LIST_RUNS_OUTPUT_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['items', 'total', 'limit', 'offset'],
+    properties: {
+        items: { type: 'array', items: AGENT_RUN_PUBLIC_SCHEMA },
+        total: { type: 'integer' },
+        limit: { type: 'integer' },
+        offset: { type: 'integer' },
+    },
+};
+const AGENT_RUN_EVENT_PUBLIC_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['id', 'run_id', 'seq', 'type'],
+    properties: {
+        id: { type: 'string' },
+        run_id: { type: 'string' },
+        seq: { type: 'integer' },
+        type: { type: 'string' },
+        created_at: { type: ['string', 'null'] },
+    },
+};
+const GET_RUN_OUTPUT_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['run', 'events'],
+    properties: {
+        run: AGENT_RUN_PUBLIC_SCHEMA,
+        events: { type: 'array', items: AGENT_RUN_EVENT_PUBLIC_SCHEMA },
+    },
+};
+const SKILL_PUBLIC_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['id', 'name', 'description', 'price', 'category', 'created_at'],
+    properties: {
+        id: { type: 'integer' },
+        name: { type: 'string' },
+        description: { type: 'string' },
+        price: { type: 'number' },
+        category: { type: ['string', 'null'] },
+        created_at: { type: 'string' },
+    },
+};
+const LIST_SKILLS_OUTPUT_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['items'],
+    properties: {
+        items: { type: 'array', items: SKILL_PUBLIC_SCHEMA },
+    },
+};
+const SEARCH_MARKETPLACE_OUTPUT_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['items'],
+    properties: {
+        items: { type: 'array', items: SKILL_PUBLIC_SCHEMA },
+        exact: {
+            ...SKILL_PUBLIC_SCHEMA,
+            type: ['object', 'null'],
+        },
+    },
+};
+const TEMPLATE_PUBLIC_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['id', 'name', 'description', 'category'],
+    properties: {
+        id: { type: 'integer' },
+        name: { type: 'string' },
+        description: { type: 'string' },
+        category: { type: 'string' },
+        image_url: { type: 'string' },
+    },
+};
+const LIST_TEMPLATES_OUTPUT_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['items'],
+    properties: {
+        items: { type: 'array', items: TEMPLATE_PUBLIC_SCHEMA },
+    },
+};
+const FILE_PUBLIC_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['id', 'filename', 'size_bytes', 'content_type', 'created_at'],
+    properties: {
+        id: { type: 'string' },
+        filename: { type: 'string' },
+        size_bytes: { type: 'integer' },
+        content_type: { type: 'string' },
+        created_at: { type: 'string' },
+    },
+};
+const LIST_FILES_OUTPUT_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['items'],
+    properties: {
+        items: { type: 'array', items: FILE_PUBLIC_SCHEMA },
+    },
+};
+const ACCOUNT_OUTPUT_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['workspace', 'subscription', 'usage', 'key', 'rate_limit', 'spend', 'mandates'],
+    properties: {
+        workspace: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['id'],
+            properties: {
+                id: { type: 'string' },
+                name: { type: ['string', 'null'] },
+            },
+        },
+        subscription: {
+            type: ['object', 'null'],
+            additionalProperties: true,
+        },
+        usage: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['cu', 'llm', 'requests_today'],
+            properties: {
+                cu: { type: ['object', 'null'], additionalProperties: true },
+                llm: { type: ['object', 'null'], additionalProperties: true },
+                requests_today: { type: ['integer', 'null'] },
+            },
+        },
+        key: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['prefix', 'scopes', 'expires_at', 'last_used_at'],
+            properties: {
+                prefix: { type: 'string' },
+                scopes: {
+                    type: 'array',
+                    items: {
+                        type: 'string',
+                        enum: ['computers', 'exec', 'runs', 'files', 'catalog', 'account'],
+                    },
+                },
+                expires_at: { type: ['string', 'null'] },
+                last_used_at: { type: ['string', 'null'] },
+            },
+        },
+        rate_limit: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['limit', 'window_s'],
+            properties: {
+                limit: { type: 'integer' },
+                window_s: { type: 'integer' },
+            },
+        },
+        spend: {
+            type: ['object', 'null'],
+            additionalProperties: false,
+            required: ['limit_usd', 'window_days', 'spent_usd', 'remaining_usd'],
+            properties: {
+                limit_usd: { type: 'number' },
+                window_days: { type: 'integer' },
+                spent_usd: { type: 'number' },
+                remaining_usd: { type: 'number' },
+            },
+        },
+        mandates: {
+            type: 'array',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['id', 'name', 'max_amount_usd', 'remaining_budget_usd', 'expires_at'],
+                properties: {
+                    id: { type: 'string' },
+                    name: { type: 'string' },
+                    max_amount_usd: { type: 'number' },
+                    remaining_budget_usd: { type: ['number', 'null'] },
+                    expires_at: { type: ['string', 'null'] },
+                },
+            },
+        },
+        warnings: {
+            type: 'array',
+            items: { type: 'string' },
+        },
+    },
+};
+const MCP_TOOL_DEFS = [
     {
         name: 'create',
-        description: 'Create a Magneto computer in the API key workspace. Scope computers. Works for both desktop and agent flavors (default flavor is agent; use flavor=desktop for CU machines). workspace_id is forced from the key; client-supplied workspace_id is ignored.',
+        title: 'Create computer',
+        annotations: HINT_WRITE,
+        description: "Use this when the user wants a new Magneto computer provisioned into their linked account's existing plan. Do not use for buying a plan, upgrading, or checkout — if the plan cannot cover the create, name the state and link to https://magnetoapp.io. Scope computers. Works for both desktop and agent flavors (default flavor is agent; use flavor=desktop for CU machines). workspace_id is forced from the key; client-supplied workspace_id is ignored.",
         inputSchema: {
             type: 'object',
             properties: {
@@ -42,8 +374,11 @@ export const MCP_TOOL_CATALOG = [
     },
     {
         name: 'list',
-        description: 'List computers for the API key minting user. Scope computers. Returns both desktop and agent computers.',
+        title: 'List computers',
+        annotations: HINT_READ,
+        description: 'Use this when the user asks which Magneto computers they have or you need a computer_id before a write. Do not use for marketplace catalog browsing (list_skills, search_marketplace, list_templates) or run history (list_runs). Scope computers. Returns both desktop and agent computers.',
         inputSchema: { type: 'object', properties: {} },
+        outputSchema: LIST_OUTPUT_SCHEMA,
         requiredScope: 'computers',
         kinds: 'both',
         specMethod: 'get',
@@ -51,12 +386,15 @@ export const MCP_TOOL_CATALOG = [
     },
     {
         name: 'get',
-        description: 'Get one computer by id. Scope computers. Works for both desktop and agent computers.',
+        title: 'Get computer',
+        annotations: HINT_READ,
+        description: "Use this when you need one computer's status by id, especially before a write when the computer_id is uncertain. Do not use for listing every computer (list) or for run replay (get_run). Scope computers. Works for both desktop and agent computers.",
         inputSchema: {
             type: 'object',
             required: ['computer_id'],
             properties: { computer_id: { type: 'string' } },
         },
+        outputSchema: COMPUTER_PUBLIC_SCHEMA,
         requiredScope: 'computers',
         kinds: 'both',
         specMethod: 'get',
@@ -64,7 +402,9 @@ export const MCP_TOOL_CATALOG = [
     },
     {
         name: 'start',
-        description: 'Start a stopped computer. Scope computers. Works for both desktop and agent computers.',
+        title: 'Start computer',
+        annotations: HINT_WRITE,
+        description: 'Use this when the user wants to start a stopped Magneto computer they already own. Do not use for create (new machine) or run (computer-use loop). Scope computers. Works for both desktop and agent computers.',
         inputSchema: {
             type: 'object',
             required: ['computer_id'],
@@ -77,7 +417,9 @@ export const MCP_TOOL_CATALOG = [
     },
     {
         name: 'stop',
-        description: 'Stop a computer. Scope computers. Works for both desktop and agent computers.',
+        title: 'Stop computer',
+        annotations: HINT_WRITE,
+        description: 'Use this when the user wants to stop a running Magneto computer they already own. Do not use for delete (irreversible deprovision) or stop_run (halt a CU loop only). Scope computers. Works for both desktop and agent computers.',
         inputSchema: {
             type: 'object',
             required: ['computer_id'],
@@ -90,7 +432,9 @@ export const MCP_TOOL_CATALOG = [
     },
     {
         name: 'restart',
-        description: 'Restart a running or degraded computer. Scope computers. Works for both desktop and agent computers.',
+        title: 'Restart computer',
+        annotations: HINT_WRITE,
+        description: 'Use this when the user wants to restart a running or degraded Magneto computer they already own. Do not use for start of a stopped computer or for stop_run. Scope computers. Works for both desktop and agent computers.',
         inputSchema: {
             type: 'object',
             required: ['computer_id'],
@@ -103,7 +447,9 @@ export const MCP_TOOL_CATALOG = [
     },
     {
         name: 'delete',
-        description: 'DESTRUCTIVE. Irreversible deprovision. confirm must equal the computer name. Scope computers. Works for both desktop and agent computers.',
+        title: 'Delete computer',
+        annotations: HINT_DESTRUCTIVE,
+        description: 'Use this when the user asks to permanently deprovision a Magneto computer they already own. Do not use for stop (reversible power-off) or uninstall_skill. DESTRUCTIVE and irreversible; confirm must equal the computer name. Scope computers. Works for both desktop and agent computers. Never refund or sell in-plugin.',
         inputSchema: {
             type: 'object',
             required: ['computer_id', 'confirm'],
@@ -119,7 +465,9 @@ export const MCP_TOOL_CATALOG = [
     },
     {
         name: 'resize',
-        description: 'Resize a desktop computer (grow-only: vcpu, ram_gb, disk_gb). Scope computers. Desktop grow-only; agent or shrink returns 422 passthrough.',
+        title: 'Resize computer',
+        annotations: HINT_WRITE,
+        description: 'Use this when the user wants to grow a desktop computer (vcpu, ram_gb, disk_gb). Do not use for shrinking, for agent computers (422), or as a plan-upgrade path — over-plan 402/403 is informational; link https://magnetoapp.io. Scope computers. Desktop grow-only.',
         inputSchema: {
             type: 'object',
             required: ['computer_id'],
@@ -137,7 +485,9 @@ export const MCP_TOOL_CATALOG = [
     },
     {
         name: 'uptime',
-        description: 'Get Fly Prometheus uptime for a computer. Scope computers. Works for both desktop and agent computers. Optional window_seconds.',
+        title: 'Get computer uptime',
+        annotations: HINT_READ,
+        description: 'Use this when the user asks Fly Prometheus uptime for a computer. Do not use as a substitute for get or list, and do not use it to start or stop a machine. Scope computers. Works for both desktop and agent computers. Optional window_seconds.',
         inputSchema: {
             type: 'object',
             required: ['computer_id'],
@@ -153,7 +503,9 @@ export const MCP_TOOL_CATALOG = [
     },
     {
         name: 'gateway_url',
-        description: 'Mint a 60-second signed gateway URL. Scope computers. Desktop uses /desk; agent uses /connect. target=terminal is desktop-only. Do not log the url.',
+        title: 'Mint gateway URL',
+        annotations: HINT_WRITE,
+        description: 'Use this when a keyed client needs a 60-second signed gateway URL. Do not use for plugin-surface workflows, do not log the url, and do not mint credentials for ChatGPT. Scope computers. Desktop uses /desk; agent uses /connect. target=terminal is desktop-only.',
         inputSchema: {
             type: 'object',
             required: ['computer_id'],
@@ -169,7 +521,9 @@ export const MCP_TOOL_CATALOG = [
     },
     {
         name: 'screenshot',
-        description: 'Take a screenshot of a desktop computer. Scope computers. Desktop-gui: real screenshot. Agent computers return structured status (screenshot: null, no action call).',
+        title: 'Take screenshot',
+        annotations: HINT_READ,
+        description: 'Use this when a keyed client needs a single desktop screenshot. Do not use for multi-step computer-use (run / get_run) or as a ChatGPT plugin tool. Scope computers. Desktop-gui: real screenshot. Agent computers return structured status (screenshot: null, no action call). Agent stub is not charged; desktop-gui is exact $0.02.',
         inputSchema: {
             type: 'object',
             required: ['computer_id'],
@@ -182,7 +536,9 @@ export const MCP_TOOL_CATALOG = [
     },
     {
         name: 'action',
-        description: 'Dispatch one desktop GUI action (screenshot, click, double_click, right_click, move, type, key, scroll, drag, wait). Scope computers. Desktop-gui only. Agent computers return structured status (action: null, no helper call).',
+        title: 'Dispatch desktop action',
+        annotations: HINT_OPEN_WORLD,
+        description: 'Use this when a keyed client needs one desktop GUI primitive (screenshot, click, double_click, right_click, move, type, key, scroll, drag, wait). Do not use for multi-step computer-use (run) or as a ChatGPT plugin tool. Scope computers. Desktop-gui only. Agent computers return structured status (action: null, no helper call). Agent stub is not charged; desktop-gui is exact $0.02.',
         inputSchema: {
             type: 'object',
             required: ['computer_id', 'action'],
@@ -213,7 +569,9 @@ export const MCP_TOOL_CATALOG = [
     },
     {
         name: 'bash',
-        description: 'Run a shell command on a computer. Scope exec (opt-in, not in DEFAULT_SCOPES). Allowed on desktop and agent. Output capped 1 MiB; timeout 1–300 s.',
+        title: 'Run shell command',
+        annotations: HINT_BASH,
+        description: 'Use this when a keyed client with opt-in exec scope needs a shell command on a computer. Do not use as a substitute for run, and do not call it from ChatGPT plugin workflows. Scope exec (opt-in, not in DEFAULT_SCOPES). Allowed on desktop and agent. Output capped 1 MiB; timeout 1–300 s. DESTRUCTIVE and open-world.',
         inputSchema: {
             type: 'object',
             required: ['computer_id', 'command'],
@@ -230,7 +588,9 @@ export const MCP_TOOL_CATALOG = [
     },
     {
         name: 'run',
-        description: 'Run a computer-use instruction on a desktop computer (streaming CU loop). Scope runs. Desktop only. Burns the platform CU spend cap or the single named BYO secret. Concurrent-run ceiling applies (429). Agent computers return 422.',
+        title: 'Run computer-use agent',
+        annotations: HINT_OPEN_WORLD,
+        description: "Use this when the user wants an agentic computer-use instruction executed on a desktop they already own. Do not use for agent-flavor computers (422), for a single GUI primitive (action), or to purchase credits — runs bill the linked account's existing CU/LLM plan (platform CU spend cap or the single named BYO secret). Scope runs. Desktop only. Concurrent-run ceiling applies (429).",
         inputSchema: {
             type: 'object',
             required: ['computer_id', 'instruction'],
@@ -248,7 +608,9 @@ export const MCP_TOOL_CATALOG = [
     },
     {
         name: 'stop_run',
-        description: 'Hard-stop a computer-use run. Scope runs. Desktop-cu. Body run_id. 404 if already finished.',
+        title: 'Stop computer-use run',
+        annotations: HINT_WRITE,
+        description: 'Use this when the user wants to hard-stop an in-flight computer-use run. Do not use for stop (power off the computer) or delete. Scope runs. Desktop-cu. Body run_id. 404 if already finished.',
         inputSchema: {
             type: 'object',
             required: ['computer_id', 'run_id'],
@@ -264,7 +626,9 @@ export const MCP_TOOL_CATALOG = [
     },
     {
         name: 'list_runs',
-        description: 'List computer-use run history for a computer. Scope runs. Desktop-cu. Optional limit and offset.',
+        title: 'List computer-use runs',
+        annotations: HINT_READ,
+        description: 'Use this when the user asks for computer-use run history on a computer. Do not use for listing computers (list) or marketplace skills (list_skills). Scope runs. Desktop-cu. Optional limit and offset.',
         inputSchema: {
             type: 'object',
             required: ['computer_id'],
@@ -274,6 +638,7 @@ export const MCP_TOOL_CATALOG = [
                 offset: { type: 'number' },
             },
         },
+        outputSchema: LIST_RUNS_OUTPUT_SCHEMA,
         requiredScope: 'runs',
         kinds: 'desktop-cu',
         specMethod: 'get',
@@ -281,7 +646,9 @@ export const MCP_TOOL_CATALOG = [
     },
     {
         name: 'get_run',
-        description: 'Get a computer-use run and its step events. Scope runs. Desktop-cu. Signed screenshot URLs are credentials — do not log them.',
+        title: 'Get computer-use run',
+        annotations: HINT_READ,
+        description: 'Use this when the user wants one computer-use run and its step events. Do not use for live control (run / stop_run) or for listing all runs. Scope runs. Desktop-cu. Signed screenshot URLs are credentials — do not log them.',
         inputSchema: {
             type: 'object',
             required: ['computer_id', 'run_id'],
@@ -290,6 +657,7 @@ export const MCP_TOOL_CATALOG = [
                 run_id: { type: 'string' },
             },
         },
+        outputSchema: GET_RUN_OUTPUT_SCHEMA,
         requiredScope: 'runs',
         kinds: 'desktop-cu',
         specMethod: 'get',
@@ -297,7 +665,9 @@ export const MCP_TOOL_CATALOG = [
     },
     {
         name: 'install_skill',
-        description: 'Install a marketplace skill onto a computer by numeric skill_id. Scope computers. Works for both desktop and agent computers.',
+        title: 'Install skill',
+        annotations: HINT_WRITE,
+        description: 'Use this when the linked account already owns the marketplace skill and the user wants it installed on a computer. Do not use for buying, quoting, or fulfilling an unowned or paid skill — refuse and link to https://magnetoapp.io. Scope computers. Works for both desktop and agent computers. Requires computer_id and numeric skill_id.',
         inputSchema: {
             type: 'object',
             required: ['computer_id', 'skill_id'],
@@ -313,7 +683,9 @@ export const MCP_TOOL_CATALOG = [
     },
     {
         name: 'uninstall_skill',
-        description: 'Uninstall a marketplace skill from a computer. Scope computers. Works for both desktop and agent computers. Missing install is a no-op.',
+        title: 'Uninstall skill',
+        annotations: HINT_DESTRUCTIVE,
+        description: 'Use this when the user wants a marketplace skill removed from one computer. Do not use for delete (deprovision the computer) or as a purchase refund. DESTRUCTIVE and irreversible for that computer; missing install is a no-op. Scope computers. Works for both desktop and agent computers.',
         inputSchema: {
             type: 'object',
             required: ['computer_id', 'skill_id'],
@@ -329,7 +701,9 @@ export const MCP_TOOL_CATALOG = [
     },
     {
         name: 'list_skills',
-        description: 'List marketplace skills (GET /skills). Scope catalog. Not the per-computer installed list. REST has no search query.',
+        title: 'List marketplace skills',
+        annotations: HINT_READ,
+        description: 'Use this when the user wants to browse the public marketplace skill catalog. Do not use to purchase, subscribe, or checkout — browse only; buying is https://magnetoapp.io. Scope catalog. Not the per-computer installed list. REST has no search query.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -337,6 +711,7 @@ export const MCP_TOOL_CATALOG = [
                 limit: { type: 'number' },
             },
         },
+        outputSchema: LIST_SKILLS_OUTPUT_SCHEMA,
         requiredScope: 'catalog',
         kinds: 'both',
         specMethod: 'get',
@@ -344,7 +719,9 @@ export const MCP_TOOL_CATALOG = [
     },
     {
         name: 'search_marketplace',
-        description: 'Search the marketplace skill page in-tool (name/description filter). Scope catalog. REST has no ?q= — this is a tool-side filter over GET /skills. A numeric query also fetches GET /skills/{id}.',
+        title: 'Search marketplace',
+        annotations: HINT_READ,
+        description: 'Use this when the user wants to search skills by name or description. Do not use to purchase or to scan the full catalog — matches outside the fetched marketplace skill page window (GET /skills skip/limit; default page size 100) are omitted. Scope catalog. REST has no ?q=. A numeric query also fetches GET /skills/{id} unfiltered. Buying is https://magnetoapp.io.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -353,6 +730,7 @@ export const MCP_TOOL_CATALOG = [
                 limit: { type: 'number' },
             },
         },
+        outputSchema: SEARCH_MARKETPLACE_OUTPUT_SCHEMA,
         requiredScope: 'catalog',
         kinds: 'both',
         specMethod: 'get',
@@ -360,7 +738,9 @@ export const MCP_TOOL_CATALOG = [
     },
     {
         name: 'list_templates',
-        description: 'List marketplace computer templates. Scope catalog.',
+        title: 'List templates',
+        annotations: HINT_READ,
+        description: "Use this when the user wants to browse marketplace computer templates before create. Do not use to purchase a plan or as a substitute for list (the user's computers). Scope catalog. Browse only; link https://magnetoapp.io for paid plans.",
         inputSchema: {
             type: 'object',
             properties: {
@@ -370,6 +750,7 @@ export const MCP_TOOL_CATALOG = [
                 featured: { type: 'boolean' },
             },
         },
+        outputSchema: LIST_TEMPLATES_OUTPUT_SCHEMA,
         requiredScope: 'catalog',
         kinds: 'both',
         specMethod: 'get',
@@ -377,8 +758,11 @@ export const MCP_TOOL_CATALOG = [
     },
     {
         name: 'list_files',
-        description: 'List workspace files. Scope files.',
+        title: 'List files',
+        annotations: HINT_READ,
+        description: 'Use this when the user wants an account-scoped workspace file listing. Do not use for upload, delete, or skill catalog browse. Scope files.',
         inputSchema: { type: 'object', properties: {} },
+        outputSchema: LIST_FILES_OUTPUT_SCHEMA,
         requiredScope: 'files',
         kinds: 'both',
         specMethod: 'get',
@@ -386,8 +770,11 @@ export const MCP_TOOL_CATALOG = [
     },
     {
         name: 'account',
-        description: 'Read-only self-budget snapshot (workspace, subscription, CU/LLM usage, key scopes). Scope account.',
+        title: 'Account snapshot',
+        annotations: HINT_READ,
+        description: 'Use this when the user asks about their linked Magneto plan, usage, or key scopes. Do not use to purchase, subscribe, upgrade, or checkout — describe entitlements only and link https://magnetoapp.io for those. Scope account. Read-only self-budget snapshot (workspace, subscription, CU/LLM usage, key scopes).',
         inputSchema: { type: 'object', properties: {} },
+        outputSchema: ACCOUNT_OUTPUT_SCHEMA,
         requiredScope: 'account',
         kinds: 'both',
         specMethod: 'get',
@@ -395,7 +782,9 @@ export const MCP_TOOL_CATALOG = [
     },
     {
         name: 'chat',
-        description: 'OpenAI-compatible chat completion over computer-use (non-stream). Scope runs. Desktop only. Burns the platform CU spend cap or the single named BYO secret. Concurrent-run ceiling applies (429). Accepts messages or a single instruction. stream is coerced to false. Agent computers return 422.',
+        title: 'Chat completion',
+        annotations: HINT_OPEN_WORLD,
+        description: 'Use this when a keyed client wants an OpenAI-compatible chat completion over computer-use (non-stream). Do not use as a second ChatGPT plugin CU entry (use run) and do not purchase credits in-plugin. Scope runs. Desktop only. Burns the platform CU spend cap or the single named BYO secret. Concurrent-run ceiling applies (429). Accepts messages or a single instruction. stream is coerced to false. Agent computers return 422.',
         inputSchema: {
             type: 'object',
             required: ['computer_id'],
@@ -418,6 +807,7 @@ export const MCP_TOOL_CATALOG = [
         specPath: '/chat/completions',
     },
 ];
+export const MCP_TOOL_CATALOG = MCP_TOOL_DEFS.map(withX402);
 export function listToolsForScopes(scopes) {
     return MCP_TOOL_CATALOG.filter((tool) => scopes.includes(tool.requiredScope));
 }