Tools

1
import { OpenRouter, tool } from '@openrouter/sdk';
2
import { z } from 'zod';
3
4
const weatherTool = tool({
5
  name: 'get_weather',
6
  description: 'Get the current weather for a location',
7
  inputSchema: z.object({
8
    location: z.string().describe('City name, e.g., "San Francisco, CA"'),
9
  }),
10
  outputSchema: z.object({
11
    temperature: z.number(),
12
    conditions: z.string(),
13
  }),
14
  execute: async (params) => {
15
    // params is typed as { location: string }
16
    const weather = await fetchWeather(params.location);
17
    return {
18
      temperature: weather.temp,
19
      conditions: weather.description,
20
    };
21
  },
22
});

1
const calculatorTool = tool({
2
  name: 'calculate',
3
  description: 'Perform a mathematical calculation',
4
  inputSchema: z.object({
5
    expression: z.string().describe('Math expression like "2 + 2"'),
6
  }),
7
  outputSchema: z.object({
8
    result: z.number(),
9
  }),
10
  execute: async (params) => {
11
    const result = eval(params.expression); // Use a safer eval in production
12
    return { result };
13
  },
14
});

1
const searchTool = tool({
2
  name: 'search_database',
3
  description: 'Search documents with progress updates',
4
  inputSchema: z.object({
5
    query: z.string(),
6
    limit: z.number().default(10),
7
  }),
8
  // eventSchema triggers generator mode
9
  eventSchema: z.object({
10
    progress: z.number().min(0).max(100),
11
    message: z.string(),
12
  }),
13
  outputSchema: z.object({
14
    results: z.array(z.string()),
15
    totalFound: z.number(),
16
  }),
17
  // execute is now an async generator
18
  execute: async function* (params) {
19
    yield { progress: 0, message: 'Starting search...' };
20
21
    const results = [];
22
    for (let i = 0; i < 5; i++) {
23
      yield { progress: (i + 1) * 20, message: `Searching batch ${i + 1}...` };
24
      results.push(...await searchBatch(params.query, i));
25
    }
26
27
    // Final yield is the output
28
    yield { progress: 100, message: 'Complete!' };
29
30
    // Return the final result (or yield it as last value)
31
    return {
32
      results: results.slice(0, params.limit),
33
      totalFound: results.length,
34
    };
35
  },
36
});

1
const manualTool = tool({
2
  name: 'send_email',
3
  description: 'Send an email (requires user confirmation)',
4
  inputSchema: z.object({
5
    to: z.string().email(),
6
    subject: z.string(),
7
    body: z.string(),
8
  }),
9
  execute: false, // Manual handling required
10
});

1
const inputSchema = z.object({
2
  // Required parameters
3
  query: z.string().describe('Search query'),
4
5
  // Optional with default
6
  limit: z.number().default(10).describe('Max results'),
7
8
  // Optional without default
9
  filter: z.string().optional().describe('Filter expression'),
10
11
  // Enum values
12
  sortBy: z.enum(['relevance', 'date', 'popularity']).default('relevance'),
13
14
  // Nested objects
15
  options: z.object({
16
    caseSensitive: z.boolean().default(false),
17
    wholeWord: z.boolean().default(false),
18
  }).optional(),
19
20
  // Arrays
21
  tags: z.array(z.string()).optional(),
22
});

1
const outputSchema = z.object({
2
  results: z.array(z.object({
3
    id: z.string(),
4
    title: z.string(),
5
    score: z.number(),
6
  })),
7
  metadata: z.object({
8
    totalCount: z.number(),
9
    searchTimeMs: z.number(),
10
  }),
11
});

1
const eventSchema = z.object({
2
  stage: z.enum(['initializing', 'processing', 'finalizing']),
3
  progress: z.number(),
4
  currentItem: z.string().optional(),
5
});

