Connected Tools

Configure integrates with external services so agents can access a user's email, calendar, files, and notes. Searches also include web search, which is always available without a user connection.

Available Tools

Tool	Service	Connection Required	Capabilities
gmail	Gmail	Yes	Search emails, send emails
calendar	Google Calendar	Yes	Get events, create events
drive	Google Drive	Yes	Search files
notion	Notion	Yes	Search pages
Web Search	Web	No	Search the web for current information

Connection Management

Listing Tools

tools.list() returns all available tools and their current connection status.

const { tools } = await client.tools.list(token);

for (const tool of tools) {
  console.log(`${tool.name}: ${tool.connected ? 'connected' : 'not connected'}`);
}

Connecting a Tool

Connecting a tool is a two-step OAuth flow:

1. Call tools.connect() to get an OAuth URL and a connectionRequestId
2. Redirect the user to the OAuth URL
3. After the user completes authorization, call tools.confirm() with the connectionRequestId

// Step 1: Initiate OAuth
const { url, connectionRequestId } = await client.tools.connect(token, 'gmail');

// Step 2: Redirect the user to `url` in a browser
// The user completes OAuth in the provider's UI

// Step 3: Confirm the connection
const result = await client.tools.confirm(token, 'gmail', connectionRequestId);

if (result.connected) {
  console.log('Gmail connected successfully');
  // Initial data sync happens automatically
  console.log(`Synced ${result.sync?.itemsSynced} items`);
}

Disconnecting Tools

// Disconnect a single tool
await client.tools.disconnect(token, 'gmail');

// Disconnect all tools
await client.tools.disconnectAll(token);

Searching Tools

All search methods require the user's token and userId. Search results are automatically saved to the user's profile for future context across agents.

Email Search

Supports Gmail search operators: from:, subject:, has:attachment, after:, before:.

// Basic search
const results = await client.tools.searchEmails(token, userId, 'flight confirmation');
console.log(`Found ${results.count} emails`);

for (const email of results.emails) {
  console.log(`${email.subject} — ${email.from} (${email.date})`);
}

// Gmail operators
const invoices = await client.tools.searchEmails(
  token, userId,
  'from:billing@stripe.com subject:invoice after:2026/01/01',
);

// Limit results
const recent = await client.tools.searchEmails(
  token, userId,
  'has:attachment',
  { maxResults: 5 },
);

Calendar

Retrieve events for a specified time range.

// Get this week's events (default)
const { events, count } = await client.tools.getCalendar(token, userId);

// Specific range: 'today', 'tomorrow', 'week', 'month'
const today = await client.tools.getCalendar(token, userId, 'today');

for (const event of today.events) {
  console.log(`${event.summary}: ${event.start} — ${event.end}`);
}

File Search

Search the user's Google Drive.

const { files, count } = await client.tools.searchFiles(token, userId, 'Q1 budget');

for (const file of files) {
  console.log(`${file.name} (${file.mimeType}) — ${file.webViewLink}`);
}

Note Search

Search the user's Notion workspace.

const { notes, count } = await client.tools.searchNotes(token, userId, 'project roadmap');

for (const note of notes) {
  console.log(`${note.title} — ${note.url}`);
}

Web Search

Web search is always available. It does not require a tool connection.

const { results, count } = await client.tools.searchWeb(token, userId, 'best restaurants in Tokyo');

for (const result of results) {
  console.log(`${result.title}: ${result.snippet}`);
  console.log(`  ${result.url}`);
}

Fetch URL

Fetch the content of a specific web page. No connection required.

const page = await client.tools.fetchUrl(token, userId, 'https://docs.configure.dev');
console.log(`${page.title} (${page.content_type})`);
console.log(page.content.slice(0, 500));

Action Tools

Action tools perform write operations on behalf of the user.

Create Calendar Event

const result = await client.tools.createCalendarEvent(token, userId, {
  title: 'Team standup',
  startTime: '2026-03-20T09:00:00',
  endTime: '2026-03-20T09:30:00',
  description: 'Daily sync with the engineering team',
  location: 'Conference Room B',
});

console.log(result.message); // "Event created: Team standup"

Send Email

const result = await client.tools.sendEmail(token, userId, {
  to: 'colleague@company.com',
  subject: 'Meeting notes from today',
  body: 'Hi, here are the key takeaways from our meeting...',
});

console.log(result.sent);    // true
console.log(result.message); // "Email sent to colleague@company.com"

Error Handling

When a tool search is called but the user has not connected that tool, the SDK throws a TOOL_NOT_CONNECTED error.

import { ConfigureError, ErrorCode } from 'configure';

try {
  const results = await client.tools.searchEmails(token, userId, 'invoices');
} catch (error) {
  if (error instanceof ConfigureError && error.code === ErrorCode.TOOL_NOT_CONNECTED) {
    // Prompt the user to connect Gmail
    const { url, connectionRequestId } = await client.tools.connect(token, 'gmail');
    // Redirect user to url...
  }
}