Expose schema-derived safeoutputs CLI syntax and validate strict labels synchronously

[alondahari]

Summary

Generate and expose mode-specific safeoutputs CLI invocation syntax from each tool's final inputSchema, rather than giving agents only generic <server> <tool> --param value guidance.

The generated syntax should reflect the workflow's issue-intent frontmatter:

• omitted: intent metadata is optional but the recommended invocation includes it;
• true: rationale and confidence are visibly required;
• false: intent parameters are absent.

Strict add_labels calls should also be recursively validated at declaration time, with an actionable error showing the required label-object shape. Today a plain-string label array can appear successful and fail only during downstream safe-output processing, after the agent can no longer correct it.

This is a follow-up to #46853. The generated schemas and descriptions are now mode-aware, but CLI-mounted agents do not see those schemas unless they explicitly request command help.

Current behavior

The runtime prompt provides generic CLI guidance:

<server> <tool> --param1 value1 --param2 value2

It tells the agent to use <server> <tool> --help, but does not expose the enabled commands' generated signatures directly. As a result, agents commonly infer a minimal call such as:

safeoutputs set_issue_type --issue_number 123 --issue_type Bug

With issue-intent: true, the MCP server rejects that call because top-level rationale and confidence are required. The agent can then retry successfully, but validation errors have become the normal schema-discovery mechanism.

Labels have a more serious failure mode. In strict mode the generated schema requires:

{
  "labels": [
    {
      "name": "bug",
      "rationale": "The report describes reproducible incorrect behavior.",
      "confidence": "HIGH"
    }
  ]
}

However, a call containing labels: ["bug"] passes the MCP server's shallow top-level required-field checks because the labels property exists. The nested labels.items requirements are enforced only later by safe-output processing. The declaration therefore appears successful to the agent, which has no reason or opportunity to correct it.

Proposed behavior

Generate CLI documentation from the final schema

After frontmatter configuration has transformed the tool schemas, render compact command signatures and recommended examples from those final schemas into the runtime CLI instructions.

The renderer should consume inputSchema rather than independently interpreting frontmatter. This keeps the exposed syntax synchronized with strict, optional, and disabled modes.

Only enabled tools need to be rendered. Prefer compact signatures plus one complete recommended example per tool to control prompt size.

issue-intent omitted

Show intent parameters as optional in the signature, but include them in the recommended invocation:

safeoutputs set_issue_type \
  --issue_number <number> \
  --issue_type <type> \
  [--rationale <reason, max 280 characters>] \
  [--confidence <LOW|MEDIUM|HIGH>] \
  [--suggest <true|false>]

Recommended invocation:

safeoutputs set_issue_type \
  --issue_number 123 \
  --issue_type Bug \
  --rationale "The report describes reproducible incorrect behavior." \
  --confidence HIGH

For optional labels, retain the schema's string compatibility but recommend structured objects:

printf '%s' '{
  "item_number": 123,
  "labels": [
    {
      "name": "bug",
      "rationale": "The report describes reproducible incorrect behavior.",
      "confidence": "HIGH"
    }
  ]
}' | safeoutputs add_labels .

issue-intent: true

Show rationale and confidence as required:

safeoutputs set_issue_type \
  --issue_number <number> \
  --issue_type <type> \
  --rationale <reason, max 280 characters> \
  --confidence <LOW|MEDIUM|HIGH> \
  [--suggest <true|false>]

For strict labels, show only the structured JSON form. Every label item must visibly require name, rationale, and confidence.

issue-intent: false

Do not show rationale, confidence, suggest, or intent guidance:

safeoutputs set_issue_type \
  --issue_number <number> \
  --issue_type <type>

Strict-label validation and error message

Validate the complete input against the generated schema synchronously, including:

• array items;
• nested required;
• oneOf/anyOf;
• enums;
• types;
• additionalProperties.

For a strict call such as:

{"item_number":123,"labels":["bug"]}

return a non-zero result immediately with an error similar to:

Invalid arguments for add_labels:
  labels[0] must be an object when issue-intent is enabled.
  Expected: {"name":"bug","rationale":"Why this label applies","confidence":"HIGH"}
  Required fields: name, rationale, confidence
  Received: "bug"

The invalid declaration must not be appended to the agent output.

Suggested implementation

1. Extend actions/setup/js/mount_mcp_as_cli.cjs to render compact command documentation from the cached final tool definitions.
2. Replace or expand __GH_AW_MCP_CLI_SERVERS_LIST__ in actions/setup/md/mcp_cli_tools_prompt.md with the generated enabled-tool signatures and recommended examples.
3. Share the renderer with mcp_cli_bridge.cjs command help so runtime instructions and safeoutputs <tool> --help cannot drift.
4. Add recursive JSON Schema validation before the safe-output handler records a declaration. This can live in the MCP server core so CLI and any other clients receive identical validation.
5. Format nested validation failures with JSON paths and schema-derived expected examples, with a targeted strict-label message where useful.

Acceptance criteria

• Runtime instructions expose generated syntax for every enabled safeoutputs command.
• Syntax is generated from the final inputSchema, not duplicated frontmatter logic.
• Omitted issue-intent shows metadata as optional while recommending a complete intent-bearing invocation.
• issue-intent: true marks rationale and confidence as required.
• Strict add_labels shows only structured label objects with required name, rationale, and confidence.
• issue-intent: false omits intent parameters and guidance.
• safeoutputs <tool> --help uses the same schema renderer.
• Strict plain-string label arrays are rejected synchronously before being recorded.
• The strict-label error identifies the failing array index and shows the expected object shape.
• Tests cover omitted, required, and disabled syntax plus recursive strict-label validation.

Rationale

The generated schema already contains the authoritative mode-specific contract. Exposing that contract as CLI syntax lets agents construct valid calls before execution, avoids making validation retries the normal discovery path, and keeps workflow prompts free from duplicated tool instructions. Recursive validation remains necessary as a correctness boundary, especially for nested label intents.

Confidence

HIGH. The generated schemas already differ correctly by issue-intent mode. The remaining gaps are that CLI-mounted agents are shown generic syntax and the MCP server's current required-field validation is shallow, allowing invalid nested label items to be recorded.