@agent-native/core 0.224.0 → 0.225.0-nightly-20261105110131

package/dist/action.d.ts

@@ -488,6 +488,13 @@ interface DefineActionWithSchema<TSchema extends StandardSchemaV1, TReturn = any
     mcpTool?: boolean;
     mcpAnnotations?: ActionMcpToolAnnotations;
     deferLoading?: boolean;
+    /** Words and short phrases a user says for this action that its name and
+     *  description do not: "auto-archive rule", "canned reply", "reschedule".
+     *  `tool-search` ranks them just below the name. They are never shown to a
+     *  model, so they add no context cost; keep them factual, not a list of
+     *  every request the action might serve. At most 12, each up to 60
+     *  characters. */
+    searchHints?: readonly string[];
     eagerInputStreaming?: boolean;
     /** An empty list on this action sets an option and erases nothing saved, so
      *  a call that pads unused fields with `null` and `[]` can run as sent. Leave
@@ -600,6 +607,8 @@ interface DefineActionWithParams<TParams extends Record<string, ParameterSchema>
     mcpTool?: boolean;
     mcpAnnotations?: ActionMcpToolAnnotations;
     deferLoading?: boolean;
+    /** See `searchHints` on the schema form above. */
+    searchHints?: readonly string[];
     eagerInputStreaming?: boolean;
     emptyListsEraseNothing?: boolean;
     readOnly?: boolean;
