Skip to main content
Glama
calebn

Podcast MCP

by calebn
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

add_comment_tool

Add timeline review comments at instant or span positions in session timeline seconds, optionally scoped to tracks or pending edit decisions for podcast collaboration.

Instructions

Add a timeline review comment (instant or span).

Times are timeline seconds (session/deliverable clock), like chapters - not source-media time. Use search_transcript_tool's timeline_start/end when anchoring to dialogue. track_ids / action_texts are optional string lists. Empty track_ids = session-wide. Undoable via history. Pass edit_decision_id to open the single Ask thread for a pending cut (unique per decision; later notes must use add_comment_reply_tool).

Input Schema

NameRequiredDescriptionDefault
bodyYes
authorYes
track_idsNo
action_textsNo
project_pathNo
timeline_endNo
timeline_startYes
edit_decision_idNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed8 schema fields changedv0.1.1
    • addedInput schema / properties / action_texts
      Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Action Texts"
+}
    • removedInput schema / properties / action_texts_json
      Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "title": "Action Texts Json"
-}
    • addedInput schema / properties / project_path / anyOf
      Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
    • addedInput schema / properties / project_path / default
      Added value: +null
    • removedInput schema / properties / project_path / type
      Removed value: -"string"
    • addedInput schema / properties / track_ids
      Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Track Ids"
+}
    • removedInput schema / properties / track_ids_json
      Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "title": "Track Ids Json"
-}
    • changedInput schema / required
      Previous value: -[
-  "project_path",
-  "body",
-  "author",
-  "timeline_start"
-]New value: +[
+  "body",
+  "author",
+  "timeline_start"
+]
  2. First observedv0.1.0

TDQS

A4.5/5.0
Behavior4/5

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

With no annotations, the description carries the behavioral load and does well: it discloses that the action is undoable via history (reversibility), that edit_decision_id creates a unique thread per decision, and how track_ids scoping behaves. It does not cover who may comment or permission requirements, and return behavior is left to the output schema, so it falls short of fully transparent.

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 purpose, then layers the clock semantics, scoping, and thread rule without filler. The line-broken, markdown-tinged formatting makes it slightly fragmentary, but every sentence contributes meaning.

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?

For an 8-parameter, no-annotation mutation tool with an output schema, the description covers the ambiguous clock semantics, optional scoping lists, undoability, and reply-thread routing. Remaining gaps (project_path meaning, span vs instant rule for timeline_end, author/body expectations) are minor but real.

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 0% with 8 bare-titled parameters, so the description must compensate and it does for the hardest ones: timeline_start/timeline_end are defined as timeline (chapter) seconds rather than source-media time, track_ids/action_texts are optional string lists, and empty track_ids means session-wide. It leaves project_path and the exact instant-vs-span rule (timeline_end null) unexplained, so compensation is substantial but incomplete.

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 ('Add a timeline review comment (instant or span)') and its scope is clear enough to separate it from list_comments_tool, get_comment_tool, and add_comment_reply_tool. The parenthetical immediately signals the two supported comment forms.

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?

Gives explicit routing: use search_transcript_tool's timeline_start/end when anchoring to dialogue, empty track_ids means session-wide, and later notes on the same pending cut must use add_comment_reply_tool rather than this tool. It also warns that edit_decision_id opens a single unique Ask thread per decision, which is a concrete when/when-not rule.

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

Deploy Server

Other Tools