What causes "operation %d: add requires description" in vxcontrol/pentagi?

Populate description for each add operation (what/how the subtask will accomplish).

operation %d: add requires description

Error message

operation %d: add requires description

What it means

Same SubtaskPatch.Validate path: for op == SubtaskOpAdd the Description field is required; this error fires when Title is present but Description is empty. Descriptions carry the plan detail the executor agent needs.

Source

Thrown at backend/pkg/tools/args.go:326

}

// PatchFlowSubtasksAction defines arguments for the patch_flow_subtasks tool.
type PatchFlowSubtasksAction struct {
	TaskID     int64              `json:"task_id" jsonschema:"required,type=integer" jsonschema_description:"ID of the task whose subtask plan to modify. Obtain this from get_flow_status with detail='tasks'."`
	Operations []SubtaskOperation `json:"operations" jsonschema:"required" jsonschema_description:"Delta operations to apply: add (insert new subtask at a position), remove (delete by ID), modify (update title/description), reorder (move to different position). Empty array returns the current plan unchanged. Each operation's title/description, when present, is an engagement-log plan entry (see operations)."`
	Message    string             `json:"message" jsonschema:"required,title=Patch summary" jsonschema_description:"Engagement-log entry — a 1-2 short sentence running commentary describing what changes are being made to the plan. Written in the engagement language declared by your system prompt."`
}

// ValidateSubtaskPatch validates the operations in a SubtaskPatch
func (sp SubtaskPatch) Validate() error {
	for i, op := range sp.Operations {
		switch op.Op {
		case SubtaskOpAdd:
			if op.Title == "" {
				return fmt.Errorf("operation %d: add requires title", i)
			}
			if op.Description == "" {
				return fmt.Errorf("operation %d: add requires description", i)
			}
		case SubtaskOpRemove:
			if op.ID == nil {
				return fmt.Errorf("operation %d: remove requires id", i)
			}
		case SubtaskOpModify:
			if op.ID == nil {
				return fmt.Errorf("operation %d: modify requires id", i)
			}
			if op.Title == "" && op.Description == "" {
				return fmt.Errorf("operation %d: modify requires at least title or description", i)
			}
		case SubtaskOpReorder:
			if op.ID == nil {
				return fmt.Errorf("operation %d: reorder requires id", i)
			}
		default:
			return fmt.Errorf("operation %d: unknown operation type %q", i, op.Op)

View on GitHub (pinned to ea665308ba)

Solutions

Populate description for each add operation (what/how the subtask will accomplish).
Pre-validate operations and auto-reject or auto-expand adds lacking descriptions.
Adjust the agent prompt/schema so descriptions are always generated.

Example fix

// before
ops := []SubtaskOperation{{Op: SubtaskOpAdd, Title: "Port scan"}}
// after
ops := []SubtaskOperation{{Op: SubtaskOpAdd, Title: "Port scan", Description: "Run nmap against target and record open ports"}}

Defensive patterns

Strategy: validation

Validate before calling

for i, op := range ops {
    if op.Op == "add" && op.Description == "" {
        return fmt.Errorf("op %d: add needs description", i)
    }
}

Type guard

func hasDescription(op SubtaskOperation) bool {
    return op.Op != SubtaskOpAdd || op.Description != ""
}

Try / catch

if err := patch.Validate(); err != nil {
    if strings.Contains(err.Error(), "add requires description") {
        // autofill a placeholder description or reject the patch before apply
    }
}

Prevention

Generate descriptions alongside titles in every plan-writing prompt.
Reject add operations lacking descriptions at patch construction time.
Keep the tool schema description explicit that description is mandatory for add.
Autofill from the title when only a title is available, then validate.

When it happens

Trigger: A patch containing {"op":"add","title":"Port scan"} with no description, submitted via patch_flow_subtasks or SubtaskPatch.Validate.

Common situations: LLM emitting terse add operations; script-generated patches that only set titles; UI/tooling that maps a one-line plan entry into an add op without description.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

AI-assisted analysis of vxcontrol/pentagi@ea665308ba (2026-09-01). Data as JSON: /api/errors/7c7b08d4d7caf808. Report an issue: GitHub.