@withone/mcp 1.4.0 → 2.0.0

package/README.md

@@ -20,7 +20,7 @@
   <a href="https://npmjs.com/package/@withone/mcp"><img src="https://img.shields.io/npm/v/%40withone%2Fmcp" alt="npm version"></a>
 </p>
 
-Connect your AI agents to 700+ apps through a single [MCP](https://modelcontextprotocol.io) server. Search for actions, read documentation, and execute API calls across platforms, without having to manage OAuth tokens or API keys.
+Connect your AI agents to 700+ apps through a single [MCP](https://modelcontextprotocol.io) server. Find the actions a task needs with their documentation, and execute API calls across platforms, without having to manage OAuth tokens or API keys.
 
 ```bash
 npm install -g @withone/cli
@@ -34,7 +34,7 @@ That's it. The [One CLI](https://www.npmjs.com/package/@withone/cli) will prompt
 - **700+ platforms.** Gmail, Slack, Shopify, HubSpot, Stripe, Linear, QuickBooks, and [more](https://app.withone.ai/tools).
 - **Natural language execution.** "read my last gmail email", "send a message to #general on Slack"
 - **Code generation.** "build a form to send emails using Gmail", "create a dashboard that lists my Linear projects"
-- **No tool bloat.** Only 4 tools exposed regardless of how many platforms or actions you connect. Actions are search-based, so your agent's context window stays clean.
+- **No tool bloat.** Only 3 tools exposed regardless of how many platforms or actions you connect. One call finds every action a task needs, across platforms, with its documentation, so your agent's context window stays clean.
 - **Fine-grained access control.** Restrict which actions, connections, and permission levels (read, write, admin) your agent has access to.
 - **Secure by default.** All requests proxied through One, secrets automatically redacted, no platform API keys to manage.
 
@@ -56,15 +56,20 @@ That's it. The [One CLI](https://www.npmjs.com/package/@withone/cli) will prompt
 
 ## Tools
 
-The server exposes four MCP tools:
+The server exposes three MCP tools:
 
 | Tool | Description |
 |------|-------------|
 | `list_one_integrations` | List available platforms and active connections, each with the `access` it confers (full, methods, or specific actions) |
-| `search_one_platform_actions` | Search for actions on a specific platform |
-| `get_one_action_knowledge` | Get detailed documentation for an action |
+| `find_one_actions` | Find the action for every operation a task needs, across platforms, with its documentation, in one call; `load` fetches more of a document or an alternative's |
 | `execute_one_action` | Execute an API action on a connected platform |
 
+### Finding actions
+
+`find_one_actions` takes one `requests` entry per operation, each a kebab-case `platform` and a short `intent` naming the operation alone (`"send a message to a channel"`, not the message). An optional `task` describes the whole job in general terms, which helps choose between similar actions. For each intent, One's decision model picks the action to use; the answer documents it, sets apart a substitute when the model was unsure, and lists a few alternatives. Large documents come back as a digest; call `find_one_actions` again with `load: [{ action_id, section }]` for a section it left out, `full: true` for the whole document, or `toc: true` for its table of contents. `ONE_ACTION_IDS`, `ONE_PERMISSIONS` and `ONE_CONNECTION_KEYS` apply to every answer: an action they refuse is never offered, and when they refuse the model's pick, the next allowed candidate takes its place.
+
+Upgrading from 1.x: `search_one_platform_actions` and `get_one_action_knowledge` are removed. `find_one_actions` replaces both.
+
 ## Remote MCP Server
 
 Prefer not to run anything locally? One hosts a remote MCP server at **`https://mcp.withone.ai/mcp`**. Point any MCP client that supports remote (HTTP) servers at that URL and authenticate with One via OAuth. There's no `npm install` and no `ONE_SECRET` to manage. You approve access in One's consent screen, where you can scope exactly which connections, actions, and permission levels the agent gets. Those choices are surfaced back to the agent through each connection's `access` field, so it knows what it can run without searching.
@@ -82,7 +87,7 @@ Add it to your client's MCP configuration. The endpoint speaks the Streamable HT
 }
 ```
 
-Some clients omit `type` and take the URL alone; UI-based clients (custom connectors) just need the URL itself. On first connect, your client opens a browser to authenticate and authorize with One. After that, the same four tools are available.
+Some clients omit `type` and take the URL alone; UI-based clients (custom connectors) just need the URL itself. On first connect, your client opens a browser to authenticate and authorize with One. After that, the same three tools are available.
 
 One-click install:
 
@@ -139,7 +144,7 @@ ONE_KNOWLEDGE_AGENT=true
 | `ONE_PERMISSIONS` | `read` \| `write` \| `admin` | `admin` | Filter actions by HTTP method. `read` = GET only, `write` = GET/POST/PUT/PATCH, `admin` = all methods |
 | `ONE_CONNECTION_KEYS` | `*` or comma-separated keys | `*` | Restrict visible connections and platforms to specific connection keys |
 | `ONE_ACTION_IDS` | `*` or comma-separated IDs | `*` | Restrict visible and executable actions to specific action IDs |
-| `ONE_KNOWLEDGE_AGENT` | `true` \| `false` | `false` | Remove the `execute_one_action` tool entirely, forcing knowledge-only mode. `get_one_action_knowledge` responses additionally include an Integration Code Guide (passthrough URL, `x-one-*` headers, `ONE_SECRET` / `ONE_{PLATFORM}_CONNECTION_KEY` env vars, backend-only placement) for writing application code |
+| `ONE_KNOWLEDGE_AGENT` | `true` \| `false` | `false` | Remove the `execute_one_action` tool entirely, forcing knowledge-only mode. `find_one_actions` then returns each chosen action's whole document with how to call it from code, and an Integration Code Guide (passthrough URL, `x-one-*` headers, `ONE_SECRET` / `ONE_{PLATFORM}_CONNECTION_KEY` env vars, backend-only placement) for writing application code |
 
 All defaults preserve current behavior. If no access control env vars are set, the server starts with full access and all tools available.
 

package/build/client.js

@@ -184,47 +184,27 @@ export class OneClient {
         }
     }
     /**
-     * Searches for actions on a specific platform using a query
-     * @param platform - The platform name to search actions for
-     * @param query - The search query to find relevant actions
-     * @param agentType - The type of agent context (execute or knowledge)
-     * @returns Array of top 5 most relevant actions for the platform
-     * @throws {Error} If platform or query is not provided or API request fails
+     * Finds the action for each intent, across platforms, in one call: search
+     * plus One's decision model, which picks among the candidates.
+     * @param requests - One entry per operation, `{ platform, intent }`
+     * @param task - The whole task in one line, which helps break ties
+     * @param knowledgeAgent - Search the catalog for writing integration code
+     *   rather than the one for executing actions
+     * @returns One answer per intent, in the order asked
+     * @throws {Error} Naming core's reason when it refuses the request
      */
-    async searchAvailableActions(platform, query, agentType) {
-        if (!platform?.trim()) {
-            throw new Error("Platform name is required");
-        }
-        if (!query?.trim()) {
-            throw new Error("Search query is required");
-        }
+    async findActions(requests, task, knowledgeAgent) {
         try {
-            const headers = this.generateHeaders();
-            const url = `${this.baseUrl}/v1/available-actions/search/${platform}`;
-            // Default to knowledgeAgent if not specified
-            const isKnowledgeAgent = !agentType || agentType === "knowledge";
-            const params = {
-                query,
-                limit: '5'
-            };
-            if (isKnowledgeAgent) {
-                params.knowledgeAgent = 'true';
-            }
-            else {
-                params.executeAgent = 'true';
-            }
-            const response = await axios.get(url, {
-                headers,
-                params
-            });
+            const response = await axios.post(`${this.baseUrl}/v1/available-actions/find`, { requests, ...(task ? { task } : {}), knowledgeAgent }, { headers: this.generateHeaders() });
             return response.data || [];
         }
         catch (error) {
-            console.error("Error searching available actions:", describeError(error));
+            console.error("Error finding actions:", describeError(error));
             if (axios.isAxiosError(error)) {
-                throw new Error(`Failed to search available actions: ${error.response?.status} ${error.response?.statusText}`);
+                const reason = error.response?.data?.message;
+                throw new Error(`Failed to find actions: ${reason ?? `${error.response?.status} ${error.response?.statusText}`}`);
             }
-            throw new Error("Failed to search available actions");
+            throw new Error("Failed to find actions");
         }
     }
     /**
@@ -269,31 +249,6 @@ export class OneClient {
             throw new Error("Failed to fetch action details");
         }
     }
-    /**
-     * Gets knowledge for a specific action by ID
-     * @param actionId - The action ID to get knowledge for
-     * @returns The knowledge string for the action
-     * @throws {Error} If action ID is not provided or API request fails
-     */
-    async getActionKnowledge(actionId) {
-        try {
-            const action = await this.getActionDetails(actionId);
-            if (!action.knowledge || !action.method) {
-                return {
-                    knowledge: "No knowledge was found",
-                    method: "No method was found"
-                };
-            }
-            return {
-                knowledge: action.knowledge,
-                method: action.method
-            };
-        }
-        catch (error) {
-            console.error("Error fetching action knowledge:", describeError(error));
-            throw error;
-        }
-    }
     /**
      * Resolves an allowlist of action ids to their metadata (title, method, and
      * owning platform), so `list_one_integrations` can report each connection's

package/build/find.js

@@ -0,0 +1,393 @@
+/**
+ * The `find_one_actions` tool: find the action for every operation a task
+ * needs, across platforms, with its documentation, in one call.
+ *
+ * Core picks the actions (`POST /v1/available-actions/find`, search plus One's
+ * decision model). This module applies what only this server knows - its
+ * action allowlist, permission level and connection scope - and renders the
+ * answer in the same layout as the remote MCP's tool, documenting each action
+ * from its raw knowledge with this package's own digest engine, so a digest's
+ * notes name `find_one_actions` rather than a route the agent cannot call.
+ *
+ * @fileoverview find_one_actions logic, free of HTTP so it can be tested
+ * @author One
+ */
+import { buildKnowledgeResponse, isActionAllowed, isMethodAllowed, platformEnvSegment } from './helpers.js';
+/** How many intents one find answers. Core enforces the same cap. */
+export const FIND_MAX_INTENTS = 10;
+/** How many documents one load returns. */
+export const FIND_MAX_LOADS = 10;
+/** Characters of documentation one answer carries in all, as core bounds its own (about 100k tokens). */
+export const FIND_DOCUMENTS_BUDGET = 400_000;
+/** What stands in for an action's documentation when it has none. */
+export const NO_KNOWLEDGE = '(No additional knowledge available for this action.)';
+/** How an agent that can execute runs what the documentation describes, with this server's real argument names. */
+export const FIND_EXECUTE_HINT = 'Run it with `execute_one_action`: `platform`, `actionId`, `connectionKey` (from `list_one_integrations`), and the `data`, `pathVariables` and `queryParams` this document calls for.';
+/** One wording for an action that does not exist and one this server may not use, so neither can be told apart. */
+export const REFUSED_LOAD = 'no such action, or this server may not use it';
+/** What a call that is neither a find nor a load is told. */
+export const FIND_ARGS_ERROR = 'Send either `requests` (to find actions, with an optional `task`) or `load` (for more documentation, without `task`), not both and not neither.';
+/** A call the agent has to fix, reported to it rather than failing the server. */
+export class FindArgsError extends Error {
+}
+/**
+ * Answers a `find_one_actions` call: finds actions for `requests`, or serves
+ * more documentation for `load`.
+ * @throws {FindArgsError} When the call is neither, both, or `task` comes with `load`
+ */
+export async function findOneActions(args, deps, settings) {
+    if (args.requests && !args.load) {
+        return find(args.requests, args.task, deps, settings);
+    }
+    if (args.load && !args.requests && args.task === undefined) {
+        return load(args.load, deps, settings);
+    }
+    throw new FindArgsError(FIND_ARGS_ERROR);
+}
+/** An action as the agent refers to it: title, method, path and `actionId`. */
+export function actionHeading(title, method, path, actionId) {
+    return `${title} · \`${method.toUpperCase()} ${path}\` · actionId: \`${actionId}\``;
+}
+function allows(settings, action) {
+    return isActionAllowed(action.systemId, settings.actionIds) && isMethodAllowed(action.method, settings.permissions);
+}
+function reaches(settings, platform) {
+    return settings.platforms === null || (platform !== undefined && settings.platforms.includes(platform));
+}
+/**
+ * Drops every action this server's settings refuse. When that removes the
+ * pick itself, the runner-up, else the first allowed alternative, takes its
+ * place, so the intent still has something to use.
+ */
+function narrow(answer, settings) {
+    const allowed = (action) => allows(settings, action);
+    const selected = answer.selected.filter(allowed);
+    const alternatives = answer.alternatives.filter(allowed);
+    let runnerUp = answer.runnerUp && allowed(answer.runnerUp) ? answer.runnerUp : undefined;
+    let replaced = false;
+    // The model's pick is the first selected action; any after it are needed
+    // beside it. A refused pick is replaced even when a companion survives, so a
+    // companion is never presented as the confident pick.
+    if (answer.selected.length > 0 && !allowed(answer.selected[0])) {
+        const next = runnerUp ?? alternatives.shift();
+        if (next) {
+            selected.unshift(next);
+            runnerUp = next === runnerUp ? undefined : runnerUp;
+        }
+        replaced = selected.length > 0;
+    }
+    const alsoSelected = (answer.alsoSelected ?? []).filter(allowed);
+    const found = answer.selected.length + answer.alternatives.length + (answer.alsoSelected?.length ?? 0) + (answer.runnerUp ? 1 : 0);
+    const kept = selected.length + alternatives.length + alsoSelected.length + (runnerUp ? 1 : 0);
+    return {
+        answer: { ...answer, selected, alsoSelected, runnerUp, alternatives },
+        replaced,
+        refusedAll: found > 0 && kept === 0,
+    };
+}
+/** Why the answer is what it is, as its opening line. */
+function status(answer, narrowed) {
+    if (narrowed.refusedAll) {
+        return "Actions were found for this intent, but this server's settings (ONE_ACTION_IDS, ONE_PERMISSIONS) allow none of them, so rephrasing will not help. Tell the user which operation is blocked.";
+    }
+    if (narrowed.replaced) {
+        return 'The chosen action is not allowed on this server, so this is the next allowed candidate: check it fits before using it.';
+    }
+    if (answer.selector === 'none_fit' || answer.selected.length === 0) {
+        return answer.alternatives.length === 0
+            ? 'No action fits this intent, and nothing close was found. Rephrase it, or check the platform name.'
+            : 'No action fits this intent. Rephrase it more specifically, or load one of the alternatives.';
+    }
+    if (answer.selector === 'search_order') {
+        return 'The decision model was unavailable, so this is the top search result: check it fits before using it.';
+    }
+    return answer.confidence === undefined
+        ? 'Chosen by the decision model.'
+        : `Chosen with confidence ${answer.confidence.toFixed(2)}.`;
+}
+/** Actions listed one per line under `lead`, with how to load any of them, or nothing when there are none. */
+function listing(lead, actions) {
+    if (actions.length === 0)
+        return [];
+    const listed = actions.map((a) => `- ${actionHeading(a.title, a.method, a.path, a.systemId)}`).join('\n');
+    return [`${lead} (load with \`find_one_actions\` and \`load: [{ action_id }]\`):\n${listed}`];
+}
+/**
+ * One action with its documentation: a digest whose notes name
+ * `find_one_actions` for an agent that executes, or the whole document with
+ * how to call it from code in knowledge mode, whose shared rules the answer
+ * adds once.
+ */
+function renderAction(doc, settings, request = {}) {
+    if (settings.knowledgeAgent) {
+        return codeGuideAction(doc, settings.baseUrl);
+    }
+    const heading = actionHeading(doc.title, doc.method, doc.path, doc.actionId);
+    if (doc.knowledge === undefined) {
+        return `### ${heading}\n\n${NO_KNOWLEDGE}`;
+    }
+    const body = buildKnowledgeResponse(doc.knowledge, doc.method, doc.platform, doc.actionId, {
+        section: request.section,
+        full: request.full,
+        toc: request.toc,
+        followUp: 'findTool',
+    }).text;
+    return `### ${heading}\n\n${body}`;
+}
+/** The sections joined, ending on what applies to every documented action - once, however many - or on nothing when nothing was documented. */
+function finish(sections, documented, settings) {
+    const body = sections.join('\n\n---\n\n');
+    if (!documented)
+        return body;
+    return `${body}\n\n---\n\n${settings.knowledgeAgent ? codeGuideRules() : FIND_EXECUTE_HINT}`;
+}
+async function find(requests, task, deps, settings) {
+    if (requests.length === 0 || requests.length > FIND_MAX_INTENTS) {
+        throw new FindArgsError(`Send between 1 and ${FIND_MAX_INTENTS} requests.`);
+    }
+    const reachable = requests.filter((r) => reaches(settings, r.platform));
+    const answers = reachable.length > 0 ? await deps.findActions(reachable, task, settings.knowledgeAgent) : [];
+    let next = 0;
+    const plans = requests.map((intent) => {
+        if (!reaches(settings, intent.platform)) {
+            return { intent, unreachable: true, replaced: false, refusedAll: false, picks: [], deferred: [], runnerUpDocumented: false };
+        }
+        const { answer, replaced, refusedAll } = narrow(answers[next++], settings);
+        const companions = settings.knowledgeAgent ? answer.selected.slice(0, 1) : answer.selected;
+        return {
+            intent,
+            unreachable: false,
+            answer,
+            replaced,
+            refusedAll,
+            picks: companions,
+            deferred: [...answer.selected.slice(companions.length), ...(answer.alsoSelected ?? [])],
+            runnerUp: answer.runnerUp,
+            runnerUpDocumented: !settings.knowledgeAgent && answer.runnerUp !== undefined,
+        };
+    });
+    const documents = await fetchDocuments(plans, deps);
+    const rendered = boundDocuments(plans, documents, settings);
+    const sections = plans.map((plan, index) => {
+        if (plan.unreachable || !plan.answer) {
+            return `## ${plan.intent.platform}: ${plan.intent.intent}\n\nPlatform "${plan.intent.platform}" has no allowed connections on this server.`;
+        }
+        const { answer } = plan;
+        const parts = [`## ${plan.intent.platform}: ${plan.intent.intent}\n\n${status(answer, plan)}`];
+        const shown = rendered[index];
+        parts.push(...shown.picks);
+        const chosen = shown.picks.length === 0
+            ? 'Chosen for this intent, documentation left out to keep the answer small'
+            : 'Also chosen for this intent, documentation left out to keep the answer small';
+        parts.push(...listing(chosen, shown.deferred));
+        if (plan.runnerUp) {
+            const lead = 'If the chosen action does not fit, use this one instead: one or the other, never both';
+            parts.push(...(shown.runnerUp ? [`${lead}.\n\n${shown.runnerUp}`] : listing(lead, [plan.runnerUp])));
+        }
+        parts.push(...listing('Alternatives, not documented', answer.alternatives));
+        return parts.join('\n\n');
+    });
+    return finish(sections, rendered.some((r) => r.picks.length > 0 || r.runnerUp !== undefined), settings);
+}
+/** Each documented action's raw knowledge, fetched once per action. */
+async function fetchDocuments(plans, deps) {
+    const ids = new Set();
+    for (const plan of plans) {
+        plan.picks.forEach((a) => ids.add(a.systemId));
+        if (plan.runnerUp && plan.runnerUpDocumented)
+            ids.add(plan.runnerUp.systemId);
+    }
+    const entries = await Promise.all([...ids].map(async (id) => {
+        try {
+            return [id, (await deps.getActionDetails(id)).knowledge];
+        }
+        catch {
+            return [id, undefined];
+        }
+    }));
+    return new Map(entries);
+}
+/**
+ * Renders the documented actions within {@link FIND_DOCUMENTS_BUDGET}, picks
+ * before any runner-up. The first document is always served. Past the budget,
+ * an intent stops at its first pick that does not fit, listing it and the rest
+ * as chosen to load, rather than documenting a smaller one in its place; a
+ * runner-up that does not fit is listed.
+ */
+function boundDocuments(plans, documents, settings) {
+    let used = 0;
+    let first = true;
+    const admit = (text) => {
+        if (first || used + text.length <= FIND_DOCUMENTS_BUDGET) {
+            used += text.length;
+            first = false;
+            return true;
+        }
+        return false;
+    };
+    const toDocumented = (action, platform) => ({
+        title: action.title,
+        method: action.method,
+        path: action.path,
+        actionId: action.systemId,
+        platform,
+        tags: action.tags ?? [],
+        knowledge: documents.get(action.systemId),
+    });
+    const rendered = plans.map((plan) => {
+        const picks = [];
+        const deferred = [];
+        for (const [index, pick] of plan.picks.entries()) {
+            const text = renderAction(toDocumented(pick, plan.intent.platform), settings);
+            if (!admit(text)) {
+                deferred.push(...plan.picks.slice(index));
+                break;
+            }
+            picks.push(text);
+        }
+        return { picks, deferred: [...deferred, ...plan.deferred] };
+    });
+    plans.forEach((plan, index) => {
+        if (plan.runnerUp && plan.runnerUpDocumented) {
+            const text = renderAction(toDocumented(plan.runnerUp, plan.intent.platform), settings);
+            if (used + text.length <= FIND_DOCUMENTS_BUDGET) {
+                used += text.length;
+                rendered[index].runnerUp = text;
+            }
+        }
+    });
+    return rendered;
+}
+async function load(loads, deps, settings) {
+    if (loads.length === 0 || loads.length > FIND_MAX_LOADS) {
+        throw new FindArgsError(`Send between 1 and ${FIND_MAX_LOADS} loads.`);
+    }
+    const entries = await Promise.all(loads.map(async (entry) => {
+        const refused = { text: `\`${entry.action_id}\`: ${REFUSED_LOAD}`, documented: false };
+        if (!isActionAllowed(entry.action_id, settings.actionIds))
+            return refused;
+        let details;
+        try {
+            details = await deps.getActionDetails(entry.action_id);
+        }
+        catch {
+            return refused;
+        }
+        if (!isMethodAllowed(details.method, settings.permissions) || !reaches(settings, details.connectionPlatform)) {
+            return refused;
+        }
+        const text = renderAction({
+            title: details.title,
+            method: details.method,
+            path: details.path,
+            actionId: entry.action_id,
+            platform: details.connectionPlatform ?? '',
+            tags: details.tags ?? [],
+            knowledge: details.knowledge,
+        }, settings, entry);
+        return { text, documented: true };
+    }));
+    let used = 0;
+    let served = false;
+    const bounded = entries.map((entry, index) => {
+        if (!entry.documented)
+            return entry;
+        if (served && used + entry.text.length > FIND_DOCUMENTS_BUDGET) {
+            return { text: `\`${loads[index].action_id}\`: too large to serve beside the others; load it on its own.`, documented: false };
+        }
+        used += entry.text.length;
+        served = true;
+        return entry;
+    });
+    return finish(bounded.map((e) => e.text), bounded.some((e) => e.documented), settings);
+}
+const CUSTOM_ACTION_NOTE = '\n\nThis is a custom action: ALSO include "connectionKey" (the same value as the x-one-connection-key header) as a field in the JSON body for non-GET requests.';
+/**
+ * One action for knowledge mode: its whole document under its heading, then
+ * how to call it through the One Passthrough API. {@link codeGuideRules}
+ * holds what every action shares, so an answer about several states it once.
+ * Worded as the remote MCP's `code_guide_action`.
+ */
+export function codeGuideAction(doc, baseUrl) {
+    const apiBase = baseUrl.replace(/\/$/, '');
+    const method = doc.method.toUpperCase();
+    const path = doc.path.startsWith('/') ? doc.path : `/${doc.path}`;
+    const connEnv = `ONE_${platformEnvSegment(doc.platform)}_CONNECTION_KEY`;
+    const customNote = doc.tags.includes('custom') ? CUSTOM_ACTION_NOTE : '';
+    return `### ${actionHeading(doc.title, doc.method, doc.path, doc.actionId)}
+**Platform:** ${doc.platform}
+
+${doc.knowledge ?? NO_KNOWLEDGE}
+
+## Calling this action from code
+URL:    ${apiBase}/v1/passthrough${path}
+Method: ${method}
+Headers:
+- x-one-secret: the value of the ONE_SECRET env var
+- x-one-connection-key: the value of the ${connEnv} env var
+- x-one-action-id: ${doc.actionId}
+- Content-Type: application/json${customNote}
+
+Environment variables: ONE_SECRET (their One API key) and ${connEnv} (the key of their ${doc.platform} connection), both from the One dashboard.
+
+\`\`\`typescript
+const response = await fetch("${apiBase}/v1/passthrough${path}", {
+method: "${method}",
+headers: {
+"x-one-secret": process.env.ONE_SECRET,
+"x-one-connection-key": process.env.${connEnv},
+"x-one-action-id": "${doc.actionId}",
+"Content-Type": "application/json",
+},
+// body: JSON.stringify(...) - only for non-GET requests
+});
+\`\`\``;
+}
+/**
+ * The Integration Code Guide's rules, which hold for every action: where the
+ * code lives, that it goes through the One Passthrough API, where each
+ * parameter goes, the deployment the user must do, and how to write it.
+ * Worded as the remote MCP's `code_guide_rules`.
+ */
+export function codeGuideRules() {
+    return `================================================================
+INTEGRATION CODE GUIDE - using these actions in an application
+================================================================
+You are in knowledge mode: actions cannot be executed here. Use this
+guide, with each action's "Calling this action from code", to write
+integration code in the user's project.
+
+## 1. Where this code must live
+Server-side only - an API route, edge function, or backend handler
+(e.g. Supabase Edge Function, Next.js route handler, Express route).
+NEVER call this API from browser/client code and NEVER hardcode secret
+values in source - read them from environment variables.
+
+## 2. The request
+All calls go through the One Passthrough API. Do NOT call the third-party
+API URL from the documentation directly. The URL is the One base plus the
+action path ONLY:
+✅ {One base}/v1/passthrough{action path}   (the path starts with /)
+❌ {One base}/v1/passthrough/https://some-vendor-api.com{action path}
+
+## 3. Parameter placement
+Per each action's documentation:
+- Path variables (placeholders like {{userId}} in the path) → substitute
+  real values into the URL path; never send them in the body.
+- Query parameters → the URL query string, not the body.
+- Body fields → the JSON request body (POST/PUT/PATCH only).
+
+## 4. Environment variables & deployment
+The code will not work until the user sets each action's environment
+variables in their hosting platform's secrets manager (Supabase secrets,
+Vercel/Netlify environment settings, or the project's env settings -
+never committed to code). When you deliver the code, explicitly tell the
+user to set them.
+
+## 5. Code generation rules
+- Use TypeScript unless the user asked for another language.
+- Include the complete input/output structure from the documentation
+  (required/optional fields, types) in the implementation.
+- Handle errors: on a non-2xx response, read the response body and
+  surface a useful message.`;
+}

