Mark conditional schema parameters in generated docs

Previously `show_ui` was listed in docs/feature-flags.md and
docs/insiders-features.md alongside ordinary parameters with no
indication that it is hidden from clients without MCP App UI support.
A reader scanning the parameter list would assume it is always available.

Add a programmatic conditional-property mechanism:

- `inventory.ConditionalSchemaPropertyDescriptions()` exposes a
  map[propertyName]conditionDescription derived from the same
  uiOnlySchemaProperties allowlist that drives the per-request strip
  in ToolsForRegistration. Single source of truth.
- The doc generator (writeToolDoc) consults this map and appends
  "conditional — <description>" to the parameter's parenthesised
  type/required suffix.

Example rendered output:

  - `show_ui`: Whether to render the MCP App form... (boolean, optional,
    conditional — only visible to clients that advertise MCP App UI support)

A small test (TestConditionalSchemaPropertyDescriptions) ensures every
entry in uiOnlySchemaProperties has a description, so a future stripped
property addition can't silently lose its doc marker.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: mattdholloway

cmd/github-mcp-server/generate_docs.go

@@ -257,6 +257,8 @@ func writeToolDoc(buf *strings.Builder, tool inventory.ServerTool) {
 		}
 		sort.Strings(paramNames)
 
+		conditional := inventory.ConditionalSchemaPropertyDescriptions()
+
 		for i, propName := range paramNames {
 			prop := schema.Properties[propName]
 			required := slices.Contains(schema.Required, propName)
@@ -282,7 +284,11 @@ func writeToolDoc(buf *strings.Builder, tool inventory.ServerTool) {
 			// Indent any continuation lines in the description to maintain markdown formatting
 			description := indentMultilineDescription(prop.Description, "    ")
 
-			fmt.Fprintf(buf, "  - `%s`: %s (%s, %s)", propName, description, typeStr, requiredStr)
+			if cond, isConditional := conditional[propName]; isConditional {
+				fmt.Fprintf(buf, "  - `%s`: %s (%s, %s, conditional — %s)", propName, description, typeStr, requiredStr, cond)
+			} else {
+				fmt.Fprintf(buf, "  - `%s`: %s (%s, %s)", propName, description, typeStr, requiredStr)
+			}
 			if i < len(paramNames)-1 {
 				buf.WriteString("\n")
 			}

docs/feature-flags.md

@@ -44,7 +44,7 @@ runtime behavior (such as output formatting) won't appear here.
   - `maintainer_can_modify`: Allow maintainer edits (boolean, optional)
   - `owner`: Repository owner (string, required)
   - `repo`: Repository name (string, required)
-  - `show_ui`: Whether to render the MCP App form instead of executing the request immediately. Defaults to true. Set to false to skip the form and execute directly — useful when you have all required values (especially ones the form does not collect, like reviewers) and the user has already confirmed the action. (boolean, optional)
+  - `show_ui`: Whether to render the MCP App form instead of executing the request immediately. Defaults to true. Set to false to skip the form and execute directly — useful when you have all required values (especially ones the form does not collect, like reviewers) and the user has already confirmed the action. (boolean, optional, conditional — only visible to clients that advertise MCP App UI support)
   - `title`: PR title (string, required)
 
 - **get_me** - Get my user profile
@@ -67,7 +67,7 @@ runtime behavior (such as output formatting) won't appear here.
   - `milestone`: Milestone number (number, optional)
   - `owner`: Repository owner (string, required)
   - `repo`: Repository name (string, required)
-  - `show_ui`: Whether to render the MCP App form instead of executing the request immediately. Defaults to true. Set to false to skip the form and execute directly — useful when you have all required values (especially ones the form does not collect, like labels, assignees, milestone, type, or state changes) and the user has already confirmed the action. (boolean, optional)
+  - `show_ui`: Whether to render the MCP App form instead of executing the request immediately. Defaults to true. Set to false to skip the form and execute directly — useful when you have all required values (especially ones the form does not collect, like labels, assignees, milestone, type, or state changes) and the user has already confirmed the action. (boolean, optional, conditional — only visible to clients that advertise MCP App UI support)
   - `state`: New state (string, optional)
   - `state_reason`: Reason for the state change. Ignored unless state is changed. (string, optional)
   - `title`: Issue title (string, optional)

docs/insiders-features.md

@@ -38,7 +38,7 @@ The list below is generated from the Go source. It covers tool **inventory and s
   - `maintainer_can_modify`: Allow maintainer edits (boolean, optional)
   - `owner`: Repository owner (string, required)
   - `repo`: Repository name (string, required)
-  - `show_ui`: Whether to render the MCP App form instead of executing the request immediately. Defaults to true. Set to false to skip the form and execute directly — useful when you have all required values (especially ones the form does not collect, like reviewers) and the user has already confirmed the action. (boolean, optional)
+  - `show_ui`: Whether to render the MCP App form instead of executing the request immediately. Defaults to true. Set to false to skip the form and execute directly — useful when you have all required values (especially ones the form does not collect, like reviewers) and the user has already confirmed the action. (boolean, optional, conditional — only visible to clients that advertise MCP App UI support)
   - `title`: PR title (string, required)
 
 - **get_me** - Get my user profile
@@ -61,7 +61,7 @@ The list below is generated from the Go source. It covers tool **inventory and s
   - `milestone`: Milestone number (number, optional)
   - `owner`: Repository owner (string, required)
   - `repo`: Repository name (string, required)
-  - `show_ui`: Whether to render the MCP App form instead of executing the request immediately. Defaults to true. Set to false to skip the form and execute directly — useful when you have all required values (especially ones the form does not collect, like labels, assignees, milestone, type, or state changes) and the user has already confirmed the action. (boolean, optional)
+  - `show_ui`: Whether to render the MCP App form instead of executing the request immediately. Defaults to true. Set to false to skip the form and execute directly — useful when you have all required values (especially ones the form does not collect, like labels, assignees, milestone, type, or state changes) and the user has already confirmed the action. (boolean, optional, conditional — only visible to clients that advertise MCP App UI support)
   - `state`: New state (string, optional)
   - `state_reason`: Reason for the state change. Ignored unless state is changed. (string, optional)
   - `title`: Issue title (string, optional)

pkg/inventory/builder.go

@@ -418,6 +418,22 @@ var uiOnlySchemaProperties = []string{
 	"show_ui", // explicit "render the MCP App form" toggle on form-backed write tools
 }
 
+// ConditionalSchemaPropertyDescriptions returns a map of schema property name
+// to a human-readable description of the condition under which the property
+// is visible to clients. The doc generator uses this to annotate conditional
+// parameters so readers can see at a glance which fields are not always
+// available. This is the single source of truth for the conditional-property
+// surface — entries here must correspond to a strip rule in
+// ToolsForRegistration.
+func ConditionalSchemaPropertyDescriptions() map[string]string {
+	const uiOnlyCondition = "only visible to clients that advertise MCP App UI support"
+	out := make(map[string]string, len(uiOnlySchemaProperties))
+	for _, name := range uiOnlySchemaProperties {
+		out[name] = uiOnlyCondition
+	}
+	return out
+}
+
 // stripUIOnlySchemaProperties removes UI-capability-gated input-schema
 // properties (currently just "show_ui") from each tool's static schema.
 // Tools whose InputSchema is not a *jsonschema.Schema (e.g. json.RawMessage)

pkg/inventory/registry_test.go

@@ -2182,6 +2182,23 @@ func TestStripUIOnlySchemaProperties(t *testing.T) {
 		"tools with a non-*jsonschema.Schema input schema must be passed through")
 }
 
+// TestConditionalSchemaPropertyDescriptions ensures every property that
+// inventory strips per-request also has a human-readable condition the doc
+// generator can render. A future addition to uiOnlySchemaProperties that
+// forgets to wire a description through will fail here.
+func TestConditionalSchemaPropertyDescriptions(t *testing.T) {
+	t.Parallel()
+
+	descs := ConditionalSchemaPropertyDescriptions()
+	require.NotEmpty(t, descs, "expected at least show_ui to be advertised as conditional")
+
+	for _, name := range uiOnlySchemaProperties {
+		desc, ok := descs[name]
+		require.Truef(t, ok, "ui-only property %q must have a conditional description", name)
+		require.NotEmptyf(t, desc, "conditional description for %q must be non-empty", name)
+	}
+}
+
 func TestToolsForRegistration_StripsShowUIUnderSameGate(t *testing.T) {
 	// A tool whose schema declares both `_meta.ui` and `show_ui`. The strip
 	// for both must fire — or not — together, governed by the same gate