Skip to main content
Glama
amigo-ai

forge-mcp

by amigo-ai
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

forge_context_graph_update

Update an existing context graph by creating a new version with states, actions, and global guidelines. Use to revise conversation flows for new and returning users.

Instructions

Update a context graph by creating a new version. All fields are required. The terminal state must have exactly one action.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
org_idNoOrg ID (uses active org if omitted)
statesYesArray of state definitions (action, decision, recall, annotation, reflection, or tool-call)
referencesNoReferences to other state machines: { ref_name: [machine_id, version] }
descriptionYesDescription of the conversation flow
terminal_stateYesName of the terminal state (must have exactly one action, alphanumeric and underscores only)
context_graph_idYesThe context graph ID to update
new_user_initial_stateYesState name for new users (must be an action state, alphanumeric and underscores only)
global_action_guidelinesYesAction guidelines applied to all states
global_boundary_constraintsYesBoundary constraints applied to all states
returning_user_initial_stateYesState name for returning users (must be an action state, alphanumeric and underscores only)
global_intra_state_navigation_guidelinesYesNavigation guidelines applied to all states

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.1.14
    • changedInput schema / properties / states / items / anyOf
      Previous value: -[
-  {
-    "properties": {
-      "action_guidelines": {
-        "items": {
-          "type": "string"
-        },
-        "type": "array"
-      },
-      "action_tool_call_specs": {
-        "items": {
-          "properties": {
-            "additional_instruction": {
-              "description": "Extra context for the LLM when using this tool",
-              "type": "string"
-            },
-            "audio_filler_triggered_after": {
-              "type": "number"
-            },
-            "audio_fillers": {
-              "items": {
-                "type": "string"
-              },
-              "type": "array"
-            },
-            "result_persistence": {
-              "description": "ephemeral = current interaction only, persisted-preferred = kept if < 5000 chars, persisted = always kept",
-              "enum": [
-                "ephemeral",
-                "persisted-preferred",
-                "persisted"
-              ],
-              "type": "string"
-            },
-            "tool_id": {
-              "description": "24-char hex ID of the tool",
-              "type": "string"
-            },
-            "version_constraint": {
-              "description": "Version constraint (e.g., \">=1\")",
-              "type": "string"
-            }
-          },
-          "required": [
-            "tool_id",
-            "version_constraint",
-            "additional_instruction",
-            "audio_fillers",
-            "audio_filler_triggered_after",
-            "result_persistence"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "actions": {
-        "description": "Actions the agent should take",
-        "items": {
-          "type": "string"
-        },
-        "minItems": 1,
-        "type": "array"
-      },
-      "boundary_constraints": {
-        "items": {
-          "type": "string"
-        },
-        "type": "array"
-      },
-      "exit_condition_tool_call_specs": {
-        "items": {
-          "properties": {
-            "additional_instruction": {
-              "description": "Extra context for the LLM when using this tool",
-              "type": "string"
-            },
-            "audio_filler_triggered_after": {
-              "type": "number"
-            },
-            "audio_fillers": {
-              "items": {
-                "type": "string"
-              },
-              "type": "array"
-            },
-            "result_persistence": {
-              "description": "ephemeral = current interaction only, persisted-preferred = kept if < 5000 chars, persisted = always kept",
-              "enum": [
-                "ephemeral",
-                "persisted-preferred",
-                "persisted"
-              ],
-              "type": "string"
-            },
-            "tool_id": {
-              "description": "24-char hex ID of the tool",
-              "type": "string"
-            },
-            "version_constraint": {
-              "description": "Version constraint (e.g., \">=1\")",
-              "type": "string"
-            }
-          },
-          "required": [
-            "tool_id",
-            "version_constraint",
-            "additional_instruction",
-            "audio_fillers",
-            "audio_filler_triggered_after",
-            "result_persistence"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "exit_conditions": {
-        "items": {
-          "properties": {
-            "description": {
-              "description": "When this transition should fire",
-              "type": "string"
-            },
-            "next_state": {
-              "description": "Name of the target state (alphanumeric and underscores only)",
-              "pattern": "^[A-Za-z0-9_]+$",
-              "type": "string"
-            }
-          },
-          "required": [
-            "description",
-            "next_state"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "intra_state_navigation_guidelines": {
-        "items": {
-          "type": "string"
-        },
-        "type": "array"
-      },
-      "name": {
-        "description": "Unique state name (alphanumeric and underscores only)",
-        "pattern": "^[A-Za-z0-9_]+$",
-        "type": "string"
-      },
-      "objective": {
-        "description": "What the agent should accomplish in this state",
-        "type": "string"
-      },
-      "skip_active_memory_retrieval": {
-        "type": "boolean"
-      },
-      "type": {
-        "const": "action",
-        "type": "string"
-      }
-    },
-    "required": [
-      "type",
-      "name",
-      "objective",
-      "actions",
-      "intra_state_navigation_guidelines",
-      "action_guidelines",
-      "boundary_constraints",
-      "exit_conditions",
-      "action_tool_call_specs",
-      "exit_condition_tool_call_specs",
-      "skip_active_memory_retrieval"
-    ],
-    "type": "object"
-  },
-  {
-    "properties": {
-      "audio_filler_triggered_after": {
-        "maximum": 10,
-        "minimum": 0,
-        "type": "number"
-      },
-      "audio_fillers": {
-        "items": {
-          "type": "string"
-        },
-        "maxItems": 5,
-        "type": "array"
-      },
-      "decision_guidelines": {
-        "description": "Rules for choosing the next state",
-        "items": {
-          "type": "string"
-        },
-        "type": "array"
-      },
-      "exit_conditions": {
-        "items": {
-          "properties": {
-            "description": {
-              "description": "When this transition should fire",
-              "type": "string"
-            },
-            "next_state": {
-              "description": "Name of the target state (alphanumeric and underscores only)",
-              "pattern": "^[A-Za-z0-9_]+$",
-              "type": "string"
-            }
-          },
-          "required": [
-            "description",
-            "next_state"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "name": {
-        "description": "Unique state name (alphanumeric and underscores only)",
-        "pattern": "^[A-Za-z0-9_]+$",
-        "type": "string"
-      },
-      "objective": {
-        "type": "string"
-      },
-      "tool_call_specs": {
-        "items": {
-          "properties": {
-            "additional_instruction": {
-              "description": "Extra context for the LLM when using this tool",
-              "type": "string"
-            },
-            "audio_filler_triggered_after": {
-              "type": "number"
-            },
-            "audio_fillers": {
-              "items": {
-                "type": "string"
-              },
-              "type": "array"
-            },
-            "result_persistence": {
-              "description": "ephemeral = current interaction only, persisted-preferred = kept if < 5000 chars, persisted = always kept",
-              "enum": [
-                "ephemeral",
-                "persisted-preferred",
-                "persisted"
-              ],
-              "type": "string"
-            },
-            "tool_id": {
-              "description": "24-char hex ID of the tool",
-              "type": "string"
-            },
-            "version_constraint": {
-              "description": "Version constraint (e.g., \">=1\")",
-              "type": "string"
-            }
-          },
-          "required": [
-            "tool_id",
-            "version_constraint",
-            "additional_instruction",
-            "audio_fillers",
-            "audio_filler_triggered_after",
-            "result_persistence"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "type": {
-        "const": "decision",
-        "type": "string"
-      }
-    },
-    "required": [
-      "type",
-      "name",
-      "objective",
-      "decision_guidelines",
-      "exit_conditions",
-      "tool_call_specs",
-      "audio_fillers",
-      "audio_filler_triggered_after"
-    ],
-    "type": "object"
-  },
-  {
-    "properties": {
-      "name": {
-        "description": "Unique state name (alphanumeric and underscores only)",
-        "pattern": "^[A-Za-z0-9_]+$",
-        "type": "string"
-      },
-      "next_state": {
-        "pattern": "^[A-Za-z0-9_]+$",
-        "type": "string"
-      },
-      "queries": {
-        "anyOf": [
-          {
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "Search queries for user memory"
-      },
-      "requested_information": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "Description of what to retrieve"
-      },
-      "type": {
-        "const": "recall",
-        "type": "string"
-      }
-    },
-    "required": [
-      "type",
-      "name",
-      "queries",
-      "requested_information",
-      "next_state"
-    ],
-    "type": "object"
-  },
-  {
-    "properties": {
-      "inner_thought": {
-        "description": "Fixed inner thought injected into context",
-        "type": "string"
-      },
-      "name": {
-        "description": "Unique state name (alphanumeric and underscores only)",
-        "pattern": "^[A-Za-z0-9_]+$",
-        "type": "string"
-      },
-      "next_state": {
-        "pattern": "^[A-Za-z0-9_]+$",
-        "type": "string"
-      },
-      "type": {
-        "const": "annotation",
-        "type": "string"
-      }
-    },
-    "required": [
-      "type",
-      "name",
-      "inner_thought",
-      "next_state"
-    ],
-    "type": "object"
-  },
-  {
-    "properties": {
-      "audio_filler_triggered_after": {
-        "maximum": 10,
-        "minimum": 0,
-        "type": "number"
-      },
-      "audio_fillers": {
-        "items": {
-          "type": "string"
-        },
-        "maxItems": 5,
-        "type": "array"
-      },
-      "name": {
-        "description": "Unique state name (alphanumeric and underscores only)",
-        "pattern": "^[A-Za-z0-9_]+$",
-        "type": "string"
-      },
-      "next_state": {
-        "pattern": "^[A-Za-z0-9_]+$",
-        "type": "string"
-      },
-      "problem": {
-        "description": "Problem for the agent to reason about",
-        "type": "string"
-      },
-      "tool_call_specs": {
-        "items": {
-          "properties": {
-            "additional_instruction": {
-              "description": "Extra context for the LLM when using this tool",
-              "type": "string"
-            },
-            "audio_filler_triggered_after": {
-              "type": "number"
-            },
-            "audio_fillers": {
-              "items": {
-                "type": "string"
-              },
-              "type": "array"
-            },
-            "result_persistence": {
-              "description": "ephemeral = current interaction only, persisted-preferred = kept if < 5000 chars, persisted = always kept",
-              "enum": [
-                "ephemeral",
-                "persisted-preferred",
-                "persisted"
-              ],
-              "type": "string"
-            },
-            "tool_id": {
-              "description": "24-char hex ID of the tool",
-              "type": "string"
-            },
-            "version_constraint": {
-              "description": "Version constraint (e.g., \">=1\")",
-              "type": "string"
-            }
-          },
-          "required": [
-            "tool_id",
-            "version_constraint",
-            "additional_instruction",
-            "audio_fillers",
-            "audio_filler_triggered_after",
-            "result_persistence"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "type": {
-        "const": "reflection",
-        "type": "string"
-      },
-      "word_limit": {
-        "exclusiveMinimum": 0,
-        "maximum": 9007199254740991,
-        "type": "integer"
-      }
-    },
-    "required": [
-      "type",
-      "name",
-      "problem",
-      "word_limit",
-      "next_state",
-      "tool_call_specs",
-      "audio_fillers",
-      "audio_filler_triggered_after"
-    ],
-    "type": "object"
-  },
-  {
-    "properties": {
-      "designated_tool": {
-        "properties": {
-          "additional_instruction": {
-            "description": "Extra context for the LLM when using this tool",
-            "type": "string"
-          },
-          "audio_filler_triggered_after": {
-            "type": "number"
-          },
-          "audio_fillers": {
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          },
-          "result_persistence": {
-            "description": "ephemeral = current interaction only, persisted-preferred = kept if < 5000 chars, persisted = always kept",
-            "enum": [
-              "ephemeral",
-              "persisted-preferred",
-              "persisted"
-            ],
-            "type": "string"
-          },
-          "tool_id": {
-            "description": "24-char hex ID of the tool",
-            "type": "string"
-          },
-          "version_constraint": {
-            "description": "Version constraint (e.g., \">=1\")",
-            "type": "string"
-          }
-        },
-        "required": [
-          "tool_id",
-          "version_constraint",
-          "additional_instruction",
-          "audio_fillers",
-          "audio_filler_triggered_after",
-          "result_persistence"
-        ],
-        "type": "object"
-      },
-      "designated_tool_call_context": {
-        "type": "string"
-      },
-      "designated_tool_call_guidances": {
-        "items": {
-          "type": "string"
-        },
-        "type": "array"
-      },
-      "designated_tool_call_objective": {
-        "type": "string"
-      },
-      "designated_tool_call_params_generation_audio_filler_triggered_after": {
-        "maximum": 10,
-        "minimum": 0,
-        "type": "number"
-      },
-      "designated_tool_call_params_generation_audio_fillers": {
-        "items": {
-          "type": "string"
-        },
-        "maxItems": 5,
-        "type": "array"
-      },
-      "designated_tool_call_validations": {
-        "items": {
-          "type": "string"
-        },
-        "type": "array"
-      },
-      "name": {
-        "description": "Unique state name (alphanumeric and underscores only)",
-        "pattern": "^[A-Za-z0-9_]+$",
-        "type": "string"
-      },
-      "next_state": {
-        "pattern": "^[A-Za-z0-9_]+$",
-        "type": "string"
-      },
-      "tool_call_specs": {
-        "items": {
-          "properties": {
-            "additional_instruction": {
-              "description": "Extra context for the LLM when using this tool",
-              "type": "string"
-            },
-            "audio_filler_triggered_after": {
-              "type": "number"
-            },
-            "audio_fillers": {
-              "items": {
-                "type": "string"
-              },
-              "type": "array"
-            },
-            "result_persistence": {
-              "description": "ephemeral = current interaction only, persisted-preferred = kept if < 5000 chars, persisted = always kept",
-              "enum": [
-                "ephemeral",
-                "persisted-preferred",
-                "persisted"
-              ],
-              "type": "string"
-            },
-            "tool_id": {
-              "description": "24-char hex ID of the tool",
-              "type": "string"
-            },
-            "version_constraint": {
-              "description": "Version constraint (e.g., \">=1\")",
-              "type": "string"
-            }
-          },
-          "required": [
-            "tool_id",
-            "version_constraint",
-            "additional_instruction",
-            "audio_fillers",
-            "audio_filler_triggered_after",
-            "result_persistence"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "type": {
-        "const": "tool-call",
-        "type": "string"
-      }
-    },
-    "required": [
-      "type",
-      "name",
-      "next_state",
-      "designated_tool",
-      "designated_tool_call_objective",
-      "designated_tool_call_context",
-      "designated_tool_call_guidances",
-      "designated_tool_call_validations",
-      "designated_tool_call_params_generation_audio_fillers",
-      "designated_tool_call_params_generation_audio_filler_triggered_after",
-      "tool_call_specs"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "properties": {
+      "action_guidelines": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "action_tool_call_specs": {
+        "items": {
+          "properties": {
+            "additional_instruction": {
+              "description": "Extra context for the LLM when using this tool",
+              "type": "string"
+            },
+            "audio_filler_triggered_after": {
+              "type": "number"
+            },
+            "audio_fillers": {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "result_persistence": {
+              "description": "ephemeral = current interaction only, persisted-preferred = kept if < 5000 chars, persisted = always kept",
+              "enum": [
+                "ephemeral",
+                "persisted-preferred",
+                "persisted"
+              ],
+              "type": "string"
+            },
+            "tool_id": {
+              "description": "24-char hex ID of the tool",
+              "type": "string"
+            },
+            "version_constraint": {
+              "description": "Version constraint (e.g., \">=1\")",
+              "type": "string"
+            }
+          },
+          "required": [
+            "tool_id",
+            "version_constraint",
+            "additional_instruction",
+            "audio_fillers",
+            "audio_filler_triggered_after",
+            "result_persistence"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "actions": {
+        "description": "Actions the agent should take",
+        "items": {
+          "type": "string"
+        },
+        "minItems": 1,
+        "type": "array"
+      },
+      "boundary_constraints": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "exit_condition_tool_call_specs": {
+        "items": {
+          "properties": {
+            "additional_instruction": {
+              "description": "Extra context for the LLM when using this tool",
+              "type": "string"
+            },
+            "audio_filler_triggered_after": {
+              "type": "number"
+            },
+            "audio_fillers": {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "result_persistence": {
+              "description": "ephemeral = current interaction only, persisted-preferred = kept if < 5000 chars, persisted = always kept",
+              "enum": [
+                "ephemeral",
+                "persisted-preferred",
+                "persisted"
+              ],
+              "type": "string"
+            },
+            "tool_id": {
+              "description": "24-char hex ID of the tool",
+              "type": "string"
+            },
+            "version_constraint": {
+              "description": "Version constraint (e.g., \">=1\")",
+              "type": "string"
+            }
+          },
+          "required": [
+            "tool_id",
+            "version_constraint",
+            "additional_instruction",
+            "audio_fillers",
+            "audio_filler_triggered_after",
+            "result_persistence"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "exit_conditions": {
+        "items": {
+          "properties": {
+            "description": {
+              "description": "When this transition should fire",
+              "type": "string"
+            },
+            "next_state": {
+              "description": "Name of the target state (alphanumeric and underscores only)",
+              "pattern": "^[A-Za-z0-9_]+$",
+              "type": "string"
+            }
+          },
+          "required": [
+            "description",
+            "next_state"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "intra_state_navigation_guidelines": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "name": {
+        "description": "Unique state name (alphanumeric and underscores only)",
+        "pattern": "^[A-Za-z0-9_]+$",
+        "type": "string"
+      },
+      "objective": {
+        "description": "What the agent should accomplish in this state",
+        "type": "string"
+      },
+      "skip_active_memory_retrieval": {
+        "type": "boolean"
+      },
+      "type": {
+        "const": "action",
+        "type": "string"
+      }
+    },
+    "required": [
+      "type",
+      "name",
+      "objective",
+      "actions",
+      "intra_state_navigation_guidelines",
+      "action_guidelines",
+      "boundary_constraints",
+      "exit_conditions",
+      "action_tool_call_specs",
+      "exit_condition_tool_call_specs",
+      "skip_active_memory_retrieval"
+    ],
+    "type": "object"
+  },
+  {
+    "properties": {
+      "audio_filler_triggered_after": {
+        "maximum": 10,
+        "minimum": 0,
+        "type": "number"
+      },
+      "audio_fillers": {
+        "items": {
+          "type": "string"
+        },
+        "maxItems": 5,
+        "type": "array"
+      },
+      "decision_guidelines": {
+        "description": "Rules for choosing the next state",
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "exit_conditions": {
+        "items": {
+          "properties": {
+            "description": {
+              "description": "When this transition should fire",
+              "type": "string"
+            },
+            "next_state": {
+              "description": "Name of the target state (alphanumeric and underscores only)",
+              "pattern": "^[A-Za-z0-9_]+$",
+              "type": "string"
+            }
+          },
+          "required": [
+            "description",
+            "next_state"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "name": {
+        "description": "Unique state name (alphanumeric and underscores only)",
+        "pattern": "^[A-Za-z0-9_]+$",
+        "type": "string"
+      },
+      "objective": {
+        "type": "string"
+      },
+      "tool_call_specs": {
+        "items": {
+          "properties": {
+            "additional_instruction": {
+              "description": "Extra context for the LLM when using this tool",
+              "type": "string"
+            },
+            "audio_filler_triggered_after": {
+              "type": "number"
+            },
+            "audio_fillers": {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "result_persistence": {
+              "description": "ephemeral = current interaction only, persisted-preferred = kept if < 5000 chars, persisted = always kept",
+              "enum": [
+                "ephemeral",
+                "persisted-preferred",
+                "persisted"
+              ],
+              "type": "string"
+            },
+            "tool_id": {
+              "description": "24-char hex ID of the tool",
+              "type": "string"
+            },
+            "version_constraint": {
+              "description": "Version constraint (e.g., \">=1\")",
+              "type": "string"
+            }
+          },
+          "required": [
+            "tool_id",
+            "version_constraint",
+            "additional_instruction",
+            "audio_fillers",
+            "audio_filler_triggered_after",
+            "result_persistence"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "type": {
+        "const": "decision",
+        "type": "string"
+      }
+    },
+    "required": [
+      "type",
+      "name",
+      "objective",
+      "decision_guidelines",
+      "exit_conditions",
+      "tool_call_specs",
+      "audio_fillers",
+      "audio_filler_triggered_after"
+    ],
+    "type": "object"
+  },
+  {
+    "properties": {
+      "name": {
+        "description": "Unique state name (alphanumeric and underscores only)",
+        "pattern": "^[A-Za-z0-9_]+$",
+        "type": "string"
+      },
+      "next_state": {
+        "pattern": "^[A-Za-z0-9_]+$",
+        "type": "string"
+      },
+      "queries": {
+        "anyOf": [
+          {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Search queries for user memory"
+      },
+      "requested_information": {
+        "description": "Description of what to retrieve",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "type": {
+        "const": "recall",
+        "type": "string"
+      }
+    },
+    "required": [
+      "type",
+      "name",
+      "queries",
+      "requested_information",
+      "next_state"
+    ],
+    "type": "object"
+  },
+  {
+    "properties": {
+      "inner_thought": {
+        "description": "Fixed inner thought injected into context",
+        "type": "string"
+      },
+      "name": {
+        "description": "Unique state name (alphanumeric and underscores only)",
+        "pattern": "^[A-Za-z0-9_]+$",
+        "type": "string"
+      },
+      "next_state": {
+        "pattern": "^[A-Za-z0-9_]+$",
+        "type": "string"
+      },
+      "type": {
+        "const": "annotation",
+        "type": "string"
+      }
+    },
+    "required": [
+      "type",
+      "name",
+      "inner_thought",
+      "next_state"
+    ],
+    "type": "object"
+  },
+  {
+    "properties": {
+      "audio_filler_triggered_after": {
+        "maximum": 10,
+        "minimum": 0,
+        "type": "number"
+      },
+      "audio_fillers": {
+        "items": {
+          "type": "string"
+        },
+        "maxItems": 5,
+        "type": "array"
+      },
+      "name": {
+        "description": "Unique state name (alphanumeric and underscores only)",
+        "pattern": "^[A-Za-z0-9_]+$",
+        "type": "string"
+      },
+      "next_state": {
+        "pattern": "^[A-Za-z0-9_]+$",
+        "type": "string"
+      },
+      "problem": {
+        "description": "Problem for the agent to reason about",
+        "type": "string"
+      },
+      "tool_call_specs": {
+        "items": {
+          "properties": {
+            "additional_instruction": {
+              "description": "Extra context for the LLM when using this tool",
+              "type": "string"
+            },
+            "audio_filler_triggered_after": {
+              "type": "number"
+            },
+            "audio_fillers": {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "result_persistence": {
+              "description": "ephemeral = current interaction only, persisted-preferred = kept if < 5000 chars, persisted = always kept",
+              "enum": [
+                "ephemeral",
+                "persisted-preferred",
+                "persisted"
+              ],
+              "type": "string"
+            },
+            "tool_id": {
+              "description": "24-char hex ID of the tool",
+              "type": "string"
+            },
+            "version_constraint": {
+              "description": "Version constraint (e.g., \">=1\")",
+              "type": "string"
+            }
+          },
+          "required": [
+            "tool_id",
+            "version_constraint",
+            "additional_instruction",
+            "audio_fillers",
+            "audio_filler_triggered_after",
+            "result_persistence"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "type": {
+        "const": "reflection",
+        "type": "string"
+      },
+      "word_limit": {
+        "exclusiveMinimum": 0,
+        "maximum": 9007199254740991,
+        "type": "integer"
+      }
+    },
+    "required": [
+      "type",
+      "name",
+      "problem",
+      "word_limit",
+      "next_state",
+      "tool_call_specs",
+      "audio_fillers",
+      "audio_filler_triggered_after"
+    ],
+    "type": "object"
+  },
+  {
+    "properties": {
+      "designated_tool": {
+        "properties": {
+          "additional_instruction": {
+            "description": "Extra context for the LLM when using this tool",
+            "type": "string"
+          },
+          "audio_filler_triggered_after": {
+            "type": "number"
+          },
+          "audio_fillers": {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "result_persistence": {
+            "description": "ephemeral = current interaction only, persisted-preferred = kept if < 5000 chars, persisted = always kept",
+            "enum": [
+              "ephemeral",
+              "persisted-preferred",
+              "persisted"
+            ],
+            "type": "string"
+          },
+          "tool_id": {
+            "description": "24-char hex ID of the tool",
+            "type": "string"
+          },
+          "version_constraint": {
+            "description": "Version constraint (e.g., \">=1\")",
+            "type": "string"
+          }
+        },
+        "required": [
+          "tool_id",
+          "version_constraint",
+          "additional_instruction",
+          "audio_fillers",
+          "audio_filler_triggered_after",
+          "result_persistence"
+        ],
+        "type": "object"
+      },
+      "designated_tool_call_context": {
+        "type": "string"
+      },
+      "designated_tool_call_guidances": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "designated_tool_call_objective": {
+        "type": "string"
+      },
+      "designated_tool_call_params_generation_audio_filler_triggered_after": {
+        "maximum": 10,
+        "minimum": 0,
+        "type": "number"
+      },
+      "designated_tool_call_params_generation_audio_fillers": {
+        "items": {
+          "type": "string"
+        },
+        "maxItems": 5,
+        "type": "array"
+      },
+      "designated_tool_call_validations": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "name": {
+        "description": "Unique state name (alphanumeric and underscores only)",
+        "pattern": "^[A-Za-z0-9_]+$",
+        "type": "string"
+      },
+      "next_state": {
+        "pattern": "^[A-Za-z0-9_]+$",
+        "type": "string"
+      },
+      "tool_call_specs": {
+        "items": {
+          "properties": {
+            "additional_instruction": {
+              "description": "Extra context for the LLM when using this tool",
+              "type": "string"
+            },
+            "audio_filler_triggered_after": {
+              "type": "number"
+            },
+            "audio_fillers": {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "result_persistence": {
+              "description": "ephemeral = current interaction only, persisted-preferred = kept if < 5000 chars, persisted = always kept",
+              "enum": [
+                "ephemeral",
+                "persisted-preferred",
+                "persisted"
+              ],
+              "type": "string"
+            },
+            "tool_id": {
+              "description": "24-char hex ID of the tool",
+              "type": "string"
+            },
+            "version_constraint": {
+              "description": "Version constraint (e.g., \">=1\")",
+              "type": "string"
+            }
+          },
+          "required": [
+            "tool_id",
+            "version_constraint",
+            "additional_instruction",
+            "audio_fillers",
+            "audio_filler_triggered_after",
+            "result_persistence"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "type": {
+        "const": "tool-call",
+        "type": "string"
+      }
+    },
+    "required": [
+      "type",
+      "name",
+      "next_state",
+      "designated_tool",
+      "designated_tool_call_objective",
+      "designated_tool_call_context",
+      "designated_tool_call_guidances",
+      "designated_tool_call_validations",
+      "designated_tool_call_params_generation_audio_fillers",
+      "designated_tool_call_params_generation_audio_filler_triggered_after",
+      "tool_call_specs"
+    ],
+    "type": "object"
+  }
+]
  2. First observedv0.1.13

TDQS

B3.2/5.0
Behavior3/5

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

With no annotations, the description must carry the burden of behavioral disclosure. It does provide two concrete constraints: all fields are required and the terminal state must have exactly one action. However, it does not disclose side effects (e.g., what happens to the previous version), return values, or any permission requirements. These constraints are helpful but incomplete for a mutation 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?

Two sentences with zero waste. The core purpose is front-loaded, and the critical constraints are stated immediately. This is exemplary conciseness for a tool with a massive schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite the schema being very detailed, the description is insufficient for a complex 11-parameter tool with nested objects and no annotations. It fails to mention what the tool returns, how versioning works, or any operational context. The agent would need to rely solely on the schema, missing guidance on overall workflow and consequences.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already thoroughly documents each parameter. The description adds minimal value beyond that—it reiterates 'all fields required' and the terminal state rule. It does not clarify parameter interactions or provide examples, so a baseline 3 is appropriate.

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?

The description states a clear verb+resource ('Update a context graph') and adds the key behavior 'by creating a new version.' This is specific and distinguishes it from a plain create operation, though it does not explicitly name the sibling forge_context_graph_create. The purpose is unambiguous.

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

Usage Guidelines2/5

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

No guidance is given on when to use this tool versus alternatives like forge_context_graph_create. There is no mention of prerequisites, scenarios, or why one would update versus create. The agent is left to infer usage from the name and sibling list.

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