OpenMAIC Agent Runtime Tools: Complete Guide to Built-In Tools and Skills

OpenMAIC provides nine categories of built-in tools and skills—generation, DSL-course, audio-deck, curriculum, material, roster, voice-clone, skill-edit, and UI utilities—exported as constant name lists and registered at runtime.

The OpenMAIC agent runtime ships with a comprehensive toolkit that AI agents can invoke directly. These tools are organized by functional domain and exposed through exported constants in lib/server/agent-runtime/. When the server starts, lib/server/agent-runtime/skill-preload.ts consumes these constants to build the final AgentTool[] array passed to the agent core. Each tool implements parameter validation via type-box schemas and executes side effects ranging from document writes to media synthesis.

Generation Tools for Scene and Action Management

The generation tools handle creation, listing, duplication, and action generation for pages (scenes) within a course.

These tools are defined in lib/server/agent-runtime/generation-tools.ts and exported as GENERATION_TOOL_NAMES:

Tool Name	Purpose
generate_scene	Create a new scene/page with specified parameters
list_scenes	Enumerate existing scenes in a stage
generate_actions	Generate actionable elements for a specific page
duplicate_scene	Clone an existing scene with modifications

import { GENERATION_TOOL_NAMES } from '@/lib/server/agent-runtime/generation-tools';

console.log('Generation tools available to the agent:');
console.log(GENERATION_TOOL_NAMES);
// → [ 'generate_scene', 'list_scenes', 'generate_actions', 'duplicate_scene' ]

To invoke a generation tool via the HTTP API:

await fetch('/api/agent/tool', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    tool: 'generate_scene',
    params: {
      stageId: 'stage-123',
      order: 1,
      title: 'Introduction',
      brief: 'Explain the basics of photosynthesis.',
      type: 'slide',
    },
  }),
});

DSL-Course Tools for Stage Manipulation

The DSL-course tools provide course-level object manipulation as defined by OpenMAIC's domain-specific language. These are exported as DSL_COURSE_TOOL_NAMES from lib/server/agent-runtime/course-tools.ts.

Tool names are dynamically built from the DSL schema. Common patterns include:

• create_stage – Instantiate a new stage
• patch_stage – Partially update stage properties
• delete_stage – Remove a stage from the course

The full enumeration depends on the DSL definition—refer to the source file for the complete list of generated tool names.

Audio-Deck and Voice-Clone Tools

OpenMAIC provides two overlapping constants for audio synthesis: COURSE_AUDIO_DECK_TOOL_NAMES and VOICE_CLONE_TOOL_NAMES. Both are exported from lib/server/agent-runtime/voice-clone-tools.ts and expose identical tool names, separated for granular permission handling.

Available audio tools:

Tool Name	Purpose
synthesize_tts	Generate text-to-speech narration
clone_voice	Create a voice clone from audio samples
list_voices	Enumerate available voice models
delete_voice	Remove a voice model from storage

Curriculum Allow-List Tool Set

The CURRICULUM_ALLOWLIST in lib/server/agent-runtime/curriculum-tools.ts does not expose individual tools but instead defines which tool identifiers the curriculum layer permits. This acts as a security gate, ensuring agents only invoke curriculum-approved operations.

Material Tools for Asset Management

The material tools handle upload, listing, and lifecycle management of learning material assets. Defined in lib/server/agent-runtime/material-tools.ts and exported as MATERIAL_TOOL_NAMES:

Tool Name	Purpose
upload_material	Ingest new media or document assets
list_materials	Query available materials with filters
delete_material	Permanently remove an asset
update_material	Modify metadata or replace content

Roster Tools for Participant Management

The roster tools manage student and participant enrollment. Exported as ROSTER_TOOL_NAMES from lib/server/agent-runtime/roster-tools.ts:

Tool Name	Purpose
add_roster_entry	Enroll a new participant
remove_roster_entry	Unenroll an existing participant
list_roster	Retrieve enrolled participants
update_roster_entry	Modify participant status or metadata

Skill-Edit Tools for Custom Skill Operations

The skill-edit tools enable the agent to inspect and modify user-defined skills at runtime. Defined in lib/server/agent-runtime/skill-edit-tools.ts and exported as SKILL_EDIT_TOOL_NAMES:

Tool Name	Purpose
read_skill	Retrieve a skill's definition and parameters
patch_skill	Apply partial updates to a skill configuration

Example invocation to read a skill:

await fetch('/api/agent/tool', {
  method: 'POST',
  body: JSON.stringify({
    tool: 'read_skill',
    params: { skillId: 'my-custom-skill' },
  }),
});

UI and Workbench Utilities

Additional convenience utilities for presenter mode, pagination, and navigation are defined in lib/workbench/. These are wired into the runtime via the same registration mechanism but are not exposed as top-level agent tools—they serve the user interface rather than agent invocations.

Tool Registration and Runtime Integration

All tool constants converge in lib/server/agent-runtime/skill-preload.ts, which orchestrates the runtime initialization:

1. Imports each constant (GENERATION_TOOL_NAMES, MATERIAL_TOOL_NAMES, etc.)
2. Maps names to concrete AgentTool implementations with type-box parameter schemas
3. Assembles the final AgentTool[] array for the agent core

Each AgentTool validates incoming parameters before executing side effects, ensuring type safety across document writes, media uploads, and audio synthesis operations.

Summary

• OpenMAIC agent runtime tools are organized into nine functional domains with exported constants for programmatic discovery
• Generation tools (generate_scene, list_scenes, generate_actions, duplicate_scene) handle page lifecycle in lib/server/agent-runtime/generation-tools.ts
• DSL-course tools provide dynamic stage manipulation based on the DSL schema in lib/server/agent-runtime/course-tools.ts
• Audio and voice tools (synthesize_tts, clone_voice, list_voices, delete_voice) support narration and voice cloning in lib/server/agent-runtime/voice-clone-tools.ts
• Material, roster, and skill-edit tools cover asset management, enrollment, and custom skill operations
• Skill-preload (lib/server/agent-runtime/skill-preload.ts) registers all tools with the agent core at startup using type-box validation

Frequently Asked Questions

How do I discover which OpenMAIC agent tools are available programmatically?

Import the exported constants from their respective files in lib/server/agent-runtime/. Each constant is a string array of tool names. For example, import { GENERATION_TOOL_NAMES } from '@/lib/server/agent-runtime/generation-tools' gives you the complete list of generation tools without hardcoding names.

What is the difference between COURSE_AUDIO_DECK_TOOL_NAMES and VOICE_CLONE_TOOL_NAMES?

Both constants expose identical tool names and originate from lib/server/agent-runtime/voice-clone-tools.ts. They are separated to enable granular permission handling—the curriculum layer can reference one while the agent runtime references the other, allowing different access policies for the same underlying capabilities.

Can I add custom tools to the OpenMAIC agent runtime?

Yes. Define your tool implementation following the AgentTool interface with type-box parameter validation, then export its name through a new constant or add it to an existing category. Import and register it in lib/server/agent-runtime/skill-preload.ts to include it in the startup tool array passed to the agent core.

How does the curriculum allow-list restrict tool usage?

The CURRICULUM_ALLOWLIST in lib/server/agent-runtime/curriculum-tools.ts contains tool identifier strings that the curriculum layer permits. Before executing a tool invocation, the runtime checks against this allow-list, rejecting any tool not explicitly authorized for the current curriculum context.

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