Improve MCP sampling documentation for clarity and consistency

[Timonwa]

Pull Request

Description

Enhance the documentation for MCP sampling to ensure clarity and consistency throughout the content. This update aims to provide better guidance for users.

Related Issue

Type of Change

• Documentation update

How Has This Been Tested?

Closes #593

Checklist

• My code follows the code style of this project
• I have updated the documentation accordingly
• I have added tests to cover my changes
• All new and existing tests passed
• My changes generate no new warnings
• I have checked for potential breaking changes and addressed them

Screenshots (if applicable)

Additional Notes

I removed the API Reference section, cos we already have an API Reference doc. they can get the information there..

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
adk-typescript-docs	Ready	Preview	Feb 24, 2026 0:41am
adk-web	Ready	Preview	Feb 24, 2026 0:41am

[changeset-bot]

⚠️ No Changeset found

Latest commit: d94233e

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[gemini-code-assist]

Summary of Changes

Hello @Timonwa, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the documentation for MCP sampling within the ADK-TS framework. The changes focus on improving clarity, consistency, and providing more practical guidance for users. It updates terminology, clarifies core concepts, and introduces new sections and examples to help users better understand and implement custom sampling handlers and architectural patterns.

Highlights

• Documentation Clarity and Consistency: Improved the overall clarity and consistency of the MCP sampling documentation, including updated terminology to refer to 'ADK-TS' agents and 'runner.ask' methods.
• Enhanced Explanations and Examples: Provided more detailed explanations of how MCP sampling works, including a new dedicated section on 'System Prompt Placement' and refined code examples for custom sampling handlers, routing, context enrichment, and honoring model preferences.
• Documentation Structure and Flow: Restructured the document by reordering sections, removing the explicit API reference, and introducing a new section on 'Managing the Sampling Handler at Runtime' to improve readability and user guidance.
• Table and Diagram Updates: Modified the 'Sampling Request Options' table to include a 'Required' column and updated descriptions, and refined the Mermaid sequence diagram for better participant labeling and notes.

Changelog

• apps/docs/content/docs/framework/tools/mcp-sampling.mdx
  • Updated the page description and clarified the definition of MCP Sampling.
  • Revised the Mermaid sequence diagram for better participant labeling and notes.
  • Refined the explanation of createSamplingHandler as a type helper.
  • Renamed and updated the 'How It Works' section, specifying ADK-TS's role in protocol conversion.
  • Added a new 'System Prompt Placement' section with a warning about contents[0].
  • Expanded and clarified code examples for LlmRequest text extraction and custom sampling handlers (routing, context, model preference).
  • Updated the 'Sampling Request Options' table with a 'Required' column and clearer descriptions.
  • Refactored a return statement in a code example for conciseness.
  • Moved and updated the 'Real-World Architecture Patterns' section, removing the explicit API reference.
  • Introduced a 'Managing the Sampling Handler at Runtime' section with dynamic handler examples.

Activity

• Documentation was updated to improve clarity and consistency.
• Changes were verified through testing.
• Code style was followed, documentation was updated, and no new warnings or breaking changes were introduced.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request significantly improves the documentation for MCP Sampling. The content has been thoughtfully restructured for better logical flow, and the explanations are much clearer and more concise. The updated code examples are more practical and demonstrate best practices effectively. Key improvements include the new sections on honouring model preferences and managing the handler at runtime, which add a lot of value for developers. Overall, this is an excellent documentation update that greatly enhances clarity and usability.

[Rohit-KK15]

Looks good 👍

[MarvelNwachukwu]

Missed this, looks good