1
import type { InferToolInput, InferToolOutput, InferToolEvent } from '@openrouter/sdk';
2
3
// Get the input type
4
type WeatherInput = InferToolInput<typeof weatherTool>;
5
// { location: string }
6
7
// Get the output type
8
type WeatherOutput = InferToolOutput<typeof weatherTool>;
9
// { temperature: number; conditions: string }
10
11
// Get event type (generator tools only)
12
type SearchEvent = InferToolEvent<typeof searchTool>;
13
// { progress: number; message: string }

1
const openrouter = new OpenRouter({ apiKey: process.env.OPENROUTER_API_KEY });
2
3
const result = openrouter.callModel({
4
  model: 'openai/gpt-5-nano',
5
  input: 'What is the weather in Tokyo?',
6
  tools: [weatherTool],
7
});
8
9
// Tools are automatically executed
10
const text = await result.getText();
11
// "The weather in Tokyo is 22°C and sunny."

1
const result = openrouter.callModel({
2
  model: 'openai/gpt-5-nano',
3
  input: 'Search for TypeScript tutorials and calculate 2+2',
4
  tools: [searchTool, calculatorTool],
5
});

1
const result = openrouter.callModel({
2
  model: 'openai/gpt-5-nano',
3
  input: 'What is the weather?',
4
  tools: [weatherTool, searchTool] as const,
5
  maxToolRounds: 0, // Get tool calls without executing
6
});
7
8
// Tool calls are typed as union of tool inputs
9
for await (const toolCall of result.getToolCallsStream()) {
10
  if (toolCall.name === 'get_weather') {
11
    // toolCall.arguments is typed as { location: string }
12
    console.log('Weather for:', toolCall.arguments.location);
13
  }
14
}

1
const contextAwareTool = tool({
2
  name: 'context_tool',
3
  inputSchema: z.object({ data: z.string() }),
4
  outputSchema: z.object({ result: z.string() }),
5
  execute: async (params, context) => {
6
    console.log('Turn number:', context?.numberOfTurns);
7
    console.log('Message history:', context?.turnRequest?.input);
8
    console.log('Model:', context?.turnRequest?.model);
9
10
    return { result: `Processed on turn ${context?.numberOfTurns}` };
11
  },
12
});

1
import { OpenRouter, tool } from '@openrouter/sdk';
2
import { z } from 'zod';
3
4
const weatherTool = tool({
5
  name: 'get_weather',
6
  inputSchema: z.object({ location: z.string() }),
7
  outputSchema: z.object({ temperature: z.number() }),
8
  execute: async ({ location }) => {
9
    return { temperature: await fetchTemperature(location) };
10
  },
11
});
12
13
const result = openrouter.callModel({
14
  model: 'openai/gpt-5-nano',
15
  input: 'What is the weather in Paris?',
16
  tools: [weatherTool],
17
});
18
19
// getText() waits for all tool execution to complete
20
const text = await result.getText();
21
// "The weather in Paris is 18°C."

1
const result = openrouter.callModel({
2
  model: 'openai/gpt-5-nano',
3
  input: 'Research this topic thoroughly',
4
  tools: [searchTool, analyzeTool],
5
  maxToolRounds: 3, // Stop after 3 rounds of tool execution
6
});

1
const result = openrouter.callModel({
2
  model: 'openai/gpt-5-nano',
3
  input: 'Research and analyze',
4
  tools: [searchTool],
5
  maxToolRounds: (context) => {
6
    // Continue if under 5 turns
7
    return context.numberOfTurns < 5;
8
  },
9
});

1
const result = openrouter.callModel({
2
  model: 'openai/gpt-5-nano',
3
  input: 'What is the weather in Tokyo and Paris?',
4
  tools: [weatherTool],
5
  maxToolRounds: 0, // Don't auto-execute
6
});
7
8
const toolCalls = await result.getToolCalls();
9
10
for (const call of toolCalls) {
11
  console.log(`Tool: ${call.name}`);
12
  console.log(`ID: ${call.id}`);
13
  console.log(`Arguments:`, call.arguments);
14
}

