Tools

AGNT · Updated

Base URL http://localhost:3333/api/ · Authentication · Conventions

Tools Routes

Base path: /api/tools

Get Orchestrator Tools

GET /orchestrator-tools

  • Authentication: Required
  • Description: Get all orchestrator tools (native, registry, and plugin tools)
  • Response:
{
  "tools": [
    {
      "id": "tool-name",
      "name": "Tool Name",
      "title": "Tool Title",
      "description": "Tool description",
      "category": "Data & Knowledge",
      "is_builtin": true,
      "is_plugin": false,
      "plugin_name": null
    }
  ]
}

Get Workflow Tools

GET /workflow-tools

  • Authentication: Required
  • Description: Get all tools for the workflow designer including plugins and custom tools
  • Response:
{
  "triggers": [
    {
      "type": "trigger-type",
      "title": "Trigger Title",
      "description": "Trigger description",
      "icon": "trigger-icon",
      "isPlugin": false
    }
  ],
  "actions": [
    {
      "type": "action-type",
      "title": "Action Title",
      "description": "Action description",
      "icon": "action-icon",
      "isPlugin": false
    }
  ],
  "utilities": [
    {
      "type": "utility-type",
      "title": "Utility Title",
      "description": "Utility description",
      "icon": "utility-icon",
      "isPlugin": false
    }
  ],
  "widgets": [],
  "controls": [],
  "custom": [
    {
      "id": "custom-tool-id",
      "name": "Custom Tool",
      "description": "Custom tool description"
    }
  ]
}

Get Plugin Tools Only

GET /plugins-only

  • Authentication: None
  • Description: Get only plugin tools (for real-time updates)
  • Response:
{
  "success": true,
  "plugins": {
    "triggers": [
      {
        "type": "plugin-trigger",
        "title": "Plugin Trigger",
        "description": "Description",
        "icon": "puzzle-piece",
        "isPlugin": true,
        "pluginName": "plugin-name"
      }
    ],
    "actions": [],
    "utilities": [],
    "widgets": [],
    "controls": [],
    "custom": []
  },
  "totalCount": 1
}

Execute Tool

POST /:toolName/execute

  • Authentication: Required
  • Parameters:
    • toolName (path): Tool identifier — accepts kebab-case (chucknorris-get-joke) or snake_case (chucknorris_get_joke). Resolves across native orchestrator tools, agent/workflow/goal/code/widget/tool-forge tools, registry tools, and installed plugin tools.
  • Body:
{
  "args": { "category": "dev" }
}
  • Description: Universal tool execution endpoint. Invokes any registered tool by name with the supplied arguments and returns the parsed result. Argument validation, OAuth resolution for tools that require it, and registry/plugin dispatch are all handled internally — this is the same pipeline the chat orchestrator uses to call tools.
  • Response (success):
{
  "success": true,
  "tool": "chucknorris-get-joke",
  "result": {
    "joke": "Chuck Norris doesn't write code...",
    "id": "abc123",
    "categories": ["dev"],
    "url": "https://api.chucknorris.io/jokes/abc123"
  }
}
  • Response (tool reported failure):
{
  "success": false,
  "tool": "chucknorris-get-joke",
  "error": "Validation failed: 'category' must be one of [...]",
  "details": { "...": "full payload returned by the tool" }
}
  • Response 401: { "success": false, "error": "Authentication required" }

Custom Tool Routes

Base path: /api/custom-tools

Health Check

GET /health

  • Authentication: None
  • Description: Check if the custom tool service is running
  • Response:
{
  "status": "OK"
}

Get All Custom Tools

GET /

  • Authentication: Required
  • Description: Retrieve all custom tools for the authenticated user
  • Response:
