When Grok decides to use one of your Metorial integrations, it returns tool calls that you need to execute and send back.

Understanding Tool Calls

Tool calls are Grok's way of requesting to use an integration. For example, if you ask "What's on my calendar today?", Grok might request to call a calendar tool.

Basic Tool Call Handling

Here's how to handle a single tool call:

await metorial.withProviderSession(
  metorialXai,
  { serverDeployments: ['your-server-deployment-id'] },
  async session => {
    let messages = [
      {
        role: 'user',
        content: 'What emails did I receive today?'
      }
    ];

    let response = await xai.chat.completions.create({
      model: 'grok-beta',
      messages,
      tools: session.tools
    });

    let choice = response.choices[0];
    let toolCalls = choice.message.tool_calls;

    // Check if Grok wants to use any tools
    if (toolCalls && toolCalls.length > 0) {
      // Execute the tool calls via Metorial
      let toolResponses = await session.callTools(toolCalls);
      
      // Add both the assistant's tool calls and the responses to history
      messages.push(
        { role: 'assistant', tool_calls: toolCalls },
        ...toolResponses
      );

      // Make another request with the tool results
      let finalResponse = await xai.chat.completions.create({
        model: 'grok-beta',
        messages,
        tools: session.tools
      });

      console.log(finalResponse.choices[0].message.content);
    } else {
      // No tools needed, just print the response
      console.log(choice.message.content);
    }
  }
);

Key Points

• Always check for tool calls before trying to execute them
• Use session.callTools() to execute tools through Metorial
• Append both tool calls and responses to your message history
• Make a follow-up request with the tool results so Grok can formulate a final answer

Next Steps

For handling multiple rounds of tool calls, see our "Building a Conversation Loop" guide.