Skip to main content
The Tools API gives you direct access to the MCP tools registered in Jarvis — including ServiceNow integrations and custom Jarvis tools. You can list available tools, filter by category, and invoke them with structured inputs. All requests require an Authorization header. See the API overview for authentication details.

​
GET /tools

List all MCP tools available in your Jarvis environment.

​
Query parameters

​
category
string
Filter tools by category (e.g., servicenow, jarvis, files, network). Returns all tools if omitted.
​
limit
integer
Maximum number of tools to return. Defaults to 50. Maximum is 200.
​
offset
integer
Number of tools to skip for pagination. Defaults to 0.

​
Response

​
tools
array
An array of tool descriptor objects.
​
total
integer
Total number of tools matching the query (before pagination).

​
Example

curl
curl "https://your-jarvis-host/tools?category=servicenow&limit=3" \
  -H "Authorization: Bearer jrv_yourkey123"
Response
{
  "tools": [
    {
      "name": "servicenow_create_incident",
      "description": "Create a new incident in ServiceNow.",
      "category": "servicenow",
      "input_schema": {
        "type": "object",
        "properties": {
          "short_description": { "type": "string" },
          "urgency": { "type": "integer", "enum": [1, 2, 3] },
          "assigned_to": { "type": "string" }
        },
        "required": ["short_description"]
      }
    },
    {
      "name": "servicenow_get_incident",
      "description": "Retrieve an incident by its number.",
      "category": "servicenow",
      "input_schema": {
        "type": "object",
        "properties": {
          "number": { "type": "string" }
        },
        "required": ["number"]
      }
    }
  ],
  "total": 2
}

​
POST /tools/invoke

Invoke a specific MCP tool with structured input. Jarvis validates your input against the tool’s schema before executing.

​
Request

​
tool
string
required
The name of the tool to invoke, as returned by GET /tools.
​
input
object
required
The tool’s input parameters. Must conform to the tool’s input_schema. See GET /tools for the schema of each tool.
​
timeout
integer
Maximum time in seconds to wait for the tool to complete. Defaults to 30. Maximum is 300.

​
Response

​
tool
string
The name of the tool that was invoked.
​
status
string
Result status. One of: success, error.
​
output
object
The tool’s output data. Structure varies by tool — refer to each tool’s documentation or input_schema for expected output shape.
​
error
string
Error message if status is error. Includes schema validation failures and execution errors.
​
duration_ms
integer
How long the tool took to execute, in milliseconds.

​
Example

curl
curl -X POST https://your-jarvis-host/tools/invoke \
  -H "Authorization: Bearer jrv_yourkey123" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "servicenow_create_incident",
    "input": {
      "short_description": "API gateway returning 503 on all requests",
      "urgency": 1,
      "assigned_to": "platform-team"
    }
  }'
Response
{
  "tool": "servicenow_create_incident",
  "status": "success",
  "output": {
    "number": "INC0012345",
    "sys_id": "abc123def456",
    "state": "New",
    "created_at": "2026-04-04T10:45:00Z"
  },
  "duration_ms": 342
}

​
Tool input and output schemas

Each tool exposes a JSON Schema in its input_schema field. You can use this to validate inputs before sending them, or to auto-generate form UIs.
Agents like Paperclip and Hermes use the same tool schemas internally. If you’re building an agent workflow, you can pass tool schemas directly to the model as function definitions in POST /chat/completions.
Inputs that don’t match the tool’s input_schema are rejected with a 400 error before the tool executes. Check required fields and data types carefully.
Output shapes are tool-specific and not standardized across categories. Always test tool outputs in a safe environment before building automation on top of them.

​
Filtering by category

Jarvis organizes tools into categories. Use the category query parameter on GET /tools to narrow results.
CategoryDescription
servicenowServiceNow ITSM integrations (526+ tools)
jarvisBuilt-in Jarvis platform tools
filesFile system read/write tools
networkNetwork diagnostics and queries
The available categories depend on which MCP servers are enabled in your Jarvis configuration. See MCP Tools for setup details.