@frontmcp/skills 1.3.0 → 1.4.0

package/catalog/create-tool/references/error-handling.md

@@ -0,0 +1,128 @@
+---
+name: error-handling
+description: this.fail, MCP error classes, error flow — when to throw vs fail.
+---
+
+# Error handling
+
+## The rule
+
+**Don't `try/catch` around `execute()`** ([rule](../rules/no-try-catch-around-execute.md)). The framework's flow catches exceptions, formats them into proper JSON-RPC errors, runs error hooks, and emits notifications. Wrapping the body defeats all of that.
+
+```typescript
+// ❌ swallows the error, breaks the framework's flow
+async execute(input: Input) {
+  try {
+    const result = await someOperation();
+    return result;
+  } catch (err) {
+    this.fail(err instanceof Error ? err : new Error(String(err)));
+  }
+}
+
+// ✅ let it propagate
+async execute(input: Input) {
+  return await someOperation();
+}
+```
+
+## Business-logic errors → `this.fail`
+
+For errors the user / agent should see (not-found, permission-denied, invalid-input, conflict, etc.), use `this.fail(new SomeMcpError(…))`:
+
+```typescript
+async execute(input: { id: string }) {
+  const record = await this.findRecord(input.id);
+  if (!record) {
+    this.fail(new ResourceNotFoundError(`record:${input.id}`));
+    // ↑ never returns; flow aborts here
+  }
+  // … keep going with `record` (typed as non-null because fail() doesn't return)
+}
+```
+
+`this.fail` throws internally and never returns — TypeScript knows it's a `never`-returning method.
+
+## Infrastructure errors → propagate
+
+For errors the framework should handle uniformly (network failure, DB unavailable, timeout), just let them throw. The framework wraps them in an `InternalMcpError` with the message redacted before reaching the client, and logs the original for ops.
+
+## MCP error classes
+
+All from `@frontmcp/sdk`. The two roots: `PublicMcpError` (message reaches the client verbatim) and `InternalMcpError` (message is redacted; full details go to logs).
+
+| Class                   | Error code                               | HTTP | When                                                              |
+| ----------------------- | ---------------------------------------- | ---- | ----------------------------------------------------------------- |
+| `PublicMcpError`        | —                                        | —    | Base for public errors. Subclass for domain-specific cases.       |
+| `InternalMcpError`      | —                                        | —    | Base for redacted infra errors                                    |
+| `ResourceNotFoundError` | `'RESOURCE_NOT_FOUND'` (-32002 JSON-RPC) | 404  | A specific resource doesn't exist                                 |
+| `ToolNotFoundError`     | `'TOOL_NOT_FOUND'`                       | 404  | Tool name not registered                                          |
+| `InvalidInputError`     | `'INVALID_INPUT'`                        | 400  | Cross-field / business-rule input invalid (Zod handles per-field) |
+| `InvalidMethodError`    | `'INVALID_METHOD'`                       | 400  | Wrong protocol method called                                      |
+| `UnauthorizedError`     | `'UNAUTHORIZED'` (-32001 JSON-RPC)       | 401  | Missing credentials                                               |
+| `EntryUnavailableError` | `'FORBIDDEN'` (-32003 JSON-RPC)          | 403  | `availableWhen` mismatch at call time                             |
+| `RateLimitError`        | `'RATE_LIMIT_EXCEEDED'`                  | 429  | Rate-limit fired                                                  |
+| `QuotaExceededError`    | `'QUOTA_EXCEEDED'`                       | 429  | Quota-style limit fired                                           |
+| `PayloadTooLargeError`  | `'PAYLOAD_TOO_LARGE'`                    | 413  | Body limit exceeded                                               |
+
+`MCP_ERROR_CODES` is the JSON-RPC numeric-code constant map (`UNAUTHORIZED: -32001`, `RESOURCE_NOT_FOUND: -32002`, `FORBIDDEN: -32003`, `INVALID_PARAMS: -32602`, `INTERNAL_ERROR: -32603`, etc.). The classes use string error codes; the numeric codes appear on the JSON-RPC wire response.
+
+```typescript
+import { InvalidInputError, MCP_ERROR_CODES, PublicMcpError, ResourceNotFoundError } from '@frontmcp/sdk';
+
+this.fail(new ResourceNotFoundError(`record:${input.id}`));
+this.fail(new InvalidInputError('start must be before end'));
+```
+
+## Custom error classes
+
+Subclass `PublicMcpError` for domain-specific errors:
+
+```typescript
+class QuotaExceededError extends PublicMcpError {
+  readonly mcpErrorCode = -32100; // any custom code outside the reserved JSON-RPC ranges
+
+  constructor(public readonly remaining: number) {
+    super(`Quota exceeded — ${remaining} requests left in window`);
+  }
+
+  toJsonRpcError() {
+    return {
+      code: this.mcpErrorCode,
+      message: this.getPublicMessage(),
+      data: { remaining: this.remaining },
+    };
+  }
+}
+
+// usage
+this.fail(new QuotaExceededError(0));
+```
+
+The `data` payload lets you surface structured info to the client (rate-limit remaining, validation field errors, etc.) without leaking internals.
+
+## `PublicMcpError` vs raw `Error`
+
+| Throw                                  | Client sees                                                             |
+| -------------------------------------- | ----------------------------------------------------------------------- |
+| `new PublicMcpError('Quota exceeded')` | `{ code: -32603, message: 'Quota exceeded' }`                           |
+| `new Error('Quota exceeded')`          | `{ code: -32603, message: 'Internal error' }` (the message is REDACTED) |
+
+Raw `Error`s have their messages **redacted** before reaching the client — the framework treats them as potentially-sensitive infrastructure errors. For anything the client should read, use `PublicMcpError` or a subclass.
+
+## Non-null assertions are forbidden
+
+```typescript
+// ❌ masks failures
+const rec = this.defs.get(token)!;
+
+// ✅ proper handling
+const rec = this.defs.get(token);
+if (!rec) this.fail(new ResourceNotFoundError(`def:${token}`));
+```
+
+## See also
+
+- [`rules/no-try-catch-around-execute.md`](../rules/no-try-catch-around-execute.md)
+- [`rules/use-this-fail-for-business-errors.md`](../rules/use-this-fail-for-business-errors.md)
+- [`execution-context.md`](./execution-context.md)

