@noodleseed/agent-kit 0.41.0 → 0.43.0

package/skills/claude-code/references/feedback.md

@@ -1,6 +1,6 @@
 # Send product feedback
 
-When you — the coding agent — discover a way Noodle Seed could be better, prepare one sanitized feedback proposal. Feedback crosses the customer project boundary and lands in Noodle Seed’s private tracker, so the user must make an informed choice. Show the user the exact command and ask for explicit user approval. Do not run or submit it until approval is given.
+When you — the coding agent — discover a way Noodle Seed could be better, prepare one sanitized feedback proposal. Feedback crosses the customer project boundary and lands in the Noodle Seed private feedback tracker, so the user must make an informed choice. Preview the exact normalized submission locally, show it with the exact live command, and ask for explicit user approval. Do not submit it until approval is given.
 
 ## Contents
 
@@ -26,20 +26,22 @@ Do not batch several findings into one proposal, and do not re-propose the same
 
 ## Approval workflow
 
-1. Draft and sanitize the title, message, labels, and exact shell command.
-2. Show the user the exact command and explain that it sends the shown content plus CLI version, OS/platform, and Node version to Noodle Seed’s private tracker.
-3. Ask for explicit user approval. Do not run, submit, or send anything until the user clearly approves that exact proposal.
-4. After approval, run it once. If authentication is missing, report that feedback was not sent and offer the normal `noodle login` path; never sign in or retry without direction.
+1. Discover the current positional arguments, flags, choices, defaults, and limits from `noodle commands --json`; `noodle feedback --help` is the human-readable view. Do not guess or rely on a remembered catalog.
+2. Draft one finding, then sanitize its title and message using the rules below.
+3. Run the proposal with `--dry-run --json`. This local preview needs no login and sends nothing. Parse `{"ok":true,"data":{"mode":"preview","willSubmit":false,"destination":"Noodle Seed private feedback tracker","submission":{...}}}`.
+4. Inspect the complete `submission`, including its normalized defaults and automatically attached diagnostics. Show the user the exact previewed proposal, its `destination`, and a POSIX-safely quoted live command containing the same fields but without `--dry-run`.
+5. Ask for explicit approval of that exact previewed proposal. If the user changes any field, preview the changed proposal again before asking.
+6. Only after approval, submit it once by running the disclosed live command without `--dry-run`. Never auto-login and never retry-loop. If authentication fails before the request or a rate limit denies it, report that nothing was sent. For `feedback_recording_failed`, report that no reference was returned and the outcome may be unknown; do not retry because the private issue might already exist.
 
 ## The command
 
 ```sh
-noodle feedback "resources list --json omits the truncated flag the docs promise" \
-  --title "resources list --json missing truncated flag" \
-  --type fix --severity P2 --area cli --json
+noodle feedback 'resources list --json omits the truncated flag the docs promise' \
+  --title 'resources list --json missing truncated flag' \
+  --type fix --severity P2 --area cli --dry-run --json
 ```
 
-This is an example only; build the exact command for the finding and show it before execution. Read `noodle feedback --help` for human-readable constraints or inspect `noodle commands --json` for the same machine-readable usage, enum, and length metadata instead of guessing accepted values. The message is required (1–4000 chars). Pass `--json` and parse the envelope: success is `{ok:true,data:{reference,labels}}`; a `429` means the per-user hourly budget (5) is spent — report that it was not sent and never retry-loop. The CLI attaches only the disclosed light diagnostics automatically: CLI version, OS/platform, Node version. Nothing else is collected.
+This is a preview example only. Build the exact command for the finding using current `noodle commands --json` metadata, POSIX-quote every user-controlled value, and inspect the returned submission instead of reconstructing it. The message is required (1–4000 chars). The CLI attaches only the disclosed light diagnostics automatically: CLI version, OS/platform, Node version. Nothing else is collected. After approval, the live success envelope is `{ok:true,data:{reference,labels}}`; a `429` means the per-user hourly budget (5) is spent — report that it was not sent and never retry-loop.
 
 ## Choose the structured fields
 

package/skills/claude-code/references/tool-design.md