@@ -643,6 +652,7 @@ export interface ActionDefinition<TInput, TReturn> {
     readonly mcpTool?: boolean;
     readonly mcpAnnotations?: ActionMcpToolAnnotations;
     readonly deferLoading?: boolean;
+    readonly searchHints?: readonly string[];
     readonly eagerInputStreaming?: boolean;
     readonly emptyListsEraseNothing?: boolean;
     readonly readOnly?: boolean;
@@ -679,6 +689,24 @@ export interface ActionDefinition<TInput, TReturn> {
     readonly audit?: ActionAuditConfig;
     readonly access?: ActionAccessConfig;
 }
+/**
+ * An action's own definition is invalid. Loaders never skip such an action or
+ * fall back to wrapping it as a CLI script: the app fails to load, naming the
+ * action, until the definition is fixed.
+ */
+export declare class ActionDefinitionError extends TypeError {
+    readonly actionDefinitionError = true;
+    readonly actionName: string | undefined;
+    constructor(message: string, actionName?: string);
+}
+export declare function isActionDefinitionError(error: unknown): error is ActionDefinitionError;
+/**
+ * The same error naming `actionName`, for a loader that knows the name the
+ * definition itself could not report.
+ */
+export declare function namedActionDefinitionError(error: ActionDefinitionError, actionName: string): ActionDefinitionError;
+/** Throws unless `value` is absent or a valid hint list. */
+export declare function validateSearchHints(value: unknown, actionName?: string): readonly string[] | undefined;
 export declare function defineAction<TSchema extends StandardSchemaV1, TReturn>(options: DefineActionWithSchema<TSchema, TReturn, undefined>): ActionDefinition<StandardSchemaV1.InferInput<TSchema>, TReturn>;
 export declare function defineAction<TParams extends Record<string, ParameterSchema> | undefined, TReturn>(options: DefineActionWithParams<TParams, TReturn, undefined>): ActionDefinition<InferParams<TParams>, TReturn>;
 export declare function defineAction<TParams extends Record<string, ParameterSchema> | undefined, TOutputSchema extends StandardSchemaV1, TStrategy extends ActionOutputErrorStrategy = "strict">(options: DefineActionWithParams<TParams, StandardSchemaV1.InferInput<TOutputSchema>, TOutputSchema, TStrategy> & {

package/dist/action.js

@@ -472,6 +472,51 @@ function withCommittedEffect(error) {
 export const MCP_APP_EXTENSION_ID = "io.modelcontextprotocol/ui";
 export const MCP_APP_MIME_TYPE = "text/html;profile=mcp-app";
 export const MCP_APP_RESOURCE_URI_META_KEY = "ui/resourceUri";
+const MAX_SEARCH_HINTS = 12;
+const MAX_SEARCH_HINT_CHARS = 60;
+/**
+ * An action's own definition is invalid. Loaders never skip such an action or
+ * fall back to wrapping it as a CLI script: the app fails to load, naming the
+ * action, until the definition is fixed.
+ */
+export class ActionDefinitionError extends TypeError {
+    actionDefinitionError = true;
+    actionName;
+    constructor(message, actionName) {
+        super(actionName ? `Action "${actionName}": ${message}` : message);
+        this.name = "ActionDefinitionError";
+        this.actionName = actionName;
+    }
+}
+export function isActionDefinitionError(error) {
+    return (error instanceof ActionDefinitionError ||
+        (!!error &&
+            typeof error === "object" &&
+            error.actionDefinitionError ===
+                true));
+}
+/**
+ * The same error naming `actionName`, for a loader that knows the name the
+ * definition itself could not report.
+ */
+export function namedActionDefinitionError(error, actionName) {
+    return error.actionName
+        ? error
+        : new ActionDefinitionError(error.message, actionName);
+}
+/** Throws unless `value` is absent or a valid hint list. */
+export function validateSearchHints(value, actionName) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value) ||
+        value.length > MAX_SEARCH_HINTS ||
+        value.some((hint) => typeof hint !== "string" ||
+            hint.trim().length === 0 ||
+            hint.length > MAX_SEARCH_HINT_CHARS)) {
+        throw new ActionDefinitionError(`searchHints must be at most ${MAX_SEARCH_HINTS} non-empty strings of up to ${MAX_SEARCH_HINT_CHARS} characters.`, actionName);
+    }
+    return Object.freeze([...value]);
+}
 export function defineAction(options) {
     const hasSchema = options.schema && "~standard" in options.schema;
     const tool = {
@@ -716,6 +761,7 @@ export function defineAction(options) {
     const deferLoading = typeof options.deferLoading === "boolean"
         ? options.deferLoading
         : undefined;
+    const searchHints = validateSearchHints(options.searchHints);
     const parallelSafe = typeof options.parallelSafe === "boolean"
         ? options.parallelSafe
         : undefined;
@@ -783,6 +829,7 @@ export function defineAction(options) {
         ...(typeof mcpTool === "boolean" ? { mcpTool } : {}),
         ...(mcpAnnotations ? { mcpAnnotations } : {}),
         ...(typeof deferLoading === "boolean" ? { deferLoading } : {}),
+        ...(searchHints ? { searchHints } : {}),
         ...(typeof options.eagerInputStreaming === "boolean"
             ? { eagerInputStreaming: options.eagerInputStreaming }
             : {}),

package/dist/agent/production-agent.d.ts

@@ -193,6 +193,8 @@ export interface ActionEntry {
      *  decision, so they never count as the action declaring its hints. */
     mcpAnnotationDefaults?: import("../action.js").ActionMcpToolAnnotations;
     deferLoading?: boolean;
+    /** See `searchHints` in `defineAction`. Read only by `tool-search`. */
+    searchHints?: readonly string[];
     eagerInputStreaming?: boolean;
     /** See `emptyListsEraseNothing` in `defineAction`. */
     emptyListsEraseNothing?: boolean;

package/dist/agent/tool-search.d.ts

@@ -23,6 +23,8 @@ type ToolSearchResult = {
     score: number;
     callable: boolean;
     planAvailability: "read" | "conditional" | "act-only";
+    /** Present on a tool that deletes or cancels; absent on every other. */
+    destructive?: true;
     parameters: ToolParameterSummary[];
 };
 type ToolSearchOptions = {

package/dist/agent/tool-search.js

@@ -1,7 +1,7 @@
 import { isActionHiddenFromEveryAgentSurface } from "../action.js";
 import { parseMcpToolName } from "../mcp-client/manager.js";
 import { isMcpToolAllowedForRequest } from "../mcp-client/visibility.js";
-import { frameworkMcpTool } from "../mcp/framework-tools.js";
+import { frameworkMcpTool, isFrameworkMcpTool, } from "../mcp/framework-tools.js";
 import { getRequestRunContext } from "../server/request-context.js";
 import { clipHead } from "./clip-text.js";
 export const TOOL_SEARCH_ACTION_NAME = "tool-search";
@@ -23,19 +23,19 @@ export function createToolSearchEntry(getRegistry, options = {}) {
     const defaultLimit = Math.max(1, Math.min(options.defaultLimit ?? DEFAULT_LIMIT, maxLimit));
     return frameworkMcpTool({
         tool: {
-            description: "Find actions and connected MCP tools by capability or exact name. The system prompt's Tool index lists every deferred tool name grouped by topic; loading several exact names in one call is the fastest path. A targeted search returns concise details and adds matches allowed in the current mode, with their full schemas, to the NEXT model step, not this one, so request every tool you need in one call (`queries` and/or `names`) and call them on the next step. If every match is already callable, call it directly instead of searching again. Omit query for a bounded alphabetical menu; menu entries are informational until you search for a capability or name.",
+            description: "Find actions and connected MCP tools by what they do or by exact name. The system prompt's Tool index lists every deferred tool name grouped by topic; loading several exact names in one call is the fastest path. A targeted search returns concise details and adds matches allowed in the current mode, with their full schemas, to the NEXT model step, not this one, so request every tool you need in one call (`queries` and/or `names`) and call them on the next step. If every match is already callable, call it directly instead of searching again. Results rank by words, not intent: before calling one marked `destructive`, confirm the user wants that change. Omit query for a bounded alphabetical menu; menu entries are informational until you search for a capability or name.",
             parameters: {
                 type: "object",
                 properties: {
                     query: {
                         type: "string",
-                        description: "Capability or exact tool name to find. A targeted search adds matches allowed in the current mode, with their full schemas, to the next model step. Omit for a bounded alphabetical inventory.",
+                        description: 'The task in a few plain words ("edit auto-archive rules") or an exact tool name; the user\'s own words work. Omit for a bounded alphabetical inventory.',
                     },
                     queries: {
                         type: "array",
                         items: { type: "string" },
                         maxItems: MAX_QUERIES,
-                        description: `Up to ${MAX_QUERIES} capability searches run together; all matches load on the next step.`,
+                        description: `Up to ${MAX_QUERIES} searches run together, one per task step; all matches load on the next step.`,
                     },
                     names: {
                         type: "array",
@@ -195,6 +195,7 @@ function searchOnce(registry, target, args, options) {
                 score: 0,
                 callable: registry[name]?.allowInPlanMode !== false,
                 planAvailability: getPlanAvailability(name, registry[name]),
+                ...destructiveMark(name, registry[name]),
                 description: "Already returned by an earlier identical tool-search call.",
                 parameters: [],
             })),
@@ -233,6 +234,7 @@ function searchOnce(registry, target, args, options) {
                 score: 0,
                 callable,
                 planAvailability,
+                ...destructiveMark(name, entry),
                 parameters: [],
             });
             continue;
@@ -246,6 +248,7 @@ function searchOnce(registry, target, args, options) {
             score: 0,
             callable,
             planAvailability,
+            ...destructiveMark(name, entry),
             parameters: parameters
                 .slice(0, MAX_PARAMETER_COUNT)
                 .map(boundParameterSummary),
@@ -258,7 +261,14 @@ function searchOnce(registry, target, args, options) {
         }
         rankable.push({
             candidate,
-            terms: searchDocumentTerms({ name, source, description, parameters }),
+            prior: isFrameworkMcpTool(entry) ? FRAMEWORK_TOOL_PRIOR : 1,
+            fields: searchDocumentFields({
+                name,
+                source,
+                hints: entry.searchHints,
+                description,
+                parameters,
+            }),
         });
     }
     if (!listAll && !exactNames) {
@@ -519,67 +529,230 @@ function summarizeType(value) {
 const BM25_K1 = 1.2;
 const BM25_B = 0.75;
 const NAME_PHRASE_BONUS = 5;
-// Weighting by repetition keeps one BM25 pass: a name hit counts three times a
-// description hit, an MCP server hit twice.
-function searchDocumentTerms(doc) {
-    const name = searchTerms(doc.name);
-    const source = searchTerms(doc.source ?? "");
-    return [
-        ...name,
-        ...name,
-        ...name,
-        ...source,
-        ...source,
-        ...searchTerms(doc.description),
-        ...searchTerms(doc.parameters
-            .map((p) => `${p.name} ${p.type ?? ""} ${p.description ?? ""}`)
-            .join(" ")),
+const SYNONYM_WEIGHT = 0.5;
+// BM25F: each field is length-normalised on its own, then weighted, so a long
+// description cannot drown a one-word name match. Search hints are words users
+// say for the action, so they rank just below the name; the first sentence of
+// a description says what the tool is for and outranks the caveats after it.
+const FIELD_WEIGHTS = {
+    name: 5,
+    hints: 4,
+    source: 2,
+    summary: 2,
+    details: 1,
+    parameters: 0.5,
+};
+const SEARCH_FIELDS = Object.keys(FIELD_WEIGHTS);
+// Framework tools (sharing, review comments, usage, settings) ship in every
+// app and share its vocabulary: in Mail, "email" also names transactional
+// email logs. A request made in an app is usually about that app's own work,
+// so on similar text the app's actions rank first. Exact names still win.
+const FRAMEWORK_TOOL_PRIOR = 0.8;
+// Stemming would fold these nouns into an unrelated word ("news" into "new",
+// which then expands to the create synonyms; "setting" into "set"), so they
+// are indexed as themselves. Declared before the stemmed set below, which
+// calls `stem` as the module loads.
+const PROTECTED_TERMS = new Map([
+    ["news", "news"],
+    ["setting", "setting"],
+    ["settings", "setting"],
+    ["recording", "recording"],
+    ["recordings", "recording"],
+    ["mapping", "mapping"],
+    ["mappings", "mapping"],
+    ["heading", "heading"],
+    ["headings", "heading"],
+]);
+// Verbs that lose data. "Remove" and "clear" also name reversible edits
+// (removing a tag, clearing a filter), so they count only through a declared
+// `destructiveHint`, as does "permanently remove" spelled any other way.
+// Verbs that lose data or undo something another person relies on. "Remove"
+// and "clear" also name reversible edits (removing a tag, clearing a filter),
+// so they count only through a declared `destructiveHint`.
+const DESTRUCTIVE_VERBS = new Set(["delete", "destroy", "trash", "purge", "cancel"].map(stem));
+/** "delete", "deleteNode", "delete-node", "delete_node": the value leads with one. */
+function leadsWithDestructiveVerb(value) {
+    const verb = searchTerms(value).at(0);
+    return verb !== undefined && DESTRUCTIVE_VERBS.has(verb);
+}
+/**
+ * The `destructive` mark every result carries, on every path that builds one.
+ * Ranking ignores it: whether the user wants the change ("delete it" or "don't
+ * delete it") is the agent's call, so a search finds the tool either way and
+ * the mark tells the agent to check.
+ *
+ * Declared annotations decide, `destructiveHint: false` included. Without
+ * them, a read-only tool is never destructive (a `status: "cancelled"` filter
+ * on a list is not a write), and any other tool is when an `enum` or `const`
+ * value anywhere in its input schema leads with a destructive verb
+ * (`operation: "delete"`, `op: "delete"`, `kind: "deleteNode"`) or its own
+ * name does, since most delete actions declare no annotations.
+ */
+function destructiveMark(name, entry) {
+    if (!entry)
+        return {};
+    if (entry.mcpAnnotations) {
+        return entry.mcpAnnotations.destructiveHint ? { destructive: true } : {};
+    }
+    if (entry.readOnly === true)
+        return {};
+    return schemaHasDestructiveValue(entry.tool.parameters, 0) ||
+        leadsWithDestructiveVerb(parseMcpToolName(name)?.toolName ?? name)
+        ? { destructive: true }
+        : {};
+}
+// Deep enough for a list of tagged operations (properties → items → oneOf →
+// properties → op), shallow enough that a huge or cyclic schema cannot stall a
+// search.
+const MAX_SCHEMA_DEPTH = 6;
+function schemaHasDestructiveValue(schema, depth) {
+    if (depth > MAX_SCHEMA_DEPTH || !schema || typeof schema !== "object") {
+        return false;
+    }
+    const node = schema;
+    const literals = [
+        ...(Array.isArray(node.enum) ? node.enum : []),
+        node.const,
+    ].filter((value) => typeof value === "string");
+    if (literals.some(leadsWithDestructiveVerb))
+        return true;
+    const children = [
+        ...(node.properties && typeof node.properties === "object"
+            ? Object.values(node.properties)
+            : []),
+        ...(Array.isArray(node.items) ? node.items : [node.items]),
+        ...[node.oneOf, node.anyOf, node.allOf].flatMap((list) => Array.isArray(list) ? list : []),
     ];
+    return children.some((child) => schemaHasDestructiveValue(child, depth + 1));
+}
+function fieldTerms(value) {
+    const terms = searchTerms(value);
+    const counts = new Map();
+    for (const term of terms)
+        counts.set(term, (counts.get(term) ?? 0) + 1);
+    return { counts, length: terms.length };
+}
+function searchDocumentFields(doc) {
+    const sentenceEnd = doc.description.search(/[.!?](\s|$)/);
+    const summaryEnd = sentenceEnd < 0 ? doc.description.length : sentenceEnd + 1;
+    return {
+        name: fieldTerms(doc.name),
+        hints: fieldTerms((doc.hints ?? []).join(" ")),
+        source: fieldTerms(doc.source ?? ""),
+        summary: fieldTerms(doc.description.slice(0, summaryEnd)),
+        details: fieldTerms(doc.description.slice(summaryEnd)),
+        parameters: fieldTerms(doc.parameters.map((p) => `${p.name} ${p.description ?? ""}`).join(" ")),
+    };
+}
+// Common verbs and nouns users say in place of the words tool names use. They
+// count for half of a literal match, so the user's own word still wins.
+const SYNONYM_GROUPS = [
+    ["create", "make", "new", "add"],
+    ["delete", "remove", "trash", "erase", "clear"],
+    ["update", "change", "edit", "modify", "rename", "adjust"],
+    ["search", "find", "look", "lookup"],
+    ["list", "show"],
+    ["view", "see", "open"],
+    ["restore", "undo", "revert", "recover"],
+    ["export", "download"],
+    ["duplicate", "copy", "clone"],
+    ["reply", "respond", "answer"],
+    ["image", "picture", "photo"],
+    ["document", "doc", "page"],
+    ["email", "mail", "message"],
+    ["setting", "preference"],
+];
+const SYNONYMS = (() => {
+    const map = new Map();
+    for (const group of SYNONYM_GROUPS) {
+        const stems = group.map(stem);
+        for (const word of stems) {
+            const others = stems.filter((other) => other !== word);
+            map.set(word, [...(map.get(word) ?? []), ...others]);
+        }
+    }
+    return map;
+})();
+function weightedQueryTerms(queryTokens) {
+    const weights = new Map(queryTokens.map((term) => [term, 1]));
+    for (const term of queryTokens) {
+        for (const synonym of SYNONYMS.get(term) ?? []) {
+            if (!weights.has(synonym))
+                weights.set(synonym, SYNONYM_WEIGHT);
+        }
+    }
+    return weights;
 }
 // Corpus statistics come from every tool that survived this call's filters, so
 // a word most tools share ("get", "list", "app") ranks below a rare one.
 function rankByBm25(query, queryTokens, docs) {
     if (queryTokens.length === 0 || docs.length === 0)
         return [];
-    const counts = docs.map((doc) => {
-        const termCounts = new Map();
-        for (const term of doc.terms) {
-            termCounts.set(term, (termCounts.get(term) ?? 0) + 1);
-        }
-        return termCounts;
-    });
-    const averageLength = docs.reduce((sum, doc) => sum + doc.terms.length, 0) / docs.length || 1;
-    const idf = new Map(queryTokens.map((term) => {
-        const frequency = counts.filter((c) => c.has(term)).length;
+    const queryTerms = weightedQueryTerms(queryTokens);
+    // Averaged over the tools that fill the field: most tools have no search
+    // hints, and counting them would make every hint list look too long.
+    const averageLength = Object.fromEntries(SEARCH_FIELDS.map((field) => {
+        const lengths = docs
+            .map((doc) => doc.fields[field].length)
+            .filter((length) => length > 0);
+        return [
+            field,
+            lengths.reduce((sum, length) => sum + length, 0) / lengths.length || 1,
+        ];
+    }));
+    const idf = new Map([...queryTerms.keys()].map((term) => {
+        const frequency = docs.filter((doc) => SEARCH_FIELDS.some((field) => doc.fields[field].counts.has(term))).length;
         return [
             term,
             Math.log(1 + (docs.length - frequency + 0.5) / (frequency + 0.5)),
         ];
     }));
     const wholeQuery = query.trim().toLowerCase();
-    const phrase = queryTokens.length > 1 ? queryTokens.join(" ") : "";
-    return docs.flatMap((doc, index) => {
+    return docs.flatMap((doc) => {
         const { candidate } = doc;
         if (candidate.name.toLowerCase() === wholeQuery) {
             return [{ ...candidate, score: EXACT_NAME_SCORE }];
         }
-        const norm = BM25_K1 * (1 - BM25_B + (BM25_B * doc.terms.length) / averageLength);
         let score = 0;
-        for (const term of queryTokens) {
-            const count = counts[index].get(term);
-            if (!count)
+        for (const [term, queryWeight] of queryTerms) {
+            let weightedFrequency = 0;
+            for (const field of SEARCH_FIELDS) {
+                const count = doc.fields[field].counts.get(term);
+                if (!count)
+                    continue;
+                weightedFrequency +=
+                    (FIELD_WEIGHTS[field] * count) /
+                        (1 -
+                            BM25_B +
+                            (BM25_B * doc.fields[field].length) / averageLength[field]);
+            }
+            if (weightedFrequency === 0)
                 continue;
             score +=
-                (idf.get(term) ?? 0) * ((count * (BM25_K1 + 1)) / (count + norm));
+                queryWeight *
+                    (idf.get(term) ?? 0) *
+                    ((weightedFrequency * (BM25_K1 + 1)) / (weightedFrequency + BM25_K1));
         }
         if (score <= 0)
             return [];
-        if (phrase && tokenize(candidate.name).join(" ").includes(phrase)) {
+        if (queryTokens.length > 1 &&
+            containsTokenRun(tokenize(candidate.name), queryTokens)) {
             score += NAME_PHRASE_BONUS;
         }
+        score *= doc.prior;
         return [{ ...candidate, score: Math.round(score * 100) / 100 }];
     });
 }
+// Whole tokens in order, so "view email" never matches inside "preview-email"
+// and "archive email" never matches inside "unarchive-email".
+function containsTokenRun(tokens, run) {
+    for (let start = 0; start + run.length <= tokens.length; start++) {
+        if (run.every((token, offset) => tokens[start + offset] === token)) {
+            return true;
+        }
+    }
+    return false;
+}
 // Suggestions are never loaded, so a query with no exact term still points the
 // model at real names instead of an empty result.
 function suggestCloseTools(docs, queryTokens) {
@@ -589,8 +762,13 @@ function suggestCloseTools(docs, queryTokens) {
     if (prefixes.length === 0)
         return [];
     return docs
-        .map(({ candidate }) => {
-        const terms = tokenize(`${candidate.name} ${candidate.description}`);
+        .map(({ candidate, fields }) => {
+        const terms = [
+            ...fields.name.counts.keys(),
+            ...fields.hints.counts.keys(),
+            ...fields.summary.counts.keys(),
+            ...fields.details.counts.keys(),
+        ];
         const overlap = prefixes.filter((prefix) => terms.some((term) => term.startsWith(prefix))).length;
         return { candidate, overlap };
     })
@@ -603,45 +781,79 @@ function suggestCloseTools(docs, queryTokens) {
         description: truncate(candidate.description, MAX_SUGGESTION_DESCRIPTION_CHARS),
     }));
 }
-const STOP_WORDS = new Set([
-    "a",
-    "an",
-    "and",
-    "are",
-    "as",
-    "at",
-    "be",
-    "by",
-    "for",
-    "from",
-    "in",
-    "is",
-    "it",
-    "of",
-    "on",
-    "or",
-    "that",
-    "the",
-    "this",
-    "to",
-    "with",
-]);
+// Function words carry no capability, and conversational requests are full of
+// them ("can you show me what I have"). Indexed text drops them too, so a
+// description's "you can" never matches a request's.
+const STOP_WORDS = new Set(("a about after again also am an and any are as at be been before being " +
+    "but by can could did do does doing done for from had has have having " +
+    "he her here hers him his how i if in into is it its just let lets me " +
+    "mine my myself no not now of off on once only or our ours please she " +
+    "should so some such than thank thanks that the their theirs them then " +
+    "there these they this those to too up us very want was we were what " +
+    "when where which while who whom why will with would you your yours").split(" "));
+// Light, inflection-only stemming, the same on both sides of the match:
+// plurals, "-ed" and "-ing" (undoubling "running" to "run"), and a final
+// "-e", so "archived", "archiving" and "archive" meet at "archiv" and "saved"
+// meets "save". Full Porter stemming was measured on the benchmark and lost a
+// held-out case: it folds derivations together ("engineering" into "engine").
 function stem(term) {
-    if (term.length > 4 && term.endsWith("ies"))
-        return `${term.slice(0, -3)}y`;
-    if (term.length > 4 && /(ches|shes|sses|xes|zes)$/.test(term))
-        return term.slice(0, -2);
-    if (term.length > 3 && term.endsWith("s") && !term.endsWith("ss"))
-        return term.slice(0, -1);
-    return term;
+    const protectedTerm = PROTECTED_TERMS.get(term);
+    if (protectedTerm)
+        return protectedTerm;
+    let stemmed = term;
+    if (stemmed.length > 4 && stemmed.endsWith("ies")) {
+        stemmed = `${stemmed.slice(0, -3)}y`;
+    }
+    else if (stemmed.length > 4 && /(ches|shes|sses|xes|zes)$/.test(stemmed)) {
+        stemmed = stemmed.slice(0, -2);
+    }
+    else if (stemmed.length > 3 &&
+        stemmed.endsWith("s") &&
+        !/(ss|us|is)$/.test(stemmed)) {
+        stemmed = stemmed.slice(0, -1);
+    }
+    if (/^[aeiou][^aeiouy](?:ing|ed)$/u.test(stemmed)) {
+        // "using" and "used" lost the "e" of "use", as "owing" did of "owe".
+        stemmed = `${stemmed.slice(0, 2)}e`;
+    }
+    else if (stemmed.length > 5 && stemmed.endsWith("ing")) {
+        stemmed = undoubleFinalConsonant(stemmed.slice(0, -3));
+    }
+    else if (stemmed.length > 4 && stemmed.endsWith("ied")) {
+        stemmed = `${stemmed.slice(0, -3)}y`;
+    }
+    else if (stemmed.length > 4 && stemmed.endsWith("ed")) {
+        stemmed = undoubleFinalConsonant(stemmed.slice(0, -2));
+    }
+    if (stemmed.length >= 4 && stemmed.endsWith("e")) {
+        stemmed = stemmed.slice(0, -1);
+    }
+    return stemmed;
+}
+// "running" and "stopped" double the consonant before the suffix, so their
+// stems must drop it to meet "run" and "stop". Base words that end in a double
+// letter ("fill", "dress", "buzz", "stuff") keep it, as do stems that would
+// shrink to two letters ("adding" stays "add"). A long "-ell" stem is the
+// British doubling of "cancelled" and "labelled"; "spell" and "sell" are short.
+function undoubleFinalConsonant(stemmed) {
+    return (stemmed.length >= 4 && /([bcdgkmnprt])\1$/.test(stemmed)) ||
+        (stemmed.length >= 6 && stemmed.endsWith("ell"))
+        ? stemmed.slice(0, -1)
+        : stemmed;
 }
 function searchTerms(value) {
     return value
-        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
-        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
-        .toLowerCase()
-        .split(/[^a-z0-9]+/)
-        .filter((term) => term.length > 0 && !STOP_WORDS.has(term))
+        .split(/[^A-Za-z0-9]+/)
+        .flatMap((word) => {
+        const parts = word
+            .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+            .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+            .toLowerCase()
+            .split(" ");
+        // Users type "PowerPoint" and "HubSpot" as one word, too.
+        return parts.length > 1 ? [...parts, word.toLowerCase()] : parts;
+    })
+        .filter((term) => (term.length > 1 || /\d/.test(term)) && !STOP_WORDS.has(term))
         .map(stem);
 }
 function tokenize(value) {

package/dist/framework-package-versions.json

@@ -1,17 +1,17 @@
 {
-  "@agent-native/agentkit": "0.224.0",
+  "@agent-native/agentkit": "0.225.0-nightly-20261105110131",
   "@agent-native/code-agents-ui": "0.1.75",
-  "@agent-native/core": "0.224.0",
-  "@agent-native/core-corpus": "0.224.0",
+  "@agent-native/core": "0.225.0-nightly-20261105110131",
+  "@agent-native/core-corpus": "0.225.0-nightly-20261105110131",
   "@agent-native/creative-context": "0.8.65",
-  "@agent-native/dispatch": "0.42.0",
+  "@agent-native/dispatch": "0.42.1-nightly-20261105110131",
   "@agent-native/embedding": "0.2.0",
   "@agent-native/migrate": "0.0.7",
   "@agent-native/otel": "0.1.32",
   "@agent-native/pinpoint": "0.1.108",
   "@agent-native/recap-cli": "0.5.96",
-  "@agent-native/scheduling": "0.2.52",
+  "@agent-native/scheduling": "0.2.53-nightly-20261105110131",
   "@agent-native/shared-app-config": "0.1.2",
-  "@agent-native/skills": "0.4.0",
-  "@agent-native/toolkit": "0.224.0"
+  "@agent-native/skills": "0.4.1-nightly-20261105110131",
+  "@agent-native/toolkit": "0.225.0-nightly-20261105110131"
 }

package/dist/mcp-client/index.js

@@ -44,6 +44,27 @@ export function syncMcpActionEntries(manager, target, options = {}) {
         }
     }
 }
+/**
+ * The upstream server's hints, so `tool-search` marks a destructive tool
+ * whatever it is called. Hints the server leaves out take the MCP spec's
+ * defaults: "destructiveHint: If true, the tool may perform destructive
+ * updates to its environment. ... Default: true", meaningful only when the
+ * tool is not read-only. Our own actions do not get this default.
+ */
+function upstreamMcpAnnotations(tool) {
+    const hints = tool.annotations ?? {};
+    const readOnlyHint = hints.readOnlyHint === true;
+    return {
+        mcpAnnotations: {
+            readOnlyHint,
+            destructiveHint: !readOnlyHint && hints.destructiveHint !== false,
+            openWorldHint: hints.openWorldHint !== false,
+            ...(typeof hints.idempotentHint === "boolean"
+                ? { idempotentHint: hints.idempotentHint }
+                : {}),
+        },
+    };
+}
 function mcpToolToActionEntry(manager, tool, options = {}) {
     const { authorize, ...resolvedEntry } = options.resolveActionEntry?.(tool) ?? {};
     return {
@@ -58,6 +79,7 @@ function mcpToolToActionEntry(manager, tool, options = {}) {
             description: "Plan mode allows MCP calls classified as read-only from annotations, operation names, and runtime arguments.",
         },
         ...(tool.annotations?.readOnlyHint === true ? { readOnly: true } : {}),
+        ...upstreamMcpAnnotations(tool),
         ...resolvedEntry,
         run: async (args, context) => {
             // Defense-in-depth: even if a cross-scope MCP tool somehow makes it

package/dist/server/action-discovery.js

@@ -1,5 +1,6 @@
 import nodePath from "node:path";
 import "../authorization/check-action.js";
+import { isActionDefinitionError, namedActionDefinitionError, } from "../action.js";
 import { CORE_ACTION_GROUPS } from "../framework-tools.js";
 import { frameworkMcpTool } from "../mcp/framework-tools.js";
 import { normalizeShellArgs, serializeCliArgs } from "../scripts/parse-args.js";
@@ -167,7 +168,7 @@ async function loadActionsIntoRegistry(actionsDir, registry, skipExisting) {
                     tool: mod.tool,
                     run: mod.run,
                     ...(mod.http !== undefined ? { http: mod.http } : {}),
-                    ...preserveActionFlags(mod),
+                    ...preserveActionFlags(mod, name),
                 };
             }
             else if (mod.default &&
@@ -178,7 +179,7 @@ async function loadActionsIntoRegistry(actionsDir, registry, skipExisting) {
                     tool: mod.default.tool,
                     run: mod.default.run,
                     ...(mod.default.http !== undefined ? { http: mod.default.http } : {}),
-                    ...preserveActionFlags(mod.default),
+                    ...preserveActionFlags(mod.default, name),
                 };
             }
             else if (typeof mod.default === "function") {
@@ -186,6 +187,11 @@ async function loadActionsIntoRegistry(actionsDir, registry, skipExisting) {
             }
         }
         catch (err) {
+            // A module that imports but defines its action wrongly is a bug in the
+            // action, not a CLI script: fail the load instead of skipping it.
+            if (isActionDefinitionError(err)) {
+                throw namedActionDefinitionError(err, name);
+            }
             const msg = err instanceof Error ? (err.stack ?? err.message) : String(err);
             console.warn(`[action-discovery] Skipped "${file}" — failed to import. If this is an ` +
                 `agent action (not a CLI script), it will be missing from the agent's tools:\n${msg}`);
@@ -203,7 +209,7 @@ export function loadActionsFromStaticRegistry(modules) {
                 tool: mod.tool,
                 run: mod.run,
                 ...(mod.http !== undefined ? { http: mod.http } : {}),
-                ...preserveActionFlags(mod),
+                ...preserveActionFlags(mod, name),
             };
             continue;
         }
@@ -216,7 +222,7 @@ export function loadActionsFromStaticRegistry(modules) {
                 tool: def.tool,
                 run: def.run,
                 ...(def.http !== undefined ? { http: def.http } : {}),
-                ...preserveActionFlags(def),
+                ...preserveActionFlags(def, name),
             };
             continue;
         }
@@ -233,6 +239,8 @@ export async function autoDiscoverActions(from) {
         await loadActionsIntoRegistry(actionsDir, registry, false);
     }
     catch (err) {
+        if (isActionDefinitionError(err))
+            throw err;
         console.warn(`[autoDiscoverActions] Could not read actions directory: ${actionsDir} — ${err?.message}`);
     }
     if (Object.keys(registry).length === 0 && from) {
@@ -253,7 +261,11 @@ export async function autoDiscoverActions(from) {
                     `Consider switching to loadActionsFromStaticRegistry(actionsRegistry) for production reliability.`);
             }
         }
-        catch {
+        catch (error) {
+            // An action in the registry that defines itself wrongly is not "no
+            // registry": the app would boot with no template tools at all.
+            if (isActionDefinitionError(error))
+                throw error;
             // No generated registry available — registry stays empty.
         }
     }
@@ -271,13 +283,17 @@ export async function autoDiscoverActions(from) {
             await loadActionsIntoRegistry(ws.actionsDir, registry, true);
         }
     }
-    catch {
+    catch (error) {
+        if (isActionDefinitionError(error))
+            throw error;
         // workspace-core discovery unavailable (e.g. edge runtime) — skip.
     }
     try {
         await mergeCoreSharingActions(registry);
     }
-    catch {
+    catch (error) {
+        if (isActionDefinitionError(error))
+            throw error;
         // Ignore — templates without sharing still work.
     }
     return registry;
@@ -882,14 +898,17 @@ export async function mergeCoreSharingActions(registry) {
                     // mcpApp) plus readOnly/parallelSafe/dedupe. Without this, the sharing
                     // actions' `toolCallable: false` (audit-H5) is dropped and the
                     // tools-iframe bridge 403 in action-routes.ts never fires.
-                    ...preserveActionFlags(def),
+                    ...preserveActionFlags(def, name),
                     ...(CORE_ACTION_GROUPS[name]
                         ? { frameworkGroup: CORE_ACTION_GROUPS[name] }
                         : {}),
                 });
             }
         }
-        catch {
+        catch (error) {
+            if (isActionDefinitionError(error)) {
+                throw namedActionDefinitionError(error, name);
+            }
             // Skip any sharing action that fails to import.
         }
     }

package/dist/server/agent-chat-plugin.js

@@ -8,6 +8,7 @@ import { hasConfiguredA2ASecret, isLoopbackAddress, isTrustedLocalRuntime, } fro
 import { sanitizeA2ACorrelationId, sanitizeA2ACorrelationMetadata, } from "../a2a/correlation.js";
 import { a2aFilePartsToAttachments } from "../a2a/file-attachments.js";
 import { createA2AApproval, a2aTaskLeaseThreadId, A2A_TASK_CLAIM_LOST_ERROR_CODE, updateTaskStatusMessage, } from "../a2a/task-store.js";
+import { ActionDefinitionError, isActionDefinitionError } from "../action.js";
 import { clientAbortReason, EXECUTION_LEASE_LOST_ABORT_REASON, } from "../agent/abort-reasons.js";
 import { canUpdateAgentAppModelDefaultSettings, normalizeAgentAppModelDefaultAppId, readAgentAppModelDefaultSettings, resetAgentAppModelDefaultSettings, writeAgentAppModelDefaultSettings, } from "../agent/app-model-defaults.js";
 import { approvalKeyWithArguments } from "../agent/approval-key.js";
@@ -77,7 +78,7 @@ import { AGENT_TEAM_PROCESS_RUN_PATH, getCurrentDelegationDepth, processAgentTea
 import { getSession, isLoopbackRequest, registerAuthPublicPaths, } from "./auth.js";
 import { captureError } from "./capture-error.js";
 import { chatTitleRequestFromBody, generateChatTitle } from "./chat-title.js";
-import { actionDefinition, discoveredActionMcpAnnotations, filesystemActionEntry, } from "./filesystem-action-entry.js";
+import { discoveredActionMcpAnnotations, importDevActionEntry, } from "./filesystem-action-entry.js";
 import { getH3App, markDefaultPluginProvided, trackPluginInit, } from "./framework-request-handler.js";
 import { publicFrameworkPath } from "./framework-route-prefix.js";
 import { getOrigin } from "./google-oauth.js";
@@ -1078,7 +1079,9 @@ export function createAgentChatPlugin(options) {
                     const { autoDiscoverActions } = await import("./action-discovery.js");
                     templateScriptsAll = await autoDiscoverActions("auto");
                 }
-                catch {
+                catch (error) {
+                    if (isActionDefinitionError(error))
+                        throw error;
                     // Filesystem discovery unavailable (serverless bundle) — skip.
                 }
             }
@@ -1169,6 +1172,7 @@ export function createAgentChatPlugin(options) {
                 // Auto-discover template action files and register as bash-based tools.
                 // This ensures templates without a custom agent-chat plugin (e.g., analytics)
                 // still have their domain actions available as tools.
+                const definitionErrors = [];
                 try {
                     const pathMod = await import("path");
                     const cwd = process.cwd();
@@ -1184,17 +1188,22 @@ export function createAgentChatPlugin(options) {
                             // run function (not a shell wrapper). This makes HTTP endpoints
                             // work correctly. Only fall back to shell wrapper if the import
                             // fails (e.g., CLI-style scripts that throw at top level).
+                            // A definition error is rethrown below, past the catch that
+                            // skips unreadable discovery, so it fails the load instead.
                             try {
-                                const mod = await import(/* @vite-ignore */ filePath);
-                                const def = actionDefinition(mod);
-                                if (def) {
-                                    discoveredActionsAll[name] = filesystemActionEntry(def);
+                                const entry = await importDevActionEntry(filePath, name);
+                                if (entry) {
+                                    discoveredActionsAll[name] = entry;
                                     continue;
                                 }
                             }
-                            catch {
-                                // Fall through to shell wrapper for CLI-style scripts
-                                // (and .ts files Node can't parse natively).
+                            catch (error) {
+                                if (isActionDefinitionError(error)) {
+                                    definitionErrors.push(error);
+                                    continue;
+                                }
+                                // Anything else falls through to the shell wrapper, as an
+                                // unimportable CLI script does.
                             }
                             // Static-parse the source for `http`, `agentTool: false`,
                             // `needsApproval`, `persistInBrowser`, `uiOnly` and
@@ -1290,6 +1299,9 @@ export function createAgentChatPlugin(options) {
                         console.log(`[agent-chat] Auto-discovered ${Object.keys(discoveredActionsAll).length} action(s): ${Object.keys(discoveredActionsAll).join(", ")}`);
                 }
                 catch { }
+                if (definitionErrors.length > 0) {
+                    throw new ActionDefinitionError(definitionErrors.map((error) => error.message).join("\n"));
+                }
             }
             // Agent-facing views of the discovered actions: actions that opted out of
             // agent exposure with `agentTool: false` are dropped from every tool

package/dist/server/filesystem-action-entry.d.ts

@@ -14,7 +14,7 @@ export declare function discoveredActionMcpAnnotations(readOnly: boolean): Reado
  * validates, asks for approval, and checks access the same way however it was
  * loaded. Each flag is kept only when its value has the right shape.
  */
-export declare function preserveActionFlags(entry: Record<string, unknown>): Partial<ActionEntry>;
+export declare function preserveActionFlags(entry: Record<string, unknown>, actionName?: string): Partial<ActionEntry>;
 /**
  * The object a loaded action module defines its action on. Named `tool` and
  * `run` exports come first, as the built registry and the directory loader
@@ -28,3 +28,11 @@ export declare function actionDefinition(mod: Record<string, unknown>): Record<s
  * annotations when the module declares no valid ones.
  */
 export declare function filesystemActionEntry(def: Record<string, any>): ActionEntry;
+/**
+ * The real entry for a dev action file, or `null` when the file should run as
+ * a CLI-script wrapper: it does not import (top-level CLI code, syntax Node
+ * cannot parse) or defines no action. A file that imports but defines its
+ * action wrongly throws an `ActionDefinitionError` naming it instead, so an
+ * invalid definition never silently changes how the action runs.
+ */
+export declare function importDevActionEntry(filePath: string, actionName: string): Promise<ActionEntry | null>;

package/dist/server/filesystem-action-entry.js

@@ -1,5 +1,5 @@
 import { isMcpReadOnlyTool } from "../action-call-classification.js";
-import { ACTION_EXECUTION_KEY } from "../action.js";
+import { ACTION_EXECUTION_KEY, isActionDefinitionError, namedActionDefinitionError, validateSearchHints, } from "../action.js";
 import { carryFrameworkMcpTool } from "../mcp/framework-tools.js";
 // Without the key an app wrapper around `run` cannot be recognized as the same
 // action, and every validation failure reads as an unknown write.
@@ -44,7 +44,7 @@ function isMcpAnnotations(value) {
  * validates, asks for approval, and checks access the same way however it was
  * loaded. Each flag is kept only when its value has the right shape.
  */
-export function preserveActionFlags(entry) {
+export function preserveActionFlags(entry, actionName) {
     const out = {};
     carryFrameworkMcpTool(entry, out);
     if (entry.schema &&
@@ -73,6 +73,11 @@ export function preserveActionFlags(entry) {
     if (typeof entry.deferLoading === "boolean") {
         out.deferLoading = entry.deferLoading;
     }
+    // Not dropped like the flags above: a malformed list would silently leave
+    // the action harder to find, so loading it fails instead.
+    const searchHints = validateSearchHints(entry.searchHints, actionName);
+    if (searchHints)
+        out.searchHints = searchHints;
     if (typeof entry.eagerInputStreaming === "boolean") {
         out.eagerInputStreaming = entry.eagerInputStreaming;
     }
@@ -204,3 +209,22 @@ export function filesystemActionEntry(def) {
     carryExecutionKey(def, out);
     return out;
 }
+/**
+ * The real entry for a dev action file, or `null` when the file should run as
+ * a CLI-script wrapper: it does not import (top-level CLI code, syntax Node
+ * cannot parse) or defines no action. A file that imports but defines its
+ * action wrongly throws an `ActionDefinitionError` naming it instead, so an
+ * invalid definition never silently changes how the action runs.
+ */
+export async function importDevActionEntry(filePath, actionName) {
+    try {
+        const def = actionDefinition(await import(/* @vite-ignore */ filePath));
+        return def ? filesystemActionEntry(def) : null;
+    }
+    catch (error) {
+        if (isActionDefinitionError(error)) {
+            throw namedActionDefinitionError(error, actionName);
+        }
+        return null;
+    }
+}

package/dist/server/prompts/framework-core-compact.js

@@ -66,7 +66,7 @@ ${sharedRule8(examples, options)}
 ${SHARED_RULE_9}
 10. **Native widgets** — For table/chart/graph/report requests, prefer actions labeled \`Native chat widget\`; use \`render-data-widget\` for already-summarized data (≤50 rows) instead of markdown tables. Above that, give the total plus the top rows — never retype a full result set as widget arguments.
 11. **Downloadable files** — Deliver files in chat, never just a path.
-12. **Your tool list is not the whole surface** — Most app actions and connected MCP tools load on demand; find exact names via the Tool index or search the registry with \`tool-search\` before concluding a capability doesn't exist.
+12. **Your tool list is not the whole surface** — Most app actions and connected MCP tools load on demand; find names in the Tool index or search \`tool-search\` for the task in plain words before concluding a capability doesn't exist.
 ${sharedRule13(options)}
 ${SHARED_RULE_14}
 ${SHARED_RULE_15}

package/dist/server/prompts/framework-core.js

@@ -95,7 +95,7 @@ ${SHARED_RULE_9}
 ${ATTACHMENT_READ_RULE}
 10. **Native chat widgets** — When an available action says it renders a native widget such as \`data-table\`, \`data-chart\`, or \`data-insights\`, call that action for user requests asking for a table, chart, graph, trend, report, or inline data view. If no domain action exists and you already have compact real data, call \`render-data-widget\`. Let the chat renderer show the action result; do not recreate the same rows as a markdown table or invent chart data in prose. Add only a short human summary or next-step link around the widget. Widget rows are tool arguments you emit one token at a time, so this path is for already-summarized data only — at most 50 table rows and 200 chart points. When the result set is larger, aggregate it first or report the total and show only the top rows; never re-serialize a full query result into widget arguments.
 11. **Downloadable files** — When the user asks you to create or export a file, deliver it in the same chat turn. For compact tabular results, prefer \`render-data-widget\` so the user gets the native Download CSV action without a second stored copy. For a complete or durable file written through \`workspaceWrite\`, use a normal non-\`scratch/\` path and then call \`show-workspace-file\` with that path so chat renders a direct download card. Never finish by giving filesystem paths or telling the user to navigate elsewhere to find the file.
-12. **Your tool list is not the whole surface** — Most app actions and connected MCP tools load on demand; find exact names via the Tool index or search the registry with \`tool-search\` before concluding a capability doesn't exist.
+12. **Your tool list is not the whole surface** — Most app actions and connected MCP tools load on demand; find names in the Tool index or search \`tool-search\` for the task in plain words before concluding a capability doesn't exist.
 ${sharedRule13(options)}
 ${SHARED_RULE_14}
 ${SHARED_RULE_15}

package/dist/templates/chat/.agents/skills/actions/SKILL.md

@@ -66,7 +66,7 @@ Every agent-exposed action is a tool in the model's context window; more tools d
 
 ## Key Actions — One Index, Every Surface
 
-Document the app's primary actions in the `AGENTS.md` action table. For first-turn loading, add those action names to the plugin's `initialToolNames` (`INITIAL_TOOL_NAMES` in some templates), or mark the full starter set `deferLoading: false` on the actions. When one action opts into per-action eager loading, unmarked actions are deferred; the remaining actions stay discoverable through `tool-search`.
+Document the app's primary actions in the `AGENTS.md` action table. For first-turn loading, add those action names to the plugin's `initialToolNames` (`INITIAL_TOOL_NAMES` in some templates), or mark the full starter set `deferLoading: false` on the actions. When one action opts into per-action eager loading, unmarked actions are deferred; the remaining actions stay discoverable through `tool-search`. When users name an action's job in words its name and description lack ("auto-archive rule", "canned reply"), add those words as `searchHints`: `tool-search` ranks them just below the name and never shows them to the model.
 
 When MCP is enabled, its `Key tools` line is generated from `mcp.keyToolNames ?? initialToolNames` and filtered to the actions served on that surface. A configured `mcp.keyToolNames` overrides the advertised MCP/WebMCP key list; it does not change the in-app agent's first-turn list. Keep the advertised subset consistent with the primary actions in the `AGENTS.md` table and the external catalog; the table may also document other in-app actions. Do not hand-write another action list in `mcp.instructions`, a skill, or an external skill; describe when to use actions there.
 

package/dist/templates/default/.agents/skills/actions/SKILL.md

@@ -66,7 +66,7 @@ Every agent-exposed action is a tool in the model's context window; more tools d
 
 ## Key Actions — One Index, Every Surface
 
-Document the app's primary actions in the `AGENTS.md` action table. For first-turn loading, add those action names to the plugin's `initialToolNames` (`INITIAL_TOOL_NAMES` in some templates), or mark the full starter set `deferLoading: false` on the actions. When one action opts into per-action eager loading, unmarked actions are deferred; the remaining actions stay discoverable through `tool-search`.
+Document the app's primary actions in the `AGENTS.md` action table. For first-turn loading, add those action names to the plugin's `initialToolNames` (`INITIAL_TOOL_NAMES` in some templates), or mark the full starter set `deferLoading: false` on the actions. When one action opts into per-action eager loading, unmarked actions are deferred; the remaining actions stay discoverable through `tool-search`. When users name an action's job in words its name and description lack ("auto-archive rule", "canned reply"), add those words as `searchHints`: `tool-search` ranks them just below the name and never shows them to the model.
 
 When MCP is enabled, its `Key tools` line is generated from `mcp.keyToolNames ?? initialToolNames` and filtered to the actions served on that surface. A configured `mcp.keyToolNames` overrides the advertised MCP/WebMCP key list; it does not change the in-app agent's first-turn list. Keep the advertised subset consistent with the primary actions in the `AGENTS.md` table and the external catalog; the table may also document other in-app actions. Do not hand-write another action list in `mcp.instructions`, a skill, or an external skill; describe when to use actions there.
 

package/dist/templates/headless/.agents/skills/actions/SKILL.md

@@ -66,7 +66,7 @@ Every agent-exposed action is a tool in the model's context window; more tools d
 
 ## Key Actions — One Index, Every Surface
 
-Document the app's primary actions in the `AGENTS.md` action table. For first-turn loading, add those action names to the plugin's `initialToolNames` (`INITIAL_TOOL_NAMES` in some templates), or mark the full starter set `deferLoading: false` on the actions. When one action opts into per-action eager loading, unmarked actions are deferred; the remaining actions stay discoverable through `tool-search`.
+Document the app's primary actions in the `AGENTS.md` action table. For first-turn loading, add those action names to the plugin's `initialToolNames` (`INITIAL_TOOL_NAMES` in some templates), or mark the full starter set `deferLoading: false` on the actions. When one action opts into per-action eager loading, unmarked actions are deferred; the remaining actions stay discoverable through `tool-search`. When users name an action's job in words its name and description lack ("auto-archive rule", "canned reply"), add those words as `searchHints`: `tool-search` ranks them just below the name and never shows them to the model.
 
 When MCP is enabled, its `Key tools` line is generated from `mcp.keyToolNames ?? initialToolNames` and filtered to the actions served on that surface. A configured `mcp.keyToolNames` overrides the advertised MCP/WebMCP key list; it does not change the in-app agent's first-turn list. Keep the advertised subset consistent with the primary actions in the `AGENTS.md` table and the external catalog; the table may also document other in-app actions. Do not hand-write another action list in `mcp.instructions`, a skill, or an external skill; describe when to use actions there.
 

package/dist/templates/workspace-core/.agents/skills/actions/SKILL.md

@@ -66,7 +66,7 @@ Every agent-exposed action is a tool in the model's context window; more tools d
 
 ## Key Actions — One Index, Every Surface
 
-Document the app's primary actions in the `AGENTS.md` action table. For first-turn loading, add those action names to the plugin's `initialToolNames` (`INITIAL_TOOL_NAMES` in some templates), or mark the full starter set `deferLoading: false` on the actions. When one action opts into per-action eager loading, unmarked actions are deferred; the remaining actions stay discoverable through `tool-search`.
+Document the app's primary actions in the `AGENTS.md` action table. For first-turn loading, add those action names to the plugin's `initialToolNames` (`INITIAL_TOOL_NAMES` in some templates), or mark the full starter set `deferLoading: false` on the actions. When one action opts into per-action eager loading, unmarked actions are deferred; the remaining actions stay discoverable through `tool-search`. When users name an action's job in words its name and description lack ("auto-archive rule", "canned reply"), add those words as `searchHints`: `tool-search` ranks them just below the name and never shows them to the model.
 
 When MCP is enabled, its `Key tools` line is generated from `mcp.keyToolNames ?? initialToolNames` and filtered to the actions served on that surface. A configured `mcp.keyToolNames` overrides the advertised MCP/WebMCP key list; it does not change the in-app agent's first-turn list. Keep the advertised subset consistent with the primary actions in the `AGENTS.md` table and the external catalog; the table may also document other in-app actions. Do not hand-write another action list in `mcp.instructions`, a skill, or an external skill; describe when to use actions there.
 

package/docs/content/actions-defining.mdx

@@ -446,6 +446,7 @@ Every action the agent can see takes up a slot in the model's tool list, and a l
 - Before adding a new read action for every query or filter, consider a more general option first: the [provider API trio](/docs/template-dispatch-developers#calling-a-provider-directly) (`provider-api-catalog`, `provider-api-docs`, and `provider-api-request`) for provider data, or the dev `db-query` tool for app data.
 - Mark UI-only or programmatic actions [`agentTool: false`](/docs/actions-access-control#agent-tool). They stay callable from the frontend or over HTTP, without taking a slot in the model's tool list.
 - Mark the handful of actions the agent reaches for constantly `deferLoading: false`. Those are the schemas sent on the first model request; everything else loads on demand through `tool-search` when the agent needs it. As soon as one action opts out this way, every unmarked action is deferred, so mark the whole starter set at once rather than one action at a time. This is about what the first turn costs, not about access: a deferred action is callable the moment `tool-search` returns it. Deferred actions still appear by name in the prompt's tool index, grouped by the noun after the leading verb, so `verb-noun` names such as `list-dashboards` and `create-dashboard` are what let the agent find them. It is the per-action form of the plugin's `initialToolNames` array, and an app can use either.
+- Give an action `searchHints` when users call its job something its name and description do not, such as `["auto-archive rule", "inbox rule"]` on an inbox-rules action. `tool-search` ranks these words just below the name, and they are never sent to the model, so they cost no context. Keep them short and factual (at most 12, each up to 60 characters), not a list of every request the action might serve.
 - Delete or hide actions the UI no longer uses, instead of leaving them exposed to the model.
 
 The repo includes an advisory helper, `node scripts/audit-template-actions.mjs [template ...]` (alias `pnpm actions:audit`). It scans a template's `actions/` folder and flags actions the UI may no longer use, along with groups of per-field actions that could be combined into one. It always exits with code 0 and never fails CI, and its heuristics are conservative, so treat its output as a suggestion, not an error.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.224.0",
+  "version": "0.225.0-nightly-20261105110131",
   "description": "The agentic application framework for building autonomous agents with intuitive UIs",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {
@@ -760,8 +760,8 @@
     "yaml": "^2.9.0",
     "yjs": "^13.6.33",
     "zod": "^4.3.6",
-    "@agent-native/recap-cli": "^0.5.96",
-    "@agent-native/agentkit": "^0.224.0"
+    "@agent-native/agentkit": "^0.225.0-nightly-20261105110131",
+    "@agent-native/recap-cli": "^0.5.96"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.71",
@@ -833,7 +833,7 @@
     "xlsx": "^0.18.5"
   },
   "peerDependencies": {
-    "@agent-native/core-corpus": ">=0.196.0",
+    "@agent-native/core-corpus": "0.225.0-nightly-20261105110131",
     "@ai-sdk/anthropic": ">=3",
     "@ai-sdk/cohere": ">=3",
     "@ai-sdk/google": ">=3",

package/src/templates/chat/.agents/skills/actions/SKILL.md

@@ -66,7 +66,7 @@ Every agent-exposed action is a tool in the model's context window; more tools d
 
 ## Key Actions — One Index, Every Surface
 
-Document the app's primary actions in the `AGENTS.md` action table. For first-turn loading, add those action names to the plugin's `initialToolNames` (`INITIAL_TOOL_NAMES` in some templates), or mark the full starter set `deferLoading: false` on the actions. When one action opts into per-action eager loading, unmarked actions are deferred; the remaining actions stay discoverable through `tool-search`.
+Document the app's primary actions in the `AGENTS.md` action table. For first-turn loading, add those action names to the plugin's `initialToolNames` (`INITIAL_TOOL_NAMES` in some templates), or mark the full starter set `deferLoading: false` on the actions. When one action opts into per-action eager loading, unmarked actions are deferred; the remaining actions stay discoverable through `tool-search`. When users name an action's job in words its name and description lack ("auto-archive rule", "canned reply"), add those words as `searchHints`: `tool-search` ranks them just below the name and never shows them to the model.
 
 When MCP is enabled, its `Key tools` line is generated from `mcp.keyToolNames ?? initialToolNames` and filtered to the actions served on that surface. A configured `mcp.keyToolNames` overrides the advertised MCP/WebMCP key list; it does not change the in-app agent's first-turn list. Keep the advertised subset consistent with the primary actions in the `AGENTS.md` table and the external catalog; the table may also document other in-app actions. Do not hand-write another action list in `mcp.instructions`, a skill, or an external skill; describe when to use actions there.
 

package/src/templates/default/.agents/skills/actions/SKILL.md

@@ -66,7 +66,7 @@ Every agent-exposed action is a tool in the model's context window; more tools d
 
 ## Key Actions — One Index, Every Surface
 
-Document the app's primary actions in the `AGENTS.md` action table. For first-turn loading, add those action names to the plugin's `initialToolNames` (`INITIAL_TOOL_NAMES` in some templates), or mark the full starter set `deferLoading: false` on the actions. When one action opts into per-action eager loading, unmarked actions are deferred; the remaining actions stay discoverable through `tool-search`.
+Document the app's primary actions in the `AGENTS.md` action table. For first-turn loading, add those action names to the plugin's `initialToolNames` (`INITIAL_TOOL_NAMES` in some templates), or mark the full starter set `deferLoading: false` on the actions. When one action opts into per-action eager loading, unmarked actions are deferred; the remaining actions stay discoverable through `tool-search`. When users name an action's job in words its name and description lack ("auto-archive rule", "canned reply"), add those words as `searchHints`: `tool-search` ranks them just below the name and never shows them to the model.
 
 When MCP is enabled, its `Key tools` line is generated from `mcp.keyToolNames ?? initialToolNames` and filtered to the actions served on that surface. A configured `mcp.keyToolNames` overrides the advertised MCP/WebMCP key list; it does not change the in-app agent's first-turn list. Keep the advertised subset consistent with the primary actions in the `AGENTS.md` table and the external catalog; the table may also document other in-app actions. Do not hand-write another action list in `mcp.instructions`, a skill, or an external skill; describe when to use actions there.
 

package/src/templates/headless/.agents/skills/actions/SKILL.md

@@ -66,7 +66,7 @@ Every agent-exposed action is a tool in the model's context window; more tools d
 
 ## Key Actions — One Index, Every Surface
 
-Document the app's primary actions in the `AGENTS.md` action table. For first-turn loading, add those action names to the plugin's `initialToolNames` (`INITIAL_TOOL_NAMES` in some templates), or mark the full starter set `deferLoading: false` on the actions. When one action opts into per-action eager loading, unmarked actions are deferred; the remaining actions stay discoverable through `tool-search`.
+Document the app's primary actions in the `AGENTS.md` action table. For first-turn loading, add those action names to the plugin's `initialToolNames` (`INITIAL_TOOL_NAMES` in some templates), or mark the full starter set `deferLoading: false` on the actions. When one action opts into per-action eager loading, unmarked actions are deferred; the remaining actions stay discoverable through `tool-search`. When users name an action's job in words its name and description lack ("auto-archive rule", "canned reply"), add those words as `searchHints`: `tool-search` ranks them just below the name and never shows them to the model.
 
 When MCP is enabled, its `Key tools` line is generated from `mcp.keyToolNames ?? initialToolNames` and filtered to the actions served on that surface. A configured `mcp.keyToolNames` overrides the advertised MCP/WebMCP key list; it does not change the in-app agent's first-turn list. Keep the advertised subset consistent with the primary actions in the `AGENTS.md` table and the external catalog; the table may also document other in-app actions. Do not hand-write another action list in `mcp.instructions`, a skill, or an external skill; describe when to use actions there.
 

package/src/templates/workspace-core/.agents/skills/actions/SKILL.md

@@ -66,7 +66,7 @@ Every agent-exposed action is a tool in the model's context window; more tools d
 
 ## Key Actions — One Index, Every Surface
 
-Document the app's primary actions in the `AGENTS.md` action table. For first-turn loading, add those action names to the plugin's `initialToolNames` (`INITIAL_TOOL_NAMES` in some templates), or mark the full starter set `deferLoading: false` on the actions. When one action opts into per-action eager loading, unmarked actions are deferred; the remaining actions stay discoverable through `tool-search`.
+Document the app's primary actions in the `AGENTS.md` action table. For first-turn loading, add those action names to the plugin's `initialToolNames` (`INITIAL_TOOL_NAMES` in some templates), or mark the full starter set `deferLoading: false` on the actions. When one action opts into per-action eager loading, unmarked actions are deferred; the remaining actions stay discoverable through `tool-search`. When users name an action's job in words its name and description lack ("auto-archive rule", "canned reply"), add those words as `searchHints`: `tool-search` ranks them just below the name and never shows them to the model.
 
 When MCP is enabled, its `Key tools` line is generated from `mcp.keyToolNames ?? initialToolNames` and filtered to the actions served on that surface. A configured `mcp.keyToolNames` overrides the advertised MCP/WebMCP key list; it does not change the in-app agent's first-turn list. Keep the advertised subset consistent with the primary actions in the `AGENTS.md` table and the external catalog; the table may also document other in-app actions. Do not hand-write another action list in `mcp.instructions`, a skill, or an external skill; describe when to use actions there.