1
const result = openrouter.callModel({
2
  model: 'openai/gpt-5-nano',
3
  input: 'Check weather in multiple cities',
4
  tools: [weatherTool],
5
  maxToolRounds: 0,
6
});
7
8
for await (const toolCall of result.getToolCallsStream()) {
9
  console.log(`Received tool call: ${toolCall.name}`);
10
11
  // Process each tool call as it arrives
12
  const weatherResult = await processWeatherRequest(toolCall.arguments);
13
  console.log('Result:', weatherResult);
14
}

1
const searchTool = tool({
2
  name: 'search',
3
  inputSchema: z.object({ query: z.string() }),
4
  eventSchema: z.object({ progress: z.number(), status: z.string() }),
5
  outputSchema: z.object({ results: z.array(z.string()) }),
6
  execute: async function* ({ query }) {
7
    yield { progress: 25, status: 'Searching...' };
8
    yield { progress: 50, status: 'Processing...' };
9
    yield { progress: 75, status: 'Ranking...' };
10
    yield { progress: 100, status: 'Complete' };
11
    return { results: ['result1', 'result2'] };
12
  },
13
});
14
15
const result = openrouter.callModel({
16
  model: 'openai/gpt-5-nano',
17
  input: 'Search for TypeScript tutorials',
18
  tools: [searchTool],
19
});
20
21
for await (const event of result.getToolStream()) {
22
  switch (event.type) {
23
    case 'delta':
24
      // Raw argument delta from the model
25
      process.stdout.write(event.content);
26
      break;
27
    case 'preliminary_result':
28
      // Progress from generator tool
29
      console.log(`Progress: ${event.result.progress}% - ${event.result.status}`);
30
      break;
31
  }
32
}

1
for await (const event of result.getFullResponsesStream()) {
2
  switch (event.type) {
3
    case 'tool.preliminary_result':
4
      // Intermediate progress from generator tools
5
      console.log(`Progress (${event.toolCallId}):`, event.result);
6
      break;
7
    case 'tool.result':
8
      // Final result when tool execution completes
9
      console.log(`Tool ${event.toolCallId} completed`);
10
      console.log('Result:', event.result);
11
      // Access any preliminary results that were emitted during execution
12
      if (event.preliminaryResults) {
13
        console.log('All progress events:', event.preliminaryResults);
14
      }
15
      break;
16
  }
17
}

1
type ToolResultEvent<TResult = unknown, TPreliminaryResults = unknown> = {
2
  type: 'tool.result';
3
  toolCallId: string;
4
  result: TResult;
5
  timestamp: number;
6
  preliminaryResults?: TPreliminaryResults[];
7
};

1
const result = openrouter.callModel({
2
  model: 'openai/gpt-5-nano',
3
  input: 'Get weather in Paris, Tokyo, and New York simultaneously',
4
  tools: [weatherTool],
5
});
6
7
// All three weather calls execute in parallel
8
const text = await result.getText();

1
const confirmTool = tool({
2
  name: 'send_email',
3
  description: 'Send an email (requires confirmation)',
4
  inputSchema: z.object({
5
    to: z.string().email(),
6
    subject: z.string(),
7
    body: z.string(),
8
  }),
9
  execute: false, // Manual handling
10
});
11
12
const result = openrouter.callModel({
13
  model: 'openai/gpt-5-nano',
14
  input: 'Send an email to [email protected]',
15
  tools: [confirmTool],
16
  maxToolRounds: 0,
17
});
18
19
const toolCalls = await result.getToolCalls();
20
21
for (const call of toolCalls) {
22
  if (call.name === 'send_email') {
23
    // Show confirmation UI
24
    const confirmed = await showConfirmDialog(call.arguments);
25
26
    if (confirmed) {
27
      await sendEmail(call.arguments);
28
    }
29
  }
30
}

