Fix missing_tool schema inconsistency - make tool field optional

[Copilot]

The missing_tool safe output tool had mismatched schemas: the tool description (safe_outputs_tools.json) marked tool as optional, but the validation schema (safe_output_validation_config.go) required it. This would cause validation failures for agents correctly following the tool description.

Changes

• Validation schema: Changed tool field from Required: true to Required: false in ValidationConfig["missing_tool"]
• Test coverage: Added TestMissingToolFieldOptional to verify field requirements

// Before
"tool": {Required: true, Type: "string", Sanitize: true, MaxLength: 128},

// After  
"tool": {Required: false, Type: "string", Sanitize: true, MaxLength: 128},

Both schemas now agree: only reason is required, tool and alternatives are optional.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[safeoutputs] Fix schema inconsistency in missing_tool - 'tool' field marked optional in description but required in validation</issue_title>
<issue_description>### Summary

Analysis of safe output tool schemas identified a schema inconsistency in the missing_tool tool where the tool field is marked as optional in the tool description but required in the validation schema. This discrepancy could cause agents to correctly follow the tool description (omitting the optional tool field) but then fail validation.

While no actual errors were found in the last 24 hours (the missing_tool tool was not used), this inconsistency represents a latent bug that could cause future agent failures.

Schema Inconsistency Details

Tool Description (pkg/workflow/js/safe_outputs_tools.json)

Line 678-700:

{
  "name": "missing_tool",
  "description": "Report that a tool or capability needed to complete the task is not available...",
  "inputSchema": {
    "type": "object",
    "required": [
      "reason"
    ],
    "properties": {
      "tool": {
        "type": "string",
        "description": "Optional: Name or description of the missing tool or capability..."
      },
      "reason": {
        "type": "string",
        "description": "Explanation of why this tool is needed..."
      },
      "alternatives": {
        "type": "string",
        "description": "Any workarounds, manual steps, or alternative approaches..."
      }
    }
  }
}

Key points:

• Required fields: [reason]
• Optional fields: [tool, alternatives]
• Description explicitly states: "Optional: Name or description of the missing tool"

Validation Schema (/opt/gh-aw/safeoutputs/validation.json)

Line 35-55:

{
  "missing_tool": {
    "defaultMax": 20,
    "fields": {
      "alternatives": {
        "type": "string",
        "sanitize": true,
        "maxLength": 512
      },
      "reason": {
        "required": true,
        "type": "string",
        "sanitize": true,
        "maxLength": 256
      },
      "tool": {
        "required": true,
        "type": "string",
        "sanitize": true,
        "maxLength": 128
      }
    }
  }
}

Key points:

• Required fields in validation: [reason, tool]
• The tool field has "required": true

Root Cause Analysis

The inconsistency exists because:

1. Tool Description Intent: The tool description was designed to make tool optional, recognizing that agents might want to report general limitations without specifying a specific tool name (e.g., "The data needed for this analysis is not available in any tool")

2. Validation Schema Mismatch: The validation schema marks tool as required, likely from an earlier design where it was always expected

3. No Runtime Errors Yet: The tool hasn't been used in the analyzed period, so this inconsistency hasn't caused actual failures

Impact Assessment

Current Impact: None (0 uses in last 24 hours)

Potential Future Impact: High

• Agents reading the tool description will believe tool is optional
• Agents may construct calls like: {"reason": "Missing data for analysis"}
• These calls will fail validation because tool is required
• This creates confusion and requires debugging time

Recommended Fix

Choose one of two approaches:

Option 1: Make 'tool' Truly Optional (Recommended)

Update /opt/gh-aw/safeoutputs/validation.json to match the tool description:

{
  "missing_tool": {
    "defaultMax": 20,
    "fields": {
      "alternatives": {
        "type": "string",
        "sanitize": true,
        "maxLength": 512
      },
      "reason": {
        "required": true,
        "type": "string",
        "sanitize": true,
        "maxLength": 256
      },
      "tool": {
        "required": false,  // Changed from true
        "type": "string",
        "sanitize": true,
        "maxLength": 128
      }
    }
  }
}

Rationale: The tool description makes a strong case for optionality. Many scenarios exist where an agent needs to report a limitation without specifying a specific tool name.

Option 2: Make 'tool' Required in Both Schemas

Update pkg/workflow/js/safe_outputs_tools.json to require the tool field:

{
  "name": "missing_tool",
  "inputSchema": {
    "type": "object",
    "required": [
      "reason",
      "tool"  // Add this
    ],
    "properties": {
      "tool": {
        "type": "string",
        "description": "Name or description of the missing tool or capability..."  // Remove "Optional:"
      },
      ...
    }
  }
}

Rationale: If every missing tool report should identify a specific tool, making it required enforces this constraint.

Testing Plan

After fixing the schema inconsistency:

1. Verify Schema Consistency:

   # Compare required fields
   cat pkg/wor...
   

• Fixes [safeoutputs] Fix schema inconsistency in missing_tool - 'tool' field marked optional in description but required in validation #12163

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.