Add Kotlin snippets to the custom tools page, including toolset filtering

[happyhuman]

Summary

docs/tools-custom/index.md had six language tab groups and not one carried
Kotlin. All six do now, plus a subsection on filtering a toolset's tools with
ToolFilter, which is genuinely new in adk-kotlin 0.7.0.

Section	Snippet
Example (tools in instructions)	WeatherSentiment.kt
State Management	UserPreferenceTools.kt
Controlling Agent Flow	CustomerSupport.kt
Artifacts / Memory	DocAnalysisTools.kt
Defining Effective Tool Functions	OrderTools.kt
Simple Math Toolset	ToolsetExample.kt:init
Filter tools in toolsets (new subsection)	ToolsetExample.kt:filter

All transcluded, so CI compiles and lints every one of them.

Corrections made during review

ToolFilter is not a Kotlin-only capability. An earlier version of this
description, and of the page, said Python and TypeScript had no equivalent. They
do — Python's BaseToolset takes tool_filter: Optional[Union[ToolPredicate, List[str]]] with readonly_context, and Java and TypeScript match it;
b/548652184 tracks the substance.
The subsection is still Kotlin-only in its code, but the heading is now the
plain "Filter tools in toolsets", the prose says outright that every SDK can do
this, and the badge's title scopes the version to the Kotlin API rather than to
filtering as a concept.

Badge versions were wrong. The page badge and the ## Toolsets badge both
claimed Kotlin v0.7.0; @Tool, ToolContext and Toolset all exist at the
v0.1.0 tag, so both now read v0.1.0 — matching function-tools.md. Only the
filtering subsection keeps v0.7.0, which is the release ToolFilter landed in.
The ## Toolsets badge also had a bare Java span with no version; it now reads
v0.3.0, the first adk-java release containing BaseToolset.

The ## Toolsets badge is rewritten by this PR — an earlier revision of this
description said it was untouched, which was wrong: commit 098bf00b replaced
its stale title="…available for Python and TypeScript" (stale because a Java
tab already existed) and added the Java and Kotlin spans.

One unrelated fix, carried because it blocks CI

MultiAgentExample.kt overrode BaseTool.run(context, args: Map<String, Any>).
adk-kotlin 0.8.0 widened that to Map<String, Any?>, so the override compiles
no more. The break came in with the 0.8.0 bump in #2143, not from this branch —
it surfaces here because the snippet runner builds the whole examples project,
while #2143 changed no .kt files and so compiled nothing. One character.

Notes for reviewers

• Source-breaking upstream change, which the snippet quietly documents:
  McpToolsetConfig.toolFilter went List<String>? (v0.6.0) → ToolFilter?
  (v0.7.0).
• The filter snippet is its own subsection, not a fourth tab on the Simple
  Math Toolset group. That group is one worked example explained by five bullets
  — agent, greet_tool, name prefixing, a tool_context.state write, close()
  — and a filtering snippet satisfies none of them. Kotlin cannot satisfy the
  prefix bullet at all: BaseTool.name is a val. A bullet now explains that
  deviation instead of leaving readers with prose that doesn't match the code.
• Deliberately left out: search_memory in the artifacts snippet (not on
  Kotlin's ToolContext; it lives on MemoryService, and the Java tab omits it
  too).

Verification

• ./gradlew compileKotlin clean; ktlint clean; check_kotlin_snippets.sh
  passes.
• Tool bodies are execution-verified, not just compiled — run through a harness
  with a real ToolContext:

unfiltered    : [addNumbers, subtractNumbers]
allowList     : [addNumbers]
predicate off : [addNumbers]
predicate on  : [addNumbers, subtractNumbers]
INVOKED addNumbers(a=7, b=3)      -> {result=10}
INVOKED subtractNumbers(a=7, b=3) -> {result=4}

• Not exercised: no LLM call — the two main() entry points need credentials, so
  they are compile-verified only.

[netlify]

✅ Deploy Preview for adk-docs-preview ready!

Name	Link
🔨 Latest commit	de751d8
🔍 Latest deploy log	https://app.netlify.com/projects/adk-docs-preview/deploys/6a85e7117d0f6f0008d4adcb
😎 Deploy Preview	https://deploy-preview-2114--adk-docs-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[wikaaaaa]

Thanks, I checked the snippet against adk-kotlin v0.7.0 and the code is correct.

Just a comment to the PRs justification -- "gives Kotlin a capability the other languages don't have" isn't accurate. Context-aware tool filtering exists in other languages, ex. Python

Out of scope for this PR, but none of the other snippets in this file include Kotlin — should we add them?

[happyhuman]

Thanks @wikaaaaa — both points addressed, and you were right on the first one.

On "a capability the other languages don't have"

Wrong, and I've corrected it. Python's BaseToolset takes tool_filter: Optional[Union[ToolPredicate, List[str]]], and ToolPredicate.__call__ receives readonly_context — that's the same context-aware filtering and the allow-list-by-name form I claimed was Kotlin's alone.

