agent4.io

update_storyline

Update part of a storyline draft — fields you don't pass stay as they are (GET-then-merge on top of a full PUT underneath).

concurrency: "user" = progress belongs to the person (shared across sessions); "session" =
progress belongs to the case (one run per session). Changes affect only **future** enrolments;
in-flight runs are not migrated.

⚠️ Especially `graph`: not passing it = keep the existing graph. (This tool once treated "no
graph" as replace-with-empty — renaming a storyline wiped its whole flow. Semantics are now
partial; to truly clear the graph, pass `{"nodes":[],"edges":[]}` explicitly.)
graph/Node/Exit/RuleAst structures: see create_storyline. Pass expected_version for optimistic
locking. Read the response to verify, then validate_storyline.

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": {
      "storyline_id": "<storyline_id>",
      "agent_name": "<agent_name>",
      "key": "<key>"
    },
    "name": "update_storyline"
  }
}

Input Schema

Name	Required	Description	Default
`key`	Yes
`name`	No
`entry`	No
`graph`	No
`agent_name`	Yes
`allow_exit`	No
`is_default`	No
`concurrency`	No
`description`	No
`on_complete`	No
`display_name`	No
`show_profile`	No
`storyline_id`	Yes
`enroll_trigger`	No
`profile_schema`	No
`user_visibility`	No
`expected_version`	No
`next_storyline_id`	No
`allow_agent_enroll`	No
`learner_visibility`	No

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedJul 31, 2026

addedInput schema / properties / allow_exit

Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Allow Exit"
+}

addedInput schema / properties / display_name

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Display Name"
+}

addedInput schema / properties / entry

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Entry"
+}

addedInput schema / properties / show_profile

Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Show Profile"
+}

addedInput schema / properties / user_visibility

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "User Visibility"
+}

Changed1 schema field changedJul 30, 2026

addedInput schema / properties / concurrency

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Concurrency"
+}

Changed21 schema fields changedJul 30, 2026
- addedInput schema / properties / allow_agent_enroll / anyOf
```
Added value: +[
+  {
+    "type": "boolean"
+  },
+  {
+    "type": "null"
+  }
+]
```
- changedInput schema / properties / allow_agent_enroll / default
```
Previous value: -falseNew value: +null
```
- removedInput schema / properties / allow_agent_enroll / type
```
Removed value: -"boolean"
```
- addedInput schema / properties / description / anyOf
```
Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
```
- changedInput schema / properties / description / default
```
Previous value: -""New value: +null
```
- removedInput schema / properties / description / type
```
Removed value: -"string"
```
- addedInput schema / properties / enroll_trigger / anyOf
```
Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
```
- changedInput schema / properties / enroll_trigger / default
```
Previous value: -""New value: +null
```
- removedInput schema / properties / enroll_trigger / type
```
Removed value: -"string"
```
- addedInput schema / properties / is_default / anyOf
```
Added value: +[
+  {
+    "type": "boolean"
+  },
+  {
+    "type": "null"
+  }
+]
```
- changedInput schema / properties / is_default / default
```
Previous value: -falseNew value: +null
```
- removedInput schema / properties / is_default / type
```
Removed value: -"boolean"
```
- addedInput schema / properties / learner_visibility / anyOf
```
Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
```
- changedInput schema / properties / learner_visibility / default
```
Previous value: -"hidden"New value: +null
```
- removedInput schema / properties / learner_visibility / type
```
Removed value: -"string"
```
- addedInput schema / properties / name / anyOf
```
Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
```
- changedInput schema / properties / name / default
```
Previous value: -""New value: +null
```
- removedInput schema / properties / name / type
```
Removed value: -"string"
```
- addedInput schema / properties / on_complete / anyOf
```
Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
```
- changedInput schema / properties / on_complete / default
```
Previous value: -"end"New value: +null
```
- removedInput schema / properties / on_complete / type
```
Removed value: -"string"
```
First observedJul 28, 2026

TDQS

A4.7/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 excels. It discloses the GET-then-merge PUT mechanism, concurrency semantics, future-enrollment-only impact, a historical bug affecting graph replacement, explicit clearing instructions, optimistic locking via expected_version, and a post-update verification/validation step. This is exemplary transparency for a mutating tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is multi-paragraph but every sentence earns its place. It front-loads the core partial-update concept, then systematically covers concurrency, the graph pitfall, validation, and locking. The formatting with bold and the warning emoji improves scannability without padding.

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?

Given the tool's high complexity (20 params, partial semantics, concurrency, optimistic locking, destructive potential), the description covers all critical aspects: what partial means, how concurrency affects future runs, how to clear the graph safely, how to handle version conflicts, and what to do after updating. It also leverages create_storyline as a reference and mentions validate_storyline for verification.

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?

The schema has 20 parameters with 0% description coverage, but the description adds critical semantics for concurrency (enumerating 'user' vs 'session' behavior), graph (partial semantics and how to clear), and expected_version (optimistic locking). It also points to create_storyline for complex structures. Most other parameters are self-explanatory from names, but not all are individually explained, so 4 is appropriate.

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?

The description opens with 'Update **part** of a storyline draft' which clearly identifies the verb ('update'), resource ('storyline draft'), and the crucial partial-update scope. It distinguishes itself from siblings like create_storyline by emphasizing that unspecified fields are preserved, making the tool's unique role unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives excellent context on when to use this tool: for partial updates where omitted fields are retained. It also provides explicit guidance for clearing the graph (pass empty arrays) and points to create_storyline for structure details. However, it does not explicitly contrast with create_storyline or clone_storyline, so it falls short of a perfect 5.

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

All agent4.io tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?