PerfLens MCP Server

Overview Schema Source Related Servers Discussions Admin

verify_trace_analysis

Read-onlyIdempotent

Replay and verify a stored sched/off-CPU/lock analysis to confirm its validity before agent interpretation, enabling reliable Linux performance conclusions.

Instructions

Replay and verify a stored sched/off-CPU/lock analysis before Agent interpretation.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`analysis_id`	Yes

Output Schema

TableJSON Schema

Name	Required	Default
`mode`	Yes
`clock`	Yes
`checks`	Yes
`limits`	Yes
`source`	Yes
`status`	Yes
`target`	Yes
`quality`	Yes
`warnings`	No
`conversion`	Yes
`analysis_id`	Yes
`input_bytes`	Yes
`input_sha256`	Yes
`content_sha256`	Yes
`schema_version`	No	1.0
`verification_id`	Yes
`perflens_version`	Yes
`verifier_version`	No	trace-verifier-v1
`observation_window`	Yes
`allowed_conclusions`	Yes
`verification_status`	Yes
`forbidden_conclusions`	Yes
`analysis_artifact_type`	Yes
`analysis_content_bytes`	Yes
`analysis_content_sha256`	Yes
`verification_fingerprint`	Yes
`agent_visible_content_sha256`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv0.3.2Aug 28, 2026

addedOutput schema / $defs / ContainerCollectionCgroupBinding

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "identity_sha256": {
+      "pattern": "^[a-f0-9]{64}$",
+      "title": "Identity Sha256",
+      "type": "string"
+    },
+    "inode": {
+      "exclusiveMinimum": 0,
+      "title": "Inode",
+      "type": "integer"
+    },
+    "version": {
+      "const": "v2",
+      "default": "v2",
+      "title": "Version",
+      "type": "string"
+    }
+  },
+  "required": [
+    "inode",
+    "identity_sha256"
+  ],
+  "title": "ContainerCollectionCgroupBinding",
+  "type": "object"
+}

addedOutput schema / $defs / ContainerCollectionNamespaceBinding

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "cgroup_namespace_inode": {
+      "exclusiveMinimum": 0,
+      "title": "Cgroup Namespace Inode",
+      "type": "integer"
+    },
+    "mount_namespace_inode": {
+      "exclusiveMinimum": 0,
+      "title": "Mount Namespace Inode",
+      "type": "integer"
+    },
+    "pid_namespace_inode": {
+      "exclusiveMinimum": 0,
+      "title": "Pid Namespace Inode",
+      "type": "integer"
+    },
+    "user_namespace_inode": {
+      "exclusiveMinimum": 0,
+      "title": "User Namespace Inode",
+      "type": "integer"
+    }
+  },
+  "required": [
+    "pid_namespace_inode",
+    "user_namespace_inode",
+    "mount_namespace_inode",
+    "cgroup_namespace_inode"
+  ],
+  "title": "ContainerCollectionNamespaceBinding",
+  "type": "object"
+}

addedOutput schema / $defs / ContainerCollectionTargetBinding

