Skip to main content

​
Overview

The Tool Hub provides pre-built integrations that agents can use, plus a place to manage your organization’s custom tools:
  • Install from marketplace — add tools to your organization
  • Server-side execution — tools run on tools.runtools.ai, not inside sandboxes
  • Encrypted credentials — AES-256-GCM encrypted, never exposed in API responses
  • OAuth integration — connect accounts once, tools auto-resolve tokens
  • Build your own — create custom tools with defineTool() and publish them

​
Available Tools

ToolSlugCategoryOAuth ProviderKey Actions
GitHubgithubDevelopergithublist_repos, create_repo, search_repos, list_issues, create_issue, comment, list_prs, create_pr
GmailgmailCommunicationgooglesend_email, list_emails, get_email, reply, search
Google Calendargoogle-calendarProductivitygooglelist_events, create_event, update_event, delete_event, find_free_time
Google Sheetsgoogle-sheetsProductivitygoogleread_range, write_range, append_rows, create_spreadsheet, list_sheets
SlackslackCommunicationslackpost_message, send_dm, list_channels, read_messages, search, set_topic, list_users
DiscorddiscordCommunicationdiscordlist_guilds, list_channels, send_message, read_messages, create_channel
OutlookoutlookCommunicationmicrosoftsend_email, list_emails, get_email, list_events, create_event
X (Twitter)x-twitterSocialxpost_tweet, search_tweets, get_user, get_timeline, like_tweet
LinkedInlinkedinSociallinkedinget_profile, create_post, get_network
TelegramtelegramCommunicationtelegramsend_message, send_photo, get_updates
You can also build and publish your own (see Custom Tools).

​
OAuth & Connected Apps

Tools with an OAuth provider automatically resolve credentials from your connected accounts. No manual token management required.

​
How It Works

  1. Connect once — Go to Dashboard → Credentials → Connected Apps, click Connect for a provider (Google, GitHub, Slack, etc.)
  2. Auto-resolve — When a tool runs, it automatically fetches a valid access token from your connected account
  3. Auto-refresh — Tokens are refreshed automatically before they expire (background daemon + on-demand refresh)

​
Credential Resolution Priority

When a tool executes, credentials are resolved in this order:
PrioritySourceDescription
1Per-requestCredentials passed in the execute request body
2StoredManually stored credentials (via CLI or dashboard)
3OAuthAutomatically resolved from connected accounts
4EmptyNo credentials (tool will likely fail)

​
BYOA (Bring Your Own App)

Organizations can register their own OAuth app credentials for any provider. When configured, the OAuth consent screen shows your app name instead of “RunTools.” 
# Configure BYOA for Google in your org
runtools oauth byoa google \
  --client-id "your-google-client-id" \
  --client-secret "your-google-client-secret"

​
Installing Tools

# Search the marketplace
runtools tool search "email"

# Install a tool
runtools tool install gmail

# List installed tools
runtools tool list --installed
Or install from the dashboard: Tool Hub > Marketplace > Find tool > Install.

​
Using Tools in Agents

Once installed, reference tool slugs in your agent definition:
agents/email-bot.ts
import { defineAgent } from '@runtools/sdk';

export default defineAgent({
  slug: 'email-bot',
  model: 'claude-sonnet-4',
  systemPrompt: 'You help manage emails using the gmail tool.',
  tools: ['bash', 'read_file', 'gmail'],  // gmail is an installed marketplace tool
});
Core tools (bash, read_file, edit_file, etc.) are always included. You only need to add marketplace and custom tools.

​
Direct Tool Execution

Call tools directly without an agent: 
# Execute a tool action
runtools tool exec gmail --action send_email \
  --params '{"to": "user@example.com", "subject": "Hello", "body": "Hi!"}'

​
Building Custom Tools

Create tools with defineTool() from the SDK:
tools/my-api.ts
import { defineTool } from '@runtools/sdk';

export default defineTool({
  name: 'my-api',
  description: 'Query my internal API',
  credentials: {
    required: ['apiKey'],
    schema: {
      apiKey: { type: 'string', description: 'API key for authentication' },
    },
    // Optional: enable OAuth auto-resolution
    oauth: {
      provider: 'google',
      scopes: ['https://www.googleapis.com/auth/spreadsheets.readonly'],
      credentialMapping: { apiKey: 'access_token' },
    },
  },
  actions: {
    query: {
      description: 'Query the API',
      parameters: {
        type: 'object',
        properties: {
          endpoint: { type: 'string', description: 'API endpoint' },
        },
        required: ['endpoint'],
      },
      execute: async (params, credentials) => {
        const res = await fetch(`https://my-api.com${params.endpoint}`, {
          headers: { 'Authorization': `Bearer ${credentials.apiKey}` },
        });
        return await res.json();
      },
    },
  },
});
Deploy and publish: 
# Deploy to your org
runtools deploy

# Make it public (optional)
runtools tool publish my-api

# List your custom tools
runtools tool list --custom
Custom tools are stored in the custom_tools database table and executed via Bun’s native TypeScript import (no VM overhead).

​
Tool Execution Flow

1. Agent calls tool (e.g., gmail.send_email)
2. RunTools API receives the tool call
3. Looks up tool: custom_tools DB (org first, then public)
4. Resolves credentials (per-request → stored → OAuth → empty)
5. If OAuth: fetches fresh token from auth service (auto-refreshes if expired)
6. Executes tool code with credentials injected
7. Returns result to agent
8. Logs execution in tool_executions table
When tools are called from inside sandbox VMs (by agents), credentials are resolved server-side. OAuth tokens never enter the sandbox.

​
Dashboard: Tool Hub

The Tool Hub page (Dashboard > Tool Hub) has three tabs:
  • Installed Tools — marketplace tools you’ve installed, with credential and connection status
  • Organization Tools — custom tools you’ve deployed via runtools deploy
  • Marketplace — browse and install all available tools
The Credentials page (Dashboard > Credentials > Connected Apps) manages your OAuth connections.

​
Best Practices

Connect your accounts via Connected Apps instead of manually managing tokens. OAuth connections auto-refresh and are more secure.
Use runtools tool exec to test a tool action directly before adding it to an agent.
If the marketplace doesn’t have what you need, write a custom tool with defineTool() — it’s just TypeScript.
You can pass credentials in the execute request body instead of storing them — useful for per-user credential scenarios.
Register your own OAuth app credentials so customers see your brand instead of RunTools during the consent flow.