fix(appkit): tool() name optional, execute returns unknown, docs accurate

Address two P0 findings from the PR #306 agentic review.

1. tool() runtime crash on the template

   `npx @databricks/appkit init` produces a helper agent whose tools
   call `tool({ description, schema, execute })` with no `name` field
   (because the record key — `current_time`, `count_words` — already
   names the tool). The previous shape required `name: string`, so
   `isFunctionTool` rejected the returned FunctionTool and agent
   registration failed with "Agent 'helper' tool 'current_time' has
   an unrecognized shape" — the very first `pnpm dev` after init.

   Make `name` optional on both ToolConfig and FunctionTool, drop the
   `typeof obj.name === "string"` check from `isFunctionTool`, and
   widen `execute` from `Promise<string> | string` to `unknown |
   Promise<unknown>` since the template's tools naturally return
   objects (`{ now: ... }`). The agents plugin already overrides
   `name` with the record key at index-build time, so the original
   field was functionally redundant in keyed-record contexts. Zod
   error messages fall back to a generic "tool" label when the name
   is omitted.

   Downstream: agents plugin already normalises non-string results
   via `normalizeToolResult`; DatabricksAdapter already `JSON.stringify`s
   non-string returns at line 438-439. No further changes needed.

2. Level 1 docs lied about auto-inherit

   `docs/docs/plugins/agents.md` Level 1 said "auto-inherits every
   registered ToolProvider plugin's tools" but the Configuration
   Reference correctly states `autoInheritTools` defaults to
   `{ file: false, code: false }`. New users following Level 1 hit
   zero tools and confusion.

   Rewrite Level 1 narrative to be truthful: "The agent starts with
   no tools. Tools are opt-in — declare them in frontmatter (Level 2)
   or opt into auto-inherit explicitly with `agents({
   autoInheritTools: { file: true } })`. See 'Auto-inherit posture'
   below."

   Same doc still had stale `fromPlugin(...)` examples in Level 3 +
   the standalone runAgent section. Rewritten to use the
   `tools(plugins) => ...` function form that v5 actually ships,
   matching the rest of the codebase. The runAgent section also gets
   a sentence on the new init contract (eager attachContext + setup,
   shared cache across sub-agents) and the trust-boundary caveat (no
   OBO, no approval gate).

Tests: +3 covering the new shape — name optional, non-string
returns, zod-error fallback label. Updated the "returns false when
name is missing" guard test to assert the new "returns true" since
the record key wins.

Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>

Author: MarioCadenas

docs/docs/api/appkit/Interface.FunctionTool.md

@@ -28,9 +28,12 @@ optional description: string | null;
 ### execute()
 
 ```ts
-execute: (args: Record<string, unknown>) => string | Promise<string>;
+execute: (args: Record<string, unknown>) => unknown;
 ```
 
+Returns any shape; downstream `normalizeToolResult` serializes to a
+string before handing the value to the LLM.
+
 #### Parameters
 
 | Parameter | Type |
@@ -39,16 +42,22 @@ execute: (args: Record<string, unknown>) => string | Promise<string>;
 
 #### Returns
 
-`string` \| `Promise`\<`string`\>
+`unknown`
 
 ***
 
-### name
+### name?
 
 ```ts
-name: string;
+optional name: string;
 ```
 
+Optional. When this tool is placed in a keyed record
+(`tools: { my_tool: ... }` or the function form), the agents plugin
+overrides this with the record key at index-build time. Only set it
+explicitly when constructing a `FunctionTool` outside any
+keyed-record context.
+
 ***
 
 ### parameters?

docs/docs/api/appkit/Interface.ToolConfig.md

@@ -34,9 +34,16 @@ optional description: string;
 ### execute()
 
 ```ts
-execute: (args: output<S>) => string | Promise<string>;
+execute: (args: output<S>) => unknown;
 ```
 