Added value: +{
+  "additionalProperties": false,
+  "description": "Privacy-safe Linux identity required to revalidate one Docker target.",
+  "properties": {
+    "adapter_recipe_id": {
+      "enum": [
+        "local-docker-read-v1",
+        "local-docker-managed-v1"
+      ],
+      "title": "Adapter Recipe Id",
+      "type": "string"
+    },
+    "adapter_sha256": {
+      "pattern": "^[a-f0-9]{64}$",
+      "title": "Adapter Sha256",
+      "type": "string"
+    },
+    "cgroup": {
+      "$ref": "#/$defs/ContainerCollectionCgroupBinding"
+    },
+    "container_identity_sha256": {
+      "pattern": "^[a-f0-9]{64}$",
+      "title": "Container Identity Sha256",
+      "type": "string"
+    },
+    "container_pid": {
+      "exclusiveMinimum": 0,
+      "title": "Container Pid",
+      "type": "integer"
+    },
+    "executable_name": {
+      "pattern": "^[^/\\x00]{1,255}$",
+      "title": "Executable Name",
+      "type": "string"
+    },
+    "host_pid": {
+      "exclusiveMinimum": 0,
+      "title": "Host Pid",
+      "type": "integer"
+    },
+    "host_start_time_ticks": {
+      "exclusiveMinimum": 0,
+      "title": "Host Start Time Ticks",
+      "type": "integer"
+    },
+    "host_uid": {
+      "minimum": 0,
+      "title": "Host Uid",
+      "type": "integer"
+    },
+    "identity_fingerprint": {
+      "pattern": "^[a-f0-9]{64}$",
+      "title": "Identity Fingerprint",
+      "type": "string"
+    },
+    "image_identity_sha256": {
+      "pattern": "^[a-f0-9]{64}$",
+      "title": "Image Identity Sha256",
+      "type": "string"
+    },
+    "namespace": {
+      "$ref": "#/$defs/ContainerCollectionNamespaceBinding"
+    },
+    "rootful_risk_authorized": {
+      "default": false,
+      "title": "Rootful Risk Authorized",
+      "type": "boolean"
+    },
+    "target_content_sha256": {
+      "pattern": "^[a-f0-9]{64}$",
+      "title": "Target Content Sha256",
+      "type": "string"
+    },
+    "target_id": {
+      "pattern": "^container-target-[a-f0-9]{20}$",
+      "title": "Target Id",
+      "type": "string"
+    },
+    "target_kind": {
+      "enum": [
+        "existing_container",
+        "managed_temporary_container"
+      ],
+      "title": "Target Kind",
+      "type": "string"
+    },
+    "uid_mapping": {
+      "enum": [
+        "rootless_same_uid",
+        "rootful_same_uid",
+        "rootful_cross_uid"
+      ],
+      "title": "Uid Mapping",
+      "type": "string"
+    }
+  },
+  "required": [
+    "target_id",
+    "target_kind",
+    "target_content_sha256",
+    "container_identity_sha256",
+    "image_identity_sha256",
+    "identity_fingerprint",
+    "container_pid",
+    "host_pid",
+    "host_uid",
+    "host_start_time_ticks",
+    "executable_name",
+    "namespace",
+    "cgroup",
+    "uid_mapping",
+    "adapter_recipe_id",
+    "adapter_sha256"
+  ],
+  "title": "ContainerCollectionTargetBinding",
+  "type": "object"
+}

addedOutput schema / $defs / TraceTargetIdentity / properties / container_target

Added value: +{
+  "anyOf": [
+    {
+      "$ref": "#/$defs/ContainerCollectionTargetBinding"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

addedOutput schema / $defs / TraceTargetIdentity / properties / target_runtime

Added value: +{
+  "default": "host",
+  "enum": [
+    "host",
+    "docker"
+  ],
+  "title": "Target Runtime",
+  "type": "string"
+}

Addedv0.3.0Aug 21, 2026

TDQS

A3.6/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that it 'replays' the analysis, implying re-execution or re-computation, which is behavioral context beyond annotations; but it doesn't disclose side effects (e.g., whether replay has external dependencies, whether it reproduces from raw traces, or requires prior artifacts) or what happens if the analysis_id is stale or invalid. It doesn't contradict annotations.

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 one concise sentence that front-loads the action ('Replay and verify') and specifies the resource scope upfront. No wasted words, and it is easy to scan. It earns a high score for efficiency but lacks some depth.

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

Completeness4/5

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

The tool is simple: 1 required string parameter, and output schema present. The description clearly communicates the tool's purpose and pipeline position ('before Agent interpretation'). However, it doesn't clarify important edge cases such as whether the analysis must already be collected, what counts as 'stored', or how verification results are returned despite the output schema existing. Given the simplicity, it is mostly complete, but a small gap remains in defining prerequisites.

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

Parameters3/5

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

Schema description coverage is 0% and there is only one parameter, analysis_id. The description uses the term 'stored sched/off-CPU/lock analysis' suggesting the analysis_id refers to an already stored/replayed analysis, but it doesn't explain the format, source, or lifecycle of analysis_id beyond what the schema already says (string). With only 1 param and no schema description, the description provides minimal added semantic value.

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

Purpose4/5

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

The description states a specific verb ('Replay and verify') and a specific resource ('a stored sched/off-CPU/lock analysis'). It clearly indicates the tool processes an existing analysis before agent interpretation. However, it doesn't explicitly distinguish it from the sibling 'verify_analysis' or 'analyze_trace_evidence', which are similar in the workflow.

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

Usage Guidelines3/5

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

The description implies usage in a verification workflow before agent interpretation but does not state when to use this tool vs alternatives like verify_analysis, analyze_trace_evidence, or inspect_collection_capabilities. There is no explicit when-not-to-use guidance or mention of alternatives.

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

Deploy Server