package/catalog/create-tool/references/execution-context.md

@@ -0,0 +1,158 @@
+---
+name: execution-context
+description: What ToolContext provides at runtime — this.get, this.fetch, this.notify, this.context.
+---
+
+# `ToolContext` runtime API
+
+`ToolContext` extends `ExecutionContextBase`. Inside `execute()` you have access to:
+
+## Methods
+
+| Method                                                           | Purpose                                                                                                        |
+| ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `execute(input: In): Promise<Out>`                               | The method you implement                                                                                       |
+| `this.get(token)`                                                | Resolve a DI dependency. Throws `DependencyNotFoundError` if not registered.                                   |
+| `this.tryGet(token)`                                             | Resolve a DI dependency. Returns `undefined` if not registered.                                                |
+| `this.fail(err)`                                                 | Abort execution, trigger the error flow. **Never returns.** Use for business-logic errors.                     |
+| `this.respond(value)`                                            | Early-return with a value. Validates against `outputSchema`. **Never returns** (throws `FlowControl.respond`). |
+| `this.mark(stage)`                                               | Set the active execution stage for debugging / tracing                                                         |
+| `this.fetch(input, init?)`                                       | HTTP fetch with context propagation (trace headers, etc.)                                                      |
+| `this.notify(message, level?)`                                   | Send a log-level notification to the client                                                                    |
+| `this.progress(progress, total?, message?)`                      | Send a progress notification. Returns `Promise<boolean>` (false when no progress token in request)             |
+| `this.notifyResourceUpdated(uri)`                                | Tell subscribed clients a resource's contents changed (`notifications/resources/updated`)                      |
+| `this.notifyResourceListChanged()`                               | Tell clients the resource list changed (`notifications/resources/list_changed`)                                |
+| `this.elicit(message, schema)`                                   | Request interactive input from the user mid-execution. See [`elicitation.md`](./elicitation.md)                |
+| `this.isPlatform(os)` / `this.isRuntime(rt)` / `this.isEnv(env)` | Imperative platform checks (declarative form is `availableWhen` — see [`availability.md`](./availability.md))  |
+
+## Properties
+
+| Property        | Type                  | Description                                                                                                                                                                |
+| --------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `this.input`    | `In`                  | The validated input object (same value as the `input` parameter)                                                                                                           |
+| `this.output`   | `Out \| undefined`    | The output value (available after `execute()` returns)                                                                                                                     |
+| `this.metadata` | tool metadata         | Frozen view of the `@Tool({...})` config                                                                                                                                   |
+| `this.scope`    | scope instance        | The current scope — DI lookups, child scopes                                                                                                                               |
+| `this.context`  | `FrontMcpContext`     | Per-request context (see below)                                                                                                                                            |
+| `this.auth`     | `FrontMcpAuthContext` | User identity & claims — `this.auth.user.sub`, `this.auth.claims['…']`, `hasRole()`, `hasPermission()`, `hasScope()`. Use this (not `this.context.authInfo`) for identity. |
+
+## `this.context` (FrontMcpContext)
+
+| Property       | Type              | Description                                                                                                                                                                                              |
+| -------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `requestId`    | `string`          | Unique ID for this request                                                                                                                                                                               |
+| `sessionId`    | `string`          | Session identifier (for stateful transports)                                                                                                                                                             |
+| `scopeId`      | `string`          | Scope identifier (for multi-app servers)                                                                                                                                                                 |
+| `authInfo`     | `AuthInfo`        | Raw validated access token — `token`, `clientId`, `scopes`, `expiresAt?`, `resource?`, `extra?`. For user identity / JWT claims use `this.auth` (`this.auth.user.sub`, `this.auth.claims['…']`) instead. |
+| `traceContext` | `TraceContext`    | Distributed-tracing context (propagated to `this.fetch` automatically)                                                                                                                                   |
+| `timestamp`    | `number`          | Request start timestamp                                                                                                                                                                                  |
+| `metadata`     | `RequestMetadata` | Request headers, client IP, MCP client name/version                                                                                                                                                      |
+
+## DI: `this.get` vs `this.tryGet`
+
+```typescript
+import { Token } from '@frontmcp/di';
+
+interface UserService { findById(id: string): Promise<User | null>; }
+const USER_SERVICE: Token<UserService> = Symbol('UserService');
+
+async execute(input: { userId: string }) {
+  // Throws DependencyNotFoundError if USER_SERVICE isn't registered in scope
+  const users = this.get(USER_SERVICE);
+
+  // Returns undefined if not registered — for optional deps
+  const cache = this.tryGet(CACHE);
+  if (cache) {
+    const cached = await cache.get(input.userId);
+    if (cached) return cached;
+  }
+
+  const user = await users.findById(input.userId);
+  if (!user) this.fail(new ResourceNotFoundError(`user:${input.userId}`));
+  return user;
+}
+```
+
+Use `this.get` (throws) when the tool genuinely requires the dependency. Use `this.tryGet` (returns undefined) when the tool degrades gracefully without it (e.g., optional cache, optional metrics emitter).
+
+## HTTP: `this.fetch`
+
+`this.fetch` is a thin wrapper around the standard `fetch` that propagates the request's `traceContext` so downstream services can stitch the call into the same trace.
+
+```typescript
+async execute(input: { url: string }) {
+  const response = await this.fetch(input.url);
+  if (!response.ok) {
+    this.fail(new InternalMcpError(`upstream returned ${response.status}`));
+  }
+  return response.json();
+}
+```
+
+It accepts the same arguments as standard `fetch`:
+
+```typescript
+this.fetch(url, {
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify(payload),
+  signal: AbortSignal.timeout(5_000),
+});
+```
+
+> Don't `try/catch` around the fetch and swallow errors — let infrastructure errors propagate to the framework. Only use `this.fail` for **business-logic** errors. See [`error-handling.md`](./error-handling.md).
+
+## Notifications: `this.notify` + `this.progress`
+
+```typescript
+async execute(input: { items: string[] }) {
+  this.mark('validation');
+  // …
+  this.mark('processing');
+  for (let i = 0; i < input.items.length; i++) {
+    await this.progress(i + 1, input.items.length, `Processing ${input.items[i]}`);
+    await this.processItem(input.items[i]);
+  }
+  await this.notify(`Processed ${input.items.length} items`, 'info');
+  this.mark('complete');
+  return { processed: input.items.length };
+}
+```
+
+- `this.notify(msg, level?)` — sends `notifications/message` to the client (`debug` / `info` / `warning` / `error`). Always-best-effort.
+- `this.progress(n, total?, msg?)` — sends `notifications/progress` IF the request had a progress token. Returns `false` when no token was provided (so the call costs almost nothing if nobody's listening).
+- `this.mark(stage)` — server-side breadcrumb, surfaced in logs / metrics / traces. No client notification.
+- `this.notifyResourceUpdated(uri)` — sends `notifications/resources/updated` to every session subscribed to `uri` (via `resources/subscribe`); no-op for non-subscribers. Call it when a tool mutates state that backs a `@Resource` so subscribers re-fetch.
+- `this.notifyResourceListChanged()` — broadcasts `notifications/resources/list_changed` so clients re-run `resources/list`. Call it after a tool adds or removes resources at runtime.
+
+```typescript
+async execute(input: { id: string; title: string }) {
+  await this.get(NOTES).save(input.id, input.title);
+  this.notifyResourceUpdated(`notes://${input.id}`); // subscribers re-fetch this resource
+  return { ok: true };
+}
+```
+
+See [`18-tool-with-progress-and-notify`](../examples/18-tool-with-progress-and-notify.md).
+
+## Early return: `this.respond`
+
+Both `return value` and `this.respond(value)` validate against `outputSchema`. `this.respond` throws an internal `FlowControl.respond` and never returns — useful for early-exit branches:
+
+```typescript
+async execute(input: Input) {
+  const cached = await this.tryGet(CACHE)?.get(input.key);
+  if (cached) this.respond(cached);   // never returns; just for early exit
+
+  const result = await this.compute(input);
+  return result;
+}
+```
+
+> `this.respond` doesn't bypass `outputSchema` — its argument is validated like a normal return value.
+
+## See also
+
+- [`error-handling.md`](./error-handling.md)
+- [`auth-providers.md`](./auth-providers.md) — `this.authProviders` (and `this.auth` for user identity / claims)
+- [`elicitation.md`](./elicitation.md) — `this.elicit`

package/catalog/create-tool/references/file-layout.md

@@ -0,0 +1,96 @@
+---
+name: file-layout
+description: Flat sibling vs folder-per-tool layouts. <name>.schema.ts / <name>.tool.ts / <name>.tool.spec.ts.
+---
+
+# File layout for tools
+
+Two endorsed layouts. Pick based on tool count per app and whether each tool has local helpers / fixtures / error types.
+
+## Flat siblings (≤3 tools per app, or each tool fits in one screen)
+
+```text
+src/apps/main/tools/
+├── get-weather.tool.ts        # @Tool class, execute()
+├── get-weather.schema.ts      # input/output schemas + derived types
+├── get-weather.tool.spec.ts   # unit tests
+├── greet-user.tool.ts
+├── greet-user.schema.ts
+└── greet-user.tool.spec.ts
+```
+
+## Folder-per-tool (>3 tools per app, or tool has helpers / fixtures / errors)
+
+```text
+src/apps/main/tools/
+├── get-weather/
+│   ├── get-weather.tool.ts        # @Tool class, execute()
+│   ├── get-weather.schema.ts      # input/output schemas + derived types
+│   ├── get-weather.tool.spec.ts   # unit tests
+│   ├── get-weather.errors.ts      # GetWeatherUnavailableError etc.
+│   ├── get-weather.fixtures.ts    # test fixtures, shared with the spec
+│   ├── helpers.ts                 # tool-local utility functions
+│   ├── index.ts                   # barrel re-export
+│   └── get-weather.widget.tsx     # optional UI widget (if ui: { file: … })
+└── greet-user/
+    └── …
+```
+
+`index.ts` for the folder layout:
+
+```typescript
+// src/apps/main/tools/get-weather/index.ts
+export { GetWeatherTool } from './get-weather.tool';
+export {
+  inputSchema as getWeatherInputSchema,
+  outputSchema as getWeatherOutputSchema,
+  type GetWeatherInput,
+  type GetWeatherOutput,
+} from './get-weather.schema';
+```
+
+## File-name conventions
+
+| File                  | Purpose                                                                                      |
+| --------------------- | -------------------------------------------------------------------------------------------- |
+| `<name>.tool.ts`      | The `@Tool`-decorated class (or `tool({...})(handler)` value)                                |
+| `<name>.schema.ts`    | `inputSchema`, `outputSchema`, and the derived `Input` / `Output` types                      |
+| `<name>.tool.spec.ts` | Unit test (jest). NOT `.test.ts` — see [CLAUDE.md test-file-naming rule](../../../CLAUDE.md) |
+| `<name>.widget.tsx`   | Optional UI widget — `.widget.tsx` is excluded from server typecheck (#445 fix)              |
+| `<name>.errors.ts`    | Optional — custom `PublicMcpError` subclasses for this tool                                  |
+| `<name>.fixtures.ts`  | Optional — test fixtures the spec imports                                                    |
+
+## Why split schema and tool?
+
+```typescript
+// ✅ Schema in its own file — re-importable by:
+// - the tool itself
+// - the .tool.spec.ts file
+// - sibling tools (e.g. the create-X tool may share a schema field with the update-X tool)
+// - generated clients
+// - elicitation flows that reuse the same Zod field
+
+// src/apps/main/tools/get-weather.schema.ts
+export const inputSchema = { city: z.string() };
+export const outputSchema = { temperatureF: z.number() };
+export type GetWeatherInput = ToolInputOf<{ inputSchema: typeof inputSchema }>;
+export type GetWeatherOutput = ToolOutputOf<{ outputSchema: typeof outputSchema }>;
+```
+
+If you hoisted the entire `@Tool({...})` config, consumers would drag the `@Tool` decorator transitively. Schemas alone are inert.
+
+## Naming
+
+- File names: `kebab-case` — `get-weather.tool.ts`.
+- Class names: `PascalCase` — `GetWeatherTool`. The `Tool` suffix is conventional, not required.
+- Tool `name:` field: `snake_case` — `get_weather`. MCP protocol convention. ([rule](../rules/snake-case-tool-names.md))
+
+## Widget files
+
+`.tsx` / `.jsx` widget files use the `*.widget.tsx` naming convention. The scaffolded `tsconfig.json` excludes `**/*.widget.tsx` from the server typecheck (#445 fix) — widgets are bundled separately by `@frontmcp/uipack` (esbuild) at render time, with React loaded externally. If you want IDE typecheck for widget sources, add a sibling `tsconfig.widget.json` with `jsx: 'react-jsx'` and `include: ['src/**/*.widget.tsx']`.
+
+## See also
+
+- [`derived-types.md`](./derived-types.md) — why schemas hoist
+- [`testing.md`](./testing.md) — `.tool.spec.ts` patterns
+- [`ui-widgets.md`](./ui-widgets.md) — widget file conventions

