@frontmcp/skills 1.3.0 → 1.4.1

package/catalog/create-tool/examples/11-tool-with-fetch.md

@@ -0,0 +1,94 @@
+---
+name: 11-tool-with-fetch
+level: intermediate
+description: 'Tool calling an external HTTP API with `this.fetch` — context propagation, status-code handling, and bounding the call with a tool `timeout`.'
+tags: [fetch, http, external-api, error-handling]
+features:
+  - 'Using `this.fetch(url, init?)` so trace context propagates to the upstream service'
+  - 'Translating non-2xx HTTP responses into `PublicMcpError` so the MCP client gets a clean error'
+  - "Bounding the call with a tool `timeout` (and `this.fetch`'s built-in per-request timeout) — without relying on a non-existent context abort signal"
+  - "Letting genuine network errors (DNS failure, ECONNREFUSED) propagate to the framework's error flow"
+---
+
+# Tool With Fetch
+
+Tool calling an external HTTP API with `this.fetch` — context propagation, status-code handling, and bounding the call with a tool `timeout`.
+
+`this.fetch` is the standard `fetch` plus trace-context propagation. Always use it instead of bare `fetch` so distributed tracing stitches the upstream call into the same trace as the MCP request.
+
+## Code
+
+```typescript
+// src/apps/main/tools/get-weather.tool.ts
+import { PublicMcpError, ResourceNotFoundError, Tool, ToolContext, z } from '@frontmcp/sdk';
+
+const inputSchema = {
+  city: z.string().describe('City name, e.g. "Seattle"'),
+  units: z.enum(['celsius', 'fahrenheit']).default('fahrenheit'),
+};
+const outputSchema = {
+  city: z.string(),
+  temperature: z.number(),
+  conditions: z.string(),
+  units: z.enum(['celsius', 'fahrenheit']),
+};
+
+@Tool({
+  name: 'get_weather',
+  description: 'Current weather from api.weather.example',
+  inputSchema,
+  outputSchema,
+  timeout: { executeMs: 10_000 }, // cap the whole call if the upstream hangs
+})
+export class GetWeatherTool extends ToolContext {
+  async execute(input: { city: string; units: 'celsius' | 'fahrenheit' }) {
+    const url = new URL('https://api.weather.example/v1/current');
+    url.searchParams.set('city', input.city);
+    url.searchParams.set('units', input.units);
+
+    const response = await this.fetch(url, {
+      headers: { accept: 'application/json' },
+      // `this.fetch` applies its own request timeout (default 30s). The tool-level
+      // `timeout` below caps the whole execute() at the framework level.
+    });
+
+    if (response.status === 404) {
+      this.fail(new ResourceNotFoundError(`weather:${input.city}`));
+    }
+    if (!response.ok) {
+      this.fail(new PublicMcpError(`Weather API returned ${response.status} ${response.statusText}`));
+    }
+
+    const body = (await response.json()) as { temp: number; summary: string };
+    return {
+      city: input.city,
+      temperature: body.temp,
+      conditions: body.summary,
+      units: input.units,
+    };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Using `this.fetch(url, init?)` so trace context propagates to the upstream service
+- Translating non-2xx HTTP responses into `PublicMcpError` so the MCP client gets a clean error
+- Bounding the call with a tool `timeout` (and `this.fetch`'s built-in per-request timeout) — without relying on a non-existent context abort signal
+- Letting genuine network errors (DNS failure, ECONNREFUSED) propagate to the framework's error flow
+
+## Don't do this
+
+```typescript
+// ❌ swallows network errors, hides infrastructure problems from observability
+async execute(input) {
+  try {
+    const response = await this.fetch(url);
+    return await response.json();
+  } catch (err) {
+    return { error: String(err) };
+  }
+}
+```
+
+Let infrastructure errors propagate. The framework wraps them in `InternalError` (`-32603`) for the client and logs them properly for ops. Only convert specific business-level conditions (status codes you know about) to `this.fail`.

package/catalog/create-tool/examples/12-tool-with-fetch-and-retries.md

@@ -0,0 +1,115 @@
+---
+name: 12-tool-with-fetch-and-retries
+level: advanced
+description: 'Tool calling a flaky external API with exponential backoff retries, an Idempotency-Key for safety, and respect for `Retry-After` on 429s.'
+tags: [fetch, retries, exponential-backoff, idempotency-key, 429-rate-limit]
+features:
+  - Retrying on transient errors (5xx + 429) with exponential backoff plus jitter
+  - "Generating an `Idempotency-Key` so retried POSTs don't duplicate side effects on the upstream"
+  - 'Respecting an upstream `Retry-After` header on 429 responses instead of guessing'
+  - "Capping the total retry budget with `timeout: { executeMs }` so a wedged upstream can't hang the call indefinitely"
+---
+
+# Tool With Fetch And Retries
+
+Tool calling a flaky external API with exponential backoff retries, an Idempotency-Key for safety, and respect for `Retry-After` on 429s.
+
+Real upstreams flake. This shows the pattern that survives them: retry the right errors, back off correctly, generate an idempotency key so retried POSTs don't double-fire, and cap the whole thing with `timeout`.
+
+## Code
+
+```typescript
+// src/apps/main/tools/create-issue.tool.ts
+import { PublicMcpError, Tool, ToolContext, z } from '@frontmcp/sdk';
+import { randomUUID } from '@frontmcp/utils';
+
+const inputSchema = {
+  repo: z.string().regex(/^[^\/]+\/[^\/]+$/, 'expected owner/repo'),
+  title: z.string().min(1).max(256),
+  body: z.string().max(65_536).optional(),
+};
+const outputSchema = { issueNumber: z.number().int().min(1), url: z.string().url() };
+
+const MAX_ATTEMPTS = 4;
+const BASE_DELAY_MS = 200;
+
+@Tool({
+  name: 'create_issue',
+  description: 'Create a GitHub issue (retries on 5xx / 429)',
+  inputSchema,
+  outputSchema,
+  rateLimit: { maxRequests: 30, windowMs: 60_000 },
+  timeout: { executeMs: 30_000 }, // hard cap across all retries
+  annotations: { destructiveHint: false, idempotentHint: true, openWorldHint: true },
+  authProviders: ['github'],
+})
+export class CreateIssueTool extends ToolContext {
+  async execute(input: { repo: string; title: string; body?: string }) {
+    const headers = await this.authProviders.headers('github');
+    const idempotencyKey = randomUUID();
+
+    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+      const response = await this.fetch(`https://api.github.com/repos/${input.repo}/issues`, {
+        method: 'POST',
+        headers: {
+          ...headers,
+          'content-type': 'application/json',
+          'idempotency-key': idempotencyKey,
+        },
+        body: JSON.stringify({ title: input.title, body: input.body }),
+        // `this.fetch` applies its own per-request timeout; the tool-level
+        // `timeout` below caps the whole retry loop at the framework level.
+      });
+
+      if (response.ok) {
+        const data = (await response.json()) as { number: number; html_url: string };
+        return { issueNumber: data.number, url: data.html_url };
+      }
+
+      // Non-retryable client errors → fail immediately
+      if (response.status >= 400 && response.status < 500 && response.status !== 429) {
+        const detail = await response.text();
+        this.fail(new PublicMcpError(`GitHub returned ${response.status}: ${detail.slice(0, 200)}`));
+      }
+
+      // Retryable (5xx or 429) — back off and try again
+      if (attempt === MAX_ATTEMPTS) {
+        this.fail(new PublicMcpError(`GitHub upstream failed after ${MAX_ATTEMPTS} attempts`));
+      }
+
+      // Retry-After is either a number of seconds ("120") or an HTTP-date — handle both.
+      const retryAfter = response.headers.get('retry-after');
+      const retryAfterMs = (() => {
+        if (!retryAfter) return undefined;
+        const seconds = Number(retryAfter);
+        if (Number.isFinite(seconds)) return Math.max(0, seconds * 1_000);
+        const at = Date.parse(retryAfter);
+        return Number.isFinite(at) ? Math.max(0, at - Date.now()) : undefined;
+      })();
+      const baseDelay = retryAfterMs ?? BASE_DELAY_MS * 2 ** (attempt - 1);
+      const jitter = Math.floor(Math.random() * baseDelay * 0.2);
+      await this.notify(
+        `Attempt ${attempt} returned ${response.status}; retrying in ${baseDelay + jitter}ms`,
+        'warning',
+      );
+      await new Promise((r) => setTimeout(r, baseDelay + jitter));
+    }
+    /* unreachable — this.fail above never returns */
+    this.fail(new PublicMcpError('unreachable'));
+  }
+}
+```
+
+## What This Demonstrates
+
+- Retrying on transient errors (5xx + 429) with exponential backoff plus jitter
+- Generating an `Idempotency-Key` so retried POSTs don't duplicate side effects on the upstream
+- Respecting an upstream `Retry-After` header on 429 responses instead of guessing
+- Capping the total retry budget with `timeout: { executeMs }` so a wedged upstream can't hang the call indefinitely
+
+## Why these choices
+
+- **`Idempotency-Key` is critical for POSTs.** Without it, a retry after a network glitch can create two issues. GitHub honors `Idempotency-Key` server-side; many other APIs (Stripe, etc.) do too.
+- **Jitter prevents thundering herds.** All clients retrying at exactly 200ms / 400ms / 800ms create synchronized spikes. ±20% jitter spreads them.
+- **`timeout: { executeMs: 30_000 }` is the safety net.** The retry loop alone can take 200 + 400 + 800 = 1.4s just in backoff. With a slow upstream, total time spirals — the tool-level timeout caps it.
+- **Don't retry 4xx (except 429).** 4xx means "your request is wrong" — retrying won't help and may double up the upstream's accounting.

package/catalog/create-tool/examples/13-tool-with-single-auth-provider.md

@@ -0,0 +1,85 @@
+---
+name: 13-tool-with-single-auth-provider
+level: intermediate
+description: "Tool requiring a single OAuth provider via the `authProviders: ['github']` string shorthand — credentials loaded before `execute()` runs."
+tags: [auth-providers, oauth, github, this.authProviders]
+features:
+  - "Declaring a single required OAuth provider with the `authProviders: ['github']` shorthand"
+  - "Reading pre-formatted credentials via `await this.authProviders.headers('github')`"
+  - "Letting the framework reject calls whose required credential is missing **before** `execute()` runs — a JSON-RPC `-32001` (MCP `UNAUTHORIZED`) error whose `data` carries `{ tool, providers: ['github'], authUrl }` (no auth-check boilerplate)"
+  - 'Trusting the framework to handle token refresh, expiration, and the connect/authorize URL'
+---
+
+# Tool With Single Auth Provider
+
+Tool requiring a single OAuth provider via the `authProviders: ['github']` string shorthand — credentials loaded before `execute()` runs.
+
+The shorthand form. By the time `execute()` runs, the user has completed the OAuth flow and credentials are in the vault — `this.authProviders.headers('github')` returns `{ Authorization: 'Bearer …' }` ready to forward.
+
+## Code
+
+```typescript
+// src/apps/main/tools/list-repos.tool.ts
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
+
+const inputSchema = {
+  visibility: z.enum(['all', 'public', 'private']).default('all'),
+  perPage: z.number().int().min(1).max(100).default(30),
+};
+const outputSchema = {
+  repos: z.array(z.object({ fullName: z.string(), stars: z.number().int(), private: z.boolean() })),
+};
+
+@Tool({
+  name: 'list_repos',
+  description: 'List GitHub repos the authenticated user has access to',
+  inputSchema,
+  outputSchema,
+  authProviders: ['github'], // shorthand — single, required provider
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+})
+export class ListReposTool extends ToolContext {
+  async execute(input: { visibility: 'all' | 'public' | 'private'; perPage: number }) {
+    const headers = await this.authProviders.headers('github');
+
+    const url = new URL('https://api.github.com/user/repos');
+    url.searchParams.set('visibility', input.visibility);
+    url.searchParams.set('per_page', String(input.perPage));
+
+    const response = await this.fetch(url, { headers });
+    const data = (await response.json()) as Array<{ full_name: string; stargazers_count: number; private: boolean }>;
+
+    return {
+      repos: data.map((r) => ({
+        fullName: r.full_name,
+        stars: r.stargazers_count,
+        private: r.private,
+      })),
+    };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Declaring a single required OAuth provider with the `authProviders: ['github']` shorthand
+- Reading pre-formatted credentials via `await this.authProviders.headers('github')`
+- Letting the framework reject calls whose required credential is missing **before** `execute()` runs — a JSON-RPC `-32001` (MCP `UNAUTHORIZED`) error whose `data` carries `{ tool, providers: ['github'], authUrl }` (no auth-check boilerplate)
+- Trusting the framework to handle token refresh, expiration, and the connect/authorize URL
+
+## What you don't have to write
+
+```typescript
+// ❌ unnecessary — the framework already did all of this before execute() ran:
+const cred = await this.authProviders.get('github');
+if (!cred) {
+  this.fail(new PublicMcpError('No GitHub auth — please sign in', { authUrl: '…' }));
+}
+const accessToken = cred.credential.accessToken;
+if (cred.expiresAt && Date.now() >= cred.expiresAt) {
+  /* refresh */
+}
+const headers = { Authorization: `Bearer ${accessToken}` };
+```
+
+The single line `await this.authProviders.headers('github')` covers it all.

package/catalog/create-tool/examples/14-tool-with-multiple-auth-providers.md

@@ -0,0 +1,105 @@
+---
+name: 14-tool-with-multiple-auth-providers
+level: advanced
+description: 'Tool with the full `authProviders` mapping form — one required provider with explicit scopes, one optional provider with an alias, and graceful degradation when the optional creds are missing.'
+tags: [auth-providers, oauth, scopes, optional-auth, this.authProviders.headers]
+features:
+  - 'Using the object form of `authProviders` to set `required`, `scopes`, and `alias`'
+  - Declaring required OAuth scopes that the server advertises in its Protected Resource Metadata (`scopes_supported`) so clients request them
+  - "Resolving an optional provider via `await this.authProviders.headers('cloud')` (returns an empty object `{}` when absent)"
+  - "Branching the tool's behavior — full deploy when both providers are present; preview-only when the cloud provider is missing"
+  - "The required `github` provider gating the call: when its credential is missing the framework aborts before `execute()` with `-32001` and `data: { tool, providers: ['github'], authUrl }`; the optional `aws`/`cloud` provider never gates"
+---
+
+# Tool With Multiple Auth Providers
+
+Tool with the full `authProviders` mapping form — one required provider with explicit scopes, one optional provider with an alias, and graceful degradation when the optional creds are missing.
+
+The full form unlocks scopes, optional providers, and aliases. Use it when the simple shorthand isn't enough.
+
+## Code
+
+```typescript
+// src/apps/main/tools/deploy-app.tool.ts
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
+
+const inputSchema = {
+  repo: z.string().regex(/^[^/]+\/[^/]+$/),
+  environment: z.enum(['staging', 'production']),
+  dryRun: z.boolean().default(false),
+};
+const outputSchema = {
+  deploymentId: z.string(),
+  url: z.string().url(),
+  mode: z.enum(['preview', 'deployed']),
+};
+
+@Tool({
+  name: 'deploy_app',
+  description: 'Build and deploy a repo to cloud',
+  inputSchema,
+  outputSchema,
+  authProviders: [
+    { name: 'github', required: true, scopes: ['repo', 'workflow'] }, // required + scoped
+    { name: 'aws', required: false, alias: 'cloud' }, // optional, aliased
+  ],
+  annotations: { destructiveHint: true, idempotentHint: false, openWorldHint: true },
+})
+export class DeployAppTool extends ToolContext {
+  async execute(input: { repo: string; environment: 'staging' | 'production'; dryRun: boolean }) {
+    const githubHeaders = await this.authProviders.headers('github');
+    const cloudHeaders = await this.authProviders.headers('cloud'); // {} when AWS not connected
+    const hasCloud = Object.keys(cloudHeaders).length > 0;
+
+    // 1. Build artifact from the repo (always works — we have GitHub creds)
+    const buildId = await this.triggerBuild(input.repo, githubHeaders);
+
+    // 2. Deploy — only if cloud creds are present
+    if (!hasCloud || input.dryRun) {
+      return {
+        deploymentId: `preview-${buildId}`,
+        url: `https://preview.example.com/${buildId}`,
+        mode: 'preview' as const,
+      };
+    }
+
+    const deploymentId = await this.deployToCloud(buildId, input.environment, cloudHeaders);
+    return {
+      deploymentId,
+      url: `https://${input.environment}.example.com/${deploymentId}`,
+      mode: 'deployed' as const,
+    };
+  }
+
+  private async triggerBuild(_repo: string, _headers: Record<string, string>): Promise<string> {
+    return 'b_42';
+  }
+  private async deployToCloud(_buildId: string, _env: string, _headers: Record<string, string>): Promise<string> {
+    return 'd_99';
+  }
+}
+```
+
+## What This Demonstrates
+
+- Using the object form of `authProviders` to set `required`, `scopes`, and `alias`
+- Declaring required OAuth scopes that the server advertises in its Protected Resource Metadata (`scopes_supported`) so clients request them
+- Resolving an optional provider via `await this.authProviders.headers('cloud')` (returns an empty object `{}` when absent)
+- Branching the tool's behavior — full deploy when both providers are present; preview-only when the cloud provider is missing
+- The required `github` provider gating the call: when its credential is missing the framework aborts before `execute()` with `-32001` and `data: { tool, providers: ['github'], authUrl }`; the optional `aws`/`cloud` provider never gates
+
+## Field reference (from auth-providers.md)
+
+| Field      | Default  | Meaning                                                                                      |
+| ---------- | -------- | -------------------------------------------------------------------------------------------- |
+| `name`     | —        | Provider name — must match a registered credential provider                                  |
+| `required` | `true`   | If `true`, the tool errors (`-32001`) before `execute()` runs when the credential is missing |
+| `scopes`   | —        | OAuth scopes — advertised via PRM `scopes_supported` so clients know to request them         |
+| `alias`    | = `name` | Local name for the provider — useful when two tools use the same provider differently        |
+
+## When to use the object form
+
+- Need scopes (`required: true, scopes: ['repo']`) — must use the object form
+- Need optional providers (`required: false`) — must use the object form
+- Need to alias the provider name (rare) — must use the object form
+- Just one always-required provider with default scopes → the `authProviders: ['github']` shorthand is shorter

package/catalog/create-tool/examples/15-tool-with-credential-vault.md

@@ -0,0 +1,115 @@
+---
+name: 15-tool-with-credential-vault
+level: advanced
+description: "Tool that reads a user-supplied static credential (a Slack webhook URL) from the per-session encrypted credential vault — the pattern for credentials that aren't OAuth."
+tags: [auth-providers, credential-vault, slack-webhook, encryption-at-rest]
+features:
+  - "Declaring a vault-backed auth provider with `authProviders: ['slack-webhook']`"
+  - "Reading the user's pasted-in credential via `await this.authProviders.headers('slack-webhook')` — same API as OAuth"
+  - Letting the framework handle per-session AES-256-GCM encryption at rest (Redis or memory store)
+  - Knowing when to pick the vault (static secrets the user knows) vs OAuth (delegated identity)
+---
+
+# Tool With Credential Vault
+
+Tool that reads a user-supplied static credential (a Slack webhook URL) from the per-session encrypted credential vault — the pattern for credentials that aren't OAuth.
+
+For credentials that aren't OAuth — webhook URLs, API keys the user pastes in, custom tokens — use a vault-backed auth provider. Same API as OAuth from the tool's perspective; the framework handles per-session encryption and key derivation.
+
+## Code
+
+```typescript
+// src/apps/main/tools/send-to-slack.tool.ts
+import { PublicMcpError, Tool, ToolContext, z } from '@frontmcp/sdk';
+
+const inputSchema = {
+  channel: z.string().regex(/^#/).describe('Slack channel, e.g. #ops'),
+  text: z.string().min(1).max(4_000),
+  username: z.string().optional(),
+  iconEmoji: z.string().optional(),
+};
+const outputSchema = { sent: z.boolean(), channel: z.string() };
+
+@Tool({
+  name: 'send_to_slack',
+  description: 'Send a message to a Slack channel via the user-supplied incoming-webhook URL',
+  inputSchema,
+  outputSchema,
+  authProviders: ['slack-webhook'], // vault-backed provider — see auth skill
+  annotations: { destructiveHint: false, idempotentHint: false, openWorldHint: true },
+})
+export class SendToSlackTool extends ToolContext {
+  async execute(input: { channel: string; text: string; username?: string; iconEmoji?: string }) {
+    const headers = await this.authProviders.headers('slack-webhook');
+    // `headers` is a plain `Record<string, string>` (NOT a `Headers` object), e.g.:
+    //   { 'x-slack-webhook-url': 'https://hooks.slack.com/services/T.../B.../...' }
+    // Read values with string-index access (`headers['x-...']`), not `headers.get(...)`.
+    // The framework reads the value from the vault, decrypts with the per-session AES-256-GCM
+    // key, and never returns the raw value — it's only available indirectly via these headers.
+
+    // Reading the key directly is safe here because we declared `authProviders: ['slack-webhook']`
+    // (required: true by default), so the framework already rejected the call before `execute()`
+    // if the vault entry was missing — by the time we read the header, the provider is guaranteed
+    // to have produced it. If you ever switch the provider to `required: false`, `headers` will be
+    // an empty object `{}` when no credential is set, so guard with
+    // `if (!webhookUrl) this.fail(new PublicMcpError('No Slack webhook configured'))` instead.
+    const webhookUrl = headers['x-slack-webhook-url'];
+    const response = await this.fetch(webhookUrl, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        channel: input.channel,
+        text: input.text,
+        username: input.username,
+        icon_emoji: input.iconEmoji,
+      }),
+    });
+
+    if (!response.ok) {
+      this.fail(new PublicMcpError(`Slack webhook returned ${response.status}`));
+    }
+
+    return { sent: true, channel: input.channel };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Declaring a vault-backed auth provider with `authProviders: ['slack-webhook']`
+- Reading the user's pasted-in credential via `await this.authProviders.headers('slack-webhook')` — same API as OAuth
+- Letting the framework handle per-session AES-256-GCM encryption at rest (Redis or memory store)
+- Knowing when to pick the vault (static secrets the user knows) vs OAuth (delegated identity)
+
+## Vault vs OAuth — when to pick which
+
+| Vault-backed                                                                 | OAuth                                                                    |
+| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| User pastes in a webhook URL, API key, or token they own                     | User clicks "Connect to GitHub" — provider issues a token to your server |
+| Static — doesn't refresh, doesn't expire                                     | Refresh token + access token + expiration                                |
+| Per-session — gone when the session ends (vs. Redis store, then it survives) | Long-lived — usually persists across sessions                            |
+| For "bring your own" integrations (Slack webhooks, custom API keys)          | For "log in with" integrations (GitHub, Google, Microsoft)               |
+
+## How vault-backed providers are configured
+
+Server side, in the `auth` skill:
+
+```typescript
+@FrontMcp({
+  auth: {
+    providers: [
+      {
+        name: 'slack-webhook',
+        kind: 'vault',
+        fields: [
+          { name: 'webhook-url', type: 'url', label: 'Slack incoming-webhook URL', required: true },
+        ],
+      },
+    ],
+  },
+})
+```
+
+The framework renders the credential UI based on `fields`, encrypts the user's input, stores it per-session, and exposes it back to tools via `this.authProviders.headers('slack-webhook')`.
+
+See the `auth` skill for full vault configuration, encryption-key management, Redis-backed storage, and the credential UI.

