Orchestra MCP Server

Official

Overview Schema Source Related Servers Discussions Admin

Write to an incident's timeline

create_incident_comment

Append a comment or AI diagnosis event to an incident timeline, returning the recorded row to track updates and outcomes.

Instructions

Append a row to an incident's timeline, returning the event it wrote.

eventType says what the row records - COMMENT_ADDED (the default) for an ordinary comment, or AI_DIAGNOSIS_REQUESTED, AI_DIAGNOSIS_COMPLETED and AI_DIAGNOSIS_FAILED to record the start, result or failure of a diagnosis.

agentSessionId names the Orchestra agent session behind the write. The row is then attributed to Orchestra AI and linked to that session rather than to the API key; an agent takes the id from its ORCHESTRA_AGENT_SESSION_ID environment variable. The AI_DIAGNOSIS_* types require it. A session may write several over its life, but posting the same text twice returns the row already written.

description sets the incident's description alongside an AI_DIAGNOSIS_COMPLETED or AI_DIAGNOSIS_FAILED row, and needs edit permission on the incident. It is not applied over a description a person wrote.

The timeline is append-only: nothing can edit or delete a row once it is there.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`comment`	Yes
`eventType`	No	What the row records. Defaults to COMMENT_ADDED. The AI_DIAGNOSIS_* types require agentSessionId.	COMMENT_ADDED
`description`	No	A summary of the cause to set as the incident's description, written in the same call as the diagnosis. Only accepted with AI_DIAGNOSIS_COMPLETED or AI_DIAGNOSIS_FAILED, and not applied over a description a person wrote.
`incident_id`	Yes	Incident ID.
`agentSessionId`	No	The agent session writing this row. Attributes it to Orchestra AI instead of the API key, and links the timeline back to the session. Agents read this from the ORCHESTRA_AGENT_SESSION_ID environment variable.
`X-Orchestra-Account-Id`	No	Act on this account rather than the one the credential resolves to. Omit it to use the credential's own account. An API key is issued to a single account, so it may only name that account; an OAuth token may name any account its grant covers.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.1.1Sep 30, 2026

addedInput schema / properties / description

Added value: +{
+  "anyOf": [
+    {
+      "maxLength": 500,
+      "minLength": 1,
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "A summary of the cause to set as the incident's description, written in the same call as the diagnosis. Only accepted with AI_DIAGNOSIS_COMPLETED or AI_DIAGNOSIS_FAILED, and not applied over a description a person wrote."
+}

First observedv0.1.0Sep 26, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Goes well beyond the annotations: append-only immutability, idempotent re-post behavior ('posting the same text twice returns the row already written'), edit-permission requirement for description, non-overwrite of human-written descriptions, and attribution to Orchestra AI vs the API key.

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-loads the core action, then groups parameter behavior into focused paragraphs; every sentence carries operational detail. Slightly dense in places but no filler.

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?

An output schema exists so return values need not be explained, and the description still notes that the written event is returned. Combined with the mutation semantics and permission notes, an agent has everything needed to call it correctly.

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

Parameters4/5

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

Schema coverage is already 83% (baseline 3), and the description adds meaning the schema lacks — the ORCHESTRA_AGENT_SESSION_ID source, the required coupling of AI_DIAGNOSIS_* to agentSessionId, and the duplicate-suppression behavior on comment text.

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?

States a specific verb and resource — 'Append a row to an incident's timeline, returning the event it wrote' — which is a narrow, well-scoped operation distinguishable from sibling mutations like update_incident or merge_incidents.

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

Usage Guidelines4/5

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

Gives explicit conditions for each eventType, including that the AI_DIAGNOSIS_* types require agentSessionId and that description is only accepted with COMPLETED/FAILED. It stops short of naming alternative tools or when not to comment at all, but the mode-selection guidance is clear.

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

Deploy Server