[Davin Chia (davinchia)]

Summary

Adds a "Useful, for example, for …" paragraph to the docstrings (which are the MCP tool descriptions) of the three external execute tools in airbyte/mcp/cloud.py. The aim is to give agents ideas for when the tools help, without saying any one use case is what the tools are for. Today the descriptions only cover parameters and constraints.

• execute_external_api_query: quick investigations with live source data. Examples: checking the latest source records when synced data looks missing or stale, confirming a field exists before relying on it, or answering a one-off question without waiting for a sync.
• execute_external_sql_query: debugging pipelines and inspecting what a sync landed. Examples: finding which tables a sync created, sampling rows to see their shape and keys, checking freshness or row counts, or exploring raw tables before designing downstream models.
• execute_external_search_query: finding records by meaning or keyword when the exact entity, table, or ID isn't known.

The examples are based on how hosted users are actually using these tools today. The change is description-only and does not change behavior.

---

Devin session

Open in Devin Desktop: https://app.devin.ai/desktop/session/d29fec08d1a147279e154885b9239cd9?variant=devin
Requested by: Davin Chia (@davinchia)

[devin-ai-integration]

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

• Disable automatic comment, CI, and merge conflict monitoring

[octavia-bot]

Note

📝 PR Converted to Draft

More info...

Thank you for creating this PR. As a policy to protect our engineers' time, Airbyte requires all PRs to be created first in draft status. Your PR has been automatically converted to draft status in respect for this policy.

As soon as your PR is ready for formal review, you can proceed to convert the PR to "ready for review" status by clicking the "Ready for review" button at the bottom of the PR page.

To skip draft status in future PRs, please include [ready] in your PR title or add the skip-draft-status label when creating your PR.

[github-actions]

👋 Greetings, Airbyte Team Member!

Here are some helpful tips and reminders for your convenience.

💡 Show Tips and Tricks

Testing This PyAirbyte Version

You can test this version of PyAirbyte using the following:

# Run PyAirbyte CLI from this branch:
uvx --from 'git+https://github.com/airbytehq/PyAirbyte.git@devin/1793033319-execute-tool-use-case-examples' pyairbyte --help

# Install PyAirbyte from this branch for development:
pip install 'git+https://github.com/airbytehq/PyAirbyte.git@devin/1793033319-execute-tool-use-case-examples'

PR Slash Commands

Airbyte Maintainers can execute the following slash commands on your PR:

• /fix-pr - Fixes most formatting and linting issues
• /uv-lock - Updates uv.lock file
• /test-pr - Runs tests with the updated PyAirbyte
• /prerelease - Builds and publishes a prerelease version to PyPI
• /evals - Runs the Cloud MCP evals that use the MCP tools this PR changed (/evals full=true runs the full suite)

📚 Show Repo Guidance

Helpful Resources

• PyAirbyte Documentation
• API Reference

Community Support

Questions? Join the #pyairbyte channel in our Slack workspace.

📝 Edit this welcome message.

[github-code-quality]

Code coverage overview

Languages: Python

Python / code-coverage/pytest-unit

release-candidate/v1	devin/1793033319-exe... 3947acd	+/-
—	77%	—

Line coverage data for the release-candidate/v1 branch is not yet available.

View coverage of the 10 most covered files.

File	release-candidate/v1	devin/1793033319-exe... 3947acd	+/-
airbyte/cloud/models.py	—	97%	—
airbyte/mcp/_sso_auth.py	—	96%	—
airbyte/_direct...ctors/models.py	—	95%	—
airbyte/cloud/client.py	—	90%	—
airbyte/exceptions.py	—	90%	—
airbyte/mcp/cloud.py	—	85%	—
airbyte/progress.py	—	80%	—
airbyte/cloud/connectors.py	—	79%	—
airbyte/shared/...ql_processor.py	—	68%	—
airbyte/_util/api_util.py	—	67%	—

ℹ️ Calculations represent line coverage. Results may change as calculations are updated.

[Copilot]

🟢 Approval recommended

The documentation-only additions match the tools’ stated capabilities and introduce no identified issues.

No open issues 🎉

What changed in this PR

Adds example use cases to three external-query MCP tool descriptions, helping agents identify when to use them without changing executable behavior.

Changes:

• Adds live-source investigation examples for API queries.
• Adds sync inspection and pipeline debugging examples for SQL queries.
• Adds meaning- and keyword-based record discovery examples for search queries.

File	Description
airbyte/​mcp/​cloud.py	Adds use-case paragraphs to the three execute_external_* tool docstrings.

_{Review effort: Balanced}