[
  {
    "id": "tool-id",
    "name": "Custom Tool",
    "description": "Tool description",
    "config": {},
    "userId": "user-id",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
]

Save/Update Custom Tool

POST /save

  • Authentication: Required
  • Description: Create a new custom tool or update an existing one
  • Body:
{
  "id": "optional-tool-id",
  "name": "Custom Tool",
  "description": "Tool description",
  "config": {}
}
  • Response:
{
  "success": true,
  "tool": {
    "id": "tool-id",
    "name": "Custom Tool",
    "description": "Tool description",
    "config": {},
    "userId": "user-id",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
}

Get Custom Tool by ID

GET /:id

  • Authentication: Required
  • Parameters:
    • id (path): Tool ID
  • Description: Retrieve a specific custom tool by ID
  • Response:
{
  "id": "tool-id",
  "name": "Custom Tool",
  "description": "Tool description",
  "config": {},
  "userId": "user-id",
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z"
}

Update Custom Tool

PUT /:id

  • Authentication: Required
  • Parameters:
    • id (path): Tool ID
  • Body:
{
  "name": "Updated Tool Name",
  "description": "Updated description",
  "config": {}
}
  • Response:
{
  "success": true,
  "tool": {
    "id": "tool-id",
    "name": "Updated Tool Name",
    "description": "Updated description",
    "config": {},
    "userId": "user-id",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
}

Delete Custom Tool

DELETE /:id

  • Authentication: Required
  • Parameters:
    • id (path): Tool ID
  • Description: Delete a custom tool by ID
  • Response:
{
  "success": true,
  "message": "Custom tool deleted successfully"
}

Tool Schema Routes

Base path: /api/tool-schemas

Get All Tool Schemas

GET /schemas

  • Authentication: None
  • Description: Get all tool schemas organized by category
  • Response:
{
  "triggers": [
    {
      "type": "trigger-type",
      "title": "Trigger Title",
      "description": "Trigger description",
      "schema": {}
    }
  ],
  "actions": [
    {
      "type": "action-type",
      "title": "Action Title",
      "description": "Action description",
      "schema": {}
    }
  ],
  "utilities": [
    {
      "type": "utility-type",
      "title": "Utility Title",
      "description": "Utility description",
      "schema": {}
    }
  ]
}

Get Tool Schema by Type

GET /schemas/:toolType

  • Authentication: None
  • Parameters:
    • toolType (path): Tool type
  • Description: Get schema for a specific tool
  • Response:
{
  "type": "tool-type",
  "title": "Tool Title",
  "description": "Tool description",
  "schema": {
    "properties": {},
    "required": []
  }
}

Get Schemas by Category

GET /schemas/category/:category

  • Authentication: None
  • Parameters:
    • category (path): Category name (triggers, actions, utilities, etc.)
  • Description: Get schemas by category
  • Response:
[
  {
    "type": "tool-type",
    "title": "Tool Title",
    "description": "Tool description",
    "schema": {}
  }
]

Get Registry Statistics

GET /stats

  • Authentication: None
  • Description: Get registry statistics
  • Response:
{
  "totalTools": 50,
  "categories": {
    "triggers": 10,
    "actions": 25,
    "utilities": 15
  },
  "lastUpdated": "2024-01-01T00:00:00Z"
}

Get Tool Metadata

GET /metadata/:toolType

  • Authentication: None
  • Parameters:
    • toolType (path): Tool type
  • Description: Get metadata for a specific tool (includes source info)
  • Response:
{
  "type": "tool-type",
  "source": "builtin|plugin|custom",
  "plugin": "plugin-name",
  "version": "1.0.0",
  "author": "Author Name",
  "createdAt": "2024-01-01T00:00:00Z"
}

Reload Registry

POST /reload

  • Authentication: Required
  • Description: Reload the registry (useful for development)
  • Response:
{
  "success": true,
  "message": "Tool registry reloaded successfully",
  "stats": {
    "totalTools": 50,
    "categories": {
      "triggers": 10,
      "actions": 25,
      "utilities": 15
    }
  }
}

NPM Routes

Base path: /api/npm

Search MCP Servers

GET /search

  • Authentication: Required
  • Parameters:
    • q (query): Search query
    • limit (query): Maximum results (optional)
  • Description: Search for MCP servers on NPM
  • Response:
{
  "success": true,
  "packages": [
    {
      "name": "package-name",
      "version": "1.0.0",
      "description": "Package description",
      "author": "Author Name",
      "keywords": ["mcp", "server"],
      "downloads": 1000
    }
  ]
}

GET /popular

  • Authentication: Required
  • Description: Get popular MCP servers from NPM
  • Response:
{
  "success": true,
  "packages": [
    {
      "name": "popular-package",
      "version": "1.0.0",
      "description": "Popular package description",
      "downloads": 10000,
      "rating": 4.5
    }
  ]
}

Get Package Details

GET /package/:packageName

  • Authentication: Required
  • Parameters:
    • packageName (path): NPM package name
  • Description: Get detailed information about a specific NPM package
  • Response:
{
  "success": true,
  "package": {
    "name": "package-name",
    "version": "1.0.0",
    "description": "Package description",
    "author": "Author Name",
    "license": "MIT",
    "repository": "https://github.com/user/repo",
    "dependencies": {},
    "downloads": {
      "lastWeek": 1000,
      "lastMonth": 5000,
      "total": 50000
    },
    "readme": "README content"
  }
}

Test Package

POST /test

  • Authentication: Required
  • Body:
{
  "packageName": "package-name",
  "version": "1.0.0"
}
  • Response:
{
  "success": true,
  "testResults": {
    "compatible": true,
    "issues": [],
    "recommendations": []
  }
}
← Back
All documentation
Improve this page
Edit on GitHub
The AGNT briefing

Stay in the loop.

New agents, workflows and field notes. Sign up for AGNT updates.

By subscribing, you agree to receive AGNT updates. Unsubscribe any time. Privacy policy.