Skip to content

Tool Registry

Jump to bottom
Corey McCallum edited this page Jan 31, 2026 · 4 revisions

Tool Registry

The CAAL Tool Registry is a community-driven platform for sharing voice-optimized n8n workflows. Think of it as an app store for CAAL capabilities. The registry is part of the CAAL Tool API, which defines how tools are built, shared, and installed.

What Makes Registry Tools Special?

Unlike generic n8n templates, registry tools are optimized for voice:

  • Voice triggers - Example phrases showing how to invoke the tool
  • Low latency - Optimized for quick responses
  • Conversational responses - Natural language, not raw JSON
  • One-click installation - Pre-configured with sensible defaults
  • Parameterized - Service URLs and credentials as variables

Tool Types

Individual Tools

Single-purpose tools that do one specific thing well.

Naming: service_action_object (e.g., truenas_get_status, radarr_add_movie)

Example:

  • "What's my TrueNAS status?" → truenas_get_status
  • "Add Inception to Radarr" → radarr_add_movie

Tool Suites

Multi-action tools that group related functionality into a single workflow using a Switch node.

Naming: service (e.g., google_tasks, truenas, espn_nhl)

Example: The google_tasks suite handles multiple actions:

  • "What's on my task list?" → action: get
  • "Add task buy groceries" → action: add
  • "Mark done the groceries task" → action: complete
  • "Delete the milk task" → action: delete

Why suites?

  • 80% fewer workflows - 100 capabilities in ~20 suites vs 100 separate workflows
  • Shared logic - Common error handling, credentials, rate limiting
  • Cleaner registry - Browse by service, not individual actions
  • Better for LLMs - Fewer top-level tool choices

Manifest fields for suites:

{
  "name": "google_tasks",
  "friendlyName": "Google Tasks",
  "toolSuite": true,
  "actions": ["get", "add", "complete", "delete"],
  "icon": "google_tasks.svg",
  ...
}

Discovering Tools

In CAAL (Recommended)

  1. Click the wrench icon in CAAL web interface
  2. Browse by category or search
  3. Click a tool to see details
  4. Click "Install" to add it to your CAAL

On GitHub

Browse the registry at github.com/CoreWorxLab/caal-tools

Categories:

  • Smart Home - Home Assistant, lights, climate, security
  • Media - Plex, Jellyfin, Jellyseerr, Sonarr, Radarr
  • Homelab - TrueNAS, Docker, Proxmox, Unraid, PiHole
  • Productivity - Calendar, tasks, email, notes
  • Developer - GitHub, GitLab, CI/CD, code tools
  • Utilities - Weather, timers, reminders
  • Sports - ESPN, fantasy sports, scores, standings
  • Social - Discord, Slack, Reddit, Telegram

Installing Tools

