Problem

Tool filtering can hide capabilities due to toolset, PAT scope, read-only mode, or lockdown, but callers do not always receive one stable reason classification.

Why now

Permission-scoped capability exposure is a core contract of the GitHub MCP server. Missing provenance for hidden tools weakens operator debugging and policy auditability.

Current insufficiency

Filtering behavior is implemented in multiple layers, but there is not a single stable reason-code contract guaranteed across all hide paths.

Expected behavior

Hidden tools should be classified with deterministic reason codes such as:

• toolset_filtered
• scope_filtered
• readonly_filtered
• lockdown_filtered

Validation requirements

• Add tests that exercise each hide path.
• Assert one stable reason code per hidden tool decision.
• Keep classification convergent across inventory and request filtering.

Scope map

• internal/ghmcp/server.go
• pkg/inventory/builder.go
• pkg/scopes/fetcher.go
• pkg/lockdown/lockdown.go