Itential MCP Server

Official

by itential

Overview Schema Source Related Servers Discussions Admin

Python

Remote

Describe Session

describe_session

Read-onlyIdempotent

Retrieve detailed records for a specific agent session, including completed reasoning turns and final text output.

Instructions

Get detailed information about a specific agent session.

Returns the full session record including the filtered reasoning event log and the final text output produced by the agent. The raw event log is filtered down to only AGENT_REASONING events whose data.stopReason is "end_turn" — these represent completed model turns. Tool-execution events, pending-inference events, tool_use-stopReason reasoning steps (mid-turn, not yet final), reasoning events with no data at all, and session-status events are all dropped.

Input Schema

Name	Required	Description	Default
`session_id`	Yes	The session ID to retrieve full details for

Output Schema

Name	Required	Description
`output`	No	Final text output produced by the agent; taken from the last kept reasoning event's text. None if the session has not completed or produced no matching reasoning event.
`status`	Yes	Session status (RUNNING, COMPLETE, FAILED)
`end_time`	No	ISO 8601 end timestamp; None if the session is still RUNNING
`agent_name`	No	Name of the agent that ran
`session_id`	Yes	Unique session identifier
`started_at`	No	ISO 8601 start timestamp
`duration_ms`	No	Total session duration in milliseconds
`reasoning_events`	No	Ordered list of kept AGENT_REASONING events (those with data.stopReason == "end_turn") captured during agent execution
`pending_manual_tasks`	No	Manual tasks currently waiting on a human. Tri-state: None means unknown (the lookup failed with an error other than not-found, e.g. 403, 500 or a timeout; the rest of this response is still valid). An empty list means none are pending, including when the session is not running (the lookup only runs while status is RUNNING). A non-empty list holds the pending tasks; use describe_manual_task with a work_item_id for detail. Detection covers manual tasks attached directly to this session's own ID; tasks inside nested or child runs are not guaranteed to be listed.

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv0.14.1Oct 18, 2026

changedOutput schema / description

Previous value: -"Response model for agent session detail endpoints.\n\nProvides the full detail of an agent session including the complete event\nlog and the final output text produced by the agent. Use this model to\ninspect what the agent did and what it returned.\n\nAttributes:\n    session_id: Unique session identifier.\n    agent_name: Name of the agent that ran.\n    status: Session status (RUNNING, COMPLETE, FAILED).\n    output: Final text output produced by the agent (from the\n        inference-succeeded event). None if the session has not yet\n        completed or produced no output.\n    started_at: ISO 8601 start timestamp.\n    end_time: ISO 8601 end timestamp (None if still running).\n    duration_ms: Total session duration in milliseconds.\n    messages: Ordered list of session event messages."New value: +"Response model for agent session detail endpoints.\n\nProvides the full detail of an agent session including the filtered\nreasoning event log and the final output text produced by the agent.\nUse this model to inspect what the agent did and what it returned.\n\nAttributes:\n    session_id: Unique session identifier.\n    agent_name: Name of the agent that ran.\n    status: Session status (RUNNING, COMPLETE, FAILED).\n    output: Final text output produced by the agent (the last kept\n        reasoning event's text). None if the session has not yet\n        completed or produced no matching reasoning event.\n    started_at: ISO 8601 start timestamp.\n    end_time: ISO 8601 end timestamp (None if still running).\n    duration_ms: Total session duration in milliseconds.\n    reasoning_events: Ordered list of kept AGENT_REASONING events (those\n        with data.stopReason == \"end_turn\").\n    pending_manual_tasks: Manual tasks waiting on a human (None if unknown)."

removedOutput schema / properties / messages

Removed value: -{
-  "description": "Ordered list of session event messages captured during agent execution",
-  "items": {
-    "description": "Represents a single event message from an agent session.\n\nSession messages capture the discrete events emitted during agent execution,\nincluding model inference steps, tool calls, and final outputs. Each message\nhas a type that classifies the event and an optional text payload.\n\nAttributes:\n    event_type: The event classification (e.g., \"inference-succeeded\",\n        \"tool-call\", \"agent-error\").\n    category: Optional grouping category for the event.\n    text: The text content of the event (e.g., model output, error message).\n    timestamp: ISO 8601 timestamp when the event was emitted.",
-    "properties": {
-      "category": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Optional grouping category for the event",
-        "title": "Category"
-      },
-      "text": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Text content of the event such as model output or error message",
-        "title": "Text"
-      },
-      "timestamp": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "ISO 8601 timestamp when this event was emitted",
-        "title": "Timestamp"
-      },
-      "type": {
-        "description": "Event classification for this message (e.g., inference-succeeded,\ntool-call, agent-error)",
-        "title": "Type",
-        "type": "string"
-      }
-    },
-    "required": [
-      "type"
-    ],
-    "title": "SessionMessage",
-    "type": "object"
-  },
-  "title": "Messages",
-  "type": "array"
-}

changedOutput schema / properties / output / description

Previous value: -"Final text output produced by the agent; extracted from the\ninference-succeeded event. None if the session has not completed\nor produced no text output."New value: +"Final text output produced by the agent; taken from the last\nkept reasoning event's text. None if the session has not\ncompleted or produced no matching reasoning event."

