@reclaimprotocol/agent 0.1.32 → 0.1.34

package/lib/mcp/tools/agent/session.js

@@ -5,10 +5,13 @@ export function sessionTools(attachRef, captures) {
     return [
         defineTool({
             name: 'get_session',
-            description: 'Report the current attach state, the live captureIds, and the '
-                + 'persisted browser config. Call it to check whether a browser is '
-                + 'still attached before reattaching, or to recover a captureId.',
+            description: 'Returns the current attach state, the live captureIds, the '
+                + 'persisted browser config, and the navigation script kept by '
+                + '`test_user_script`. Call it to check whether a browser is still '
+                + 'attached before reattaching, or to recover a captureId or the '
+                + 'kept script.',
             inputSchema: { type: 'object', properties: {} },
+            annotations: { readOnlyHint: true, openWorldHint: false },
         }, async () => ({
             config: attachRef.config.read()?.browser_agent,
             attached: Boolean(attachRef.current),
@@ -19,22 +22,27 @@ export function sessionTools(attachRef, captures) {
             orgId: attachRef.current?.orgId,
             captures: [...captures.sessions.keys()],
             activeTab: captures.activeTab,
+            keptUserScript: captures.keptScript?.script,
         })),
         defineTool({
             name: 'dispose_browser',
-            description: 'Stop captures, disconnect the current browser, and immediately '
-                + 'delete a Builder-hosted Popcorn session. Custom CDP sessions '
-                + 'are disconnected but never deleted by Reclaim.',
+            description: 'Stops captures, disconnects the current browser, and deletes a '
+                + 'Builder-hosted browser session at once. Clears the kept '
+                + 'navigation script. Reclaim disconnects a custom CDP browser but '
+                + 'never deletes it.',
             inputSchema: { type: 'object', properties: {} },
+            annotations: { destructiveHint: true, openWorldHint: true },
         }, async () => {
             await resetAll(attachRef, captures);
             return { disposed: true };
         }),
         defineTool({
             name: 'reset_session',
-            description: 'Stop all captures and clear capture state — drops every '
-                + 'session\'s drafts and their in-memory secrets.',
+            description: 'Stops all captures and clears capture state, dropping every '
+                + 'draft and its in-memory secrets. Also disconnects the browser '
+                + 'and clears the kept navigation script.',
             inputSchema: { type: 'object', properties: {} },
+            annotations: { destructiveHint: true, openWorldHint: true },
         }, async () => {
             await resetAll(attachRef, captures);
             return { reset: true };

package/lib/mcp/tools/agent/shared.js

@@ -32,12 +32,13 @@ function withLocalOprfMode(provider) {
 /** The local backend for one capture: drive its tab over CDP, read its
  *  captured requests, prove via the in-process attestor, replay by re-fetching
  *  FROM INSIDE the tab (real cookies/session — see proof/page-replay.ts). */
-function localBackend(entry) {
+function localBackend(entry, kept) {
     const { tabClient, session, drafts } = entry;
     const sendCdp = (method, params) => {
         return tabClient.send(method, params ?? {});
     };
     return {
+        kept,
         capture: session,
         drafts,
         sendCdp,
@@ -131,7 +132,7 @@ export function sharedAuthoringTools(captures) {
             throw new Error(`no capture ${captureId} — call start_capture first `
                 + '(it has been reset or never started).');
         }
-        return localBackend(entry);
+        return localBackend(entry, captures);
     };
     return authoringTools(resolveBackend).map((tool) => {
         if (tool.definition.name === 'run_proof') {

package/lib/mcp/tools/agent/start-integration.d.ts

@@ -0,0 +1,15 @@
+import { type RegisteredTool } from '../../server.ts';
+interface StartIntegrationArgs {
+    goal: string;
+    orgId?: string;
+    providerIds?: string[];
+}
+/**
+ * Returns the plan a coding agent follows to add Reclaim verification to the
+ * developer's app, from sign-in to a tested Verify button. The plan lives in
+ * `skill/start-integration.md`; this tool fills in the inputs.
+ */
+export declare function startIntegrationTool(): RegisteredTool;
+/** Fill the plan template. Exported for tests. */
+export declare function renderStartIntegration(args: StartIntegrationArgs): string;
+export {};

package/lib/mcp/tools/agent/start-integration.js

@@ -0,0 +1,61 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { defineTool } from "../../server.js";
+/**
+ * Returns the plan a coding agent follows to add Reclaim verification to the
+ * developer's app, from sign-in to a tested Verify button. The plan lives in
+ * `skill/start-integration.md`; this tool fills in the inputs.
+ */
+export function startIntegrationTool() {
+    return defineTool({
+        name: 'start_integration',
+        description: 'Returns a step-by-step plan for adding Reclaim verification to the '
+            + 'current codebase: sign in, build or choose a provider, then add the '
+            + 'session route, callback, and Verify button. Call it first when a '
+            + 'developer wants their users to prove something, and follow the '
+            + 'plan to the end. Changes nothing itself.',
+        inputSchema: {
+            type: 'object',
+            required: ['goal'],
+            properties: {
+                goal: {
+                    type: 'string',
+                    minLength: 1,
+                    maxLength: 300,
+                    description: 'What the developer\'s users prove, for example, "they have '
+                        + 'a GitHub account with 100 followers".',
+                },
+                orgId: {
+                    type: 'string',
+                    format: 'uuid',
+                    description: 'Organization to use. Omit to choose from the list.',
+                },
+                providerIds: {
+                    type: 'array',
+                    maxItems: 10,
+                    items: { type: 'string' },
+                    description: 'Existing provider IDs to use. Omit to build a new provider.',
+                },
+            },
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async (args) => renderStartIntegration(args));
+}
+/** Fill the plan template. Exported for tests. */
+export function renderStartIntegration(args) {
+    const providerIds = args.providerIds?.length
+        ? args.providerIds.map((id) => `\`${id}\``).join(', ')
+        : undefined;
+    const values = {
+        goal: args.goal,
+        orgId: args.orgId,
+        providerIds,
+    };
+    const template = readFileSync(fileURLToPath(new URL('../../../../skill/start-integration.md', import.meta.url)), 'utf8');
+    return template
+        // Keep a conditional block only when its input was given (or not given).
+        .replace(/<!-- (if|ifnot):(\w+) -->\n([\s\S]*?)<!-- endif -->\n/g, (_, kind, name, body) => {
+        return (kind === 'if') === Boolean(values[name]) ? body : '';
+    })
+        .replace(/\{\{(\w+)\}\}/g, (_, name) => values[name] ?? '');
+}

package/lib/mcp/tools/authenticate/authenticate.js

@@ -16,18 +16,16 @@ export function authenticateTool(client, name = 'reclaim_authenticate') {
                 + 'get_me_providers; those need the separate old-devtools login, '
                 + 'reclaim_authenticate. Check both with get_devtools_mode. '
             : '')
-            + 'Authorize the CLI / MCP to make authenticated API calls. Opens '
-            + 'the '
-            + 'browser to the builder sign-in page (standard OAuth 2.0 ' +
-            'authorization-code + PKCE with a localhost redirect) and waits for ' +
-            'the user to sign in and approve. On success the access token is ' +
-            'cached in ~/.reclaim/config.json and activated for this session.\n\n' +
-            'Call with no arguments. This bearer token authenticates ' +
-            'dashboard/org-management calls (for example, list_orgs, or ' +
-            'issuing an org secret). Programmatic verification calls use a ' +
-            'separate org secret ' +
-            '(rorg_…, set as RECLAIM_ORG_SECRET).',
+            + 'Signs the developer in to Builder. Opens the Builder sign-in page '
+            + 'in their browser (OAuth 2.0 authorization code with PKCE, '
+            + 'redirecting to a localhost port this server opens) and waits for '
+            + 'them to approve. Saves the access token in ~/.reclaim/config.json '
+            + 'with mode 0600 and uses it for this session; the token is never '
+            + 'returned. The token authorizes organization-management tools such '
+            + 'as `list_orgs`. Programmatic verification tools use a separate '
+            + 'organization key; see `issue_org_token`. Call with no arguments.',
         inputSchema: { type: 'object', properties: {} },
+        annotations: { openWorldHint: true, idempotentHint: true },
     }, async () => runOAuthLoopback(client));
 }
 const _customFetchForOauth = async (url, options) => {

package/lib/mcp/tools/authenticate/build.js

@@ -1,6 +1,7 @@
 import { authenticateTool } from "./authenticate.js";
 import { importTool } from "./import.js";
 import { issueTool } from "./issue.js";
+import { issueOrgTokenTool } from "./issue-org-token.js";
 import { resolveOwnerKeyTool } from "./resolve-owner-key.js";
 /**
  * Local-only key tools — no backend client needed. These manage the eth
@@ -23,6 +24,7 @@ export function buildLocalCredentialTools() {
 export function buildCredentialTools(client) {
     return [
         authenticateTool(client),
+        issueOrgTokenTool(client),
         ...buildLocalCredentialTools(),
     ];
 }

package/lib/mcp/tools/authenticate/builder-access.js

@@ -26,6 +26,7 @@ export function buildBuilderOrganizationTools(client) {
                     cursor: { type: 'string', maxLength: 500 },
                 },
             },
+            annotations: { readOnlyHint: true, openWorldHint: true },
         }, async ({ cursor }) => {
             const { data } = await client.call('ListOrgs', {
                 query: { ...(cursor ? { cursor } : {}) },

package/lib/mcp/tools/authenticate/eth-key.d.ts

@@ -19,6 +19,14 @@ export declare function normalizeEthHex(value: string): string;
  * ask for one (see `resolve_owner_key`).
  */
 export declare function resolveEthKey(projectDir?: string): ResolvedEthKey | undefined;
+/** Append `entry` to the project `.gitignore` if not already present. */
+export declare function ensureGitignored(projectDir: string, entry: string): void;
+/**
+ * Set `name=value` in a dotenv file, replacing an existing line or appending
+ * one. Writes with mode 0600 and adds the file to the project `.gitignore`.
+ * `envFile` is relative to `projectDir`.
+ */
+export declare function upsertEnvVar(projectDir: string, envFile: string, name: string, value: string): string;
 /**
  * Persist a raw eth private key to the project `.env` as
  * `RECLAIM_PRIVATE_KEY=0x…` (upsert; mode 0600; `.env` added to `.gitignore`).

package/lib/mcp/tools/authenticate/eth-key.js

@@ -16,8 +16,8 @@
  */
 import { deriveFromPrivateKey } from '@reclaimprotocol/client';
 import assert from 'node:assert';
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { isAbsolute, join } from 'node:path';
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { privateKey, privateKeyFile } from "../../../consts.js";
 import { findProjectRoot } from "../../../paths.js";
 const ENV_VAR = 'RECLAIM_PRIVATE_KEY';
@@ -80,7 +80,7 @@ export function resolveEthKey(projectDir = findProjectRoot(process.cwd())) {
     return undefined;
 }
 /** Append `entry` to the project `.gitignore` if not already present. */
-function ensureGitignored(projectDir, entry) {
+export function ensureGitignored(projectDir, entry) {
     const path = join(projectDir, '.gitignore');
     const current = existsSync(path) ? readFileSync(path, 'utf8') : '';
     if (current.split('\n').some((l) => l.trim() === entry)) {
@@ -90,26 +90,38 @@ function ensureGitignored(projectDir, entry) {
     writeFileSync(path, current + prefix + entry + '\n');
 }
 /**
- * Persist a raw eth private key to the project `.env` as
- * `RECLAIM_PRIVATE_KEY=0x…` (upsert; mode 0600; `.env` added to `.gitignore`).
- * Used by `issue_credentials` (generate) and `import_credentials` (supplied
- * hex). Returns the derived address and the `.env` path.
+ * Set `name=value` in a dotenv file, replacing an existing line or appending
+ * one. Writes with mode 0600 and adds the file to the project `.gitignore`.
+ * `envFile` is relative to `projectDir`.
  */
-export function writeEthKey(privateKeyHex, projectDir = findProjectRoot(process.cwd())) {
-    const hex = normalizeEthHex(privateKeyHex);
-    const envPath = join(projectDir, ENV_FILE);
-    const line = `${ENV_VAR}=${hex}`;
+export function upsertEnvVar(projectDir, envFile, name, value) {
+    const envPath = resolve(projectDir, envFile);
+    const line = `${name}=${value}`;
     const existing = existsSync(envPath) ? readFileSync(envPath, 'utf8') : '';
-    const re = new RegExp(`^\\s*${ENV_VAR}\\s*=.*$`, 'm');
+    const re = new RegExp(`^\\s*${name}\\s*=.*$`, 'm');
     let next;
     if (re.test(existing)) {
-        next = existing.replace(re, line);
+        // A function replacer keeps `$` sequences in the value literal.
+        next = existing.replace(re, () => line);
     }
     else {
         const prefix = existing && !existing.endsWith('\n') ? '\n' : '';
         next = existing + prefix + line + '\n';
     }
+    mkdirSync(dirname(envPath), { recursive: true });
     writeFileSync(envPath, next, { mode: 0o600 });
-    ensureGitignored(projectDir, ENV_FILE);
-    return { path: envPath, address: deriveFromPrivateKey(hex).address };
+    chmodSync(envPath, 0o600);
+    ensureGitignored(projectDir, relative(projectDir, envPath));
+    return envPath;
+}
+/**
+ * Persist a raw eth private key to the project `.env` as
+ * `RECLAIM_PRIVATE_KEY=0x…` (upsert; mode 0600; `.env` added to `.gitignore`).
+ * Used by `issue_credentials` (generate) and `import_credentials` (supplied
+ * hex). Returns the derived address and the `.env` path.
+ */
+export function writeEthKey(privateKeyHex, projectDir = findProjectRoot(process.cwd())) {
+    const hex = normalizeEthHex(privateKeyHex);
+    const path = upsertEnvVar(projectDir, ENV_FILE, ENV_VAR, hex);
+    return { path, address: deriveFromPrivateKey(hex).address };
 }

package/lib/mcp/tools/authenticate/import.js

@@ -5,53 +5,40 @@ import { writeEthKey } from "./eth-key.js";
 export function importTool() {
     return defineTool({
         name: 'import_credentials',
-        description: 'Import an eth proof-owner key the dev already holds and persist it ' +
-            'to the project `.env` as RECLAIM_PRIVATE_KEY=0x… (mode 0600; `.env` ' +
-            'added to .gitignore). Provide EITHER `privateKey` (raw 0x-hex, 64 ' +
-            'chars) OR `keyFile` (path to a file holding the raw 0x-hex key). ' +
-            'The address is derived locally; the private key is never ' +
-            'returned. This is a local signing key only (not registered ' +
-            'with any server, ' +
-            'unrelated to org auth or encryption).',
+        description: 'Imports an eth proof-owner key from a file the developer already '
+            + 'holds. Reads the raw 0x-hex key from `keyFile` and writes it to '
+            + 'the project `.env` as RECLAIM_PRIVATE_KEY (mode 0600; `.env` '
+            + 'added to .gitignore). Returns the derived address and the `.env` '
+            + 'path; never the key. The key is a local signing key only: it is '
+            + 'not registered with any server and is unrelated to org auth or '
+            + 'encryption. To create a new key instead, use `issue_credentials`.',
         inputSchema: {
             type: 'object',
+            required: ['keyFile'],
             properties: {
-                privateKey: {
-                    type: 'string',
-                    pattern: '^0x?[0-9a-fA-F]{64}$',
-                    description: 'Raw Ethereum private key, 0x-prefixed hex (64 hex chars).',
-                },
                 keyFile: {
                     type: 'string',
-                    description: 'Path to a file containing the raw 0x-hex private key ' +
-                        '(absolute or project-relative).',
+                    description: 'Path to a file containing the raw 0x-hex private key '
+                        + '(absolute or relative to the working directory).',
                 },
                 projectDir: {
                     type: 'string',
-                    description: 'Project directory whose `.env` the key is written to. ' +
-                        'Defaults to the closest ancestor of cwd containing .git or ' +
-                        'package.json.',
+                    description: 'Project directory whose `.env` the key is written to. '
+                        + 'Defaults to the closest ancestor of cwd containing .git or '
+                        + 'package.json.',
                 },
             },
         },
+        annotations: { readOnlyHint: false, destructiveHint: false },
     }, async (args) => {
-        if (!args.privateKey && !args.keyFile) {
-            throw new Error('Provide either `privateKey` (0x-hex) or `keyFile`.');
-        }
-        if (args.privateKey && args.keyFile) {
-            throw new Error('Provide only one of `privateKey` or `keyFile`.');
-        }
         const projectDir = findProjectRoot(args.projectDir || process.cwd());
-        const privateKeyHex = args.keyFile
-            ? readFileSync(args.keyFile, 'utf8')
-            : args.privateKey;
-        const { path, address } = writeEthKey(privateKeyHex, projectDir);
+        const { path, address } = writeEthKey(readFileSync(args.keyFile, 'utf8'), projectDir);
         return {
             address,
             path,
-            note: 'Eth proof-owner key written to .env as RECLAIM_PRIVATE_KEY ' +
-                '(mode 0600). resolve_owner_key resolves it from .env. Keep .env ' +
-                'secret — it has been added to .gitignore.',
+            note: 'Eth proof-owner key written to .env as RECLAIM_PRIVATE_KEY '
+                + '(mode 0600). resolve_owner_key resolves it from .env. Keep .env '
+                + 'secret: it has been added to .gitignore.',
         };
     });
 }

package/lib/mcp/tools/authenticate/issue-org-token.d.ts

@@ -0,0 +1,8 @@
+import type { ReclaimClient } from '@reclaimprotocol/client/api';
+import { type RegisteredTool } from '../../server.ts';
+/**
+ * Issues an organization API key and stores it on disk, so the key never
+ * passes through the agent's transcript. Replaces the generated
+ * `issue_org_token` operation, which returned the key in its response.
+ */
+export declare function issueOrgTokenTool(client: ReclaimClient): RegisteredTool;

package/lib/mcp/tools/authenticate/issue-org-token.js

@@ -0,0 +1,60 @@
+import assert from 'node:assert';
+import { isAbsolute, relative, resolve } from 'node:path';
+import { defineTool } from "../../server.js";
+import { upsertEnvVar } from "./eth-key.js";
+import { saveOrgKey } from "./org-key-store.js";
+/**
+ * Issues an organization API key and stores it on disk, so the key never
+ * passes through the agent's transcript. Replaces the generated
+ * `issue_org_token` operation, which returned the key in its response.
+ */
+export function issueOrgTokenTool(client) {
+    return defineTool({
+        name: 'issue_org_token',
+        description: 'Issues an organization API key (owner only) and writes it to a '
+            + 'server env file in the project, so the app can read it at runtime. '
+            + 'Also saves it on this machine for the org-key tools. Returns the '
+            + 'org, file, variable, and last four characters; never the key. '
+            + 'Replaces an existing variable of the same name in the file. '
+            + 'Adds the file to .gitignore. Use when the app needs a key, or '
+            + 'before `create_verification_session`.',
+        inputSchema: {
+            type: 'object',
+            required: ['orgId', 'projectDir'],
+            properties: {
+                orgId: { type: 'string', format: 'uuid' },
+                projectDir: {
+                    type: 'string',
+                    description: 'Absolute path of the app\'s project directory.',
+                },
+                envFile: {
+                    type: 'string',
+                    description: 'Env file to write, relative to `projectDir`. Default `.env`.',
+                },
+                envVar: {
+                    type: 'string',
+                    pattern: '^[A-Za-z_][A-Za-z0-9_]*$',
+                    description: 'Variable name to set. Default `RECLAIM_ORG_SECRET`.',
+                },
+            },
+        },
+        annotations: { openWorldHint: true, destructiveHint: false },
+    }, async (args) => {
+        assert(isAbsolute(args.projectDir), new Error('`projectDir` must be an absolute path.'));
+        const envFile = args.envFile || '.env';
+        const envVar = args.envVar || 'RECLAIM_ORG_SECRET';
+        const inside = relative(args.projectDir, resolve(args.projectDir, envFile));
+        assert(inside && !inside.startsWith('..') && !isAbsolute(inside), new Error('`envFile` must be inside `projectDir`.'));
+        const { data } = await client.call('IssueOrgToken', {
+            params: { orgId: args.orgId },
+        });
+        const path = upsertEnvVar(args.projectDir, envFile, envVar, data.orgSecret);
+        saveOrgKey(args.orgId, data.orgSecret);
+        return {
+            orgId: args.orgId,
+            envFile: path,
+            envVar,
+            last4: data.last4,
+        };
+    });
+}

package/lib/mcp/tools/authenticate/issue.js

@@ -5,15 +5,14 @@ import { writeEthKey } from "./eth-key.js";
 export function issueTool() {
     return defineTool({
         name: 'issue_credentials',
-        description: 'Generate a fresh secp256k1 eth proof-owner key-pair (the key ' +
-            'that signs local claim creation) and write the raw private key to ' +
-            'the project `.env` as RECLAIM_PRIVATE_KEY=0x… (mode 0600; `.env` ' +
-            'added to .gitignore). This is a LOCAL signing key only — it is NOT ' +
-            'registered with any server and is unrelated to org auth (the org ' +
-            'secret) or encryption (the eth decrypt key). ALWAYS confirm with ' +
-            'the dev before generating a new key. After writing, run_proof picks ' +
-            'it up automatically via resolve_owner_key. The private key is never ' +
-            'returned in the response.',
+        description: 'Generates a new secp256k1 eth proof-owner key and writes the '
+            + 'private key to the project `.env` as RECLAIM_PRIVATE_KEY (mode '
+            + '0600; `.env` added to .gitignore). Returns the address and the '
+            + '`.env` path; never the key. The key is a local signing key only: '
+            + 'it is not registered with any server and is unrelated to org auth '
+            + 'or encryption. Confirm with the developer before replacing an '
+            + 'existing key. `run_proof` then picks it up through '
+            + '`resolve_owner_key`.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -25,6 +24,7 @@ export function issueTool() {
                 },
             },
         },
+        annotations: { destructiveHint: false },
     }, async (args) => {
         const projectDir = findProjectRoot(args.projectDir || process.cwd());
         const keypair = generateKeypair();

package/lib/mcp/tools/authenticate/org-key-store.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Save an organization API key (`rorg_…`) in the local config (mode 0600), so
+ * the org-key tools can use it without the key passing through a transcript.
+ */
+export declare function saveOrgKey(orgId: string, secret: string): void;
+/**
+ * The saved key for `orgId`, or the most recently saved key when no org is
+ * given. Returns `undefined` when none is saved.
+ */
+export declare function savedOrgKey(orgId?: string): string | undefined;

package/lib/mcp/tools/authenticate/org-key-store.js

@@ -0,0 +1,23 @@
+import { ConfigStore } from "../../../config/store.js";
+/**
+ * Save an organization API key (`rorg_…`) in the local config (mode 0600), so
+ * the org-key tools can use it without the key passing through a transcript.
+ */
+export function saveOrgKey(orgId, secret) {
+    const saved = new ConfigStore().read()?.org_keys;
+    new ConfigStore().write({
+        org_keys: {
+            byOrg: { ...saved?.byOrg, [orgId]: secret },
+            recent: orgId,
+        },
+    });
+}
+/**
+ * The saved key for `orgId`, or the most recently saved key when no org is
+ * given. Returns `undefined` when none is saved.
+ */
+export function savedOrgKey(orgId) {
+    const saved = new ConfigStore().read()?.org_keys;
+    const id = orgId || saved?.recent;
+    return id ? saved?.byOrg[id] : undefined;
+}

package/lib/mcp/tools/authenticate/resolve-owner-key.js

@@ -16,18 +16,16 @@ import { ENV_FILE, resolveEthKey } from "./eth-key.js";
 export function resolveOwnerKeyTool() {
     return defineTool({
         name: 'resolve_owner_key',
-        description: 'Resolve which eth proof-owner key run_proof should sign with — ' +
-            'call this BEFORE run_proof. Checks, in order: RECLAIM_PRIVATE_KEY ' +
-            'in the MCP env, a RECLAIM_PRIVATE_KEY=0x… line in the project .env, ' +
-            'then a file at RECLAIM_PRIVATE_KEY_FILE holding the raw hex. ' +
-            'Returns { ready: true, address, source } when one is ' +
-            'available — pass `address` to run_proof as `ownerAddress`. ' +
-            'Returns { ready: false } ' +
-            'when none exists: then ask the dev to generate one ' +
-            '(issue_credentials) or import one they already hold ' +
-            '(import_credentials, accepts 0x-hex or a key-file path), and call ' +
-            'resolve_owner_key again. Never exposes the private key.',
+        description: 'Finds the eth proof-owner key `run_proof` signs with. Call it '
+            + 'before `run_proof`. Checks RECLAIM_PRIVATE_KEY in the MCP env, a '
+            + 'RECLAIM_PRIVATE_KEY line in the project .env, then the file at '
+            + 'RECLAIM_PRIVATE_KEY_FILE. Returns { ready: true, address, source '
+            + '}: pass `address` to `run_proof` as `ownerAddress`. Returns { '
+            + 'ready: false } when none exists: ask the developer to create one '
+            + 'with `issue_credentials` or import one with `import_credentials` '
+            + '(a key file), then call it again. Never returns the key.',
         inputSchema: { type: 'object', properties: {} },
+        annotations: { readOnlyHint: true, openWorldHint: false },
     }, async () => {
         const projectDir = findProjectRoot(process.cwd());
         const resolved = resolveEthKey(projectDir);
@@ -45,7 +43,7 @@ export function resolveOwnerKeyTool() {
                 `env, no RECLAIM_PRIVATE_KEY in ${join(projectDir, ENV_FILE)}, and ` +
                 'no RECLAIM_PRIVATE_KEY_FILE. Ask the dev to generate one via ' +
                 'issue_credentials, or import one they already hold via ' +
-                'import_credentials (0x-hex or a key-file path). Then call ' +
+                'import_credentials (a key file). Then call ' +
                 'resolve_owner_key again and pass its address to run_proof as ' +
                 'ownerAddress.',
         };

package/lib/mcp/tools/mode/mode.js

@@ -44,6 +44,7 @@ export function buildModeTools(config, currentOldMode) {
                 },
                 required: ['mode'],
             },
+            annotations: { openWorldHint: false, idempotentHint: true },
         }, async (parsed) => {
             config.write({ mode: parsed.mode });
             const restartRequired = parsed.mode !== current;
@@ -71,6 +72,7 @@ export function buildModeTools(config, currentOldMode) {
                 + 'the staleness with an error naming the tool to re-run. Which '
                 + 'login authorizes what: how_it_works({ topic: "auth" }).',
             inputSchema: { type: 'object', properties: {} },
+            annotations: { readOnlyHint: true, openWorldHint: false },
         }, async () => {
             const persisted = config.read()?.mode;
             const oldIdentity = config.read()?.old_devtools;