package/catalog/create-tool/references/function-style-builder.md

@@ -0,0 +1,118 @@
+---
+name: function-style-builder
+description: tool({...})(handler) — when to pick over a class, register, ctx parameter.
+---
+
+# Function-style tools — `tool({...})(handler)`
+
+For simple tools that don't need DI, lifecycle hooks, or UI widgets, the `tool()` function builder is a one-liner alternative to a class.
+
+## Shape
+
+```typescript
+import { tool, z } from '@frontmcp/sdk';
+
+const AddNumbers = tool({
+  name: 'add_numbers',
+  description: 'Add two numbers',
+  inputSchema: {
+    a: z.number().describe('First number'),
+    b: z.number().describe('Second number'),
+  },
+  outputSchema: 'number',
+})((input) => input.a + input.b);
+```
+
+Register it the same way as a class tool:
+
+```typescript
+@App({ name: 'main', tools: [AddNumbers] })
+class MainApp {}
+```
+
+## With `ctx`
+
+The handler receives `(input, ctx)`. `ctx` is the tool's `ToolContext`, but from an external `(input, ctx) => …` handler you can only reach its **public** surface — the same members a class tool reaches via `this.*` that aren't `protected`:
+
+```typescript
+import { PublicMcpError } from '@frontmcp/sdk';
+
+const GetCurrentUser = tool({
+  name: 'get_current_user',
+  description: 'Return the authenticated user',
+  inputSchema: {},
+  outputSchema: { id: z.string(), email: z.string().email() },
+})(async (_input, ctx) => {
+  // Identity comes from `ctx.auth` (not `ctx.context.authInfo`, which is the raw access token).
+  const userId = ctx.auth.user?.sub;
+  // `ctx.fail(...)` is protected → not callable here. Throw a PublicMcpError instead.
+  if (!userId) throw new PublicMcpError('No authenticated user');
+  const users = ctx.get(USER_SERVICE);
+  return users.findById(userId);
+});
+```
+
+`ctx` provides (public): `get`, `tryGet`, `mark`, `fetch`, `respond`, `context`, `scope`, `input`, `metadata`, `isPlatform`, `isRuntime`, `isEnv`, `callTool`, `auth`, `config`, `clientInfo`, `platform`.
+
+> `fail`, `notify`, `progress`, and `elicit` are **`protected`** on `ToolContext` — they're reachable only from inside a class tool's `execute()` (via `this.*`), **not** from an external function-builder handler (calling them on `ctx` is a compile error). To signal a failure from a function tool, `throw new PublicMcpError(...)`. If you need `notify` / `progress` / `elicit`, use a class tool.
+
+## When to pick which
+
+| Class (`@Tool` + `extends ToolContext`)           | Function (`tool({...})(handler)`)      |
+| ------------------------------------------------- | -------------------------------------- |
+| Needs DI (`this.get`) — most production tools     | Pure-input math / formatting / parsing |
+| Needs lifecycle / hooks                           | One-off conversions                    |
+| Needs a `ui:` widget                              | No bridge / no widget                  |
+| Wants a `.tool.spec.ts` with module-level helpers | Spec testing via simple closure        |
+| Needs to be extended / decorated                  | Standalone                             |
+
+**Default to class.** Pick function only for tools that are trivially short AND don't need DI.
+
+## Async vs sync
+
+The handler can be sync or async — both are fine:
+
+```typescript
+tool({ … })((input) => input.a + input.b);              // sync
+tool({ … })(async (input, ctx) => { /* … */ });          // async
+```
+
+## All the decorator options work
+
+`rateLimit`, `concurrency`, `timeout`, `annotations`, `authProviders`, `availableWhen`, `examples`, `visibility` (and the deprecated `hideFromDiscovery` alias) are all valid on the function builder:
+
+```typescript
+const SendEmail = tool({
+  name: 'send_email',
+  description: 'Send an email via SendGrid',
+  inputSchema: { to: z.string().email(), subject: z.string(), body: z.string() },
+  outputSchema: { messageId: z.string() },
+  rateLimit: { maxRequests: 100, windowMs: 60_000 },
+  authProviders: ['sendgrid'],
+  annotations: { openWorldHint: true },
+})(async (input, ctx) => {
+  const headers = await ctx.authProviders.headers('sendgrid');
+  // …
+});
+```
+
+The `ui:` block also works:
+
+```typescript
+const ShowCard = tool({
+  name: 'show_card',
+  inputSchema: { text: z.string() },
+  outputSchema: { text: z.string() },
+  ui: {
+    template: (ctx) => `<div>${ctx.helpers.escapeHtml(ctx.output.text)}</div>`,
+  },
+})((input) => ({ text: input.text }));
+```
+
+…but at that point, you usually want a class for the file layout and `.tool.spec.ts` ergonomics.
+
+## See also
+
+- [`02-basic-function-tool`](../examples/02-basic-function-tool.md)
+- [`execution-context.md`](./execution-context.md) — same surface available on `ctx`
+- [`registration.md`](./registration.md)