@@ -0,0 +1,103 @@
+# Tool design
+
+## Contents
+
+- Design tools for the model
+- Title and annotations
+- Bound every output
+- Keep the tool surface small
+- Provision context deliberately
+- Errors an agent can act on
+- What `noodle check` reports
+
+## Design tools for the model
+
+Design tools around what a user says, not 1:1 around API endpoints. A raw wrapper per endpoint (`get_task`, `list_tasks`, `close_task`) forces the model to orchestrate low-level calls and to know identifiers the user never sees — an MCP connector, but not a usable product. Instead:
+
+- **Shape by intent.** Name and scope tools for the job to be done — "find my overdue tasks", "complete the task matching this text" — combining multiple backing calls in one recorded flow (`when(...)`) where it helps.
+- **Prefer names/text over raw IDs.** When an action needs an id the user does not know, pair the id-taking operation with a find/search operation that returns model-friendly summaries (id + a human label), so the model resolves text → id itself. Write descriptions that tell the model when to use each tool and how they chain.
+- **Return only what the model needs.** Map the response to a small, typed `output` (a few labelled fields), not the raw API payload.
+
+This example pairs a name resolver with an id-taking action: the model calls `find_tasks` to turn the user’s words into an id, then `complete_task`. It is compile-verified on every `pnpm test`.
+
+```ts
+import { connector, secret, server, tool, z } from '@noodleseed/one';
+
+const tasks = connector('tasks').version('1.0.0').http({
+  baseUrl: 'https://api.tasks.example',
+  allowedOrigins: ['https://api.tasks.example'],
+  auth: { kind: 'bearer', secret: secret('TASKS_TOKEN') },
+  operations: {
+    search_tasks: {
+      type: 'read',
+      method: 'GET',
+      path: '/tasks',
+      query: ['query'],
+      input: z.object({ query: z.string() }),
+      output: z.object({ matches: z.array(z.unknown()) }),
+      response: { matches: '${response.results}' },
+    },
+    close_task: {
+      type: 'action',
+      method: 'POST',
+      path: '/tasks/{id}/close',
+      input: z.object({ id: z.string() }),
+      output: z.object({ ok: z.boolean() }),
+      response: { ok: '${response.ok}' },
+    },
+  },
+});
+
+export default server('todo', { title: 'Tasks', version: '1.0.0', use: { tasks } }, [
+  tool('find_tasks', {
+    description: 'Find tasks whose text matches a query — call this first to resolve a task the user names by text into its id, then pass that id to complete_task.',
+    input: z.object({ query: z.string() }),
+    output: z.object({ matches: z.array(z.object({ id: z.string(), title: z.string() })) }),
+    fulfil: ({ input, connectors }) => {
+      const found = connectors.tasks.search_tasks({ query: input.query });
+      return { matches: found.matches };
+    },
+  }),
+  tool('complete_task', {
+    description: 'Mark a task complete by its id (get the id from find_tasks).',
+    input: z.object({ id: z.string() }),
+    output: z.object({ ok: z.boolean() }),
+    fulfil: ({ input, connectors }) => {
+      const result = connectors.tasks.close_task({ id: input.id });
+      return { ok: result.ok };
+    },
+  }),
+]);
+```
+
+The model never sees a task id from the user; `find_tasks` returns `{ id, title }` summaries it can pick from, then `complete_task` acts by id. Keep write actions (`complete_task`) separate and explicitly described so the host can gate them.
+
+## Title and annotations
+
+Every model-visible tool needs a `title` — the action name hosts show in tool pickers and confirmation prompts — and `annotations`. `annotations.readOnly()` is a closed-world safe read; `annotations.action()` affects the world; `annotations.localAction()` affects only this app's data; `annotations.openAction()` reaches the open internet. Keep reads and writes in separate tools: one tool that both lists and mutates cannot be annotated honestly, so no host can gate it correctly. Missing titles and hints are also the most common consumer-directory rejection.
+
+## Bound every output
+
+Always declare `output`. Without it the model has to parse prose and hosts have no structured result to render. Then bound any list: cap the array with `z.array(item).max(50)`, or take a bounded pagination input (`limit`, `cursor`). An unbounded list either exhausts the context window or is truncated somewhere you do not control. Map the response to the few labelled fields the model needs, never the raw upstream payload — every field you pass through is context paid for on every later turn.
+
+## Keep the tool surface small
+
+`noodle check` warns above 20 model-visible tools. That is a documented heuristic, not a host limit: no host publishes a hard number, and the real threshold depends on how distinct your descriptions are. Collapse variants that differ only by a filter into one intent-shaped tool with a typed enum, and mark widget-only helpers `visibility: ['app']` so they stay callable from the app surface without entering the model's list.
+
+## Provision context deliberately
+
+Most “the model guessed wrong” bugs are missing context, not a missing tool. Every invocation already carries a server-authoritative instant plus locale and time zone, so never ask the model for today's date. Set `server(..., { context: { defaults: { locale, timeZone } } })` for ambient defaults, and mark one zero-input tool `contextProvider: true` when the model needs portable application context such as workspace, plan, or permissions. `references/authoring-workflow.md` owns the full invocation-context contract.
+
+## Errors an agent can act on
+
+An agent cannot recover from “Request failed”. Say which argument was wrong, which tool resolves it, and whether retrying helps. Error text is part of the tool interface and is read far more often by a model than by a human.
+
+## What `noodle check` reports
+
+- `tool_design_titles` — a model-visible tool has no `title`.
+- `tool_design_output_shape` — a model-visible tool has no `output` schema.
+- `tool_design_output_bounds` — an output array has no `maxItems` and the tool takes no pagination input.
+- `tool_design_surface_budget` — more than 20 model-visible tools.
+- `tool_design_context` — which tool provides application context (informational).
+
+All five are warnings, never failures, so they never change the exit code. Use `noodle check --min-severity warn` to see only what needs fixing and `noodle check --json` to consume them programmatically.

