story_mentor_run MCP Tool

Tools

Story Collaboration

story_mentor_run

orchestration

beta

auth: project:write

approval: suggest

status: v1

Hold a Story Mentor conversation over one project using guided mentor turns or freeform project chat turns.

When to use

Use when the caller wants a turn-by-turn conversation rather than a one-shot wizard.

Use `mode=guided` to advance Story Mentor decisions and `mode=freeform` for project-context chat that does not advance the mentor planner.

When not to use

Do not use for a one-shot concept-to-outline bootstrap; use `story_development_run`.

Do not use for direct screenplay block edits.

Examples

“Start a Story Mentor session for this project.”

“Ask a guided mentor turn about the protagonist goal.”

“Ask a freeform project chat question about the current outline.”

Anti-examples

Generate a screenplay draft from an outline.
Reorder scenes directly.

Workflows

Switch behavior by setting the phase input field.

start

Calls: story_mentor.start

turn

Calls: story_mentor.turn

regenerate

Calls: story_mentor.regenerate

finalize

Calls: story_mentor.finalize

Linked resources

Tool calls may return resource_links pointing at these resource families.

story_mentor_session project_canon_summary project_chat_history

Input schema

story_mentor_run input

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": [
    "phase",
    "project_id"
  ],
  "properties": {
    "phase": {
      "type": "string",
      "enum": [
        "start",
        "turn",
        "regenerate",
        "finalize"
      ]
    },
    "project_id": {
      "type": "integer"
    },
    "session_id": {
      "type": "integer"
    },
    "turn_id": {
      "type": "string"
    },
    "mode": {
      "type": "string",
      "enum": [
        "guided",
        "freeform"
      ],
      "default": "guided"
    },
    "message": {
      "type": "string",
      "maxLength": 20000
    },
    "decision_key": {
      "type": "string"
    },
    "writer_signal": {
      "type": "string"
    },
    "modifiers": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 10
    },
    "stage_id": {
      "type": "string"
    },
    "writing_mode": {
      "type": "string"
    },
    "if_match_updated_at": {
      "type": "string"
    },
    "force": {
      "type": "boolean"
    }
  },
  "additionalProperties": false,
  "allOf": [
    {
      "if": {
        "properties": {
          "phase": {
            "const": "turn"
          }
        }
      },
      "then": {
        "required": [
          "session_id",
          "message"
        ]
      }
    },
    {
      "if": {
        "properties": {
          "phase": {
            "const": "regenerate"
          }
        }
      },
      "then": {
        "required": [
          "session_id",
          "turn_id"
        ]
      }
    },
    {
      "if": {
        "properties": {
          "phase": {
            "const": "finalize"
          }
        }
      },
      "then": {
        "required": [
          "session_id"
        ]
      }
    }
  ]
}

Output schema

story_mentor_run output

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": [
    "phase",
    "mode",
    "session"
  ],
  "properties": {
    "phase": {
      "type": "string"
    },
    "mode": {
      "type": "string"
    },
    "session": {
      "type": "object"
    },
    "turn": {
      "type": "object"
    },
    "credits_charged": {
      "type": "number"
    },
    "credits_skipped_reason": {
      "type": "string"
    },
    "resource_links": {
      "type": "array",
      "items": {
        "type": "object"
      }
    }
  },
  "additionalProperties": true
}

← All toolsv1 · workflow_runner