Via CAAL Frontend (Easiest)

  1. Open Tools panel (wrench icon)
  2. Browse or search for a tool
  3. Click the tool card to view details
  4. Click "Install"
  5. Fill in required configuration:
    • Variables - Service URLs (e.g., TRUENAS_URL: http://192.168.1.100)
    • Credentials - n8n credential names (e.g., truenas_api)
  6. Click "Install Tool"

CAAL automatically:

  • Imports the workflow into n8n
  • Substitutes your variables
  • Links your credentials
  • Activates the workflow
  • Reloads tools

Via CLI

curl -s https://raw.githubusercontent.com/CoreWorxLab/caal-tools/main/scripts/install.sh | bash -s <tool-name>

Example:

curl -s https://raw.githubusercontent.com/CoreWorxLab/caal-tools/main/scripts/install.sh | bash -s truenas-get-status

Manual Installation

  1. Download workflow.json from the tool's folder in the registry
  2. In n8n: Settings > Import from File
  3. Create required credentials (see tool's README)
  4. Update service URLs in workflow nodes
  5. Activate the workflow
  6. Reload tools: curl -X POST http://localhost:8889/reload-tools

Submitting Your Tools

From CAAL Frontend (Recommended)

The best way to submit tools is through the CAAL interface itself - if you're using it, you can share it!

  1. Build and test your workflow in n8n

    • Create workflow with webhook trigger
    • Test it thoroughly
    • Make sure it works with CAAL

  2. Open Tools Panel → Installed Tools tab

    • Your custom workflows appear here
    • Registry tools show up separately

  3. Click "Share" on your custom workflow

    • CAAL sanitizes the workflow locally in your browser
    • Strips API keys, tokens, passwords
    • Replaces hardcoded URLs with variables
    • Shows you exactly what was removed

  4. Review security dialog

    ⚠️ Security Check Complete

Stripped from workflow:
- 2 API keys
- 1 bearer token

URLs detected (will be parameterized):
- http://192.168.1.100 → ${TRUENAS_URL}

Credentials detected:
- TrueNAS API (httpHeaderAuth)

✅ Your secrets never leave your network.

  5. Click "Continue to Submission Form"

    • Opens registry.caal.io/submit/{session-id} in new tab
    • Form pre-filled with detected values

  6. Fill in tool metadata

    • Tool name (kebab-case)
    • Category
    • Description (20+ chars)
    • Voice triggers (2 minimum)
    • Services required
    • Your GitHub username

  7. Submit

    • Creates GitHub PR automatically
    • PR includes: workflow.json, manifest.json, README.md
    • Automated review runs within minutes

Via intake.js Script (Alternative)

For bulk submissions or if you're not running CAAL:

cd caal-tools
node scripts/intake.js ~/Downloads/my-workflow.json

The script will:

  • Detect and strip secrets
  • Prompt for metadata
  • Replace hardcoded URLs with variables
  • Generate manifest and README
  • Create PR structure

Then manually create PR:

git checkout -b add-my-tool
git add .
git commit -m "feat: add my-tool"
git push origin add-my-tool

Quality Guidelines

Your tool must:

  • Have webhook trigger with description in notes
  • Include at least 2 voice trigger examples
  • Return voice-friendly responses (not raw JSON)
  • Handle errors gracefully
  • Not contain hardcoded secrets
  • Respond quickly. Use quick response + delayed /announce webhook for longer tasks

See the CAAL Tool API for the complete tool spec and How Tool Calling Works for how CAAL discovers and executes tools.

Submission Pipeline

Here's what happens after you submit:

┌────────────────────────────────────────────────────────────────┐
│  1. CAAL Frontend (Your Browser)                               │
│                                                                │
│  • Sanitizes workflow locally (secrets never sent)             │
│  • Shows security confirmation dialog                          │
│  • POSTs sanitized workflow to registry.caal.io                │
└────────────────────────┬───────────────────────────────────────┘
                         │
                         ▼
┌────────────────────────────────────────────────────────────────┐
│  2. Submission Form (registry.caal.io)                         │
│                                                                │
│  • Pre-filled with suggested values                            │
│  • User adds voice triggers, category, description             │
│  • Validates inputs                                            │
│  • Shows detected variables/credentials                        │
└────────────────────────┬───────────────────────────────────────┘
                         │
                         ▼
┌────────────────────────────────────────────────────────────────┐
│  3. PR Creation                                                │
│                                                                │
│  • Creates branch in caal-tools repo                           │
│  • Commits files:                                              │
│    - workflow.json (sanitized)                                 │
│    - manifest.json (metadata)                                  │
│    - README.md (generated)                                     │
│  • Opens pull request                                          │
│  • Tags PR with submitter username                             │
└────────────────────────┬───────────────────────────────────────┘
                         │
                         ▼
┌────────────────────────────────────────────────────────────────┐
│  4. Automated Review                                           │
│                                                                │
│  • Validates manifest schema                                   │
│  • Checks workflow structure                                   │
│  • Verifies no hardcoded secrets                               │
│  • Reviews README quality                                      │
│  • Auto-fixes common issues                                    │
│  • Posts review comment                                        │
│  • Applies label: ready-to-merge / needs-changes               │
└────────────────────────┬───────────────────────────────────────┘
                         │
                         ▼
┌────────────────────────────────────────────────────────────────┐
│  5. Merge & Publish                                            │
│                                                                │
│  • Maintainer reviews and merges PR                            │
│  • Registry index regenerates                                  │
│  • Tool appears in registry                                    │
│  • Available for installation in all CAAL instances            │
└────────────────────────────────────────────────────────────────┘

Tool Quality Tiers

Tier Badge Meaning
CoreWorxLab Gold Official tools maintained by CoreWorxLab team
Community Silver Community-contributed tools

All tools pass automated review before appearing in the registry.

Privacy & Security

Client-Side Sanitization

Your secrets never leave your network.

When you click "Share" in CAAL, sanitization happens entirely in your browser:

  1. Secret Detection - Scans workflow JSON for:

    • API keys (patterns like api_key: "sk_xxxxx")
    • Bearer tokens
    • Passwords
    • Credential IDs

  2. Secret Stripping - Removes found secrets:

    • Credential IDs set to null
    • API key values deleted
    • Tokens removed

  3. URL Parameterization - Replaces hardcoded URLs:

    • http://192.168.1.100 → ${TRUENAS_URL}
    • http://192.168.1.50:8080 → ${SERVICE_URL}

  4. Confirmation Dialog - Shows exactly what was stripped before transmission

Only the sanitized workflow is sent to registry.caal.io.

What Gets Shared

Included in submission:

  • Workflow structure (nodes, connections)
  • Service integrations used
  • Credential types (e.g., "httpHeaderAuth")
  • Variable placeholders (e.g., ${TRUENAS_URL})

Never included:

  • API keys or tokens
  • Passwords
  • Your actual service URLs
  • Your n8n credential names
  • Any data from your environment

Registry Index

Tools are cataloged in index.json:

{
  "tools": [
    {
      "id": "truenas-get-status",
      "name": "TrueNAS Get Status",
      "description": "Get system status from TrueNAS",
      "category": "homelab",
      "tier": "coreworxlab",
      "version": "1.0.0",
      "author": {
        "github": "cmac86"
      },
      "voice_triggers": [
        "what's my TrueNAS status",
        "how's my NAS doing"
      ],
      "required_services": ["truenas"],
      "required_credentials": [
        {
          "credential_type": "httpHeaderAuth",
          "name": "truenas_api",
          "description": "TrueNAS API key (Header Auth)"
        }
      ],
      "required_variables": [
        {
          "name": "TRUENAS_URL",
          "description": "Your TrueNAS instance URL",
          "example": "http://192.168.1.100"
        }
      ],
      "tags": ["truenas", "nas", "storage", "monitoring"]
    }
  ]
}

Generated automatically on every merge to main.

Contributing Guidelines

See the full Contributing Guide for:

  • Detailed submission instructions
  • Quality standards checklist
  • Manifest schema reference
  • Voice-first design principles
  • README template

Tool Request

Don't know how to build a tool but have an idea? Request it!

Community members or maintainers may build it for you.

FAQ

How do I update a tool I've installed?

Tools panel shows an "Update Available" badge when registry has a newer version. Click to reinstall with the latest version.

Can I modify registry tools after installation?

Yes! Once installed, they're regular n8n workflows. Edit them however you want. Just note that modifications disconnect them from registry updates.

What happens if I submit a tool with secrets?

The client-side sanitizer catches secrets before submission. If anything slips through, the automated review will reject the PR with specific feedback about what to remove.

How long does PR review take?

Automated review runs within 1-5 minutes of PR creation. Manual maintainer review depends on queue, typically 1-3 days.

Can I submit tools anonymously?

The submission form asks for your GitHub username for attribution, but the PR is created on your behalf. Your username appears in the tool's metadata and PR description.

What if my tool needs a service most people don't have?

That's fine! Niche tools are welcome. Just document the requirements clearly. Users can see required services before installing.

Do I need to maintain tools I submit?

No obligation, but appreciated! If a tool breaks due to API changes, community members or maintainers may update it.

Further Reading

Home

Getting Started

Architecture

Tools

Integrations

Language Support

Deployment

Links

Clone this wiki locally