More importantly, that claim had leaked into the page, not just the description. A single-language badge asserts exclusivity in this repo — the Python-only precedent I cited in the description (docs/agents/llm-agents.md:426) sits on set_default_model, which genuinely is Python-only. So Supported in ADK | Kotlin v0.7.0 under the conceptual heading "Filtering which tools a toolset exposes" was telling readers Python can't do this.

Fixed by scoping the heading to the API rather than the concept: "Filtering which tools a toolset exposes with ToolFilter". ToolFilter really is Kotlin v0.7.0, so the badge is now true, and the title attribute notes other languages have their own mechanisms.

On the other snippets — done, all of them

The page had six language tab groups and not one had Kotlin. All six do now:

Section	Snippet
Example (tools in instructions)	WeatherSentiment.kt
State Management	UserPreferenceTools.kt
Controlling Agent Flow	CustomerSupport.kt
Artifacts / Memory	DocAnalysisTools.kt
Defining Effective Tool Functions	OrderTools.kt
Simple Math Toolset	ToolsetExample.kt:init

All transcluded, so CI compiles and lints them. Also fixed the ## Toolsets section badge, which claimed "Python and TypeScript" despite the Java tab that was already there.

These are execution-verified, not just compiled. I wired a temporary harness with a real ToolContext and ran every tool: filtering, transferToAgent, artifact load/save, and state deltas all behave as documented. Two things that caught real bugs:

• The toolset example originally had no greet_tool, so bullets 2 and 3 of "In this example" described code that wasn't in the Kotlin tab. Added greetUser.
• The state snippet wrote a nested map to stateDelta while reading committed state. Unlike Python's layered tool_context.state, Kotlin's view doesn't include deltas written earlier in the same invocation, so a second call in one turn silently dropped the first. Now one flat key per preference — the same shape the Java tab uses.

What I deliberately left out

• search_memory in the artifacts/memory snippet. Not available on Kotlin's ToolContext; it lives on MemoryService. The Kotlin tab covers artifacts only, which is exactly what the Java tab already does, and the bullet above it already scopes search_memory to "Python, Go and TypeScript". The KDoc points at LoadMemoryTool/PreloadMemoryTool as the Kotlin route.
• Tool-name prefixing in the toolset example. adk-kotlin 0.7.0 has no prefix mechanism and BaseTool.name is a val. Rather than leave a bullet describing absent code, I added one explaining the deviation.
• Live-model execution for the two main() entry points — they need credentials, same as the Python originals. Every tool body is execution-verified; those two entry points are compile-verified only.

Heads up that this outgrew the PR title, which I'll update along with the description. Happy to split the five backfilled snippets into their own PR if you'd rather review them separately from the ToolFilter change you already approved.

[wikaaaaa]

Thanks for filling in the other snippets!

[joefernandez]

Technical review report

Verification method — the PR is entirely Kotlin, so verified against google/adk-kotlin v0.7.0 (the version examples/kotlin/build.gradle.kts pins), not adk-python. Checked out the PR head, ran ./gradlew compileKotlin (BUILD SUCCESSFUL, KSP + compile), ran the toolset logic for real, and reproduced the PR's claimed output exactly:

unfiltered    : [addNumbers, subtractNumbers]
allowList     : [addNumbers]
predicate off : [addNumbers]
predicate on  : [addNumbers, subtractNumbers]

Code: technically correct. Every API the six snippets use exists with the signature used — cited with line numbers in the artifact. Key ones:

• ToolFilter sealed interface + allowList — ToolFilter.kt#L32-L43
• nullable-receiver isToolSelected, null -> true — #L52-L57
• ToolFilter.Predicate { tool, context -> } SAM form — ToolPredicate.kt#L26-L37
• tools vs toolsets split — LlmAgent.kt#L138-L139; filter re-applied per turn at LlmAgentTurn.kt#L171
• BaseTool.name is a val — BaseTool.kt#L38-L43 (backs the "no prefix" bullet)
• 0.7.0 provenance and the List<String>? → ToolFilter? break: v0.6.0 L264 vs v0.7.0 L383

[] Also flagged: the Kotlin v0.7.0 badges overstate the requirement (@Tool/ToolContext/Toolset all ship in v0.1.0, and function-tools.md already says v0.1.0); the new Java span has no version; and the PR description describes only one of its two commits (it says the Toolsets badge is untouched — commit 098bf00b rewrote it).

[joefernandez]

Follow up item from technical review: filed b/548652184

PR claims ToolFilter gives Kotlin "a capability the other languages don't have" and that "Python and TypeScript have no ToolFilter equivalent". All three other SDKs have it, context parameter and all — Kotlin's naming is a direct port of Java's:

• Python base_toolset.py#L41-L56 and #L194-L206 (_is_tool_selected, same three branches)
• Java BaseToolset.java#L60-L75
• TypeScript base_toolset.ts#L79-L95

That undercuts the reason given for making it a Kotlin-only subsection instead of a four-tab one.

[joefernandez]

Approved with comments

[happyhuman]

All four addressed in 840b9b0: heading shortened, badges corrected to v0.1.0 (Java v0.3.0), exclusivity claim dropped, description rewritten. Thanks for the catch.