Skip to main content
Glama
Podcast MCP
by calebn

segment_insert_tool

Insert a podcast library segment at the start, end, or a specific timeline second; later clips and edits shift automatically, and dry-run previews duration and movement before applying.

Instructions

Insert a library segment into an episode at start, end or a timeline second.

at is the text start or end (any case) or a number of seconds; end is read when the edit runs, under the document lock.

Later clips, chapters, review comments and pending edits move by the segment's length (podcast segment insert). The edit goes through the document plane as InsertSegment: it is journaled, shows in Studio at once and is one undo step (history_undo). It is applied, not held as a pending proposal, because a pending proposal only exists for remove, mute and split edits. Use dry_run=true first: it reports the new duration and what would move, and changes nothing (it also probes the segment's audio, so it refuses what the insert would). version picks an older version; the one used is journaled. The result carries dry_run (true or false). Errors: segment_version_invalid, segment_unknown, segment_hash_mismatch, segment_position_out_of_range, segment_media_invalid, segment_write_failed.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "segment_id": "<segment_id>",
      "at": "<at>"
    },
    "name": "segment_insert_tool"
  }
}

Input Schema

NameRequiredDescriptionDefault
atYes
dry_runNo
versionNo
segment_idYes
project_pathNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.1.4

TDQS

A4.1/5.0
Behavior5/5

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

With no annotations, the description carries the full burden and does so: it discloses journaling, single-undo-step semantics tied to history_undo, immediate visibility in Studio, application under the document lock, the downstream shift of clips, chapters, comments and pending edits, and that `end` is resolved at edit time. It also enumerates six specific error codes and states dry_run's side effects (audio probe, reports new duration, changes nothing).

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?

The core action is stated first, then placement semantics, then side effects, then dry-run advice, then errors — a sensible front-loaded order with no filler sentences. The trailing error enumeration is dense but earns its place for an agent that needs to handle failures.

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?

For a mutating editor tool with no annotations, the description covers safety profile, locking, undo granularity, ripple effects, dry-run contract and error taxonomy, and it even notes what the result carries. Since an output schema exists, it does not need to explain the return shape in detail, and nothing an agent needs to call it correctly appears missing.

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 description coverage is 0%, so the description must compensate, and it explains three of five parameters well: `at` (accepted forms, case-insensitivity, seconds, late resolution of `end`), `dry_run` (what it reports and that it validates segment audio), and `version` (older version selection, journaled). `segment_id` and `project_path` remain undocumented, which keeps it short of a 5.

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?

Opens with a specific verb and resource plus the placement target ('Insert a library segment into an episode at start, end or a timeline second'). It also distinguishes itself from propose-style edits by noting pending proposals exist only for remove, mute and split, but it never names close siblings such as copy_segment_tool, paste_segment_tool or insert_gap_tool, so an agent must infer the boundary.

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?

Gives one concrete procedural instruction ('Use dry_run=true first') and explains a key behavioral fork versus pending proposals, which is real guidance. However, it never states when to choose this over paste_segment_tool, copy_segment_tool or insert_gap_tool, and offers no explicit when-not-to-use condition.

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