Application linked-role metadata audit and reviewed changes

audit_application_role_connection_metadata, discord://application/role-connection-metadata, and review_application_role_connection_metadata belong to the connector toolset and inspect only the verified current application's complete role-connection metadata schema. The caller supplies no application ID. Each read re-verifies the pinned application and bot, validates verification-endpoint presence without returning its URL, and fetches Discord's complete inventory of at most five metadata records. The audit adds no bearer token, configuration field, write authority, Gateway connection, activity record, cache, or persistent file.

The strict projection returns exact metadata keys, transient untrusted names and descriptions with character counts, normalized value families and comparison semantics for all eight documented types, localization counts without localized strings, record and aggregate unknown-field counts, unknown future type counts, projection completeness, and fixed findings. It rejects malformed known evidence, duplicate keys, oversized payloads, excess records, invalid Unicode or controls, unsupported bounds, and malformed identity or endpoint evidence. Unknown future fields and types are preserved only as bounded structural counts and never guessed.

The audit omits the verification URL, localization values, user role-connection values, raw Discord payloads, and unknown field values. Metadata definitions do not reveal which guild roles use them, prove whether any user satisfies them, or predict whether Discord will grant a linked role. The guided audit prompt calls the audit exactly once, treats all returned text as untrusted data, explains incomplete future evidence and these limits, and stops without a write.

Schema changes have no immediate-call path. Set capabilities.applicationRoleConnectionMetadataChanges: true and include the separate linked-roles toolset. No guild allowlist, guild permission, privileged intent, bearer token, or caller-selected application ID participates. The strict action union accepts only replace with one complete non-empty ordered schema and acknowledgeGlobalReplacement: true, or clear with acknowledgeSchemaClearance: true. Replacement records use named comparison types for all eight documented Discord type codes, exact unique keys, bounded names and descriptions, and complete ordered locale-keyed localization arrays. Raw Discord objects, numeric type codes, partial updates, empty replacement arrays, unknown fields, guild role configuration, and user role-connection values are rejected.

Planning re-verifies the pinned application and bot identities, validates verification-endpoint presence without returning its URL, and fetches the authoritative complete current schema. The process-keyed digest binds both complete transient schemas and their public SHA-256 digests, exact ordering, count-only added, changed, removed, unchanged, and reordered evidence, acknowledgements, application-wide risks, warnings, and a domain-separated one-shot operation-key hash. A connector restart invalidates outstanding plan digests. Metadata labels, descriptions, localization values, and keys remain visible only in the transient plan needed for exact human review.

Use the workflow in this order:

1. Call audit_application_role_connection_metadata when a structural read-only review is useful.
2. Call plan_application_role_connection_metadata_change with exactly one strict complete replacement or clearance request and a unique operation key.
3. Review the exact application and bot IDs, verification-endpoint presence, complete current and desired schemas, schema digests, ordering, count-only diff, privacy boundary, risks, warnings, operation-key hash, and keyed plan digest.
4. If the plan reports already-current or already-empty, stop. The no-op requests no confirmation, reservation, activity record, or Discord mutation; the production facade may briefly acquire and release the application collection claim while rechecking that result.
5. Call execute_application_role_connection_metadata_change with the identical request and digest. A compatible MCP host must grant write approval and return the server's signed interactive confirmation.
6. Inspect the exact complete observed schema and digest returned only after response validation and an independent fresh readback.

The signed request state contains only the action, application ID, desired-schema digest, operation-key hash, and plan digest. It contains no metadata key, label, description, localization value, verification URL, or raw operation key. Execution rebuilds the plan before approval and again before mutation. It acquires a durable exact application role-connection-metadata collection claim, atomically reserves the one-shot key, appends pending content-free activity, and sends exactly one non-retried complete-schema PUT. Discord's route replaces the complete schema, so omission is deletion and no merge or patch behavior is inferred. Both the mutation response and an independent fresh GET must reproduce the reviewed complete schema exactly.

A definite pre-response Discord client refusal other than rate limiting may settle as failed. Rate limiting, transport ambiguity, server error, malformed or mismatched mutation evidence, readback failure, or failed durable receipt finalization is uncertain and may have changed Discord. Every reserved key remains spent, an uncertain result retains the application-wide claim, and same-application changes remain quarantined until an operator inspects Discord and resolves the durable evidence. The connector never retries, merges, compensates, restores, or rolls back automatically.

Activity and operation records contain only exact application and bot IDs, action, record counts, reorder state, plan digest, operation-key hash, timestamps, fixed verification and outcome values, activity ID, and sanitized error category. Metadata keys, labels, descriptions, localization values, verification URLs, user values, guild-role configuration, raw requests or responses, raw keys, credentials, and transport causes never enter persistent records, diagnostics, or telemetry. review_application_role_connection_metadata_change accepts one strict request JSON object, emits only the validated plan input, calls only the planner, and explicitly stops before execution.

Canonical source: docs/reference.md