package/catalog/create-tool/examples/16-tool-with-rate-limit.md

@@ -0,0 +1,71 @@
+---
+name: 16-tool-with-rate-limit
+level: intermediate
+description: 'Tool with `rateLimit: { maxRequests, windowMs }` capping invocations per session per minute — the protection for expensive / external-API-billed operations.'
+tags: [throttling, rate-limit, abuse-protection]
+features:
+  - "Capping the tool to N invocations per windowMs, partitioned per session via `partitionBy: 'session'`"
+  - "Letting the framework reject over-limit calls with `RateLimitError` (code `'RATE_LIMIT_EXCEEDED'`, HTTP status 429) carrying a retry-after hint in its message that clients can back off against"
+  - 'Combining `rateLimit` with `annotations.openWorldHint: true` so clients know the tool talks to billed external services'
+  - Sizing the limit against upstream quota / billing — not just "what feels reasonable"
+---
+
+# Tool With Rate Limit
+
+Tool with `rateLimit: { maxRequests, windowMs }` capping invocations per session per minute — the protection for expensive / external-API-billed operations.
+
+The first throttle to reach for. Caps invocations over time. The default partition is `'global'` (one shared limit); this example sets `partitionBy: 'session'` so a runaway agent loop on one session can't burn through a quota that other sessions need.
+
+## Code
+
+```typescript
+// src/apps/main/tools/translate.tool.ts
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
+
+const inputSchema = {
+  text: z.string().min(1).max(2_000),
+  targetLang: z.string().regex(/^[a-z]{2}$/, 'ISO 639-1 code'),
+};
+const outputSchema = { translated: z.string(), sourceLang: z.string() };
+
+@Tool({
+  name: 'translate',
+  description: 'Translate text via the external translation API (billed per call)',
+  inputSchema,
+  outputSchema,
+  rateLimit: { maxRequests: 60, windowMs: 60_000, partitionBy: 'session' }, // 60 calls / minute / session
+  authProviders: ['translate-api'],
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+})
+export class TranslateTool extends ToolContext {
+  async execute(input: { text: string; targetLang: string }) {
+    const headers = await this.authProviders.headers('translate-api');
+    const response = await this.fetch('https://api.translate.example/v1/translate', {
+      method: 'POST',
+      headers: { ...headers, 'content-type': 'application/json' },
+      body: JSON.stringify({ text: input.text, target: input.targetLang }),
+    });
+    const data = (await response.json()) as { translated: string; detectedSource: string };
+    return { translated: data.translated, sourceLang: data.detectedSource };
+  }
+}
+```
+
+> **Testing.** The framework throws `RateLimitError` (HTTP 429, code `'RATE_LIMIT_EXCEEDED'`) for over-limit calls. Tests that assert the rate-limit fires after N calls live in the dedicated `testing` skill — the canonical pattern uses `@frontmcp/testing`'s `TestServer` + Playwright `test`/`expect` fixtures.
+
+## What This Demonstrates
+
+- Capping the tool to N invocations per windowMs, partitioned per session via `partitionBy: 'session'`
+- Letting the framework reject over-limit calls with `RateLimitError` (code `'RATE_LIMIT_EXCEEDED'`, HTTP status 429) carrying a retry-after hint in its message that clients can back off against
+- Combining `rateLimit` with `annotations.openWorldHint: true` so clients know the tool talks to billed external services
+- Sizing the limit against upstream quota / billing — not just "what feels reasonable"
+
+## Sizing the limit
+
+- **External API quotas** — set well below the upstream quota. If GitHub allows 5,000/hour authenticated, a per-session limit of 30/min (1,800/hr) gives room for multiple sessions to share the budget.
+- **Billed services** — lower. A `translate` call may cost $0.02. 60/min × 60min × 24h × 1 session = $1,728/day worst case.
+- **Pure rate concern, not cost** — 100/min is generous for almost anything.
+
+## Global vs per-session
+
+The default partition is `'global'` — one limit shared across all callers. For a limit that's tracked independently per session, set `partitionBy: 'session'` (so a runaway loop on one session can't burn through everyone's budget). See the `throttling` reference for the full set of `partitionBy` strategies (`'global' | 'session' | 'userId' | 'ip'` or a custom function).