How Agent Tools Power Project and Timeline Operations in Palmier Pro

Agent tools serve as the programmatic counterpart to Palmier Pro’s user interface, ensuring that automated editing requests reuse the same domain mutations as manual operations while maintaining atomic validation and undo compatibility.

Palmier Pro treats Agent tools as the structured interface between automation systems and project state. Within the palmier-io/palmier-pro repository, these tools encapsulate every programmatic editing request—from trimming clips to renaming tracks—routing them through the same validation and mutation pipelines that the UI employs.

What Are Agent Tools?

Design Philosophy and Purpose

According to AGENTS.md in the repository root, Agent tools express automated editing requests as discrete, reusable operations rather than ad-hoc model manipulations. Developers implement the AgentTool protocol to define specific mutations, ensuring that validation, undo grouping, and receipt generation occur uniformly across both interactive and scripted workflows. This design guarantees that agents cannot bypass the safety invariants built into the application core.

Core Responsibilities of Agent Tools

Single Source of Truth for Domain Mutations

Agent tools invoke the exact domain-mutation operations that the UI uses, such as project.timeline.trimClip(id:to:) or project.timeline.renameTrack(id:to:). By centralizing all modifications through these shared methods, Palmier Pro preserves invariants like track linking, time-scale conversion, and project integrity regardless of whether the action originates from a user gesture or an MCP (Model Context Protocol) command.

Undo-Compatible Execution

Each tool execution is automatically wrapped in an undo group. If the operation succeeds, the infrastructure records an undo entry; if validation fails or the tool is cancelled, no undo entry is created. This behavior aligns with the Editor mutations and undo guidelines documented in AGENTS.md, ensuring that batch operations performed by agents can be rolled back identically to manual edits.

Validation and Atomicity

Before performing any mutation, an Agent tool validates the full request—including bounds checking, identifier verification, and constraint satisfaction—within its perform(on:) method. The tool then executes the mutation atomically, preventing partial changes from reaching the project file system or UI. Invalid operations throw errors before any state change occurs.

Structured Receipts

Upon completion, Agent tools return a ToolResult receipt containing the changed entity IDs, any warnings, and a clear success or failure status. This structured response enables calling agents to react appropriately without guessing what changed, facilitating reliable automation workflows.

Implementing Agent Tools

The following examples illustrate how concrete tools implement the AgentTool protocol to manipulate timeline state. These patterns are exercised in Tests/PalmierProTests/Agent/UndoToolTests.swift.

// Example: an Agent tool that trims a clip on the timeline
struct TrimClipTool: AgentTool {
    let clipID: Clip.ID
    let newRange: TimeRange   // validated by the tool before execution

    func perform(on project: Project) throws -> ToolResult {
        // Reuse the same domain mutation that the UI uses
        try project.timeline.trimClip(id: clipID, to: newRange)

        // Return a structured receipt
        return .success(changedIDs: [clipID])
    }
}

// Invocation from an agent or MCP client
let tool = TrimClipTool(clipID: someClip, newRange: desiredRange)
do {
    let result = try tool.perform(on: currentProject)
    // `result` contains the changed IDs and any warnings
} catch {
    // Uniform error handling – the tool reports why it failed
}

// Example: an undo‑aware Agent tool
struct RenameTrackTool: AgentTool {
    let trackID: Track.ID
    let newName: String

    func perform(on project: Project) throws -> ToolResult {
        // Validate name length, uniqueness, etc.
        try project.timeline.renameTrack(id: trackID, to: newName)

        // The surrounding infrastructure automatically creates an undo entry
        return .success(changedIDs: [trackID])
    }
}

// The tool is used exactly like any UI command; undo / redo work identically

Key Source Files and Testing

The Agent tool architecture is documented and validated in specific locations within the palmier-io/palmier-pro repository:

• AGENTS.md: Defines design principles, parameter validation requirements, undo semantics, and the receipt format specification.
• Tests/PalmierProTests/Agent/UndoToolTests.swift: Provides unit test coverage ensuring tools correctly create undo groups, validate inputs, and produce structured receipts.
• Sources/PalmierPro/Agent/: Contains the AgentTool protocol definition and concrete implementations such as timeline manipulation tools, following the patterns established in AGENTS.md.

Summary

• Agent tools provide the programmatic interface for project and timeline operations in Palmier Pro, bridging UI commands and automated scripts.
• They enforce a single source of truth by reusing domain mutations like trimClip(id:to:) and renameTrack(id:to:) that the UI invokes.
• Every execution is undo-compatible, automatically grouping changes into undoable units that can be rolled back if validation fails.
• Atomic validation ensures invalid operations never partially modify project state, protecting file system integrity.
• Structured receipts (ToolResult) return changed entity IDs and status information, enabling reliable automation without guesswork.

Frequently Asked Questions

How do Agent tools differ from direct model manipulation in Palmier Pro?

Direct model manipulation bypasses validation and undo infrastructure, risking data corruption and inconsistent state. Agent tools wrap mutations in the perform(on:) method, ensuring that all changes validate inputs, execute atomically, and register with the undo system before returning a structured receipt.

Can Agent tools be used outside of the MCP layer?

Yes. While designed to support MCP clients, Agent tools are general-purpose interfaces that any automation script or internal service can invoke. The tools are agnostic to their caller, requiring only a valid Project instance to execute against the timeline.

What happens if an Agent tool fails validation halfway through execution?

Agent tools execute atomically. If validation fails at any point during perform(on:), the tool throws an error and no partial changes are committed to the project timeline. Consequently, no undo entry is created, leaving the project state exactly as it was before invocation.

Where can I find the protocol definition for creating custom Agent tools?

The AgentTool protocol and related infrastructure are defined within the Sources/PalmierPro/Agent/ directory, with comprehensive design guidelines available in AGENTS.md at the repository root. The UndoToolTests.swift file provides implementation examples demonstrating proper undo grouping and receipt generation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}