Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.runtools.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Tool Hub is the hosted integration layer for Runtools. Tools run on tools.runtools.ai, resolve credentials server-side, and can be called directly or from agents. Tools are stored in the same public/private custom-tool system whether they are official marketplace tools or tools your organization deploys.

​
Marketplace

runtools tool search github
runtools tool install github
runtools tool list --installed

​
Credential Resolution

When executing a tool, Runtools fills credentials in this order:
PrioritySource
1Per-request credentials
2Per-request credentialOverrides that map credential fields to named secrets
3Stored credentials for the installed tool
4Matching user-private or org-shared secrets
5OAuth connection declared by the tool credentials spec
OAuth-enabled tools use Connected Apps: 
runtools oauth connect github
runtools oauth status

​
Execute a Tool

runtools tool exec github \
  --action list_repos \
  --params '{}'
Responses are normalized: 
{
  "data": {
    "success": true,
    "result": {},
    "durationMs": 123
  }
}

​
Custom Tools

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

export default defineTool({
  name: 'customer-api',
  description: 'Look up customer records',
  credentials: {
    required: ['apiKey'],
    schema: {
      apiKey: { type: 'string', description: 'Customer API key' },
    },
  },
  actions: {
    lookup: {
      description: 'Find a customer by email',
      parameters: {
        type: 'object',
        properties: {
          email: { type: 'string', description: 'Customer email' },
        },
        required: ['email'],
      },
      execute: async (params, credentials) => {
        const res = await fetch(`https://api.example.com/customers?email=${params.email}`, {
          headers: { Authorization: `Bearer ${credentials.apiKey}` },
        });
        return res.json();
      },
    },
  },
});
Deploy and optionally share inside your org: 
runtools deploy --tools-only
runtools tool list --custom
runtools tool publish customer-api --org

​
SDK Methods

MethodDescription
rt.tools.marketplace()List public tools
rt.tools.search(query)Search public tools
rt.tools.get(slug)Fetch public tool metadata
rt.tools.list()List installed tools for the caller
rt.tools.custom()List visible custom tools
rt.tools.install(slug)Install a tool
rt.tools.uninstall(slug)Uninstall a tool
rt.tools.storeCredentials(slug, credentials)Store user-owned credentials
rt.tools.credentials(slug)Check stored credential status
rt.tools.clearCredentials(slug)Remove stored credentials
rt.tools.execute(slug, options)Execute an action

​
Best Practices

Connected Apps avoid manual token handling and refresh automatically.
Store shared API keys as org-wide secrets or user-private secrets instead of passing them in every request.
Run runtools tool exec before adding a tool to an agent definition.