package/catalog/create-tool/references/input-schema.md

@@ -0,0 +1,141 @@
+---
+name: input-schema
+description: Define the tool's input contract — raw Zod shapes, refinements, defaults, optional fields.
+---
+
+# `inputSchema` reference
+
+The `inputSchema` field on `@Tool({...})` accepts a **Zod raw shape** — a plain object mapping field names to Zod types. The framework wraps it in `z.object(...)` internally and validates every call.
+
+## The raw-shape rule
+
+```typescript
+// ✅ Raw shape
+@Tool({
+  name: 'search',
+  inputSchema: {
+    query: z.string().min(1),
+    limit: z.number().int().min(1).max(100).default(10),
+  },
+})
+
+// ❌ z.object() at the top level
+@Tool({
+  name: 'search',
+  inputSchema: z.object({
+    query: z.string(),
+  }),
+})
+```
+
+See [`rules/input-schema-is-raw-shape.md`](../rules/input-schema-is-raw-shape.md). The wrapper is the framework's job — wrapping it yourself confuses the type inference and breaks `ToolInputOf<>`.
+
+## Field types
+
+| Want                | Zod                                                                      |
+| ------------------- | ------------------------------------------------------------------------ |
+| Required string     | `z.string()`                                                             |
+| Optional string     | `z.string().optional()`                                                  |
+| String with default | `z.string().default('hello')`                                            |
+| Bounded number      | `z.number().int().min(1).max(100)`                                       |
+| Number with default | `z.number().default(10)`                                                 |
+| Enum                | `z.enum(['a', 'b', 'c'])`                                                |
+| Array               | `z.array(z.string())`                                                    |
+| Nested object       | `z.object({ city: z.string() })` (Zod object **inside** a field is fine) |
+| Discriminated union | `z.discriminatedUnion('kind', […])`                                      |
+| Date                | `z.string().datetime()` (ISO 8601) or `z.date()`                         |
+| URL                 | `z.string().url()`                                                       |
+| Email               | `z.string().email()`                                                     |
+| Refined             | `z.string().refine((v) => v.length % 2 === 0, 'must be even length')`    |
+| Branded             | `z.string().brand<'UserId'>()`                                           |
+
+> Only the **top-level** `inputSchema` must be a raw shape. Nested objects use `z.object({...})` normally.
+
+## Descriptions
+
+Every field should carry `.describe('…')` — it's shown to AI clients in `tools/list`, helping them choose argument values:
+
+```typescript
+inputSchema: {
+  city: z.string().describe('City name, e.g. "Seattle" or "Tel Aviv"'),
+  units: z.enum(['celsius', 'fahrenheit']).default('celsius').describe('Temperature units'),
+}
+```
+
+## Optional vs default
+
+```typescript
+inputSchema: {
+  // Required — caller must provide
+  query: z.string(),
+
+  // Optional — execute() sees `string | undefined`
+  category: z.string().optional(),
+
+  // Optional with default — execute() sees `string` (the default fills in)
+  limit: z.number().default(10),
+}
+```
+
+## Refinements
+
+For cross-field validation, wrap individual fields:
+
+```typescript
+inputSchema: {
+  start: z.string().datetime(),
+  end: z.string().datetime(),
+  // single-field refinements:
+  email: z.string().email().refine((v) => v.endsWith('@example.com'), 'must be a corporate email'),
+}
+```
+
+For cross-field refinements (`start < end`), keep `inputSchema` simple and validate in `execute()`:
+
+```typescript
+async execute(input: { start: string; end: string }) {
+  if (input.start >= input.end) {
+    this.fail(new InvalidInputError('start must be before end'));
+  }
+  // …
+}
+```
+
+(Or use a custom `.transform` / `.refine` on a wrapped `z.object({...})` _outside_ `inputSchema` and pass `.shape` — but that's usually overkill.)
+
+## Empty input
+
+A no-input tool declares an empty shape:
+
+```typescript
+@Tool({
+  name: 'ping',
+  inputSchema: {},
+  outputSchema: 'string',
+})
+class PingTool extends ToolContext {
+  execute(): string {
+    return 'pong';
+  }
+}
+```
+
+## Where the validated input lives
+
+After validation, `execute(input)` receives the typed/defaulted input. It's also available via `this.input` if you'd rather:
+
+```typescript
+async execute(_input: SearchInput) {
+  // these are equivalent:
+  const fromArg = _input.query;
+  const fromCtx = this.input.query;
+}
+```
+
+Prefer the parameter — it's typed without needing the `ToolInputOf<>` annotation on `this.input`.
+
+## See also
+
+- [`output-schema.md`](./output-schema.md)
+- [`derived-types.md`](./derived-types.md)
+- [`rules/input-schema-is-raw-shape.md`](../rules/input-schema-is-raw-shape.md)