Tools

Tools are how the models call external MCP servers and Chariot tool packages. Declare them under mcp_tools and chariot_tools on the orchestrator and on each service agent using the same patterns (see Agents).

note

Service agents: Chariot invalidates configurations where a service agent could return approval-gated tool output. Configure this behavior on the orchestrator instead.

Example

This configuration demonstrates one MCP server with filters and approval/artifact rules, plus chariot_tools.

{
  "name": "Tools Demo",
  "orchestrator": {
    "name": "Tools Demo",
    "model_settings": {
      "ai_provider": "openai",
      "name": "gpt-5-mini",
      "api_key": {
        "owner_type": "project",
        "owner_id": "<your-project-id>",
        "path": "secret/Custom/<openai-api-key-secret-id>/value"
      }
    },
    "system_prompt": "You help operators look up records and export reports on request. Use the available tools when they improve accuracy.",
    "mcp_tools": {
      "example_server": {
        "mcp_config": {
          "transport": "streamable-http",
          "url": "https://your-mcp-server.example/mcp",
          "headers": {
            "Authorization": "Bearer your-mcp-token"
          },
          "timeout": 60.0
        },
        "tools": {
          "include": ["^allowed_.*"]
        },
        "approval_required_tools": {
          "include": ["^delete_.*"]
        },
        "artifact_tools": {
          "include": ["^export_report$"]
        }
      }
    },
    "chariot_tools": {
      "packages": ["datasets"]
    }
  }
}

MCP tools (mcp_tools)

MCP tools are external MCP servers that this workflow can call.

Each mcp_tools entry is a map from a label you choose (e.g., example_server) to one server object. That object always has mcp_config and may also set tools, approval_required_tools, and artifact_tools on the same object.

mcp_config currently supports a single transport: streamable-http. Supply the url and, optionally, headers, timeout, or retries. Use headers to pass any authentication values that the server requires, such as a bearer token.

You can add any of these optional filter keys on the server object:

• tools: Limits which tools from the server are exposed to the model.
• approval_required_tools: Marks matching tools so they wait for approval before they run.
• artifact_tools: Marks matching tools so their outputs are stored and highlighted as artifacts.

Filter format

Each filter key holds an object with exactly one of include or exclude. A tool matches the filter when it matches any rule in include (or matches none of the rules in exclude).

Each rule in the list is either:

• A regular expression string matched against the tool name.
• An object with optional name, metadata, and args matchers for finer-grained conditions—for example, matching only when the tool is called with certain arguments.

Example: Require approval for publish_report only when it’s called against production:

"approval_required_tools": {
  "include": [
    {
      "name": "publish_report",
      "args": {
        "environment": "production"
      }
    }
  ]
}

Chariot tool packages (chariot_tools)

Chariot tool packages give the agent the ability to act on Chariot itself — for example, listing models in a project, deploying a model's Inference Server, querying the Inference Store for past predictions, or launching a Training Run. Each package wraps the agent-callable functions for one Chariot service and exposes them over MCP.

Set packages to the list of package names you want to enable. The available packages are:

• datasets: Datasets and annotations.
• projects: Project lookup and metadata.
• models: Model registry actions, including deploying Inference Servers.
• training_v2: Start and inspect Training Runs.
• bulk_inference: Launch and monitor bulk inference jobs.
• inference_store: Query the Inference Store for past predictions.
• system_resources: Read cluster compute information.
• watchbox: Tools associated with Sentinel Watch Boxes.

Example

The following workflow does three things: 1) lets the agent look up models and query past predictions, 2) requires human approval before any tool that deploys an Inference Server, and 3) saves Inference Store queries as artifacts:

"chariot_tools": {
  "packages": ["models", "inference_store", "projects"],
  "approval_required_tools": {
    "include": ["^MODELS_.*deploy.*"]
  },
  "artifact_tools": {
    "include": ["^INFERENCE_STORE_.*"]
  }
}

Tools from each package are exposed under the prefix <PACKAGE>_* (uppercase) — for example, MODELS_* or INFERENCE_STORE_* — which is what filter patterns match against. The same three optional filter keys that are used for MCP tools can be applied on the chariot_tools object:

• tools: Limits which packaged tools are exposed to the model.
• approval_required_tools: Marks matching tools so they wait for approval before they run.
• artifact_tools: Marks matching tools so their outputs are stored and highlighted as artifacts.

Each filter uses the same filter format as MCP tools.