package/build/find.test.js

@@ -0,0 +1,134 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { FIND_ARGS_ERROR, FIND_EXECUTE_HINT, FindArgsError, REFUSED_LOAD, findOneActions, } from './find.js';
+// Pure: core and the knowledge endpoint are stubbed, so no network is touched.
+const LARGE = [
+    '# Send Email',
+    '## Endpoint\nPOST /v1/gmail/send-email',
+    '## Request Body\n### Required Request Body Fields\n- to: string',
+    `## Response Fields\n${Array.from({ length: 400 }, (_, i) => `- field ${i}: a described response field`).join('\n')}`,
+].join('\n\n');
+const action = (id, method = 'POST', tags = []) => ({
+    systemId: id,
+    title: `Action ${id}`,
+    key: `key-${id}`,
+    method,
+    path: `/v1/${id}`,
+    tags,
+    knowledge: 'a digest core rendered for its own route',
+});
+const answer = (overrides = {}) => ({
+    platform: 'gmail',
+    intent: 'send an email',
+    selected: [action('a')],
+    alternatives: [action('b'), action('c', 'GET')],
+    selector: 'model',
+    confidence: 0.92,
+    ...overrides,
+});
+const settings = (overrides = {}) => ({
+    knowledgeAgent: false,
+    permissions: 'admin',
+    actionIds: ['*'],
+    platforms: null,
+    baseUrl: 'https://api.withone.ai',
+    ...overrides,
+});
+/** Core answering `answers` in turn, and raw knowledge per action. */
+function deps(answers, knowledge = {}) {
+    const asked = [];
+    return {
+        asked,
+        async findActions(requests) {
+            asked.push(requests);
+            return answers.slice(0, requests.length);
+        },
+        async getActionDetails(id) {
+            if (id === 'missing')
+                throw new Error('not found');
+            return {
+                _id: id,
+                title: `Action ${id}`,
+                method: id === 'c' ? 'GET' : 'POST',
+                path: `/v1/${id}`,
+                tags: id === 'custom' ? ['custom'] : [],
+                knowledge: knowledge[id] ?? `# Action ${id}\n\nSmall doc for ${id}.`,
+                connectionPlatform: 'gmail',
+            };
+        },
+    };
+}
+const intent = [{ platform: 'gmail', intent: 'send an email' }];
+describe('find_one_actions', () => {
+    it('takes requests or load, never both, never neither, and no task with a load', async () => {
+        for (const args of [{}, { requests: intent, load: [{ action_id: 'a' }] }, { load: [{ action_id: 'a' }], task: 't' }]) {
+            await assert.rejects(findOneActions(args, deps([answer()]), settings()), (e) => e instanceof FindArgsError && e.message === FIND_ARGS_ERROR);
+        }
+    });
+    it('names each action by actionId, documents the pick from its raw knowledge, and ends on the execute arguments once', async () => {
+        const text = await findOneActions({ requests: intent, ai_model: 'claude-sonnet-5' }, deps([answer()], { a: LARGE }), settings());
+        assert.ok(text.startsWith('## gmail: send an email\n\nChosen with confidence 0.92.'));
+        assert.ok(text.includes('### Action a · `POST /v1/a` · actionId: `a`'));
+        assert.ok(!text.includes('a digest core rendered for its own route'), "core's route digest is re-rendered, not relayed");
+        assert.ok(text.includes('find_one_actions with load: [{ action_id: "a"'), 'the digest sends the agent back to this tool');
+        assert.ok(!text.includes('get_one_action_knowledge') && !text.includes('/v1/available-actions/find/load'));
+        assert.ok(text.includes('Alternatives, not documented (load with `find_one_actions` and `load: [{ action_id }]`):\n- Action b'));
+        assert.equal(text.split(FIND_EXECUTE_HINT).length, 2, 'the execute hint closes the answer once');
+    });
+    it('sets the runner-up apart as a substitute', async () => {
+        const text = await findOneActions({ requests: intent }, deps([answer({ runnerUp: action('b'), alternatives: [] })]), settings());
+        assert.ok(text.includes('If the chosen action does not fit, use this one instead: one or the other, never both.\n\n### Action b'));
+    });
+    it('never offers an action this server refuses, promoting the next allowed one in place of a refused pick', async () => {
+        const text = await findOneActions({ requests: intent }, deps([answer({ selected: [action('a')], alternatives: [action('b'), action('c', 'GET')] })]), settings({ permissions: 'read' }));
+        assert.ok(text.includes('The chosen action is not allowed on this server, so this is the next allowed candidate'));
+        assert.ok(text.includes('### Action c · `GET /v1/c`'));
+        assert.ok(!text.includes('actionId: `a`') && !text.includes('actionId: `b`'), 'refused actions are not even listed');
+    });
+    it('replaces a refused pick even when a companion survives, so the companion is never shown as the pick', async () => {
+        const text = await findOneActions({ requests: intent }, deps([answer({ selected: [action('a'), action('c', 'GET')], runnerUp: action('d', 'GET'), alternatives: [] })]), settings({ permissions: 'read' }));
+        assert.ok(text.includes('The chosen action is not allowed on this server, so this is the next allowed candidate'));
+        assert.ok(text.indexOf('actionId: `d`') < text.indexOf('actionId: `c`'), 'the runner-up stands in first, the companion after it');
+        assert.ok(!text.includes('use this one instead'), 'the promoted runner-up is not also offered as a substitute');
+    });
+    it('serves the first document a load actually returns, however large, even after a refused entry', async () => {
+        const huge = `# Huge\n\n${'x'.repeat(450_000)}`;
+        const text = await findOneActions({ load: [{ action_id: 'missing' }, { action_id: 'a', full: true }] }, deps([], { a: huge }), settings());
+        assert.ok(text.includes(huge), 'the only served document is not refused as too large');
+    });
+    it('says the settings are why when they refuse every action found, rather than asking for a rephrase', async () => {
+        const text = await findOneActions({ requests: intent }, deps([answer({ selected: [action('a')], alternatives: [action('b')] })]), settings({ permissions: 'read' }));
+        assert.ok(text.includes("this server's settings (ONE_ACTION_IDS, ONE_PERMISSIONS) allow none of them"));
+        assert.ok(!text.includes('Rephrase it'));
+    });
+    it('answers a platform no allowed connection reaches without asking core about it', async () => {
+        const core = deps([answer({ platform: 'slack', intent: 'post a message' })]);
+        const text = await findOneActions({ requests: [intent[0], { platform: 'slack', intent: 'post a message' }] }, core, settings({ platforms: ['slack'] }));
+        assert.deepEqual(core.asked, [[{ platform: 'slack', intent: 'post a message' }]]);
+        assert.ok(text.includes('## gmail: send an email\n\nPlatform "gmail" has no allowed connections on this server.'));
+        assert.ok(text.includes('## slack: post a message'));
+    });
+    it('in knowledge mode documents the pick whole with how to call it from code, and states the rules once', async () => {
+        const text = await findOneActions({ requests: intent }, deps([answer({ selected: [action('custom', 'POST', ['custom']), action('b')] })], { custom: LARGE }), settings({ knowledgeAgent: true }));
+        assert.ok(text.includes(LARGE), 'the whole document, not a digest');
+        assert.ok(text.includes('### Action custom · `POST /v1/custom` · actionId: `custom`\n**Platform:** gmail'));
+        assert.ok(text.includes('x-one-action-id: custom'));
+        assert.ok(text.includes('This is a custom action'));
+        assert.ok(text.includes('Also chosen for this intent, documentation left out to keep the answer small'), 'whole documents are large, so only the pick is documented');
+        assert.equal(text.split('INTEGRATION CODE GUIDE').length, 2);
+        assert.ok(!text.includes('execute_one_action'));
+    });
+    it('says why when nothing fits, and adds no closing hint when nothing was documented', async () => {
+        const text = await findOneActions({ requests: intent }, deps([answer({ selected: [], alternatives: [], selector: 'none_fit' })]), settings());
+        assert.ok(text.includes('No action fits this intent, and nothing close was found.'));
+        assert.ok(!text.includes(FIND_EXECUTE_HINT));
+    });
+    it('loads what each entry asked for, refusing one this server may not use in the words for a missing one', async () => {
+        const text = await findOneActions({ load: [{ action_id: 'a', section: 'Response Fields' }, { action_id: 'missing' }, { action_id: 'b' }] }, deps([], { a: LARGE }), settings({ actionIds: ['a', 'missing'] }));
+        assert.ok(text.includes('### Action a'));
+        assert.ok(text.includes('field 399'), 'the named section is served');
+        assert.ok(!text.includes('POST /v1/gmail/send-email'), 'and only that section');
+        assert.ok(text.includes(`\`missing\`: ${REFUSED_LOAD}`));
+        assert.ok(text.includes(`\`b\`: ${REFUSED_LOAD}`), 'an action outside ONE_ACTION_IDS reads as missing');
+    });
+});