addedOutput schema / properties / pending_manual_tasks

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "description": "Summary of a manual task that is waiting on a human.\n\nAttributes:\n    work_item_id: Work item identifier; pass to describe_manual_task.\n    title: The task's human-readable title, verbatim from the platform.\n    view_type: The task view type (for example \"ViewData\").\n    waiting_age_seconds: Seconds the task has been waiting, or None if\n        the creation time is unavailable.\n    completion_supported: Whether MCP can complete this view type.",
+        "properties": {
+          "completion_supported": {
+            "default": false,
+            "description": "True if this view type is one that MCP can complete (ViewData,\nViewHTML, InteractiveHTML); False for form views and unknown\nview types",
+            "title": "Completion Supported",
+            "type": "boolean"
+          },
+          "title": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "Human-readable title of the manual task, as set by the\nworkflow author",
+            "title": "Title"
+          },
+          "view_type": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "Manual task view type, for example ViewData, ViewHTML,\nInteractiveHTML or RenderJsonSchema",
+            "title": "View Type"
+          },
+          "waiting_age_seconds": {
+            "anyOf": [
+              {
+                "type": "integer"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "Seconds the task has been waiting on a human (now minus the\nwork item's creation time); None if unavailable",
+            "title": "Waiting Age Seconds"
+          },
+          "work_item_id": {
+            "description": "Work item identifier; pass to describe_manual_task for detail",
+            "title": "Work Item Id",
+            "type": "string"
+          }
+        },
+        "required": [
+          "work_item_id"
+        ],
+        "title": "ManualTaskSummary",
+        "type": "object"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Manual tasks currently waiting on a human. Tri-state: None\nmeans unknown (the lookup failed with an error other than\nnot-found, e.g. 403, 500 or a timeout; the rest of this\nresponse is still valid). An empty list means none are\npending, including when the session is not running (the\nlookup only runs while status is RUNNING). A non-empty list holds the\npending tasks; use describe_manual_task with a work_item_id for\ndetail. Detection covers manual tasks attached directly to\nthis session's own ID; tasks inside nested or child runs are not\nguaranteed to be listed.",
+  "title": "Pending Manual Tasks"
+}

addedOutput schema / properties / reasoning_events

Added value: +{
+  "description": "Ordered list of kept AGENT_REASONING events (those with\ndata.stopReason == \"end_turn\") captured during agent execution",
+  "items": {
+    "description": "Represents a single kept AGENT_REASONING event from an agent session.\n\ndescribe_session filters the raw session event log down to only the\nAGENT_REASONING events whose data.stopReason is \"end_turn\" — these are\nthe reasoning steps that represent a completed model turn, as opposed to\ntool-execution events, pending-inference events, tool_use-stopReason\nreasoning steps (mid-turn, not yet final), or reasoning events with no\ndata at all. Each kept event carries its own text payload.\n\nAttributes:\n    event_id: Unique identifier for this event.\n    sequence_number: Ordering number for this event within the session.\n    timestamp: ISO 8601 timestamp when this event was emitted.\n    text: Text content of this reasoning event.",
+    "properties": {
+      "event_id": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Unique identifier for this event",
+        "title": "Event Id"
+      },
+      "sequence_number": {
+        "anyOf": [
+          {
+            "type": "integer"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Ordering number for this event within the session",
+        "title": "Sequence Number"
+      },
+      "text": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Text content of this reasoning event",
+        "title": "Text"
+      },
+      "timestamp": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "ISO 8601 timestamp when this event was emitted",
+        "title": "Timestamp"
+      }
+    },
+    "title": "SessionReasoningEvent",
+    "type": "object"
+  },
+  "title": "Reasoning Events",
+  "type": "array"
+}

First observedv0.1.0Aug 4, 2026

TDQS

A3.5/5.0

Behavior4/5

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint), but the description adds real value by disclosing exactly what the returned event log contains: only AGENT_REASONING events with data.stopReason='end_turn', with tool-execution, pending-inference, mid-turn reasoning, empty-data, and session-status events dropped. It still says nothing about size limits, pagination, or behavior when the session_id is unknown.

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

Conciseness4/5

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

Front-loaded with the one-line purpose before the return-content detail, and the structure is easy to scan. The five-item enumeration of dropped event types is thorough but somewhat over-specified for a tool description, where it borders on documentation of the return payload.

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?

An output schema exists, so explaining return values is optional, yet the description usefully clarifies the filtering semantics an agent would otherwise misread. Gaps remain around error behavior for invalid session ids and the scale/pagination of the returned log, but the core contract is conveyed.

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?

Only one parameter (session_id) and schema description coverage is 100%, so the schema already documents it fully. The description adds no format or constraint detail beyond what the schema provides, which is the baseline-3 case for a single well-documented parameter.

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?

States a specific verb and resource ('Get detailed information about a specific agent session') and immediately scopes it to one session, which contrasts with the list-oriented get_sessions sibling. It never names a sibling or explains the describe-vs-get distinction explicitly, so it is clear but not fully differentiated.

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

Usage Guidelines2/5

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

The description gives no when-to-use guidance, no exclusions, and no mention of alternatives such as get_sessions (list) or describe_session_token_usage. The only implied usage is that the caller already has a session_id, which is thin for a tool with several near-neighbor siblings.

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

Deploy Server