Repository navigation
docs(mcp): clarify that get_agent_skill_docs is for a deployed connector's direct-access docs - #1389
Conversation
…tor's direct-access docs Co-Authored-By: alexandre@airbyte.io <alexandre@airbyte.io>
|
I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".
|
|
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 |
👋 Greetings, Airbyte Team Member!Here are some helpful tips and reminders for your convenience. 💡 Show Tips and TricksTesting This PyAirbyte VersionYou 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/1792092702-skill-docs-description' pyairbyte --help
# Install PyAirbyte from this branch for development:
pip install 'git+https://github.com/airbytehq/PyAirbyte.git@devin/1792092702-skill-docs-description'PR Slash CommandsAirbyte Maintainers can execute the following slash commands on your PR:
📚 Show Repo GuidanceHelpful ResourcesCommunity SupportQuestions? Join the #pyairbyte channel in our Slack workspace. |
Code coverage overviewLanguages: Python Python / code-coverage/pytest-no-creds
View coverage of the 10 most impacted files.
Python / code-coverage/pytest
View coverage of the 10 most impacted files.
Python / code-coverage/pytest-unit
Line coverage data for the release-candidate/v1 branch is not yet available. View coverage of the 10 most covered files.
ℹ️ Calculations represent line coverage. Results may change as calculations are updated. Updated |
|
Eval evidence. I added two regression scenarios to cloud-mcp-evals, based on the rc.28 public session where both failures happened. I ran them in the local sandbox on
What's simulated:
|
0360edc
into
release-candidate/v1
There was a problem hiding this comment.
🟢 Approval recommended
The documentation-only changes align with the existing interfaces, with no unresolved issues.
0 open findings
What changed in this PR
Clarifies MCP tool guidance so agents request connector-specific direct-access docs with the correct identifier. No runtime behavior changes.
Changes:
- Distinguishes deployed connector IDs from definition IDs and redirects general Airbyte questions.
- Clarifies the required identifier when requesting the documentation overview without a section.
| File | Description |
|---|---|
airbyte/mcp/guidance.py |
Clarifies tool purpose and connector ID requirements. |
airbyte/mcp/cloud.py |
Corrects shared instructions for requesting documentation sections. |
🧠 Review effort: Balanced
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Overview
👉 TL;DR: Rewords the tool description so agents stop calling the connector-docs tool for general Airbyte questions or with the wrong kind of ID.
Specifically, this rewrites the
get_agent_skill_docsdocstring andconnector_iddescription, and fixes the "nosection" wording inSKILL_DOCS_SECTION_HINT(shared withexecute_external_api_query).Summary
Requested by Alexandre Girard (@girarda) after triaging production
get_agent_skill_docserrors (BigQuerymcp_events+ Datadogservice:cloud-mcp). Two of the external failures came from caller confusion rather than server bugs:Provide exactly one of docs_skill_id or connector_id. The old hint said "Callget_agent_skill_docswith nosectioninput to list all available sections", which reads like the tool is a general guidance index.source-google-sheetsdefinition ID asconnector_id→ 403 on both/v1/sources/{id}and/v1/destinations/{id}.Changes
get_agent_skill_docsdocstring: describes it as a deployed connector's direct-access docs (entity types/actions/args forexecute_external_api_query), says it's not general Airbyte guidance and points tosearch_airbyte_knowledge_sources, and statesconnector_idmust be a deployed workspace connector ID (e.g. fromlist_cloud_connectors), not a registry definition ID.connector_idfield description: adds "(not a connector definition ID)".SKILL_DOCS_SECTION_HINT: "Callget_agent_skill_docswith the deployedconnector_id(or adocs_skill_id) and nosectionto get the overview and list of available sections, then retrieve the relevant section(s)…".Text-only; no behavior change.
Follow-ups
Not in this PR (discussed, not requested): returning the skill index when called with no args, detecting registry definition IDs on 403, and returning a result instead of raising when direct access isn't enabled.
Test plan
ruff format/ruff checkandpyrefly checkon the two files: pass.pytest tests/unit_tests -k "guidance or skill or mcp": 1078 passed.fastmcp.Clientand confirmed the newget_agent_skill_docsandexecute_external_api_querydescriptions are what MCP clients receive.Link to Devin session: https://app.devin.ai/sessions/8fc02d415e774a5cbf1d9c07c0ddb97b
Open in Devin Desktop: https://app.devin.ai/desktop/session/8fc02d415e774a5cbf1d9c07c0ddb97b?variant=devin