diff --git a/airbyte/mcp/cloud.py b/airbyte/mcp/cloud.py
index e9bfb4ffd..b5368029a 100644
--- a/airbyte/mcp/cloud.py
+++ b/airbyte/mcp/cloud.py
@@ -603,8 +603,9 @@ def deploy_connector_to_cloud(  # noqa: PLR0913  # Mirrors the API surface.
         str,
         Field(
             description=(
-                "The canonical name of the connector (e.g., 'source-faker' or "
-                "'destination-postgres')."
+                "The canonical registry name of the connector (e.g., 'source-faker' or "
+                "'destination-postgres'). Not a custom definition name or ID; see "
+                "`publish_custom_source_definition` for custom connectors."
             ),
         ),
         TraceArg.FINGERPRINT,
@@ -661,6 +662,10 @@ def deploy_connector_to_cloud(  # noqa: PLR0913  # Mirrors the API surface.
 ) -> str:
     """Deploy a source or destination connector to Airbyte Cloud.
 
+    Only for connectors in the Airbyte registry. For custom (e.g. YAML manifest) source
+    connectors, use `publish_custom_source_definition`, or `list_custom_source_definitions` and
+    `update_custom_source_definition` for one that already exists.
+
     With `defer_credentials=True`, returns a JSON `DeferredDeployResult` whose `settings_url`
     is where a person completes the credentials.
     """
@@ -3041,6 +3046,8 @@ def publish_custom_source_definition(
 ) -> str:
     """Publish a custom YAML source connector definition to Airbyte Cloud.
 
+    For connectors already in the Airbyte registry, use `deploy_connector_to_cloud` instead.
+
     Note: Only YAML (declarative) connectors are currently supported.
     Docker-based custom sources are not yet available.
     """