@frontmcp/skills 1.3.0 → 1.4.0

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

@@ -0,0 +1,175 @@
+---
+name: output-schema
+description: Define the tool's output contract — Zod shape, primitives, media, multi-content arrays.
+---
+
+# `outputSchema` reference
+
+`outputSchema` is **always required** ([rule](../rules/always-define-output-schema.md)). It declares what `execute()` returns and gives the framework permission to strip any fields you didn't declare — the safety net against accidental PII / token / debug-trace leaks.
+
+## Supported shapes
+
+| Shape                 | Use for                                                                     | Returns                                                            |
+| --------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| **Zod raw shape**     | Structured JSON                                                             | `{ field: z.string(), count: z.number() }`                         |
+| **Zod schema**        | Complex types (unions, discriminated unions, arrays of objects, transforms) | `z.object({…})`, `z.array(…)`, `z.discriminatedUnion('kind', […])` |
+| **Primitive literal** | Single value                                                                | `'string'`, `'number'`, `'boolean'`, `'date'`                      |
+| **Media literal**     | Binary / link content                                                       | `'image'`, `'audio'`, `'resource'`, `'resource_link'`              |
+| **Array of literals** | Multi-content response                                                      | `['string', 'image']` — text + image in one response               |
+
+## Zod raw shape (most common)
+
+```typescript
+const outputSchema = {
+  temperatureF: z.number(),
+  conditions: z.string(),
+  humidityPct: z.number().int().min(0).max(100),
+};
+
+@Tool({ name: 'get_weather', inputSchema, outputSchema })
+class GetWeatherTool extends ToolContext {
+  async execute(input: GetWeatherInput): Promise<GetWeatherOutput> {
+    const data = await this.fetch(`https://api.weather.example/${input.city}`).then((r) => r.json());
+    // Even if `data` contains { temperatureF, conditions, internalApiKey, debugTrace, … }
+    // only temperatureF / conditions / humidityPct flow through.
+    return data;
+  }
+}
+```
+
+## Zod schema (full Zod)
+
+When the output is a union, discriminated union, or array of objects:
+
+```typescript
+const outputSchema = z.discriminatedUnion('kind', [
+  z.object({ kind: z.literal('user'), id: z.string(), name: z.string() }),
+  z.object({ kind: z.literal('group'), id: z.string(), members: z.array(z.string()) }),
+]);
+
+@Tool({ name: 'resolve_principal', inputSchema, outputSchema })
+class ResolvePrincipalTool extends ToolContext {
+  async execute(input: { handle: string }) {
+    return { kind: 'user' as const, id: 'u_1', name: 'Ada' };
+  }
+}
+```
+
+`z.object()` is fine here — it's only the **top-level `inputSchema`** that must be a raw shape, not `outputSchema`.
+
+## Primitive literals
+
+For single-value outputs:
+
+```typescript
+@Tool({ name: 'add', inputSchema: { a: z.number(), b: z.number() }, outputSchema: 'number' })
+class AddTool extends ToolContext {
+  execute(input: { a: number; b: number }): number {
+    return input.a + input.b;
+  }
+}
+
+@Tool({ name: 'now', inputSchema: {}, outputSchema: 'date' })
+class NowTool extends ToolContext {
+  execute(): Date {
+    return new Date();
+  }
+}
+```
+
+## Media literals
+
+Binary content or links to MCP resources:
+
+```typescript
+@Tool({ name: 'render_chart', inputSchema, outputSchema: 'image' })
+class RenderChartTool extends ToolContext {
+  async execute(input: ChartInput): Promise<{ type: 'image'; data: string; mimeType: string }> {
+    return {
+      type: 'image' as const, // required — without it the content block is dropped
+      data: 'iVBORw0KGgoAAAANSU…', // base64
+      mimeType: 'image/png',
+    };
+  }
+}
+```
+
+Each return object must carry the matching `type` discriminator (`'image'`, `'audio'`, `'resource'`, `'resource_link'`) — without it the content block is silently dropped:
+
+| Literal           | Return shape                                                                                   |
+| ----------------- | ---------------------------------------------------------------------------------------------- |
+| `'image'`         | `{ type: 'image', data: base64String, mimeType: 'image/png' \| 'image/jpeg' \| … }`            |
+| `'audio'`         | `{ type: 'audio', data: base64String, mimeType: 'audio/wav' \| 'audio/mpeg' \| … }`            |
+| `'resource'`      | `{ type: 'resource', resource: { uri: 'custom://…', mimeType?, text? \| blob? } }`             |
+| `'resource_link'` | `{ type: 'resource_link', uri: 'custom://…' }` (link only — host fetches via `resources/read`) |
+
+See [`26-tool-with-resource-link-output`](../examples/26-tool-with-resource-link-output.md) for the resource-link pattern.
+
+## Multi-content arrays
+
+Some tools return more than one block — e.g. a text summary plus an image:
+
+```typescript
+@Tool({ name: 'analyze_image', inputSchema, outputSchema: ['string', 'image'] })
+class AnalyzeImageTool extends ToolContext {
+  async execute(input: { imageUrl: string }): Promise<[string, { type: 'image'; data: string; mimeType: string }]> {
+    const summary = 'Detected: 2 people, 1 cat.';
+    const annotated = await this.annotate(input.imageUrl);
+    return [summary, { type: 'image' as const, data: annotated, mimeType: 'image/png' }];
+  }
+}
+```
+
+## Advertisement in `tools/list`
+
+Structured object outputs are converted to JSON Schema and advertised on the tool's `outputSchema` in `tools/list` — symmetric with how `inputSchema` is advertised:
+
+- **Advertised:** a Zod raw shape (`{ field: z.string() }`) or a top-level `z.object({...})` — these serialize to a `type: 'object'` JSON Schema.
+- **Not advertised:** primitives (`'string'` / `'number'` / `'boolean'` / `'date'`), media (`'image'` / `'audio'` / `'resource'` / `'resource_link'`), multi-content arrays (`['string', 'image']`), and unions (`z.discriminatedUnion(...)`). These flow through `content` rather than `structuredContent`, and the MCP spec requires `outputSchema` to be a top-level `type: 'object'` — so there is nothing object-shaped to advertise. Runtime output validation still applies to every form.
+
+If a client reports _"Output schema recommended,"_ declare a structured object `outputSchema` (a raw shape or `z.object`) — that's the form that gets advertised.
+
+### Exposure mode
+
+A cascading `output` policy controls _how_ the (object-shaped) schema reaches clients in `tools/list`. Declare it on `@FrontMcp`, `@App`, or `@Tool`:
+
+```typescript
+output?: {
+  schemaMode?: 'definition' | 'description' | 'both' | 'none'; // default 'definition'
+  schemaDescriptionFormat?: 'summary' | 'jsonSchema';          // default 'summary'
+};
+```
+
+| `schemaMode`    | Effect                                                                                  |
+| --------------- | --------------------------------------------------------------------------------------- |
+| `'definition'`  | **Default.** Advertise the schema as the tool's `outputSchema` (JSON Schema).           |
+| `'description'` | Fold a readable rendering of the schema into the tool description; omit `outputSchema`. |
+| `'both'`        | Advertise as `outputSchema` **and** fold it into the description.                       |
+| `'none'`        | Expose nothing — no `outputSchema`, no description suffix.                              |
+
+`schemaDescriptionFormat` controls the rendering for `'description'` / `'both'`: `'summary'` (default) is a compact property list; `'jsonSchema'` is a fenced JSON Schema block.
+
+The effective value resolves with a **Tool > App > server > default** cascade — set a server-wide default on `@FrontMcp` and override per tool. This mirrors the OpenAPI adapter's `outputSchema.mode`.
+
+```typescript
+// This tool folds its schema into the description instead of advertising `outputSchema`
+@Tool({ name: 'get_status', inputSchema, outputSchema, output: { schemaMode: 'description' } })
+class GetStatusTool extends ToolContext {
+  /* … */
+}
+```
+
+The default (`'definition'`) preserves the current behavior described above — omit `output` entirely and nothing changes.
+
+## Why this matters
+
+- **Data leak prevention** — without `outputSchema`, accidentally returning `{ result, internalApiKey }` leaks the key. With it, only `result` flows.
+- **CodeCall compatibility** — the CodeCall plugin uses `outputSchema` to chain tool calls in its VM. Tools without it degrade chain-ability.
+- **Compile-time type safety** — `ToolContext` infers `execute()`'s return type from `outputSchema` (when `ToolOutputOf<>` is used). The compiler catches divergence at build time.
+- **Self-documenting** — a structured object `outputSchema` is converted to JSON Schema and exposed in `tools/list` (see [Advertisement in `tools/list`](#advertisement-in-toolslist)); AI clients pick tools partly based on what they return.
+
+## See also
+
+- [`input-schema.md`](./input-schema.md)
+- [`derived-types.md`](./derived-types.md)
+- [`rules/always-define-output-schema.md`](../rules/always-define-output-schema.md)

package/catalog/create-tool/references/quick-start.md

@@ -0,0 +1,124 @@
+---
+name: quick-start
+description: 60-second tour — minimal tool, schemas, registration, calling it.
+---
+
+# Quick start
+
+Goal: a working tool in five files (schema, tool, app, server, spec) in 60 seconds.
+
+## 1. The schemas (single source of truth)
+
+```typescript
+// src/apps/main/tools/greet-user.schema.ts
+import { ToolInputOf, ToolOutputOf, z } from '@frontmcp/sdk';
+
+export const inputSchema = {
+  name: z.string().describe('The name of the user to greet'),
+};
+
+export const outputSchema = {
+  greeting: z.string(),
+};
+
+export type GreetUserInput = ToolInputOf<{ inputSchema: typeof inputSchema }>;
+export type GreetUserOutput = ToolOutputOf<{ outputSchema: typeof outputSchema }>;
+```
+
+## 2. The tool
+
+```typescript
+// src/apps/main/tools/greet-user.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+
+import { inputSchema, outputSchema, type GreetUserInput, type GreetUserOutput } from './greet-user.schema';
+
+@Tool({
+  name: 'greet_user',
+  description: 'Greet a user by name',
+  inputSchema,
+  outputSchema,
+})
+export class GreetUserTool extends ToolContext {
+  async execute(input: GreetUserInput): Promise<GreetUserOutput> {
+    return { greeting: `Hello, ${input.name}!` };
+  }
+}
+```
+
+## 3. The app
+
+```typescript
+// src/apps/main/index.ts
+import { App } from '@frontmcp/sdk';
+
+import { GreetUserTool } from './tools/greet-user.tool';
+
+@App({
+  name: 'main',
+  tools: [GreetUserTool],
+})
+export class MainApp {}
+```
+
+## 4. The server
+
+```typescript
+// src/main.ts
+import { FrontMcp } from '@frontmcp/sdk';
+
+import { MainApp } from './apps/main';
+
+@FrontMcp({
+  info: { name: 'demo', version: '1.0.0' },
+  apps: [MainApp],
+})
+export default class DemoServer {}
+```
+
+## 5. The test
+
+```typescript
+// src/apps/main/tools/greet-user.e2e.spec.ts
+import { expect, test } from '@frontmcp/testing';
+
+test.use({
+  server: './src/main.ts',
+  port: 3003,
+});
+
+test('greets the user', async ({ mcp }) => {
+  // mcp.tools.call returns a ToolResultWrapper around the MCP CallToolResult —
+  // not the bare return value. Assert on the MCP result, not on `{ greeting }` directly.
+  const result = await mcp.tools.call('greet_user', { name: 'Ada' });
+
+  expect(result).toBeSuccessful();
+  // structuredContent mirrors the typed output schema.
+  expect(result.json()).toEqual({ greeting: 'Hello, Ada!' });
+  // …or assert on the rendered text content.
+  expect(result).toHaveTextContent('Hello, Ada!');
+});
+```
+
+## Run it
+
+```bash
+yarn dev     # starts the server
+yarn test    # runs the spec
+```
+
+## What you just did
+
+- Hoisted the **schemas** to their own file (so specs / generated clients can reuse them).
+- Derived `execute()`'s **input/output types** from the schemas via `ToolInputOf<>` / `ToolOutputOf<>`. The schema is the single source of truth — change a Zod field and the type follows.
+- Used a **raw Zod shape** for `inputSchema` (not `z.object({...})`) — the framework wraps it internally.
+- Always defined an **`outputSchema`**. Without it, any field your code accidentally returns leaks to the client.
+- Registered the tool in an **`@App({ tools })`**, not directly on `@FrontMcp` — apps own modularity and per-app lifecycle / auth.
+- Wrote a test using the **`@frontmcp/testing`** fixture API (`test.use` + `{ mcp }`) — booting the real server and asserting on the MCP `CallToolResult` (via `result.json()` / `toHaveTextContent`), not on a bare return value.
+
+## What's next
+
+- Add a real implementation → read [`execution-context.md`](./execution-context.md) for `this.get`, `this.fetch`, `this.notify`.
+- Return structured / media / multi-content output → [`output-schema.md`](./output-schema.md).
+- Make it interactive with a UI widget → [`ui-widgets.md`](./ui-widgets.md).
+- Pick an example matching your scenario from [`SKILL.md` § Scenario routing table](../SKILL.md#scenario-routing-table).

package/catalog/create-tool/references/registration.md

@@ -0,0 +1,132 @@
+---
+name: registration
+description: @App({ tools }) vs @FrontMcp({ tools }), multi-app composition.
+---
+
+# Registering tools
+
+## Best practice — register in `@App`
+
+```typescript
+// src/apps/main/index.ts
+import { App } from '@frontmcp/sdk';
+
+import { AddNumbersTool, GreetUserTool, SearchDocumentsTool } from './tools';
+
+@App({
+  name: 'main',
+  tools: [GreetUserTool, SearchDocumentsTool, AddNumbersTool],
+})
+export class MainApp {}
+```
+
+```typescript
+// src/main.ts
+import { FrontMcp } from '@frontmcp/sdk';
+
+import { MainApp } from './apps/main';
+
+@FrontMcp({
+  info: { name: 'demo', version: '1.0.0' },
+  apps: [MainApp],
+})
+export default class DemoServer {}
+```
+
+Apps provide:
+
+- **Modularity** — each app is a self-contained surface; you can install / uninstall / disable apps without touching the others.
+- **Per-app auth** — different apps can use different `auth: { mode: 'public' | 'transparent' | 'local' | 'remote' }`.
+- **Per-app providers** — DI tokens registered in `@App({ providers })` are visible only to tools in that app.
+- **Per-app lifecycle hooks** — `onAppStart`, `onAppStop`, etc.
+
+## Escape hatch — top-level `@FrontMcp({ tools })`
+
+For single-app servers, you can register tools directly on `@FrontMcp` instead of declaring an `@App`:
+
+```typescript
+@FrontMcp({
+  info: { name: 'demo', version: '1.0.0' },
+  tools: [GreetUserTool, SearchDocumentsTool],
+})
+export default class DemoServer {}
+```
+
+`@FrontMcp` accepts the same arrays as `@App`: `tools`, `resources`, `prompts`, `providers`, `plugins`, `jobs`, `channels`, `authorities`, `skills`.
+
+Use this for prototypes / very small servers. Promote to an `@App` as soon as you want any of the per-app benefits above.
+
+See [`rules/register-in-app.md`](../rules/register-in-app.md).
+
+## Multi-app composition
+
+Real-world servers have multiple apps. Each app owns its own tools, providers, and (optionally) auth mode:
+
+```typescript
+@FrontMcp({
+  info: { name: 'company-mcp', version: '1.0.0' },
+  apps: [PublicApp, AuthenticatedApp, AdminApp],
+})
+export default class CompanyServer {}
+
+@App({
+  name: 'public',
+  auth: { mode: 'public', anonymousScopes: ['read:public'] },
+  tools: [SearchPublicDocsTool],
+})
+class PublicApp {}
+
+@App({
+  name: 'authenticated',
+  auth: { mode: 'remote', clientId: process.env.OAUTH_CLIENT_ID },
+  tools: [GetMyProfileTool, UpdateMyProfileTool],
+})
+class AuthenticatedApp {}
+
+@App({
+  name: 'admin',
+  auth: { mode: 'remote', requiredScopes: ['admin'] },
+  tools: [DeleteUserTool, GrantRoleTool],
+})
+class AdminApp {}
+```
+
+Tool names must be unique **across the whole server** — even though they live in different apps. The tool name is the lookup key in `tools/call`.
+
+## Tool sharing across apps
+
+Same tool registered in two apps:
+
+```typescript
+@App({ name: 'public',        tools: [SearchTool] })
+@App({ name: 'authenticated', tools: [SearchTool] })
+```
+
+This is fine — the tool instance is constructed per-scope. Each app sees its own. But you'll want different names if the auth posture differs:
+
+```typescript
+@App({ name: 'public',        tools: [SearchPublicTool] })
+@App({ name: 'authenticated', tools: [SearchPrivateTool] })
+```
+
+## Conditional registration
+
+For tools that should only register in certain envs:
+
+```typescript
+@App({
+  name: 'main',
+  tools: [
+    GreetUserTool,
+    ...(process.env.NODE_ENV !== 'production' ? [DebugTool] : []),
+  ],
+})
+```
+
+Better — use `availableWhen: { env: ['development', 'test'] }` on the tool itself. Same effect, plus the constraint is self-documenting on the tool.
+
+## See also
+
+- [`rules/register-in-app.md`](../rules/register-in-app.md)
+- [`availability.md`](./availability.md)
+- `architecture` skill — multi-app patterns, module boundaries, scope / DI tokens

package/catalog/create-tool/references/remote-and-esm.md

@@ -0,0 +1,68 @@
+---
+name: remote-and-esm
+description: Tool.esm / Tool.remote — load tools from ESM URLs or remote MCP servers.
+---
+
+# Remote and ESM tools
+
+Two ways to register tools you don't ship directly in your codebase:
+
+## `Tool.esm(...)` — ESM URL
+
+Loads a tool implementation from an ES module published to npm or hosted on a CDN.
+
+```typescript
+const RemoteTool = Tool.esm('@my-org/tools@^1.0.0', 'MyTool', {
+  description: 'A tool loaded from an ES module',
+});
+
+@App({ name: 'main', tools: [RemoteTool] })
+class MainApp {}
+```
+
+| Arg          | Purpose                                                                                                              |
+| ------------ | -------------------------------------------------------------------------------------------------------------------- |
+| `specifier`  | npm package + optional semver range (`'@my-org/tools@^1.0.0'`) OR a full URL (`'https://esm.sh/@acme/widget@2.1.0'`) |
+| `exportName` | Named export to load from the module                                                                                 |
+| `options`    | Optional override for description / annotations / throttling — the module's defaults are used otherwise              |
+
+The framework loads the module at server startup. Compatibility tip: the loaded module should export a `@Tool`-decorated class or a `tool({...})(handler)` value.
+
+## `Tool.remote(...)` — remote MCP server
+
+Proxies a tool from another MCP server. Tool calls hop through your server to the remote.
+
+```typescript
+const CloudTool = Tool.remote('https://example.com/tools/cloud-tool', 'CloudTool', {
+  description: 'A tool loaded from a remote MCP server',
+});
+
+@App({ name: 'main', tools: [CloudTool] })
+class MainApp {}
+```
+
+| Arg         | Purpose                                    |
+| ----------- | ------------------------------------------ |
+| `serverUrl` | Remote MCP server URL                      |
+| `toolName`  | The remote tool's `name`                   |
+| `options`   | Local overrides (description, annotations) |
+
+The framework establishes a long-lived connection to the remote server at startup and re-uses it for every call. Auth headers from your server's session can be forwarded — configure via the remote-server registration in `@FrontMcp({ remoteServers: [...] })`.
+
+## When to use
+
+| Pattern                      | When                                                                                       |
+| ---------------------------- | ------------------------------------------------------------------------------------------ |
+| `@Tool` (class in your code) | Your tool, your code. The default.                                                         |
+| `Tool.esm(...)`              | Third-party tool packages, internal monorepo tools served via a CDN, shared tool libraries |
+| `Tool.remote(...)`           | Federation — your server exposes a tool that physically lives on another MCP server        |
+
+## Limitations
+
+- **`Tool.esm`**: the loaded module runs in the same Node process. You inherit its dependencies. Pin versions; don't `^` against untrusted modules.
+- **`Tool.remote`**: a remote outage means the proxied tool fails. Pair with `timeout` and consider a fallback. Auth headers may or may not be forwarded depending on your federation config.
+
+## See also
+
+- [`registration.md`](./registration.md)
+- [`decorator-options.md`](./decorator-options.md)

package/catalog/create-tool/references/testing.md

@@ -0,0 +1,59 @@
+---
+name: testing
+description: Per-tool unit tests — pointer to the dedicated `testing` skill for the canonical patterns.
+---
+
+# Per-tool unit testing
+
+Every tool ships with `<name>.tool.spec.ts`. The canonical test surface lives in the dedicated **`testing` skill** — this reference is a short pointer plus the per-tool checklist.
+
+## What `@frontmcp/testing` actually exposes
+
+| Surface                                                      | Purpose                                                    |
+| ------------------------------------------------------------ | ---------------------------------------------------------- |
+| `TestServer` (+ `TestServerOptions`)                         | Boot a real `@FrontMcp({...})` server in-process for tests |
+| `McpTestClient` (+ `McpTestClientBuilder`)                   | Client to talk to the test server                          |
+| `test` (Playwright-style fixture) + `expect` + `mcpMatchers` | Test runner and matchers                                   |
+| `mockResponse`, `httpMock`, `httpResponse`, `interceptors`   | HTTP / outbound mocking                                    |
+| `TestUsers`, `TestTokenFactory`, `AuthHeaders`               | Auth fixtures for authenticated tools                      |
+| `MockOAuthServer`, `MockCimdServer`, `MockAPIServer`         | Mocks for end-to-end auth flows                            |
+
+The `testing` skill is where you'll find:
+
+- The canonical `test({ mcp }) => …` fixture pattern.
+- How to register a single tool / app for a focused test scope.
+- How to assert MCP responses via `mcpMatchers` (`toHaveRenderedHtml`, `toBeXssSafe`, `toContainBoundValue`, etc.).
+- How to mock outbound HTTP with `httpMock` (so `this.fetch` returns deterministic responses).
+- How to inject mock providers for DI tokens.
+- How to drive interactive `this.elicit` flows from a test.
+- How to assert `this.progress` / `this.notify` event streams.
+- E2E patterns (subprocess CLI exec, real-port transports — those live in `apps/e2e/demo-e2e-*/`, not in per-library specs).
+
+## Per-tool unit test — what to cover
+
+For every tool, the spec covers (at minimum):
+
+- [ ] **Happy path** — typical valid input → expected output, with `mcpMatchers` asserting the shape of the response.
+- [ ] **Input-validation rejection** — Zod constraints fire (`min`, `max`, `regex`, `enum`).
+- [ ] **At least one business-logic failure path** — `this.fail(new SomeMcpError(...))` triggers, the client sees the right MCP error code.
+- [ ] **Mocked DI** — providers swapped via the testing harness; verify the tool calls the right service methods.
+- [ ] **(If `this.fetch`)** — outbound HTTP mocked via `httpMock`, asserting URL / headers / body.
+- [ ] **(If `this.elicit`)** — pre-arrange the elicitation response in the test harness and assert the `accept` / `decline` / `cancel` branches.
+- [ ] **(If `this.progress`)** — assert the progress events fire with the expected `current` / `total` values.
+
+## File naming
+
+- `<name>.tool.spec.ts` — never `.test.ts` (the repo enforces `.spec.ts`).
+- Co-located with the tool source — `src/apps/<app>/tools/<name>/<name>.tool.spec.ts` (folder-per-tool layout) OR `src/apps/<app>/tools/<name>.tool.spec.ts` (flat sibling).
+
+## Don't
+
+- Don't boot the full real server (production transport, real auth, real DBs) for a per-tool unit test. Use the testing skill's focused fixtures.
+- Don't assert the precise text of `PublicMcpError` messages. Assert the error class / `errorCode` (e.g. `'RATE_LIMIT_EXCEEDED'`, `'RESOURCE_NOT_FOUND'`) so the test isn't brittle to wording.
+- Don't put end-to-end tests in per-library `__tests__/`. They belong in `apps/e2e/demo-e2e-*/` per the e2e-tests-location rule.
+
+## See also
+
+- `testing` skill — the canonical fixtures, mock patterns, and matchers
+- [`error-handling.md`](./error-handling.md) — error codes to assert against
+- [`execution-context.md`](./execution-context.md) — what `this.*` does, so you know what to mock

package/catalog/create-tool/references/throttling.md

@@ -0,0 +1,109 @@
+---
+name: throttling
+description: rateLimit, concurrency, timeout — semantics, interaction, defaults.
+---
+
+# Throttling — `rateLimit`, `concurrency`, `timeout`
+
+Three independent controls on `@Tool({...})`. Apply them when the tool calls expensive services, holds a scarce resource, or could legitimately hang.
+
+## `rateLimit`
+
+Cap invocations over a time window.
+
+```typescript
+@Tool({
+  name: 'send_notification',
+  // 100 calls / minute, shared across all callers (partitionBy defaults to 'global')
+  rateLimit: { maxRequests: 100, windowMs: 60_000 },
+  // For a per-session limit instead:
+  // rateLimit: { maxRequests: 100, windowMs: 60_000, partitionBy: 'session' },
+  // …
+})
+```
+
+- **Partition**: `partitionBy: 'global'` by default — one shared limit across all callers. To scope the limit per session, set `partitionBy: 'session'` (the session ID becomes the rate-limit key). Other values: `'userId'`, `'ip'`, or a custom `(ctx) => string` function.
+- **Behavior on overflow**: the tool call returns a `RateLimitError` (HTTP status 429, MCP error code `'RATE_LIMIT_EXCEEDED'`). The retry-after hint is carried in the error message string (`Rate limit exceeded. Retry after N seconds`) so clients can back off intelligently.
+- **No half-allowed**: a call either counts fully toward the limit or doesn't run at all. Long-running calls don't block the window — only the start counts.
+
+## `concurrency`
+
+Cap simultaneous in-flight executions.
+
+```typescript
+@Tool({
+  name: 'render_pdf',
+  concurrency: { maxConcurrent: 5 }, // at most 5 PDFs rendering at once
+  // …
+})
+```
+
+- **Scope**: server-wide by default. Concurrency caps the resource — there's no point in per-session concurrency for shared resources like CPU / GPU / DB connection pools.
+- **Behavior on overflow**: the call **queues** until a slot opens. Queue depth is unbounded by default; pair with a `timeout` to avoid pathological backups.
+- **Use for**: tools that hold a real bottleneck — image / PDF rendering, ML inference, DB write transactions.
+
+## `timeout`
+
+Hard deadline on a single execution.
+
+```typescript
+@Tool({
+  name: 'long_query',
+  timeout: { executeMs: 30_000 }, // 30s
+  // …
+})
+```
+
+- **Scope**: per call. Wraps the entire `execute()` invocation.
+- **Behavior on timeout**: the framework throws an `ExecutionTimeoutError` (from `@frontmcp/guard`, code `'EXECUTION_TIMEOUT'`, HTTP status 408) and aborts the wrapped execution. The abort is internal to the timeout guard — it is **not** surfaced into `execute()` as a readable signal, so don't expect to observe it from inside the tool body.
+- **Default**: no timeout. Tools can hang forever unless `timeout` is set.
+
+## Interaction
+
+The three controls are **orthogonal** — they apply independently:
+
+```typescript
+@Tool({
+  name: 'expensive_operation',
+  rateLimit:    { maxRequests: 10, windowMs: 60_000 },  // ≤10 starts / min
+  concurrency:  { maxConcurrent: 2 },                    // ≤2 simultaneous
+  timeout:      { executeMs: 30_000 },                   // ≤30s each
+})
+```
+
+Order of effects per call:
+
+1. `rateLimit` checked → reject early if over limit (no concurrency slot consumed)
+2. `concurrency` checked → queue if all slots taken
+3. `timeout` armed → wraps `execute()` once it runs
+
+## Common combinations
+
+| Scenario                               | Recipe                                                                                                                |
+| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| Spammy external API                    | `rateLimit: { maxRequests: 60, windowMs: 60_000 }` (60/min)                                                           |
+| Shared DB / GPU                        | `concurrency: { maxConcurrent: 5 }`                                                                                   |
+| Anything calling LLMs / 3rd-party HTTP | `timeout: { executeMs: 30_000 }`                                                                                      |
+| All three                              | `rateLimit: { maxRequests: 10, windowMs: 60_000 }, concurrency: { maxConcurrent: 2 }, timeout: { executeMs: 30_000 }` |
+
+## Timeout and abort signals
+
+`timeout` does **not** hand your `execute()` an abort signal — the abort lives inside the timeout guard and is not exposed on the context. `FrontMcpContext` has no `abortSignal` property, so don't reach for `this.context.abortSignal`.
+
+The only tool-level abort signal is `this.signal`, and it is populated **only** for task-augmented `tools/call` invocations (cancelled via `tasks/cancel`) — not by `timeout`. It is `undefined` for ordinary calls, so guard for that:
+
+```typescript
+async execute(input: { url: string }) {
+  // this.signal is defined only for task-augmented calls; undefined otherwise
+  const response = await this.fetch(input.url, { signal: this.signal });
+  return response.json();
+}
+```
+
+For ordinary calls, rely on `this.fetch`'s own per-request timeout (default 30s) to bound in-flight HTTP work; `timeout` then caps the overall `execute()` duration.
+
+## See also
+
+- [`decorator-options.md`](./decorator-options.md)
+- [`error-handling.md`](./error-handling.md)
+- [`execution-context.md`](./execution-context.md)