1
const result = openrouter.callModel({
2
  model: 'openai/gpt-5-nano',
3
  input: 'What is 2+2 and the weather in Paris?',
4
  tools: [calculatorTool, weatherTool],
5
});
6
7
const response = await result.getResponse();
8
9
// Response includes all execution rounds
10
console.log('Final output:', response.output);
11
console.log('Usage:', response.usage);

1
const riskyTool = tool({
2
  name: 'risky_operation',
3
  inputSchema: z.object({ input: z.string() }),
4
  outputSchema: z.object({ result: z.string() }),
5
  execute: async (params) => {
6
    if (params.input === 'fail') {
7
      throw new Error('Operation failed: invalid input');
8
    }
9
    return { result: 'success' };
10
  },
11
});
12
13
const result = openrouter.callModel({
14
  model: 'openai/gpt-5-nano',
15
  input: 'Try the risky operation with "fail"',
16
  tools: [riskyTool],
17
});
18
19
// Model receives error message and can respond appropriately
20
const text = await result.getText();
21
// "I tried the operation but it failed with: Operation failed: invalid input"

1
const strictTool = tool({
2
  name: 'strict',
3
  inputSchema: z.object({
4
    email: z.string().email(),
5
    age: z.number().min(0).max(150),
6
  }),
7
  execute: async (params) => {
8
    // Only runs with valid input
9
    return { valid: true };
10
  },
11
});

1
const robustTool = tool({
2
  name: 'fetch_data',
3
  inputSchema: z.object({ url: z.string().url() }),
4
  outputSchema: z.object({
5
    data: z.unknown().optional(),
6
    error: z.string().optional(),
7
  }),
8
  execute: async (params) => {
9
    try {
10
      const response = await fetch(params.url);
11
      if (!response.ok) {
12
        return { error: `HTTP ${response.status}: ${response.statusText}` };
13
      }
14
      return { data: await response.json() };
15
    } catch (error) {
16
      return { error: `Failed to fetch: ${error.message}` };
17
    }
18
  },
19
});

1
// Good: Clear name and description
2
const tool1 = tool({
3
  name: 'search_knowledge_base',
4
  description: 'Search the company knowledge base for documents, FAQs, and policies. Returns relevant articles with snippets.',
5
  // ...
6
});
7
8
// Avoid: Vague or generic
9
const tool2 = tool({
10
  name: 'search',
11
  description: 'Searches stuff',
12
  // ...
13
});

1
const inputSchema = z.object({
2
  query: z.string().describe('Natural language search query'),
3
  maxResults: z.number()
4
    .min(1)
5
    .max(100)
6
    .default(10)
7
    .describe('Maximum number of results to return (1-100)'),
8
  dateRange: z.enum(['day', 'week', 'month', 'year', 'all'])
9
    .default('all')
10
    .describe('Filter results by time period'),
11
});

1
const createUserTool = tool({
2
  name: 'create_user',
3
  inputSchema: z.object({
4
    email: z.string().email(),
5
    name: z.string(),
6
  }),
7
  execute: async (params) => {
8
    // Check if user exists first
9
    const existing = await findUserByEmail(params.email);
10
    if (existing) {
11
      return { userId: existing.id, created: false };
12
    }
13
14
    const user = await createUser(params);
15
    return { userId: user.id, created: true };
16
  },
17
});

1
const longRunningTool = tool({
2
  name: 'process_data',
3
  inputSchema: z.object({ dataId: z.string() }),
4
  execute: async (params) => {
5
    const timeoutMs = 30000;
6
7
    const result = await Promise.race([
8
      processData(params.dataId),
9
      new Promise((_, reject) =>
10
        setTimeout(() => reject(new Error('Operation timed out')), timeoutMs)
11
      ),
12
    ]);
13
14
    return result;
15
  },
16
});