Understand how Metorial's tools work with the Vercel AI SDK and how to maximize their effectiveness.

What Are Tools?

Tools (also called functions) are capabilities you give to your AI model. With Metorial, these tools represent integrations with external services like Google Calendar, Slack, Notion, and 600+ others.

Accessing Tools

When you create a Metorial session, tools are automatically available via session.tools:

await metorial.withProviderSession(
  metorialAISDK,
  { serverDeployments: ['your-deployment-id'] },
  async (session) => {
    // session.tools contains all tools from your deployment
    console.log(`Available tools: ${session.tools.length}`);
    
    const result = await generateText({
      model: yourModel,
      messages: [...],
      tools: session.tools  // Pass tools to AI SDK
    });
  }
);

How AI SDK Uses Tools

The AI SDK handles the tool execution flow automatically:

1. Model analyzes request: Determines if tools are needed
2. Tool selection: Chooses appropriate tools from session.tools
3. Tool execution: Calls the tools through Metorial
4. Result integration: Uses tool results to generate response

Controlling Tool Behavior

Use AI SDK's maxSteps parameter to control iterations:

const result = await generateText({
  model: yourModel,
  messages: [...],
  tools: session.tools,
  maxSteps: 5  // Limit to 5 tool call iterations
});

This prevents infinite loops while allowing complex multi-step tasks.

Tool Execution Results

Access detailed information about tool calls:

const result = await generateText({
  model: yourModel,
  messages: [...],
  tools: session.tools
});

// Check what tools were called
console.log('Steps taken:', result.steps);
console.log('Tool calls:', result.toolCalls);
console.log('Tool results:', result.toolResults);

Best Practices

Be specific in prompts: Clear requests help the model choose the right tools

// Good
"Schedule a meeting with John for tomorrow at 2pm"

// Less effective
"Help me with my calendar"

Provide context: Give the model information needed to execute tools effectively

const messages = [
  { role: 'system', content: 'You are a helpful assistant with access to the user\'s calendar and email.' },
  { role: 'user', content: 'Schedule a team sync' }
];

Handle errors gracefully: Some tool calls may fail

const result = await generateText({
  model: yourModel,
  messages: [...],
  tools: session.tools,
  maxSteps: 10
});

if (result.finishReason === 'error') {
  console.error('Tool execution failed');
}

Tool Categories

Metorial provides tools across many categories:

• Productivity: Google Calendar, Microsoft Outlook, Notion
• Communication: Slack, Discord, Microsoft Teams
• Development: GitHub, GitLab, Jira, Linear
• CRM: Salesforce, HubSpot, Pipedrive
• And 590+ more integrations

All tools work the same way through the AI SDK interface.