package/build/helpers.js

@@ -75,7 +75,10 @@ export async function fetchPaginatedData(baseUrl, headers, additionalParams) {
  * @param method - The action's HTTP method (echoed into the envelope)
  * @param platform - The kebab-case platform identifier (for the load-more hint)
  * @param actionId - The action ID (for the load-more hint)
- * @param options - `section`/`toc`/`full` select what to return
+ * @param options - `section`/`toc`/`full` select what to return; `followUp`
+ *   names the tool a digest's notes send the agent to, `find_one_actions` unless
+ *   set (the engine's `get_one_action_knowledge` wording is kept for its other
+ *   surfaces)
  */
 export function buildKnowledgeResponse(knowledge, method, platform, actionId, options = {}) {
     const doc = parseSections(knowledge);
@@ -139,12 +142,13 @@ export function buildKnowledgeResponse(knowledge, method, platform, actionId, op
     if (wantFull) {
         return { text: knowledge, structured: { title: doc.title, method, truncated: false } };
     }
-    const digest = buildDigest(doc);
+    const followUp = options.followUp ?? 'findTool';
+    const digest = buildDigest(doc, { load: { followUp, platform, actionId } });
     if (!digest.truncated) {
         return { text: knowledge, structured: { title: doc.title, method, truncated: false } };
     }
     const toc = omittedSections(digest);
-    const text = [renderDigestBanner(digest), digest.markdown, renderDigestNotice(digest, platform, actionId)]
+    const text = [renderDigestBanner(digest), digest.markdown, renderDigestNotice(digest, platform, actionId, followUp)]
         .filter(Boolean)
         .join('\n\n');
     return {
@@ -173,93 +177,6 @@ export function platformEnvSegment(platform) {
         .filter(Boolean)
         .join("_");
 }
-const CUSTOM_ACTION_NOTE = `
-- This is a custom action: ALSO include "connectionKey" (the same value as the
-  x-one-connection-key header) as a field in the JSON body for non-GET requests.`;
-/**
- * Builds the knowledge-mode response: the action's knowledge document followed
- * by the Integration Code Guide for writing application code against the One
- * Passthrough API (env vars, backend-only placement, headers, deployment).
- * Used only when ONE_KNOWLEDGE_AGENT is enabled; normal mode keeps
- * buildActionKnowledgeWithGuidance.
- * @param details - Full action details from the knowledge endpoint
- * @param platform - The kebab-case platform identifier from the tool args
- * @param baseUrl - The One API base URL (e.g. https://api.withone.ai)
- * @returns The knowledge text with the appended Integration Code Guide
- */
-export function buildKnowledgeModeGuidance(details, platform, baseUrl) {
-    const apiBase = baseUrl.replace(/\/$/, "");
-    const knowledge = details.knowledge || "No knowledge was found";
-    const method = (details.method || "").toUpperCase();
-    const path = details.path.startsWith("/") ? details.path : `/${details.path}`;
-    const connEnv = `ONE_${platformEnvSegment(platform)}_CONNECTION_KEY`;
-    const customNote = details.tags?.includes("custom") ? CUSTOM_ACTION_NOTE : "";
-    return `${knowledge}
-
-================================================================
-INTEGRATION CODE GUIDE — using this action in an application
-================================================================
-You are in knowledge mode: this action cannot be executed here. Use this
-guide to write integration code in the user's project.
-
-## 1. Where this code must live
-Server-side only — an API route, edge function, or backend handler
-(e.g. Supabase Edge Function, Next.js route handler, Express route).
-NEVER call this API from browser/client code and NEVER hardcode secret
-values in source — read them from environment variables.
-
-## 2. The request
-All calls go through the One Passthrough API. Do NOT call the third-party
-API URL from the documentation above directly.
-
-URL:    ${apiBase}/v1/passthrough${path}
-Method: ${method}
-Headers:
-- x-one-secret: the value of the ONE_SECRET env var
-- x-one-connection-key: the value of the ${connEnv} env var
-- x-one-action-id: ${details._id}
-- Content-Type: application/json
-
-The URL is the One base plus the action path ONLY:
-✅ ${apiBase}/v1/passthrough${path}
-❌ ${apiBase}/v1/passthrough/https://some-vendor-api.com${path}
-
-## 3. Parameter placement
-Per the documentation above:
-- Path variables (placeholders like {{userId}} in the path) → substitute
-  real values into the URL path; never send them in the body.
-- Query parameters → the URL query string, not the body.
-- Body fields → the JSON request body (POST/PUT/PATCH only).${customNote}
-
-## 4. Environment variables & deployment
-The code will not work until the user sets these in their hosting
-platform's secrets manager (Supabase secrets, Vercel/Netlify environment
-settings, or the project's env settings — never committed to code):
-- ONE_SECRET → their One API key (from the One dashboard)
-- ${connEnv} → the connection key for ${platform} (from list_one_integrations)
-When you deliver the code, explicitly tell the user to set both.
-
-## 5. Code generation rules
-- Use TypeScript unless the user asked for another language.
-- Include the complete input/output structure from the documentation
-  above (required/optional fields, types) in the implementation.
-- Handle errors: on a non-2xx response, read the response body and
-  surface a useful message.
-- Minimal example:
-
-\`\`\`typescript
-const response = await fetch("${apiBase}/v1/passthrough${path}", {
-  method: "${method}",
-  headers: {
-    "x-one-secret": process.env.ONE_SECRET,
-    "x-one-connection-key": process.env.${connEnv},
-    "x-one-action-id": "${details._id}",
-    "Content-Type": "application/json",
-  },
-  // body: JSON.stringify(...) — only for non-GET requests
-});
-\`\`\``;
-}
 /** Folds a path variable name for loose matching: `ticket_id`, `ticketId`, `TICKET-ID` all fold to `ticketid`. */
 const foldVariableName = (name) => name.toLowerCase().replace(/[\s_-]/g, '');
 /**
@@ -298,12 +215,6 @@ const PERMISSION_METHODS = {
     write: ["GET", "POST", "PUT", "PATCH"],
     admin: null,
 };
-export function filterByPermissions(actions, permissions) {
-    const allowed = PERMISSION_METHODS[permissions];
-    if (allowed === null)
-        return actions;
-    return actions.filter((a) => allowed.includes(a.method.toUpperCase()));
-}
 export function isMethodAllowed(method, permissions) {
     const allowed = PERMISSION_METHODS[permissions];
     if (allowed === null)
@@ -368,12 +279,3 @@ export function buildIntegrationsResponse(connections, access, available) {
     }
     return response;
 }
-/** Back office tag for actions agents must not use (a `custom` action covers them). */
-export const HIDDEN_FROM_AGENTS_TAG = "hidden:agents";
-/**
- * Whether an action is hidden from executing agents. Knowledge/code-gen mode
- * still sees these: writing integration code may target the raw endpoint.
- */
-export function isHiddenFromAgents(tags) {
-    return (tags ?? []).includes(HIDDEN_FROM_AGENTS_TAG);
-}

package/build/index.js

@@ -11,8 +11,9 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { ErrorCode, McpError, } from '@modelcontextprotocol/sdk/types.js';
 import { OneClient } from './client.js';
-import { buildKnowledgeModeGuidance, buildKnowledgeResponse, filterByPermissions, isMethodAllowed, isActionAllowed, buildIntegrationsResponse, isHiddenFromAgents, } from './helpers.js';
-import { listOneIntegrationsToolConfig, searchOnePlatformActionsToolConfig, getOneActionKnowledgeToolConfig, executeOneActionToolConfig } from './schemas.js';
+import { isMethodAllowed, isActionAllowed, buildIntegrationsResponse, } from './helpers.js';
+import { FindArgsError, findOneActions } from './find.js';
+import { listOneIntegrationsToolConfig, findOneActionsToolConfig, executeOneActionToolConfig } from './schemas.js';
 const SERVER_NAME = "one-mcp-server";
 const SERVER_VERSION = "1.0.0";
 const ONE_SECRET = process.env.ONE_SECRET;
@@ -74,13 +75,9 @@ server.registerTool("list_one_integrations", listOneIntegrationsToolConfig, asyn
     await initializeOne();
     return await handleGetIntegrations(args);
 });
-server.registerTool("search_one_platform_actions", searchOnePlatformActionsToolConfig, async (args) => {
+server.registerTool("find_one_actions", findOneActionsToolConfig, async (args) => {
     await initializeOne();
-    return await handleSearchPlatformActions(args);
-});
-server.registerTool("get_one_action_knowledge", getOneActionKnowledgeToolConfig, async (args) => {
-    await initializeOne();
-    return await handleGetActionKnowledge(args);
+    return await handleFindOneActions(args);
 });
 if (!ONE_KNOWLEDGE_AGENT) {
     server.registerTool("execute_one_action", executeOneActionToolConfig, async (args) => {
@@ -116,127 +113,36 @@ async function handleGetIntegrations(args) {
         throw new McpError(ErrorCode.InternalError, `Failed to retrieve integrations: ${error instanceof Error ? error.message : 'Unknown error'}`);
     }
 }
-async function handleSearchPlatformActions(args) {
+async function handleFindOneActions(args) {
     try {
-        // Force knowledge mode when ONE_KNOWLEDGE_AGENT is enabled
-        // With execute available, default to the execute catalog: it hides actions
-        // tagged hidden:agents and offers the custom actions that replace them.
-        const agentType = ONE_KNOWLEDGE_AGENT ? "knowledge" : (args.agentType ?? "execute");
-        let actions = await oneClient.searchAvailableActions(args.platform, args.query, agentType);
-        // Apply permission-level filtering
-        actions = filterByPermissions(actions, ONE_PERMISSIONS);
-        // Apply action allowlist filtering
-        actions = actions.filter(a => isActionAllowed(a.systemId, ONE_ACTION_IDS));
-        const cleanedActions = actions.map(action => ({
-            actionId: action.systemId,
-            title: action.title,
-            method: action.method,
-            path: action.path
-        }));
-        // Handle empty results with helpful suggestions
-        if (cleanedActions.length === 0) {
-            const suggestionsText = `No actions found for platform '${args.platform}' matching query '${args.query}'.
-
-SUGGESTIONS:
-- Try a more general query (e.g., 'list', 'get', 'search', 'create')
-- Verify the platform name is correct
-- Check that actions exist for this platform using list_one_integrations
-
-EXAMPLES OF GOOD QUERIES:
-- "search contacts"
-- "send email"
-- "create customer"
-- "list orders"`;
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: suggestionsText,
-                    },
-                ],
-            };
-        }
-        // Build structured response
-        const structuredResponse = {
-            actions: cleanedActions,
-            metadata: {
-                platform: args.platform,
-                query: args.query,
-                count: cleanedActions.length
-            }
-        };
-        const responseText = `Found ${cleanedActions.length} action(s) for platform '${args.platform}' matching query '${args.query}':
-
-${JSON.stringify(structuredResponse, null, 2)}
-
-NEXT STEP: Use get_one_action_knowledge with an actionId to get detailed documentation before building requests or executing actions.`;
+        const text = await findOneActions(args, oneClient, {
+            knowledgeAgent: ONE_KNOWLEDGE_AGENT,
+            permissions: ONE_PERMISSIONS,
+            actionIds: ONE_ACTION_IDS,
+            platforms: ONE_CONNECTION_KEYS.includes("*")
+                ? null
+                : oneClient.getUserConnections().map(c => c.platform),
+            baseUrl: oneClient.getBaseUrl(),
+        });
         return {
             content: [
                 {
                     type: "text",
-                    text: responseText,
+                    text,
                 },
             ],
-            structuredContent: structuredResponse,
         };
     }
     catch (error) {
-        throw new McpError(ErrorCode.InternalError, `Failed to search platform actions: ${error instanceof Error ? error.message : 'Unknown error'}`);
-    }
-}
-async function handleGetActionKnowledge(args) {
-    try {
-        const actionId = args.actionId;
-        if (!isActionAllowed(actionId, ONE_ACTION_IDS)) {
-            throw new McpError(ErrorCode.InvalidRequest, `Action "${actionId}" is not in the allowed action list`);
-        }
-        if (!ONE_CONNECTION_KEYS.includes("*")) {
-            const connectedPlatforms = oneClient.getUserConnections().map(c => c.platform);
-            if (!connectedPlatforms.includes(args.platform)) {
-                throw new McpError(ErrorCode.InvalidRequest, `Platform "${args.platform}" has no allowed connections`);
-            }
-        }
-        if (ONE_KNOWLEDGE_AGENT) {
-            // Knowledge/code-gen mode returns the full document: the appended
-            // Integration Code Guide tells the agent to reproduce the complete
-            // input and output structure, which the digest would defer. Digesting
-            // is for the execute flow below, where the agent only needs to build
-            // one request.
-            const details = await oneClient.getActionDetails(actionId);
-            const knowledgeWithGuide = buildKnowledgeModeGuidance(details, args.platform, oneClient.getBaseUrl());
+        // A call the agent has to fix goes back to it as a tool error it can read
+        // and correct, rather than a protocol failure.
+        if (error instanceof FindArgsError) {
             return {
-                content: [
-                    {
-                        type: "text",
-                        text: knowledgeWithGuide,
-                    },
-                ],
+                content: [{ type: "text", text: error.message }],
+                isError: true,
             };
         }
-        if (isHiddenFromAgents((await oneClient.getActionDetails(actionId)).tags)) {
-            throw new McpError(ErrorCode.InvalidRequest, `Action "${actionId}" is hidden from agents; search for the task again to find the action to use instead`);
-        }
-        const { knowledge, method } = await oneClient.getActionKnowledge(actionId);
-        const response = buildKnowledgeResponse(knowledge, method, args.platform, actionId, {
-            section: args.section,
-            full: args.full,
-            toc: args.toc,
-        });
-        // Execute mode returns the documentation alone: execute_one_action builds
-        // the passthrough request itself, so the raw-HTTP guidance code-gen mode
-        // appends (base URL, x-one-* headers, env var names) would only add tokens.
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: response.text,
-                },
-            ],
-            structuredContent: response.structured,
-        };
-    }
-    catch (error) {
-        throw new McpError(ErrorCode.InternalError, `Failed to retrieve action knowledge: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        throw new McpError(ErrorCode.InternalError, `Failed to find actions: ${error instanceof Error ? error.message : 'Unknown error'}`);
     }
 }
 async function handleExecuteOneAction(args) {
@@ -251,9 +157,6 @@ async function handleExecuteOneAction(args) {
             }
         }
         const actionDetails = await oneClient.getActionDetails(args.actionId);
-        if (isHiddenFromAgents(actionDetails.tags)) {
-            throw new McpError(ErrorCode.InvalidRequest, `Action "${args.actionId}" is hidden from agents; search for the task again to find the action to use instead`);
-        }
         if (!isMethodAllowed(actionDetails.method, ONE_PERMISSIONS)) {
             throw new McpError(ErrorCode.InvalidRequest, `Method "${actionDetails.method}" is not allowed under "${ONE_PERMISSIONS}" permission level`);
         }

package/build/knowledge-response.test.js

@@ -22,7 +22,8 @@ describe('buildKnowledgeResponse', () => {
         assert.ok(r.structured.omitted >= 1);
         assert.ok(Array.isArray(r.structured.sections) && r.structured.sections.length >= 1);
         assert.ok(r.text.includes('**Digest.**'));
-        assert.ok(r.text.includes('get_one_action_knowledge'));
+        assert.ok(r.text.includes('find_one_actions with load: [{ action_id: "act_1"'));
+        assert.ok(!r.text.includes('get_one_action_knowledge'), 'this server has no knowledge tool to send the agent to');
         // A deferred body is not inlined into the digest text.
         assert.ok(!r.text.includes('Response Fields field 100'));
         // No CLI-flag phrasing leaks into agent-visible text.

package/build/knowledge-sections.js

@@ -17,6 +17,13 @@
  *
  * Everything in this module is pure: string in, structure out. No I/O.
  */
+/** How to load section `id` in full, closing a cut section. */
+function loadSection(load, id) {
+    if (load?.followUp === 'findTool') {
+        return `calling find_one_actions with load: [{ action_id: "${load.actionId}", section: "${id}" }]`;
+    }
+    return `calling get_one_action_knowledge again with section: "${id}"`;
+}
 export const DEFAULT_WHOLE_DOC_THRESHOLD = 8_000;
 export const DEFAULT_DIGEST_BUDGET = 8_000;
 export const DEFAULT_SECTION_CAP = 6_000;
@@ -204,13 +211,13 @@ function deferredPriority(heading) {
         return 6;
     return 4;
 }
-function truncateText(text, cap, id) {
+function truncateText(text, cap, id, load) {
     const cut = text.slice(0, cap);
     // Back up to a line boundary so we never split a table row or code fence mid-way.
     const nl = cut.lastIndexOf('\n');
     const head = nl > cap * 0.5 ? cut.slice(0, nl) : cut;
     const remaining = text.length - head.length;
-    return `${head}\n\n_[truncated — ${remaining.toLocaleString('en-US')} more chars. Load the full section by calling get_one_action_knowledge again with section: "${id}"]_`;
+    return `${head}\n\n_[truncated — ${remaining.toLocaleString('en-US')} more chars. Load the full section by ${loadSection(load, id)}]_`;
 }
 /**
  * Build the digest: essential sections in full (capped), then deferred
@@ -247,7 +254,7 @@ export function buildDigest(doc, opts = {}) {
             if (node.tier === 'essential' || (node.level >= 3 && hasEssentialDescendant(node))) {
                 const own = node.text;
                 if (own.length > cap) {
-                    const render = truncateText(own, cap, node.id);
+                    const render = truncateText(own, cap, node.id, opts.load);
                     decisions.set(node.id, { node, included: 'partial', render });
                     used += render.length;
                 }
@@ -398,7 +405,7 @@ export function omittedSections(digest, max = DEFAULT_TOC_MAX_ENTRIES) {
  * The trailer appended to a digest so an agent that only reads the markdown
  * (and never looks at the JSON envelope) still knows the document continues.
  */
-export function renderDigestNotice(digest, platform, actionId) {
+export function renderDigestNotice(digest, platform, actionId, followUp = 'knowledge') {
     if (!digest.truncated)
         return '';
     // List only the top-most omitted sections: in document order the nearest
@@ -433,8 +440,15 @@ export function renderDigestNotice(digest, platform, actionId) {
     return [
         '---',
         `**This is a digest, not the full document.** ${topMost.length} section${topMost.length === 1 ? '' : 's'} omitted (${digest.omittedChars.toLocaleString('en-US')} chars): ${nameList}.`,
-        `Load one or more by calling get_one_action_knowledge again for ${platform} / ${actionId} with section: "${topMost[0]?.heading ?? 'Response'}" (comma-separate several).`,
-        `Load the whole document with full: true.`,
+        ...(followUp === 'findTool'
+            ? [
+                `Load one or more by calling find_one_actions with load: [{ action_id: "${actionId}", section: "${topMost[0]?.heading ?? 'Response'}" }] (comma-separate several).`,
+                `Load the whole document with full: true in place of section.`,
+            ]
+            : [
+                `Load one or more by calling get_one_action_knowledge again for ${platform} / ${actionId} with section: "${topMost[0]?.heading ?? 'Response'}" (comma-separate several).`,
+                `Load the whole document with full: true.`,
+            ]),
     ].join('\n');
 }
 /**

package/build/knowledge-sections.test.js

@@ -224,6 +224,28 @@ describe('renderDigestNotice', () => {
         assert.ok(!notice.includes('Success Response (201 Created)'), 'children of an omitted parent are implied');
         assert.ok(notice.includes('Response Fields'));
     });
+    // Byte-for-byte the Rust engine's `KnowledgeFollowUp::FindTool` wording, so
+    // an agent reads the same call from the remote MCP and from this package.
+    it('names find_one_actions with the exact load call for the find tool', () => {
+        const d = buildDigest(parseSections(GITHUB), {
+            wholeDocThreshold: 0,
+            budget: 0,
+            load: { followUp: 'findTool', platform: 'github', actionId: 'conn_mod_def::X::Y' },
+        });
+        const notice = renderDigestNotice(d, 'github', 'conn_mod_def::X::Y', 'findTool');
+        const [, , load, whole] = notice.split('\n');
+        assert.match(load, /^Load one or more by calling find_one_actions with load: \[\{ action_id: "conn_mod_def::X::Y", section: "[^"]+" \}\] \(comma-separate several\)\.$/);
+        assert.equal(whole, 'Load the whole document with full: true in place of section.');
+        assert.ok(!notice.includes('get_one_action_knowledge'));
+    });
+    it('names find_one_actions in a cut section\'s note for the find tool', () => {
+        const body = `# Upload\n\n## Request Body\n\n${'field: value\n'.repeat(1_000)}\n## Response Fields\n\nid`;
+        const d = buildDigest(parseSections(body), {
+            wholeDocThreshold: 0,
+            load: { followUp: 'findTool', platform: 'gmail', actionId: 'gmail::upload' },
+        });
+        assert.ok(d.markdown.includes('more chars. Load the full section by calling find_one_actions with load: [{ action_id: "gmail::upload", section: "request-body" }]]_'), d.markdown.slice(-300));
+    });
 });
 describe('renderDigestBanner', () => {
     it('is empty when nothing was omitted and one line otherwise', () => {

package/build/schemas.js

@@ -13,29 +13,29 @@ import { z } from 'zod';
  */
 export const listOneIntegrationsInputSchema = {};
 /**
- * Schema for searching platform actions
+ * Schema for finding actions and their documentation. Worded as the remote
+ * MCP's `find_one_actions`, so an agent reads one tool on either surface.
  */
-export const searchOnePlatformActionsInputSchema = {
-    platform: z.string().describe("The platform name to search actions for (e.g., 'ship-station', 'shopify'). This is the kebab-case platform name from list_one_integrations."),
-    query: z.string().describe("The search query to find relevant actions (e.g., 'search contacts', 'create customer', 'send email'). Be specific about what you want to do."),
-    agentType: z.enum(["execute", "knowledge"]).optional().describe("The type of agent context: 'execute' if the user wants to execute an action, 'knowledge' if they want to get information or write code. Defaults to 'execute' when this server can execute actions (knowledge-only servers always use 'knowledge').")
-};
-/**
- * Schema for getting action knowledge
- */
-export const getOneActionKnowledgeInputSchema = {
-    actionId: z.string().describe("The action ID to get knowledge for (from the actions list returned by search_one_platform_actions). REQUIRED: This tool must be called before execute_one_action to load the action's documentation into context."),
-    platform: z.string().describe("The platform name to get knowledge for (e.g., 'ship-station', 'shopify'). This is the kebab-case platform name from list_one_integrations."),
-    section: z.string().optional().describe("Load specific section(s) of the documentation by name (e.g. 'Response Fields', or comma-separated 'Response Fields, Optional Request Body Fields'). Large docs return a digest first; use this on a follow-up call to pull a section the digest omitted."),
-    full: z.boolean().optional().describe("Return the entire documentation verbatim instead of the token-saving digest. Ignored when `section` is set. Leave unset by default; only set it when you genuinely need every section."),
-    toc: z.boolean().optional().describe("Return only the table of contents (every section's id, heading, and size), no bodies. Use it to see everything available when the digest collapsed its list. Ignored when `section` is set.")
+export const findOneActionsInputSchema = {
+    requests: z.array(z.object({
+        platform: z.string().describe('The kebab-case platform identifier (e.g. "gmail", "stripe").'),
+        intent: z.string().describe('The operation alone, in a few words (e.g. "send a message to a channel"), without its data: no IDs, names or message text.')
+    })).min(1).max(10).optional().describe('What to do, one entry per API operation, on any platforms (1 to 10). Each is the kebab-case platform (e.g. "gmail", "hubspot") and a short intent (e.g. "send an email", "find a contact by email").'),
+    task: z.string().optional().describe('The whole task in one line, in general terms (e.g. "email a report to a contact"): what it does, without names, addresses, IDs or message text. It helps choose between similar actions. Never the chat history. Only with `requests`.'),
+    load: z.array(z.object({
+        action_id: z.string().describe("The actionId from a find_one_actions answer."),
+        section: z.string().optional().describe('Section name(s) to load, comma-separated (e.g. "Response Fields"). Omit, with `full` and `toc` unset, for the digest. In knowledge mode every load returns the whole document, so `section` and `toc` do not narrow it.'),
+        full: z.boolean().optional().describe("Load the whole document. Ignored when `section` is set."),
+        toc: z.boolean().optional().describe("Load only the table of contents. Ignored when `section` is set.")
+    })).min(1).max(10).optional().describe("More documentation for actions already found (1 to 10): a section the digest omitted, the whole document, the table of contents, or an alternative's documentation. Use instead of `requests`."),
+    ai_model: z.string().optional().describe('The AI model you are running as (e.g. "claude-sonnet-5", "gpt-5"), which helps optimize the documentation returned. Optional.')
 };
 /**
  * Schema for executing One actions
  */
 export const executeOneActionInputSchema = {
     platform: z.string().describe("Platform name"),
-    actionId: z.string().describe("Action ID from search_one_platform_actions"),
+    actionId: z.string().describe("The actionId from find_one_actions"),
     connectionKey: z.string().describe("Key of the connection to use"),
     data: z.any().optional().describe("Request data (for POST, PUT, etc.)"),
     pathVariables: z.record(z.union([z.string(), z.number(), z.boolean()])).optional().describe("Variables to replace in the path"),
@@ -81,22 +81,6 @@ export const listOneIntegrationsOutputSchema = {
         availableCount: z.number().optional()
     }).describe("Counts of connections (and available platforms in knowledge/code-gen mode)")
 };
-/**
- * Output schemas for search_one_platform_actions tool
- */
-export const searchOnePlatformActionsOutputSchema = {
-    actions: z.array(z.object({
-        actionId: z.string().describe("Unique identifier for the action"),
-        title: z.string().describe("Human-readable action name"),
-        method: z.string().describe("HTTP method (GET, POST, etc.)"),
-        path: z.string().describe("API endpoint path")
-    })).describe("Array of matching actions (max 5)"),
-    metadata: z.object({
-        platform: z.string().describe("Platform that was searched"),
-        query: z.string().describe("Search query used"),
-        count: z.number().describe("Number of results returned")
-    }).describe("Metadata about the search results")
-};
 /**
  * Tool configuration objects for registerTool
  */
@@ -106,26 +90,19 @@ export const listOneIntegrationsToolConfig = {
     inputSchema: listOneIntegrationsInputSchema,
     outputSchema: listOneIntegrationsOutputSchema
 };
-export const searchOnePlatformActionsToolConfig = {
-    title: "Search Platform Actions",
-    description: "Search for relevant actions on a specific platform using a query. Call this after list_one_integrations to find actions that match your intent. Returns the top 5 most relevant actions based on your search query. Use the exact kebab-case platform name from the integrations list.",
-    inputSchema: searchOnePlatformActionsInputSchema,
-    outputSchema: searchOnePlatformActionsOutputSchema
-};
-export const getOneActionKnowledgeToolConfig = {
-    title: "Get Action Knowledge",
-    description: "Get comprehensive documentation for a specific action including parameters, requirements, and usage examples. MANDATORY: You MUST call this tool before execute_one_action to understand the action's requirements, parameter structure, caveats, and proper usage. This loads the action documentation into context and is required for successful execution. Large documents come back as a digest (the sections needed to build a correct request, plus a list of what was omitted); request an omitted section by name with `section`, or the whole document with `full: true`.",
-    inputSchema: getOneActionKnowledgeInputSchema
+export const findOneActionsToolConfig = {
+    title: "Find Platform Actions",
+    description: "Use this to find the API actions a task needs, on any platforms, in one call: send one `requests` entry per operation (platform and a short intent) and get back, for each, the action to use with its documentation, plus a few alternatives. Large documents come back as a digest; call again with `load` for a section it omitted, the whole document, the table of contents, or an alternative's documentation. Results are limited to what this server's settings allow. Call list_one_integrations first to see the connected platforms.",
+    inputSchema: findOneActionsInputSchema
 };
 export const executeOneActionToolConfig = {
     title: "Execute One Action",
-    description: "Execute a One action to perform actual operations on third-party platforms. CRITICAL: Only call this when the user's intent is to EXECUTE an action (e.g., 'read my last Gmail email', 'fetch 5 contacts from HubSpot', 'create a task in Asana'). DO NOT call this when the user wants to BUILD or CREATE code/forms/applications - in those cases, stop after get_one_action_knowledge and provide implementation guidance instead. REQUIRED WORKFLOW: Must call get_one_action_knowledge first. If uncertain about execution intent or parameters, ask for confirmation before proceeding.",
+    description: "Execute a One action to perform actual operations on third-party platforms. CRITICAL: Only call this when the user's intent is to EXECUTE an action (e.g., 'read my last Gmail email', 'fetch 5 contacts from HubSpot', 'create a task in Asana'). DO NOT call this when the user wants to BUILD or CREATE code/forms/applications - in those cases, stop after find_one_actions and provide implementation guidance instead. REQUIRED WORKFLOW: Must call find_one_actions first, which returns the action's documentation. If uncertain about execution intent or parameters, ask for confirmation before proceeding.",
     inputSchema: executeOneActionInputSchema
 };
 /**
  * Zod object schemas for type inference (for internal use)
  */
 export const listOneIntegrationsZodSchema = z.object(listOneIntegrationsInputSchema);
-export const searchOnePlatformActionsZodSchema = z.object(searchOnePlatformActionsInputSchema);
-export const getOneActionKnowledgeZodSchema = z.object(getOneActionKnowledgeInputSchema);
+export const findOneActionsZodSchema = z.object(findOneActionsInputSchema);
 export const executeOneActionZodSchema = z.object(executeOneActionInputSchema);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withone/mcp",
-  "version": "1.4.0",
+  "version": "2.0.0",
   "description": "A Model Context Protocol Server for One",
   "type": "module",
   "bin": {

package/build/hidden-actions.test.js

@@ -1,12 +0,0 @@
-import { describe, it } from 'node:test';
-import assert from 'node:assert/strict';
-import { isHiddenFromAgents } from './helpers.js';
-describe('isHiddenFromAgents', () => {
-    it('flags only actions tagged hidden:agents', () => {
-        assert.equal(isHiddenFromAgents(['hidden:agents']), true);
-        assert.equal(isHiddenFromAgents(['custom', 'hidden:agents']), true);
-        assert.equal(isHiddenFromAgents(['custom']), false);
-        assert.equal(isHiddenFromAgents([]), false);
-        assert.equal(isHiddenFromAgents(undefined), false);
-    });
-});