WorkloadTruth MCP Server

Overview Schema Source Related Servers Discussions Admin

classify_workload

Identify whether a GPU is actually training, inferencing, or idle from telemetry alone, catching misreported or unauthorized workloads.

Instructions

Classify what a GPU is actually doing right now (TRAINING, INFERENCE, or IDLE) from raw telemetry alone -- utilization, memory-growth slope, and power draw -- with no reliance on a job's self-reported label and no inspection of its code, weights, or data.

Call this to catch cost misallocation (a job billed as low-priority "inference" that is really running full training) or an unauthorized workload change (an inference endpoint that quietly starts training on live traffic). Do not call it for compliance/regulatory reporting -- no such requirement exists for this signal, see the README's "What WorkloadTruth is not" section.

Prerequisites: backend="nvml" (the default) requires an NVIDIA GPU and driver on the host running this MCP server, plus the mcp+nvml extras (pip install "workloadtruth-cli[mcp,nvml]"). backend= "synthetic" needs neither a GPU nor extra driver setup -- it replays a documented synthetic trace selected by profile, so use it to test agent integrations or CI without hardware.

Side effects: read-only and safe to call repeatedly by default. It blocks for roughly samples * interval_seconds seconds while it collects telemetry (defaults: 10 x 1.0s = 10s), then returns. No network calls are made, ever. Setting write_to_audit_log=True is the one mutating path: it appends one hash-chained line to the local workloadtruth.log.jsonl file (each call adds a new entry, so this is not idempotent) -- everything else about the call is idempotent. If backend="nvml" is requested with no NVIDIA GPU/driver present, the call raises rather than returning a fabricated result.

Parameters: backend -- "nvml" or "synthetic". profile -- one of "training"/"inference"/"idle", synthetic backend only. gpu_index -- which GPU to sample, 0-indexed, ignored for synthetic. samples -- telemetry samples to collect. interval_seconds -- delay between samples. write_to_audit_log -- append the result to the hash chain. Example calls: {"backend": "synthetic", "profile": "training", "samples": 10, "interval_seconds": 0} to try it with no GPU; {"backend": "nvml", "samples": 20, "interval_seconds": 1.0, "write_to_audit_log": true} for a real 20s hardware sample that also logs the result.

Returns a dict with workload_type ("TRAINING"/"INFERENCE"/"IDLE"), confidence (0-1), gpu_index, window_seconds, sample_count, reasons (the specific thresholds that fired, e.g. "avg GPU utilization 82.3% >= 65.0% training threshold"), and features (the raw avg/std utilization, memory-growth, and power numbers the decision was based on -- nothing here is a black box).

Input Schema

TableJSON Schema

Name	Required	Default
`backend`	No	nvml
`profile`	No	training
`samples`	No
`gpu_index`	No
`interval_seconds`	No
`write_to_audit_log`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.2.0Sep 27, 2026

TDQS

A5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It covers read-only safety by default, blocking duration, no network calls, the single mutating path (write_to_audit_log) and its non-idempotency, and the error behavior when nvml is requested without a GPU. This is exhaustive and leaves no ambiguity about side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every section earns its place. It is structured into purpose, usage, prerequisites, side effects, parameters, examples, and return format, with the core purpose front-loaded. No sentences are redundant; the organization makes the length manageable and scannable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is complete for a complex tool: it explains the return dict fields (workload_type, confidence, gpu_index, window_seconds, sample_count, reasons, features), prerequisites, side effects, error handling, and parameter semantics. Even with an output schema present, the description adds essential context about the meaning of each field and the reasoning process, so nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema provides zero description coverage (0%), so the description must fully explain each parameter. It does so in a dedicated 'Parameters:' section, detailing backend, profile, gpu_index, samples, interval_seconds, and write_to_audit_log, including types, defaults, and context (e.g., profile only for synthetic backend). Example calls further illustrate parameter combinations. This fully compensates for the schema gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a precise statement of what the tool does: it classifies GPU activity into TRAINING, INFERENCE, or IDLE based on raw telemetry, explicitly distinguishing it from self-reported labels and code inspection. It clearly names the verb, resource, and method, and the use-case framing differentiates it from the sibling tools (run_benchmark, verify_audit_log) even without naming them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to call it ('catch cost misallocation', 'unauthorized workload change') and when not to ('Do not call it for compliance/regulatory reporting'), and provides a clear alternative (synthetic backend) for testing without hardware. It also lists prerequisites, so an agent knows exactly the conditions under which it is appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server