DEV Community

Alex Chen
Alex Chen

Posted on

Learn AI SDK 7 Scoped Tool Context With a Two-Tool Secret Boundary

#typescript #ai #tutorial #security

Vercel's AI SDK 7 adds scoped tool context: a tool can declare a contextSchema, while the caller supplies per-tool values through toolsContext. The purpose is practical—third-party tools do not need to receive every secret or configuration value held by an agent.

Primary source: Vercel, “AI SDK 7 is now available”.

Let's turn that feature into a tiny security exercise. We will create two tools:

  • lookupOrder may receive an internal order-service URL;
  • createTicket may receive a support token;
  • neither tool should receive the other's value.

Setup

Use a fresh project and pin the versions you actually install in your lockfile:

mkdir scoped-tools && cd scoped-tools
npm init -y
npm install ai zod
npm install -D typescript tsx @types/node
Enter fullscreen mode Exit fullscreen mode

Create demo.ts:

import { tool } from 'ai';
import { z } from 'zod';

const lookupOrder = tool({
  description: 'Read the status of one order',
  inputSchema: z.object({ orderId: z.string().min(1) }),
  contextSchema: z.object({ baseUrl: z.string().url() }),
  execute: async ({ orderId }, { context }) => ({
    orderId,
    source: new URL(`/orders/${orderId}`, context.baseUrl).toString(),
    status: 'demo-only',
  }),
});

const createTicket = tool({
  description: 'Create a support ticket',
  inputSchema: z.object({ subject: z.string().min(3) }),
  contextSchema: z.object({ supportToken: z.string().min(12) }),
  execute: async ({ subject }, { context }) => ({
    subject,
    accepted: context.supportToken.startsWith('support_'),
  }),
});

const tools = { lookupOrder, createTicket };
const toolsContext = {
  lookupOrder: { baseUrl: 'https://orders.invalid' },
  createTicket: { supportToken: 'support_demo_token' },
};

async function run() {
  const order = await lookupOrder.execute!(
    { orderId: 'A-17' },
    { context: toolsContext.lookupOrder } as never,
  );
  const ticket = await createTicket.execute!(
    { subject: 'Order is delayed' },
    { context: toolsContext.createTicket } as never,
  );
  console.log(JSON.stringify({ order, ticket }, null, 2));
}

run().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});
Enter fullscreen mode Exit fullscreen mode

The exact execution callback types may evolve with SDK releases, so use the current AI SDK 7 documentation and your lockfile as the source of truth. The important shape is the boundary: each context object is validated for one tool.

Run it:

npx tsx demo.ts
Enter fullscreen mode Exit fullscreen mode

Expected output is shaped like:

{
  "order": {
    "orderId": "A-17",
    "source": "https://orders.invalid/orders/A-17",
    "status": "demo-only"
  },
  "ticket": {
    "subject": "Order is delayed",
    "accepted": true
  }
}
Enter fullscreen mode Exit fullscreen mode

No network request is made; this lesson tests data flow, not an external service.

Add the failure exercise

Now deliberately provide the wrong context:

const wrong = { supportToken: 'support_demo_token' };
const parsed = z.object({ baseUrl: z.string().url() }).safeParse(wrong);
console.log(parsed.success); // false
Enter fullscreen mode Exit fullscreen mode

The desired result is rejection before tool execution. If your orchestration layer silently supplies a global environment object, both tools may see both secrets and the exercise has failed.

Create this table during review:

Tool Allowed context Forbidden context Missing-context behavior
lookupOrder base URL support token reject before call
createTicket support token order URL, database credentials reject before call

Why not pass process.env?

This is convenient but dangerous:

// Avoid this pattern
execute(input, { context: process.env })
Enter fullscreen mode Exit fullscreen mode

It makes a future tool change an implicit privilege expansion. A package that only needed a weather API key could suddenly read database, deployment, and payment credentials.

Scoped context gives code reviewers a visible capability list. It does not encrypt secrets, prevent a permitted tool from leaking its own token, or replace sandboxing. You still need log redaction, outbound network controls, token rotation, and tests.

Extension exercise

Add a sendEmail tool with only:

{ senderId: string; allowedDomains: string[] }
Enter fullscreen mode Exit fullscreen mode

Then test three cases:

  1. an allowed destination succeeds;
  2. an unlisted domain fails before sending;
  3. a missing allowedDomains field fails schema validation.

Print structured evidence for all three. Do not use a real email credential.

The broader lesson is that an AI tool is a capability boundary. AI SDK 7 makes that boundary easier to express, but the developer still decides whether the context is narrow, validated, and observable.

Which value in your current agent's global environment would be easiest to remove from most tool calls?

Top comments (0)