package/skills/claude-code/reporting-noodle-feedback/SKILL.md

@@ -3,11 +3,11 @@ name: reporting-noodle-feedback
 description: "Use when a Noodle Seed bug, misleading instruction, missing capability, or concrete product improvement should be proposed to the user."
 ---
 
-<!-- noodle-skill version:0.41.0 hash:1e23938b39956ef8 -->
+<!-- noodle-skill version:0.43.0 hash:0f404109f4845683 -->
 
 # reporting-noodle-feedback
 
-Offer one sanitized feedback command and submit it only after informed explicit approval.
+Preview one sanitized feedback proposal and submit it once only after informed explicit approval.
 
 ## Use when
 
@@ -23,7 +23,7 @@ Offer one sanitized feedback command and submit it only after informed explicit
 
 - One distinct finding.
 - Sanitized observed and expected behavior.
-- User approval for the exact command.
+- User approval for the exact dry-run preview and live command.
 
 ## Workflow
 
@@ -31,15 +31,15 @@ Read and follow the canonical playbook `references/feedback.md` at `../noodle-se
 
 ## Verification evidence
 
-The user saw the exact sanitized command; only a returned reference proves submission.
+The user saw the exact sanitized preview, diagnostics, destination, and live command; only a returned reference proves submission.
 
 ## Recovery paths
 
-If login or rate limits block submission, report that nothing was sent and do not retry-loop.
+If login or rate limits block the one live submission, report that nothing was sent. A recording failure has an unknown outcome: report no reference and never auto-login or retry-loop.
 
 ## Stop conditions
 
-Stop before running the command until the user explicitly approves it.
+Stop after the local dry-run and before the live command until the user explicitly approves it.
 
 ## Handoff contract
 

package/skills/claude-code/verifying-mcp-delivery/SKILL.md

@@ -3,7 +3,7 @@ name: verifying-mcp-delivery
 description: "Use when proving a Noodle Seed MCP project works at a named compile, local, connector, App, host, deployment, or production evidence level."
 ---
 
-<!-- noodle-skill version:0.41.0 hash:6ef6ef551e26b78e -->
+<!-- noodle-skill version:0.43.0 hash:6ef6ef551e26b78e -->
 
 # verifying-mcp-delivery
 

package/skills/codex/SKILL.md

@@ -3,7 +3,7 @@ name: noodle-seed
 description: "Use when building, validating, testing, deploying, or operating a local or hosted Noodle Seed MCP server or app authored in TypeScript with the noodle CLI."
 ---
 
-<!-- noodle-skill version:0.41.0 hash:2ea7d6dcc8358b35 -->
+<!-- noodle-skill version:0.43.0 hash:cd6ca0d915e6acb9 -->
 
 # Noodle Seed
 
@@ -35,11 +35,11 @@ Negative routing examples: “Inspect hosted logs/status” → `inspect-hosted`
 | Deploy, configure, connect with writes, change access, or roll back a hosted MCP service when explicitly requested | `deploying-mcp-services` | `references/deploy-and-ops.md` (`references/cli-commands.md`) | The requested hosted state is evidenced without claiming unperformed host or production checks. |
 | Embed a Noodle assistant in an existing SaaS or web application | `embedding-mcp-assistants` | `references/embedded-assistant.md` (`references/authoring-workflow.md`) | The requested embed boundary works with verified identity and credential separation at the tested level. |
 | Prepare or submit an integration to a host directory | `publishing-mcp-integrations` | `references/publishing.md` (`references/app-directory-compliance.md`) | The requested submission evidence is complete and any host-review uncertainty is explicit. |
-| Report a Noodle Seed bug, documentation gap, or product improvement | `reporting-noodle-feedback` | `references/feedback.md` (None) | A sanitized command is shown to the user and is submitted only after explicit approval. |
+| Report a Noodle Seed bug, documentation gap, or product improvement | `reporting-noodle-feedback` | `references/feedback.md` (None) | A sanitized dry-run preview and exact live command are shown, then one submission occurs only after explicit approval. |
 
 ## Common machine loop
 
-The cold-agent commands speak the `--json` envelope. Parse machine state instead of scraping human prose; `references/agent-contract.md` owns the envelope and exit codes.
+Every `--json` command speaks the canonical envelope on stdout. Parse machine state instead of scraping human prose; `references/agent-contract.md` owns the envelope, streaming records, and exit codes.
 
 1. **Discover** — use `noodle commands --json` when the required command or flags are uncertain; don't read CLI source.
 2. **Author** — for build routes, edit the configured TypeScript entrypoint, usually `src/server.ts`.
@@ -57,7 +57,8 @@ This is a lookup catalog, not a discovery checklist. Return here only when the s
 - `references/cli-commands.md` — every `noodle` command, grouped by area.
 - `references/compile-errors.md` — fix `noodle validate` errors by code.
 - `references/build-an-mcp-server.md` — outcome-first workflow for a focused, tested, model-facing MCP product.
-- `references/authoring-workflow.md` — input paths, fit checks, connector patterns, authentication, tool design, testing, and managed config.
+- `references/authoring-workflow.md` — input paths, fit checks, connector patterns, authentication, invocation context, testing, and managed config.
+- `references/tool-design.md` — intent-shaped tools, titles and annotations, bounded outputs, tool-surface budget, and context provisioning.
 - `references/embedded-assistant.md` — HTTPS origins, managed model config, deploy sequencing, session exchange, browser mounting, and credential boundaries.
 - `references/connect-an-api.md` — secure credentials, probe the live API, model the observed shape, and prove real output.
 - `references/build-an-mcp-app.md` — product-fit, output-boundary, fallback, and evidence workflow for an MCP App.
@@ -75,7 +76,7 @@ This is a lookup catalog, not a discovery checklist. Return here only when the s
 
 ## Product feedback
 
-When you discover a bug, missing capability, misleading doc, or improvement idea, draft one sanitized `noodle feedback` command per finding. Show the user the exact command and ask for explicit user approval. Do not run or submit it until approval is given. Follow `references/feedback.md`; never include customer code, secrets, personal data, or identifying project details.
+When you discover a bug, missing capability, misleading doc, or improvement idea, discover current fields with `noodle commands --json`, draft and sanitize one finding, then run `noodle feedback ... --dry-run --json`. Inspect and show the exact normalized submission, diagnostics, private destination, and POSIX-safely quoted live command. Ask for explicit approval of that exact proposal; do not submit it until approval. Then submit once without `--dry-run`. Follow `references/feedback.md`; never include customer code, secrets, personal data, or identifying project details, and never auto-login or retry-loop.
 
 ## Safety
 

package/skills/codex/authoring-mcp-servers/SKILL.md

@@ -3,7 +3,7 @@ name: authoring-mcp-servers
 description: "Use when creating or extending a headless Noodle Seed MCP server, tool, resource, prompt, or typed model-facing capability."
 ---
 
-<!-- noodle-skill version:0.41.0 hash:0b2fd8c7e43fc69f -->
+<!-- noodle-skill version:0.43.0 hash:0b2fd8c7e43fc69f -->
 
 # authoring-mcp-servers
 

package/skills/codex/building-mcp-apps/SKILL.md

@@ -3,7 +3,7 @@ name: building-mcp-apps
 description: "Use when a Noodle Seed MCP App, widget, interactive card, visual interaction, or host-visible UI is the primary requested outcome."
 ---
 
-<!-- noodle-skill version:0.41.0 hash:f7fa54992c8d7692 -->
+<!-- noodle-skill version:0.43.0 hash:f7fa54992c8d7692 -->
 
 # building-mcp-apps
 

package/skills/codex/connecting-apis-to-mcp/SKILL.md

@@ -3,7 +3,7 @@ name: connecting-apis-to-mcp
 description: "Use when credentials, an API URL, an OpenAPI document, or an observed response must become real Noodle Seed MCP behavior."
 ---
 
-<!-- noodle-skill version:0.41.0 hash:1e86b8704f407bd3 -->
+<!-- noodle-skill version:0.43.0 hash:1e86b8704f407bd3 -->
 
 # connecting-apis-to-mcp
 

package/skills/codex/debugging-mcp-delivery/SKILL.md

@@ -3,7 +3,7 @@ name: debugging-mcp-delivery
 description: "Use when an existing Noodle Seed MCP project has a concrete validation, runtime, connector, App, host, deployment, or production failure."
 ---
 
-<!-- noodle-skill version:0.41.0 hash:aa715bae12041d7c -->
+<!-- noodle-skill version:0.43.0 hash:aa715bae12041d7c -->
 
 # debugging-mcp-delivery
 

package/skills/codex/deploying-mcp-services/SKILL.md

@@ -3,7 +3,7 @@ name: deploying-mcp-services
 description: "Use when the user explicitly requests a Noodle Seed hosted link, configuration write, deployment, access change, rollback, or connection write."
 ---
 
-<!-- noodle-skill version:0.41.0 hash:93e735b7ffb45df1 -->
+<!-- noodle-skill version:0.43.0 hash:93e735b7ffb45df1 -->
 
 # deploying-mcp-services
 

package/skills/codex/designing-mcp-products/SKILL.md

@@ -3,7 +3,7 @@ name: designing-mcp-products
 description: "Use when a Noodle Seed MCP product idea needs conversational fit, user benefit, scope, interaction, or evidence design before implementation."
 ---
 
-<!-- noodle-skill version:0.41.0 hash:76cce86729cffbee -->
+<!-- noodle-skill version:0.43.0 hash:76cce86729cffbee -->
 
 # designing-mcp-products
 

package/skills/codex/embedding-mcp-assistants/SKILL.md

@@ -3,7 +3,7 @@ name: embedding-mcp-assistants
 description: "Use when embedding a Noodle assistant into an existing SaaS or web application with browser, identity, session, and credential boundaries."
 ---
 
-<!-- noodle-skill version:0.41.0 hash:5d8f40f904d6ab4b -->
+<!-- noodle-skill version:0.43.0 hash:5d8f40f904d6ab4b -->
 
 # embedding-mcp-assistants
 

package/skills/codex/examples/acme-bistro/src/server.ts

@@ -53,13 +53,16 @@ export default server(
   },
   [
     tool('show_menu', {
+      title: 'Show the menu',
       description: 'Show the Acme Bistro menu and render the ordering widget.',
       annotations: readOnly,
       input: z.object({ customer: z.string().default('Guest') }),
       output: z.object({
         status: z.string(),
         customer: z.string(),
-        items: z.array(menuItemOutput),
+        // Bounded list: the menu is a fixed catalog, so the ceiling is declared on the shape rather
+        // than taken as a pagination input. `noodle check` reports `tool_design_output_bounds`.
+        items: z.array(menuItemOutput).max(50),
       }),
       fulfil: ({ input }) => ({
         status: `Acme Bistro menu is ready for ${input.customer}. Build the order here; pay at checkout.`,
@@ -125,6 +128,7 @@ export default server(
     // The only handoff: payment. The widget computes the total (live React) and passes a url-safe cart
     // token + total; the card is entered on Acme's PCI-scoped checkout, never in chat.
     tool('create_checkout', {
+      title: 'Create checkout',
       description:
         'Create the Acme Bistro payment checkout link for the current order. Pass a url-safe cart token ' +
         'and the numeric total computed in the widget. Payment happens off-app; the card never reaches this app.',

package/skills/codex/examples/acme-discovery/src/server.ts

@@ -116,6 +116,7 @@ export default server(
   },
   [
     tool('discover_getaways', {
+      title: 'Discover getaways',
       description:
         'Suggest Acme Getaways destinations for a vibe and month and render a discovery carousel.',
       annotations: readOnly,
@@ -125,7 +126,9 @@ export default server(
         vibe: z.string(),
         month: z.string(),
         travelers: z.number(),
-        options: z.array(destinationOutput),
+        // Bounded list: the curated catalog is fixed and small, and the declared ceiling tells the
+        // model and host the payload cannot grow. `noodle check` reports `tool_design_output_bounds`.
+        options: z.array(destinationOutput).max(20),
       }),
       // The carousel presents Acme's curated catalog; the model narrates which fit the stated vibe.
       // (A tool cannot filter on an input value — that is connector/flow work — so all are returned.)
@@ -154,6 +157,7 @@ export default server(
       },
     }),
     tool('create_handoff', {
+      title: 'Create booking handoff',
       description:
         'Create the Acme booking deep link for a chosen destination, carrying the configured trip. ' +
         'Pass the destination id (url-safe slug, e.g. "coral_bay") and its display name.',

package/skills/codex/examples/acme-tasks/src/server.ts

@@ -62,10 +62,13 @@ export default server(
       description: 'Show today’s Acme Tasks and render the task-list widget.',
       annotations: readOnly,
       input: z.object({ focus: z.string().default('today') }),
+      // Bound the list output. A recorded `fulfil` cannot slice an array, so the honest bound here is
+      // a cap on the shape itself; a connector-backed list takes a pagination input instead (see the
+      // `weather` example). `noodle check` reports an unbounded array as `tool_design_output_bounds`.
       output: z.object({
         status: z.string(),
         focus: z.string(),
-        tasks: z.array(taskOutput),
+        tasks: z.array(taskOutput).max(20),
       }),
       fulfil: ({ input }) => ({
         status: `Acme Tasks for ${input.focus}: ${today.length} open items, highest priority first.`,

package/skills/codex/examples/customer-auth/src/server.ts

@@ -142,8 +142,12 @@ export default server(
       description: 'List the NoodleSeed.com organizations the signed-in customer belongs to.',
       contextProvider: true,
       input: z.object({}),
+      // The dev app API returns every organization for the signed-in customer in one response, with no
+      // page parameter to pass through, so the bound is declared on the shape. A customer belongs to a
+      // handful of organizations; `noodle check` reports an unbounded list as
+      // `tool_design_output_bounds`.
       output: z.object({
-        organizations: z.array(z.unknown()),
+        organizations: z.array(z.unknown()).max(100),
       }),
       annotations: annotations.readOnly(),
       fulfil({ connectors }) {

package/skills/codex/examples/food-ordering/src/server.ts

@@ -132,7 +132,9 @@ const menuItemShape = z.object({
   name: z.string(),
   price: z.number(),
   description: z.string(),
-  modifiers: z.array(z.string()),
+  // Nested lists count toward the output budget too: unbounded modifiers multiply by every item in a
+  // menu payload, so the ceiling is declared here rather than only on the outer array.
+  modifiers: z.array(z.string()).max(10),
 });
 
 const cartOutput = z.object({
@@ -240,6 +242,7 @@ export default server(
   },
   [
     tool('open_ordering', {
+      title: 'Open food ordering',
       description:
         'Open a complete food-ordering widget with store discovery, menu browsing, cart review, and checkout handoff.',
       annotations: readOnly,
@@ -247,11 +250,14 @@ export default server(
         query: z.string().optional(),
         customer: z.string().default('Guest'),
       }),
+      // List outputs declare a ceiling so a host and the model both know the payload is bounded.
+      // A recorded `fulfil` cannot slice, so the cap belongs on the shape; connector-backed lists take
+      // a pagination input instead. `noodle check` reports `tool_design_output_bounds` without one.
       output: z.object({
         status: z.string(),
         customer: z.string(),
-        stores: z.array(storeShape),
-        featuredItems: z.array(menuItemShape),
+        stores: z.array(storeShape).max(20),
+        featuredItems: z.array(menuItemShape).max(20),
         localDate: z.string(),
         serviceArea: z.string(),
         fallback: z.string(),
@@ -371,16 +377,18 @@ export default server(
       },
     }),
     tool('summarize_ordering_options', {
+      title: 'Summarize ordering options',
       description: 'Summarize available stores and menu examples without opening the widget.',
       annotations: readOnly,
       input: z.object({}),
       output: z.object({
-        stores: z.array(storeShape),
-        featuredItems: z.array(menuItemShape),
+        stores: z.array(storeShape).max(20),
+        featuredItems: z.array(menuItemShape).max(20),
       }),
       fulfil: () => ({ stores, featuredItems: menu }),
     }),
     tool('plan_order', {
+      title: 'Plan an order',
       description:
         'Collect a fulfilment method and requested date as structured input, then return a reviewable order plan without placing an order.',
       annotations: readOnly,
@@ -409,6 +417,7 @@ export default server(
       },
     }),
     tool('show_capabilities', {
+      title: 'Show capabilities',
       description: 'Return a concise summary for the standalone widget capability preview.',
       annotations: readOnly,
       input: z.object({}),

package/skills/codex/examples/gmail-multi-account/src/server.ts

@@ -35,10 +35,13 @@ const vacationOptionalFields = {
   start_time: epochMillis.optional(),
   end_time: epochMillis.optional(),
 };
+// One shared output shape for every tool: one entry per account the call fanned out to. The cap is
+// exactly the number of canonical accounts, so it is a true bound rather than a guess — `noodle check`
+// reports an unbounded array output as `tool_design_output_bounds`.
 const output = z.object({
-  results: z.array(
-    z.object({ account: z.enum([PERSONAL_ACCOUNT, WORK_ACCOUNT]), data: z.unknown() }),
-  ),
+  results: z
+    .array(z.object({ account: z.enum([PERSONAL_ACCOUNT, WORK_ACCOUNT]), data: z.unknown() }))
+    .max(2),
 });
 
 const gmail = gmailConnector();
@@ -84,6 +87,7 @@ export default server(
   },
   [
     tool('search_messages', {
+      title: 'Search messages',
       description: 'Search one connected Gmail account or the canonical personal-and-work pair.',
       input: z.object({
         accounts: readAccounts,
@@ -119,6 +123,7 @@ export default server(
       },
     }),
     tool('get_message', {
+      title: 'Get message',
       description: 'Get one Gmail message from one connected account or both canonical accounts.',
       input: z.object({
         accounts: readAccounts,
@@ -154,6 +159,7 @@ export default server(
       },
     }),
     tool('get_thread', {
+      title: 'Get thread',
       description: 'Get one Gmail thread from one connected account or both canonical accounts.',
       input: z.object({
         accounts: readAccounts,
@@ -189,6 +195,7 @@ export default server(
       },
     }),
     tool('list_drafts', {
+      title: 'List drafts',
       description: 'List drafts from one connected Gmail account or both canonical accounts.',
       input: z.object({
         accounts: readAccounts,
@@ -224,6 +231,7 @@ export default server(
       },
     }),
     tool('get_draft', {
+      title: 'Get draft',
       description: 'Get one draft from one connected Gmail account or both canonical accounts.',
       input: z.object({
         accounts: readAccounts,
@@ -259,6 +267,7 @@ export default server(
       },
     }),
     tool('get_vacation', {
+      title: 'Get vacation responder',
       description: 'Read vacation-responder settings from one connected account or both accounts.',
       input: z.object({ accounts: readAccounts }),
       output,
@@ -281,6 +290,7 @@ export default server(
       },
     }),
     tool('create_draft', {
+      title: 'Create draft',
       description:
         'Create a Gmail draft in exactly one selected account from a base64url MIME message.',
       annotations: confirmedWrite,
@@ -301,6 +311,7 @@ export default server(
       },
     }),
     tool('update_draft', {
+      title: 'Update draft',
       description:
         'Replace a Gmail draft in exactly one selected account with a base64url MIME message.',
       annotations: confirmedWrite,
@@ -322,6 +333,7 @@ export default server(
       },
     }),
     tool('send_draft', {
+      title: 'Send draft',
       description: 'Send an existing Gmail draft from exactly one selected account.',
       annotations: confirmedWrite,
       input: z.object({ accounts: writeAccounts, draft_id: identifier }),
@@ -341,6 +353,7 @@ export default server(
       },
     }),
     tool('modify_message_labels', {
+      title: 'Change message labels',
       description: 'Add or remove Gmail label ids on one message in exactly one selected account.',
       annotations: confirmedWrite,
       input: z.object({
@@ -370,6 +383,7 @@ export default server(
       },
     }),
     tool('archive_message', {
+      title: 'Archive message',
       description: 'Archive one Gmail message in exactly one account by removing INBOX.',
       annotations: confirmedWrite,
       input: z.object({ accounts: writeAccounts, message_id: identifier }),
@@ -389,6 +403,7 @@ export default server(
       },
     }),
     tool('send_message', {
+      title: 'Send message',
       description: 'Send one base64url MIME message from exactly one selected Gmail account.',
       annotations: confirmedWrite,
       input: z.object({
@@ -413,6 +428,7 @@ export default server(
       },
     }),
     tool('trash_message', {
+      title: 'Move message to trash',
       description: 'Move one Gmail message to trash in exactly one account. This is reversible.',
       annotations: confirmedTrash,
       input: z.object({ accounts: writeAccounts, message_id: identifier }),
@@ -432,6 +448,7 @@ export default server(
       },
     }),
     tool('update_vacation', {
+      title: 'Update vacation responder',
       description: 'Update vacation-responder settings on exactly one selected Gmail account.',
       annotations: confirmedWrite,
       input: z.object({

package/skills/codex/examples/hello/README.md

@@ -10,8 +10,13 @@ When an installed Noodle Developer plugin drives this example, its skill runs th
 Do not install or update a global CLI: the coding agent writes and tests this source while Noodle
 guides and operates the validate, preview, deploy, inspect, and debug workflow.
 If that agent discovers a Noodle Seed product gap while working, the installed skill prepares a
-sanitized `noodle feedback` proposal, discovers current fields from `noodle commands --json`, and
-submits it only after showing the exact command and receiving explicit user approval.
+sanitized `noodle feedback` proposal, discovers current fields from `noodle commands --json`, runs
+`--dry-run --json` to inspect the exact normalized submission, diagnostics, and private destination,
+then shows a POSIX-safely quoted live command. It submits once without `--dry-run` only after explicit
+user approval of that exact preview; it never auto-logs in or retry-loops.
+Every `--json` command writes its canonical success or failure envelope to stdout and leaves stderr
+empty. One-shot commands write one envelope; streaming commands write NDJSON snapshot, event, and
+terminal-failure envelopes so agents can parse each line independently.
 
 ```sh
 noodle dev examples/hello/src/server.ts --app hello

package/skills/codex/examples/hello/src/server.ts

@@ -14,6 +14,9 @@ export default server(
   },
   [
     tool('greet', {
+      // Every model-visible tool declares a title: hosts show it in tool pickers and confirmation
+      // prompts, and both consumer directories reject tools without one.
+      title: 'Greet someone',
       description: 'Greet someone by name.',
       input: z.object({
         // Defaults are advertised to the model and applied at runtime when the argument is omitted.