+Returning a non-string value is fine: the agent runtime serializes
+the result via `normalizeToolResult` before handing it to the LLM
+(strings pass through; `null` becomes `"null"`; everything else gets
+`JSON.stringify`'d; `undefined` becomes `""`). Return whatever shape
+is most natural for your tool — typically an object — and let the
+runtime handle the wire format.
+
 #### Parameters
 
 | Parameter | Type |
@@ -45,16 +52,23 @@ execute: (args: output<S>) => string | Promise<string>;
 
 #### Returns
 
-`string` \| `Promise`\<`string`\>
+`unknown`
 
 ***
 
-### name
+### name?
 
 ```ts
-name: string;
+optional name: string;
 ```
 
+Optional. When the tool is placed in a keyed record (the standard
+`tools: { my_tool: tool({...}) }` form, or the function form
+`tools(plugins) => ({ my_tool: tool({...}) })`), the agents plugin
+overrides the tool's LLM-visible name with the record key. Set
+`name` explicitly only if you're constructing a `FunctionTool`
+outside any keyed-record context — otherwise the record key wins.
+
 ***
 
 ### schema

docs/docs/plugins/agents.md

@@ -54,8 +54,9 @@ On startup the plugin:
 1. Discovers `./config/agents/assistant/agent.md` and registers agent id `assistant`.
 2. Parses the YAML frontmatter and markdown body as the agent's `instructions`.
 3. Resolves the adapter from `endpoint` (or falls back to `DATABRICKS_AGENT_ENDPOINT`).
-4. Auto-inherits every registered ToolProvider plugin's tools (`analytics.*`, `files.*`, …).
-5. Mounts the agent at the default name (`assistant`).
+4. Mounts the agent at the default name (`assistant`).
+
+The agent starts with **no tools**. Tools are opt-in — declare them in frontmatter (Level 2 below) or opt into auto-inherit explicitly with `agents({ autoInheritTools: { file: true } })`. See "Auto-inherit posture" further down for what that costs and why it's off by default.
 
 Requests land at `POST /invocations` with an OpenAI Responses-compatible body. Every tool call runs through `asUser(req)` so SQL executes as the requesting user, file access respects Unity Catalog ACLs, and telemetry spans are created automatically.
 
@@ -87,30 +88,23 @@ When any `tools:` is declared the auto-inherit default is turned off — the age
 ## Level 3: code-defined agents
 
 ```ts
-import {
-  agents,
-  analytics,
-  createAgent,
-  createApp,
-  files,
-  fromPlugin,
-  server,
-  tool,
-} from "@databricks/appkit";
+import { agents, analytics, createApp, files, server } from "@databricks/appkit";
+import { createAgent, tool } from "@databricks/appkit/beta";
 import { z } from "zod";
 
 const support = createAgent({
   instructions: "You help customers with data and files.",
-  model: "databricks-claude-sonnet-4-5",                  // string sugar
-  tools: {
-    ...fromPlugin(analytics),                             // all analytics tools
-    ...fromPlugin(files, { only: ["uploads.read"] }),     // filtered subset
-    get_weather: tool({
-      name: "get_weather",
-      description: "Weather",
-      schema: z.object({ city: z.string() }),
-      execute: async ({ city }) => `Sunny in ${city}`,
-    }),
+  model: "databricks-claude-sonnet-4-5",                      // string sugar
+  tools(plugins) {
+    return {
+      ...plugins.analytics.toolkit(),                          // all analytics tools
+      ...plugins.files.toolkit({ only: ["uploads.read"] }),    // filtered subset
+      get_weather: tool({
+        description: "Weather",
+        schema: z.object({ city: z.string() }),
+        execute: async ({ city }) => `Sunny in ${city}`,
+      }),
+    };
   },
 });
 
@@ -119,13 +113,15 @@ await createApp({
 });
 ```
 
-Code-defined agents start with no tools by default. `fromPlugin(factory)` is the primary way to pull in a plugin's tools — it returns a spread-friendly marker that the agents plugin resolves against registered `ToolProvider`s at setup time. No intermediate variable, no duplicate `plugins: [analyticsP, filesP, ...]` dance: you write the factory reference once inside `fromPlugin` and again in `plugins: [...]`.
+Code-defined agents start with no tools by default. The function form `tools(plugins) => Record<string, AgentTool>` is the primary way to pull in plugin tools: each plugin registered in `createApp({ plugins: [...] })` shows up on the `plugins` parameter, and you call `.toolkit(opts?)` on it to get a spread-friendly record. The runtime invokes the function once at agent setup and caches the result — every plugin is mentioned exactly once (in `createApp`), with no held variables or marker imports.
+
+Inline `tool({...})` calls live in the same record. `name` is optional — the agents plugin overrides it with the record key (`get_weather` above).
 
 The asymmetry (file: auto-inherit, code: strict) matches the personas: prompt authors want zero ceremony, engineers want no surprises.
 
 ### Scoping tools in code
 
-`fromPlugin(factory, opts?)` accepts the same `ToolkitOptions` as markdown frontmatter:
+`plugins.<name>.toolkit(opts?)` accepts the same `ToolkitOptions` as markdown frontmatter:
 
 | Option | Example | Meaning |
 |---|---|---|
@@ -134,7 +130,7 @@ The asymmetry (file: auto-inherit, code: strict) matches the personas: prompt au
 | `prefix` | `{ prefix: "" }` | Drop the `${pluginName}.` prefix |
 | `rename` | `{ rename: { query: "q" } }` | Remap specific local names |
 
-For plugins that don't expose a `.toolkit()` method (e.g., third-party `ToolProvider` plugins authored with plain `toPlugin`), `fromPlugin` falls back to walking `getAgentTools()` and synthesizing namespaced keys (`${pluginName}.${localName}`). The fallback respects `only` / `except` / `rename` / `prefix` the same way.
+For plugins that don't expose a `.toolkit()` method (e.g., third-party `ToolProvider` plugins authored with plain `toPlugin`), the runtime falls back to walking `getAgentTools()` and synthesizing namespaced keys (`${pluginName}.${localName}`). The fallback respects `only` / `except` / `rename` / `prefix` the same way.
 
 If a referenced plugin is not registered in `createApp({ plugins })`, the agents plugin throws at setup with an `Available: …` listing so you can fix the wiring before the first request.
 
@@ -190,15 +186,18 @@ for (const ticket of tickets) {
 }
 ```
 
-`runAgent` drives the adapter without `createApp` or HTTP. Inline `tool()` calls work standalone as shown above. To use plugin tools in standalone mode, pass the plugin factories through `RunAgentInput.plugins` — `runAgent` will resolve any `fromPlugin` markers in the def against that list:
+`runAgent` drives the adapter without `createApp` or HTTP. Inline `tool()` calls work standalone as shown above. To use plugin tools in standalone mode, pass the plugin factories through `RunAgentInput.plugins` and reach into them via the `tools(plugins)` function form:
 
 ```ts
-import { analytics, createAgent, fromPlugin, runAgent } from "@databricks/appkit";
+import { analytics } from "@databricks/appkit";
+import { createAgent, runAgent } from "@databricks/appkit/beta";
 
 const classifier = createAgent({
   instructions: "Classify tickets. Use analytics.query for historical data.",
   model: "databricks-claude-sonnet-4-5",
-  tools: { ...fromPlugin(analytics) },
+  tools(plugins) {
+    return { ...plugins.analytics.toolkit() };
+  },
 });
 
 const result = await runAgent(classifier, {
@@ -207,7 +206,9 @@ const result = await runAgent(classifier, {
 });
 ```
 
-Hosted tools (MCP) are still `agents()`-only since they require the live MCP client. Plugin tool dispatch in standalone mode runs as the service principal (no OBO) since there is no HTTP request.
+`runAgent` eagerly constructs each plugin in `RunAgentInput.plugins`, runs the standard `attachContext({})` + `await setup()` lifecycle, and shares the instances across the top-level run and every sub-agent dispatch. Plugins whose `setup()` requires `createApp`-only runtime (e.g. `WorkspaceClient`, `ServiceContext`) throw at standalone-init with a clear "use createApp instead" message rather than mid-stream.
+
+Hosted tools (MCP) are still `agents()`-only since they require the live MCP client. Plugin tool dispatch in standalone mode runs as the service principal (no OBO) and **bypasses the agents-plugin approval gate** — treat standalone runAgent as a trusted-prompt environment (CI, batch eval, internal scripts), not as an exposed user-facing surface.
 
 ## Configuration reference
 

packages/appkit/src/core/agent/tests/function-tool.test.ts

@@ -47,10 +47,14 @@ describe("isFunctionTool", () => {
     expect(isFunctionTool({ type: "function", name: "x" })).toBe(false);
   });
 
-  test("returns false when name is missing", () => {
-    expect(isFunctionTool({ type: "function", execute: () => "y" })).toBe(
-      false,
-    );
+  test("returns true when name is omitted (record key wins downstream)", () => {
+    // Regression: previously `tool({ description, schema, execute })` (no
+    // name) produced a FunctionTool whose `name: undefined` failed this
+    // guard and broke registration with "unrecognized shape". The agents
+    // plugin always overrides `name` with the record key from
+    // `tools: { my_tool: tool({...}) }`, so requiring `name` here was
+    // rejecting valid input.
+    expect(isFunctionTool({ type: "function", execute: () => "y" })).toBe(true);
   });
 });
 

packages/appkit/src/core/agent/tests/tool.test.ts

@@ -86,6 +86,50 @@ describe("tool()", () => {
     expect(t.description).toBe("my_tool");
     expect(t.parameters).toBeDefined();
   });
+
+  test("name is optional — agents plugin overrides it with the record key", () => {
+    // Regression: PR #306 reviewer hit a runtime crash because the
+    // template wrote `tool({ description, schema, execute })` (no name)
+    // and the FunctionTool shape guard rejected the result. The agent
+    // runtime always overrides `name` with the record key in
+    // `tools: { my_tool: tool({...}) }`, so requiring it here was
+    // mis-shaping a valid input.
+    const t = tool({
+      description: "Returns the current server time",
+      schema: z.object({}),
+      execute: () => "2026-05-11T00:00:00Z",
+    });
+
+    expect(t.type).toBe("function");
+    expect(t.name).toBeUndefined();
+    expect(t.description).toBe("Returns the current server time");
+  });
+
+  test("execute may return non-string shapes; downstream normalises", async () => {
+    // Regression: `execute` was typed `Promise<string> | string` but the
+    // template's tools naturally return objects. The runtime serialises
+    // via `normalizeToolResult`; tighten typing to `unknown` and verify
+    // the value flows through.
+    const t = tool({
+      name: "now",
+      schema: z.object({}),
+      execute: () => ({ now: "2026-05-11T00:00:00Z" }),
+    });
+    const result = (await t.execute({})) as { now: string };
+    expect(result).toEqual({ now: "2026-05-11T00:00:00Z" });
+  });
+
+  test("zod-error message uses a generic label when name is omitted", async () => {
+    const t = tool({
+      description: "needs a city",
+      schema: z.object({ city: z.string() }),
+      execute: () => "ok",
+    });
+    const result = await t.execute({});
+    expect(typeof result).toBe("string");
+    expect(result).toContain("Invalid arguments for tool");
+    expect(result).toContain("city");
+  });
 });
 
 describe("formatZodError", () => {

packages/appkit/src/core/agent/tools/function-tool.ts

@@ -2,7 +2,14 @@ import type { AgentToolDefinition, ToolAnnotations } from "shared";
 
 export interface FunctionTool {
   type: "function";
-  name: string;
+  /**
+   * Optional. When this tool is placed in a keyed record
+   * (`tools: { my_tool: ... }` or the function form), the agents plugin
+   * overrides this with the record key at index-build time. Only set it
+   * explicitly when constructing a `FunctionTool` outside any
+   * keyed-record context.
+   */
+  name?: string;
   description?: string | null;
   parameters?: Record<string, unknown> | null;
   strict?: boolean | null;
@@ -16,25 +23,34 @@ export interface FunctionTool {
    * tool indexes.
    */
   annotations?: ToolAnnotations;
-  execute: (args: Record<string, unknown>) => Promise<string> | string;
+  /**
+   * Returns any shape; downstream `normalizeToolResult` serializes to a
+   * string before handing the value to the LLM.
+   */
+  execute: (args: Record<string, unknown>) => unknown | Promise<unknown>;
 }
 
 export function isFunctionTool(value: unknown): value is FunctionTool {
   if (typeof value !== "object" || value === null) return false;
   const obj = value as Record<string, unknown>;
-  return (
-    obj.type === "function" &&
-    typeof obj.name === "string" &&
-    typeof obj.execute === "function"
-  );
+  // `name` is intentionally not required: the agents plugin overrides it
+  // with the record key (`tools: { my_tool: tool({...}) }` -> "my_tool")
+  // so requiring it on the FunctionTool shape rejects perfectly-valid
+  // `tool({ description, schema, execute })` calls that omit the name.
+  return obj.type === "function" && typeof obj.execute === "function";
 }
 
 export function functionToolToDefinition(
   tool: FunctionTool,
 ): AgentToolDefinition {
+  // `name` is guaranteed to be overridden downstream by the record key
+  // when the tool is registered through `AgentDefinition.tools`. Falling
+  // back to an empty string here keeps the type honest without
+  // surfacing a sentinel that could leak into a non-record context.
+  const name = tool.name ?? "";
   return {
-    name: tool.name,
-    description: tool.description ?? tool.name,
+    name,
+    description: tool.description ?? name,
     parameters: (tool.parameters as AgentToolDefinition["parameters"]) ?? {
       type: "object",
       properties: {},

packages/appkit/src/core/agent/tools/tool.ts

@@ -4,7 +4,15 @@ import type { FunctionTool } from "./function-tool";
 import { toToolJSONSchema } from "./json-schema";
 
 export interface ToolConfig<S extends z.ZodType> {
-  name: string;
+  /**
+   * Optional. When the tool is placed in a keyed record (the standard
+   * `tools: { my_tool: tool({...}) }` form, or the function form
+   * `tools(plugins) => ({ my_tool: tool({...}) })`), the agents plugin
+   * overrides the tool's LLM-visible name with the record key. Set
+   * `name` explicitly only if you're constructing a `FunctionTool`
+   * outside any keyed-record context — otherwise the record key wins.
+   */
+  name?: string;
   description?: string;
   schema: S;
   /**
@@ -16,7 +24,15 @@ export interface ToolConfig<S extends z.ZodType> {
    * added this field.
    */
   annotations?: ToolAnnotations;
-  execute: (args: z.infer<S>) => Promise<string> | string;
+  /**
+   * Returning a non-string value is fine: the agent runtime serializes
+   * the result via `normalizeToolResult` before handing it to the LLM
+   * (strings pass through; `null` becomes `"null"`; everything else gets
+   * `JSON.stringify`'d; `undefined` becomes `""`). Return whatever shape
+   * is most natural for your tool — typically an object — and let the
+   * runtime handle the wire format.
+   */
+  execute: (args: z.infer<S>) => unknown | Promise<unknown>;
 }
 
 /**
@@ -34,16 +50,23 @@ export function tool<S extends z.ZodType>(config: ToolConfig<S>): FunctionTool {
     unknown
   >;
 
+  // `name` is only used for the zod-validation error message and the
+  // FunctionTool's `name` field; the agents plugin overrides the latter
+  // with the record key (`tools: { my_tool: ... }` -> "my_tool") at
+  // index-build time. Fall back to a generic label so errors are still
+  // legible when `name` is omitted.
+  const labelForErrors = config.name ?? "tool";
+
   return {
     type: "function",
-    name: config.name,
+    ...(config.name !== undefined ? { name: config.name } : {}),
     description: config.description ?? config.name,
     parameters,
     ...(config.annotations ? { annotations: config.annotations } : {}),
     execute: async (args: Record<string, unknown>) => {
       const parsed = config.schema.safeParse(args);
       if (!parsed.success) {
-        return formatZodError(parsed.error, config.name);
+        return formatZodError(parsed.error, labelForErrors);
       }
       return config.execute(parsed.data as z.infer<S>);
     },