ADK Integration Page Reviewer (integration-review)
This skill guides a rigorous review of integration documentation pages in the
adk-docs repository. Integration pages
live under docs/integrations/ and document third-party tools, plugins,
observability platforms, data stores, MCP servers, connectors, and other
extensions to ADK agents.
The authoritative sources of truth for this review are:
- The repository's
CONTRIBUTING.md (see the "Integrations" section and its
acceptance criteria).
- The existing shipping integration pages, which are the real template.
Always open and compare against peers of the same category:
- MCP tools:
docs/integrations/github.md, docs/integrations/notion.md
- Observability:
docs/integrations/phoenix.md, docs/integrations/arize-ax.md
- Plugins:
docs/integrations/daytona.md, docs/integrations/goodmem.md
- The catalog rendering logic in
scripts/integrations.py.
[!NOTE]
Read this skill and follow its steps whenever asked to review an integration
page or an integration PR.
Review workflow
Step 1: Gather the change
- If reviewing a PR, use
gh to pull it and read the full cumulative diff,
not a single commit: gh pr view <n> --repo google/adk-docs and gh pr diff <n> --repo google/adk-docs. A stale mkdocs.yml entry or asset can hide in
files that only show in the full diff.
- Check whether "Allow edits from maintainers" is enabled
(
maintainerCanModify) so fixes can be pushed directly if requested later.
- Confirm the CLA is signed (the
google-cla bot). An unsigned CLA is a 🔴
Critical finding and blocks merge until signed.
- If reviewing a local file, run
git status and git diff to see the change.
Step 2: Find and read similar pages
Find 5 or more similar pages and read them in full. Identify candidates in one
pass by scanning catalog_tags (grep catalog_tags docs/integrations/*.md) and
matching the tag under review (e.g. mcp, observability); widen the set with
other signals such as product domain, structural template, and language support
(they need not all be the exact same category). Reading the full pages, not just
frontmatter, grounds the review in live examples and repo conventions rather
than inferring everything from the templates in this skill.
Step 3: Run the checklist
Work through every dimension in the review checklist below.
Step 4: Verify code, packages, and links
Do real verification, not a surface read (see "Deep verification").
Step 5: Research developer value and maturity
Gather objective evidence about the project's maturity, adoption, and whether it
genuinely integrates with ADK (see "Developer value and maturity"). Base the
assessment on verifiable facts, not impressions or the PR's own marketing.
Step 6: Report, decide, and stop
Produce the prioritized report (see "Report format"), then emit the three
follow-on outputs in "Review decision and response": a top-level review
response, a decision (approve, request changes, or close PR), and draft
line-anchored comments. Do not edit files, post to GitHub, or offer to fix
issues by default. Stop and wait for an explicit instruction to fix.
Step 7 (only if asked): Apply fixes
If, and only if, the user explicitly asks you to fix findings: apply precise
edits, keep the contributor's wording where possible, fix only ADK-owned issues
unless told otherwise (leave vendor-SDK bugs for the author), and verify with
mkdocs serve where practical.
Review checklist
1. Frontmatter (catalog metadata)
Every page starts with exactly these four YAML fields:
---
catalog_title: <Display Name>
catalog_description: <short verb-led phrase>
catalog_icon: /integrations/assets/<slug>.png
catalog_tags: ["<tag>", "<tag>"]
---
catalog_title: the human-readable product name shown on the card.
catalog_description: short, verb-led, roughly 45 to 75 characters (about
6 to 11 words). Flag anything over ~80 characters as likely to wrap awkwardly
on a card. It must not repeat the product name (the title already shows
it). No verbose lists of technologies; describe what the integration does. No
overclaims.
catalog_icon: /integrations/assets/<slug>.png (or .svg or .jpg).
The referenced asset file must actually exist in docs/integrations/assets/
and be a real image.
catalog_tags: a JSON array of lowercase tags. Use only tags that
already exist in the catalog; never invent a new one. Tags combine (e.g.
["data", "mcp"]). Any page that uses MCP in its body must carry the mcp
tag. Enumerate the valid tags in one pass with grep catalog_tags docs/integrations/*.md.
2. Structure and required elements
H1 follows # <Product> <type> for ADK, where <type> matches the
category (e.g. # GitHub MCP tool for ADK, # AgentOps observability for ADK, # Daytona plugin for ADK).
Language support tag immediately after the H1, as HTML (not bold
markdown):
<div class="language-support-tag">
<span class="lst-supported">Supported in ADK</span><span class="lst-python">Python</span><span class="lst-typescript">TypeScript</span>
</div>
- Drop the TypeScript span for Python-only integrations.
- Spans must be on a single line. No multi-line span splitting.
- Using plain bold markdown instead of this div is a defect.
Section order should match one of the three category templates:
- MCP tool:
## Use cases -> ## Prerequisites -> ## Use with agent
(tabbed Python / TypeScript) -> ## Available tools -> ## Configuration
(optional) -> ## Additional resources
- Observability: intro ->
## Overview -> ## Installation ->
## Setup -> ## Observe -> ## Support and Resources
- Plugin:
## Use cases -> ## Prerequisites -> ## Installation ->
## Use with agent -> ## Available tools -> ## Configuration
(optional) -> ## Additional resources
Section names: prefer ## Use with agent over ## Usage or verbose
## Example: ... headings. Prefer ## Installation for the install step.
Prefer specific names (Available tools, Available methods) over a bare
## API.
Flag thin or over-fragmented sections (many H2s that are each a single
code block); recommend consolidating into a ## Setup with numbered steps. A
single copy-pasteable end-to-end code block is acceptable and often better for
the user than a split Setup/Observe.
3. Code correctness
- Model strings should be
gemini-flash-latest, gemini-pro-latest, or other
valid *-latest aliases in sample code rather than specific versioned model
strings, which increase the maintenance burden when new model versions are
released.
- Canonical imports:
from google.adk.agents import Agent (short form), and for
MCP from google.adk.tools.mcp_tool import McpToolset.
- Agent variable is
root_agent (Python) / rootAgent (TypeScript); TypeScript
files end with export { rootAgent };.
- MCP examples should use MkDocs Material tabs (
=== "Python" / === "TypeScript", with nested sub-tabs like === "Local MCP Server" where
relevant). Admonitions inside tabs use 8-space indentation.
- Code must be complete and runnable, and must match the real ADK and vendor API
(see "Deep verification").
4. Style and typography
- Little to no use of em dashes or other overly used AI-generated content.
In
**term** — definition bullets replace the em dash with a colon; in prose
split into two sentences or use commas / parentheses. On third-party-owned
content, flag but leave to the author; on anything you edit, remove them.
- Agent Development Kit should be referred to as "ADK", never "Google ADK" or
"The ADK", in prose and code comments.
- Do not start a sentence with an inline-code word. Rephrase (e.g. "The
package-name library adds..." rather than "package-name adds...").
- No marketing bias. These are the ADK docs: remove copy that reads like
marketing and makes sweeping claims.
5. Links and assets
- Internal ADK-docs links should be site-relative (e.g.
/sessions/memory/), not absolute https://adk.dev/... or legacy
https://google.github.io/.... Relative links resolve in PR previews, survive
domain changes, and are caught by the link checker. This is a nit on
vendor-owned pages but generally fix it.
- Image references from a page in
docs/integrations/ should use
assets/<img>.png, not ../assets/... unless the image genuinely lives in
docs/assets/. Trace the path against what peer pages actually do; do not
theorize.
- External links must resolve (HTTP 200). Hunt for hallucinated links to
nonexistent repos, samples, or docs. When you find one, suggest removing it or
ask the author for the real target rather than assuming.
6. Catalog mechanics
- Integration pages are auto-discovered by
render_catalog('integrations/*.md') in docs/integrations/index.md. No
mkdocs.yml nav entry is needed; adding one is an error.
- Cards sort alphabetically by filename. Choose filenames that sort sensibly
and drop package-name prefixes (e.g.
mongodb.md, not
mongodb-mcp-server.md; avoid adk--prefixed names that float to the top).
- Add a redirect in
mkdocs.yml only when a page is renamed or moved from
an existing URL. Point redirects directly at the final destination; never
chain them.
- Adding a new integration requires only the
.md file with correct frontmatter
plus the icon asset in assets/.
Deep verification
Verify all code samples against actual APIs and library code. The canonical
source repositories are listed in docs/community/contributing-guide.md.
- Package reality: confirm the PyPI (or npm) package exists and that any
stated version and Python requirement match the prose.
- ADK API: verify every ADK symbol and pattern used in the code samples
against the canonical source repositories (listed in
docs/community/contributing-guide.md) for the relevant language SDK (e.g.
Runner, run_async, create_session, append_event, save_artifact,
session/artifact service URIs, adk web / adk run CLI flags, genai types).
Do not assume a local checkout: fetch the source with gh or git (or use a
local clone if one exists), and check the released version the docs target
rather than a main branch that may be ahead of or behind the release. Note the
version you verified against, and flag mismatches.
- Vendor SDK: verify the vendor's classes, methods, and arguments against
the vendor SDK source or docs.
- Ownership of bugs: distinguish ADK-owned issues from vendor-SDK-owned
issues (flag and leave for the author).
- Test by hand when practical: run the example with a real ADK agent, or at
minimum
mkdocs serve to confirm the card renders and the icon loads.
Developer value and maturity
Integration pages are official ADK documentation, so an integration must earn
its place by offering real, demonstrated value to developers. The goal here is
to research and determine if the integration is for an established platform with
genuine utility, a track record, and real adoption vs. for a brand-new or
low-adoption project with little substance behind it. Do the research and report
the evidence; do not infer value from the PR's own description or marketing.
Gather objective, verifiable signals and cite each with a source:
- Package reality and age: confirm a real published package exists. Query
the PyPI JSON API (
https://pypi.org/pypi/<pkg>/json) or the npm registry
(https://registry.npmjs.org/<pkg>) for the first-release date, number of
releases, and latest version, and check download counts (pypistats or the npm
downloads API). A missing package, or one published the same day as the PR, is
a strong negative signal.
- Source repository signals: use
gh api repos/<owner>/<repo> to read
created_at, stars, forks, contributor count, commit count, releases,
license, and last-commit date. A repository created within the last few weeks,
with a handful of commits, a single author, or no license is a negative
signal.
- Adoption and track record: gauge real usage from verifiable signals:
package download counts (see above), repository stars, forks, and dependent
projects, plus any documented production users, case studies, or independent
third-party coverage found via web search, and how long the product has
operated. Broad, verifiable usage is a positive signal; its absence across
every source is a negative one.
- Genuine ADK integration: confirm the project actually uses ADK extension
points (callbacks, plugins, toolsets, MCP) rather than patching a dependency
such as
google-genai, or wrapping a REST API with plain functions and
presenting that as an ADK integration (cross-check against "Deep verification"
and the scope trigger below).
- Website liveness: confirm the linked site is a real, live product site,
not a parked domain or placeholder.
Weighing the evidence. A new project is not automatically low-value: an
established vendor shipping a brand-new package, or a project with clear utility
plus a real source repository, tests, and a license, is credible and should not
be treated as a value concern. Genuine concern is the accumulation of negative
signals: brand-new and unpublished, no adoption or track record, no source or
license, no real ADK extension use, and claims the page makes that your
verification could not confirm. When the evidence is mixed, give the contributor
the benefit of the doubt, lay out the facts, and recommend closing as a judgment
call for the maintainer rather than asserting a verdict. Keep the write-up
neutral and factual.
Acceptance and rejection
Rejection triggers (close the PR):
- Documents unreleased, unmerged, or fabricated APIs. We cannot document
functionality that does not exist yet.
- Duplicates a page that already exists (vendor-specific features belong in the
vendor's own docs, with at most a one-line link from the existing ADK page).
- Code that does not match the real ADK or vendor API.
- Broken or hallucinated links.
- Unsigned CLA.
- Insufficient developer value or maturity: a brand-new repository, an
unpublished or same-day package, no adoption or track record, or no source
repository or license. Support this with the evidence from "Developer value
and maturity" and treat it as a maintainer judgment call, not an automatic
verdict.
- Misrepresented integration: manual code that ignores ADK's extension points
while claiming to integrate with ADK.
- Out of scope: a generic "wrap a REST API as a function tool" page with no
ADK-specific artifact. The ADK docs are not an API directory.
- Spam signals (no connection to either project, no ADK-specific functionality,
contribution-graph padding, very new integrations with low usage).
A good page: complete four-field frontmatter with a short verb-led
description and a valid existing tag; correct H1 and single-line
language-support div; the right category template with specific, non-fragmented
sections; complete, runnable, hand-tested code using gemini-flash-latest (or a
valid *-latest alias) and canonical imports (plus Python and TypeScript tabs
for MCP); relative internal links, working external links, valid icon asset; no
verbose AI-generated language, correct use when referring to "ADK", no
overclaims or marketing bias; auto-discovered with no nav edits.
Report format
Produce a Markdown report categorized by priority, each finding with an exact
file:line and context. Derive line numbers from the file under review (the
local page, or the PR via gh pr diff or a fetched copy) using a line-numbered
read, grep -n, or the diff's hunk headers; never approximate (no ~).
Always list all four tiers in order and print None under any tier with no
findings, so the absence of Critical issues is stated, not merely implied. A
finding you consider genuinely take-or-leave belongs under 🔵 Nits; keep 🔴,
🟠, and 🟡 reserved for items that must be fixed before merge.
- 🔴 Critical: fabricated/unreleased APIs, non-working code, broken or
hallucinated links, unsigned CLA, wrong destination directory, duplicate page.
- 🟠 Quality: structure or template mismatch, missing/misnamed sections,
overclaims, incorrect vendor/ADK API details.
- 🟡 Style: verbose AI-generated language, improper usage of "ADK",
inline-code sentence starts, word-choice, model string, imports, description
length, marketing tone.
- 🔵 Nits: tag comma spacing, absolute-vs-relative ADK links on vendor-owned
pages, image size, heading-capitalization variants.
Every finding you list here must produce at least one line-anchored comment in
output 3 (a finding that spans multiple locations gets one comment per
location); the report and the comments must cover the same items.
After the tiers, add a short Developer value and maturity narrative
paragraph: summarize the evidence gathered in the "Research developer value and
maturity" step (package age, adoption and track record, repository signals,
genuine ADK extension use), cite each signal with a source link, and end with a
provisional lean. When the research concludes value or maturity is insufficient,
also record it as a 🔴 Critical finding tagged "judgment call" so it stays
consistent with the approve gate.
After the prioritized report, produce the outputs in "Review decision and
response" below.
Review decision and response
After the prioritized report, emit these three outputs in order. They map onto a
GitHub PR review (review body + decision + inline comments). Everything here is
a draft: do not post to GitHub, do not run gh, and do not edit files
unless the user explicitly asks.
1. Top-level review response
A short review body (a few sentences), suitable to paste as the GitHub PR review
summary. State what the integration is, the overall assessment, the headline
reasons, and what needs to happen next. Use the "Feedback tone" below: short,
direct, diplomatic, and actionable. For a Close PR outcome, adapt the matching
snippet from "Decline response templates" and fill in the specific evidence.
2. Decision
Choose exactly one, justified by citing the specific findings from the report
above it. Cross-reference the "Acceptance and rejection" criteria so the
decision stays consistent with them.
- Approve: the report shows no 🔴, 🟠, or 🟡 findings (all three are
None); at most 🔵 nits remain, and the page meets the "A good page" bar.
- Request changes (the common case): a salvageable page with any 🔴/🟠/🟡
finding that must be fixed before it can merge. List the must-fix items.
- Close PR: hits a rejection trigger from "Acceptance and rejection"
(fabricated/unreleased APIs, duplicate page, code that does not match the real
ADK or vendor API, broken or hallucinated links, unsigned CLA, misrepresented
integration, out of scope, insufficient value/maturity, spam signals).
Recommend the PR be closed and record the reason (link the superseding doc or
PR where relevant). When insufficient developer value/maturity is the only
concern (the code otherwise works), present it as a recommendation explicitly
flagged as a maintainer judgment call, backed by the "Developer value and
maturity" narrative, rather than an automatic hard blocker.
Do not use a plain "comment" (no-decision) outcome unless there is a strong,
stated reason the review genuinely cannot land on one of the three above.
3. Line-anchored comments
A copy-pasteable list of inline PR comments a maintainer can drop onto the diff.
Cover every finding in the report, across all four tiers (🔴 🟠 🟡 🔵). Do
not filter by severity or decide that some categories are not worth commenting:
every flagged item, down to the last nit, gets a comment so the maintainer can
relay all of it and nothing is silently dropped.
Format each comment to be pasted as-is into a GitHub inline comment: a
file:line (or file:start-end) locator with the tier emoji on its own line,
then the one- to two-sentence suggestion as a blockquote so it copies cleanly.
For example:
docs/integrations/weave.md:76 🟡 Style
Use model="gemini-flash-latest" instead of the pinned
model="gemini-2.5-flash" to match repo convention and avoid
model-version churn.
Use the exact file:line for the finding, taken from the file under review
(the local page or the PR diff), never approximated (no ~). Only when a
finding genuinely maps to no line (for example, a missing section, or the
value and maturity judgment call) fall back to a page-level or
frontmatter-level comment, and say so explicitly.
Give the contributor an out where appropriate (e.g. "remove this link and the
page serves as the sample").
Group the comments by tier in the same order as the report.
One finding can produce more than one comment: a finding that spans multiple
locations (e.g. the same issue in the Python and TypeScript samples) gets one
comment per location.
Reconcile before finishing: every finding in the report has at least one
comment (so comments equal or outnumber findings). If any finding lacks one,
add it rather than shipping a partial list.
These are drafts only; do not post them.
After these three outputs, stop. Do not modify files unless the user
explicitly asks.
Feedback tone (for PR comments you draft)
- Short and direct. A couple of sentences per point.
- Diplomatic and actionable; give the contributor an out (e.g. "Do you have a
sample agent in a repo? Otherwise you can remove this link and this page will
serve as the sample.").
- Use precise, actionable terminology (e.g. "rename the catalog title" for the
frontmatter field, not "rename the page"). Reference the contributing guide
for mechanics instead of over-explaining.
Decline response templates
When the decision is Close PR, adapt the matching template below for the
top-level review response. These mirror the maintainer's established voice; keep
them short and replace every [bracket] with the specific, verified
evidence for this PR. Link the acceptance criteria
(https://github.com/google/adk-docs/blob/main/CONTRIBUTING.md#acceptance-criteria).
More than one may apply; combine the relevant paragraphs.
- Value for developers: "Thank you for the PR! After reviewing it against
our [acceptance criteria], we're not able to accept this integration at this
time. Value for developers: We look for integrations that provide clear,
demonstrated value to developers building agents with ADK, and we evaluate
factors such as project maturity, active user base, and track record.
[evidence: e.g. the supporting repository was created within the last few
weeks, there is no published package to integrate against, and the project
does not yet have the community adoption or track record we look for.]"
- Completeness and testability: "Thank you for the PR. After reviewing it
against our [acceptance criteria], we're not able to accept this integration
at this time. Completeness and testability: Code examples in our docs must
be functional and runnable by developers. [evidence: e.g. the ADK imports and
classes referenced do not exist / the
<pkg> package is not published / the
example imports from an unmerged PR.]"
- Publishability: "Thanks for the PR. However, we're unable to accept this
integration. Per our [acceptance criteria], we can't publish integrations for
services that may circumvent technical protection measures, violate terms of
service, or access services without authorization. [evidence]"
- Out of scope: "Thanks for the PR! However, this integration page is out of
scope for the ADK docs. Integration pages are for third-party functionality
that extends or tightly integrates with ADK (tools, plugins, toolsets, MCP
servers, or observability platforms). [evidence: e.g. this defines plain
functions that call a REST API, the generic 'wrap a REST API as a function
tool' pattern, which is already documented and applies to any API. The ADK
docs are not an API directory.]"
- Duplicate / superseded: "Thanks for the PR. This is superseded by #
<N> /
duplicates the existing [<page>]. [Optional: vendor-specific features belong
in the vendor's own docs, with at most a one-line link from the existing ADK
page.]"
1---
2name: integration-review
3description: Reviews an ADK integration documentation page (a Markdown file under docs/integrations/) or an integration pull request for correctness, structure, style, working code, valid links, and catalog conventions. Produces a prioritized review report, a recommended decision (approve, request changes, or close PR), a top-level review response, and draft line-anchored comments; only fixes issues when explicitly asked. Triggers on "integration-review", "review integration page", "review integration PR", "review this integration", "check integration docs".
4metadata:
5 source: https://skillmd.com/skills/google/integration-review
6---
7
8# ADK Integration Page Reviewer (integration-review)
9
10This skill guides a rigorous review of integration documentation pages in the
11[adk-docs](https://github.com/google/adk-docs) repository. Integration pages
12live under `docs/integrations/` and document third-party tools, plugins,
13observability platforms, data stores, MCP servers, connectors, and other
14extensions to ADK agents.
15
16The authoritative sources of truth for this review are:
17
181. The repository's `CONTRIBUTING.md` (see the "Integrations" section and its
19 acceptance criteria).
202. The **existing shipping integration pages**, which are the real template.
21 Always open and compare against peers of the same category:
22 - MCP tools: `docs/integrations/github.md`, `docs/integrations/notion.md`
23 - Observability: `docs/integrations/phoenix.md`, `docs/integrations/arize-ax.md`
24 - Plugins: `docs/integrations/daytona.md`, `docs/integrations/goodmem.md`
253. The catalog rendering logic in `scripts/integrations.py`.
26
27> [!NOTE]
28> Read this skill and follow its steps whenever asked to review an integration
29> page or an integration PR.
30
31## Review workflow
32
33### Step 1: Gather the change
34
35- If reviewing a PR, use `gh` to pull it and read the **full cumulative diff**,
36 not a single commit: `gh pr view <n> --repo google/adk-docs` and `gh pr diff
37 <n> --repo google/adk-docs`. A stale `mkdocs.yml` entry or asset can hide in
38 files that only show in the full diff.
39- Check whether "Allow edits from maintainers" is enabled
40 (`maintainerCanModify`) so fixes can be pushed directly if requested later.
41- Confirm the CLA is signed (the `google-cla` bot). An unsigned CLA is a 🔴
42 Critical finding and blocks merge until signed.
43- If reviewing a local file, run `git status` and `git diff` to see the change.
44
45### Step 2: Find and read similar pages
46
47Find 5 or more similar pages and read them in full. Identify candidates in one
48pass by scanning `catalog_tags` (`grep catalog_tags docs/integrations/*.md`) and
49matching the tag under review (e.g. `mcp`, `observability`); widen the set with
50other signals such as product domain, structural template, and language support
51(they need not all be the exact same category). Reading the full pages, not just
52frontmatter, grounds the review in live examples and repo conventions rather
53than inferring everything from the templates in this skill.
54
55### Step 3: Run the checklist
56
57Work through every dimension in the review checklist below.
58
59### Step 4: Verify code, packages, and links
60
61Do real verification, not a surface read (see "Deep verification").
62
63### Step 5: Research developer value and maturity
64
65Gather objective evidence about the project's maturity, adoption, and whether it
66genuinely integrates with ADK (see "Developer value and maturity"). Base the
67assessment on verifiable facts, not impressions or the PR's own marketing.
68
69### Step 6: Report, decide, and stop
70
71Produce the prioritized report (see "Report format"), then emit the three
72follow-on outputs in "Review decision and response": a top-level review
73response, a decision (approve, request changes, or close PR), and draft
74line-anchored comments. Do **not** edit files, post to GitHub, or offer to fix
75issues by default. Stop and wait for an explicit instruction to fix.
76
77### Step 7 (only if asked): Apply fixes
78
79If, and only if, the user explicitly asks you to fix findings: apply precise
80edits, keep the contributor's wording where possible, fix only ADK-owned issues
81unless told otherwise (leave vendor-SDK bugs for the author), and verify with
82`mkdocs serve` where practical.
83
84## Review checklist
85
86### 1. Frontmatter (catalog metadata)
87
88Every page starts with exactly these four YAML fields:
89
90```yaml
91---
92catalog_title: <Display Name>
93catalog_description: <short verb-led phrase>
94catalog_icon: /integrations/assets/<slug>.png
95catalog_tags: ["<tag>", "<tag>"]
96---
97```
98
99- **`catalog_title`**: the human-readable product name shown on the card.
100- **`catalog_description`**: short, verb-led, roughly 45 to 75 characters (about
101 6 to 11 words). Flag anything over ~80 characters as likely to wrap awkwardly
102 on a card. It must **not repeat the product name** (the title already shows
103 it). No verbose lists of technologies; describe what the integration does. No
104 overclaims.
105- **`catalog_icon`**: `/integrations/assets/<slug>.png` (or `.svg` or `.jpg`).
106 The referenced asset file must actually exist in `docs/integrations/assets/`
107 and be a real image.
108- **`catalog_tags`**: a JSON array of lowercase tags. **Use only tags that
109 already exist in the catalog; never invent a new one.** Tags combine (e.g.
110 `["data", "mcp"]`). Any page that uses MCP in its body must carry the `mcp`
111 tag. Enumerate the valid tags in one pass with `grep catalog_tags
112 docs/integrations/*.md`.
113
114### 2. Structure and required elements
115
116- **H1** follows `# <Product> <type> for ADK`, where `<type>` matches the
117 category (e.g. `# GitHub MCP tool for ADK`, `# AgentOps observability for
118 ADK`, `# Daytona plugin for ADK`).
119- **Language support tag** immediately after the H1, as HTML (not bold
120 markdown):
121
122 ```html
123 <div class="language-support-tag">
124 <span class="lst-supported">Supported in ADK</span><span class="lst-python">Python</span><span class="lst-typescript">TypeScript</span>
125 </div>
126 ```
127
128 - Drop the TypeScript span for Python-only integrations.
129 - **Spans must be on a single line.** No multi-line span splitting.
130 - Using plain bold markdown instead of this div is a defect.
131- **Section order** should match one of the three category templates:
132 - **MCP tool**: `## Use cases` -> `## Prerequisites` -> `## Use with agent`
133 (tabbed Python / TypeScript) -> `## Available tools` -> `## Configuration`
134 (optional) -> `## Additional resources`
135 - **Observability**: intro -> `## Overview` -> `## Installation` ->
136 `## Setup` -> `## Observe` -> `## Support and Resources`
137 - **Plugin**: `## Use cases` -> `## Prerequisites` -> `## Installation` ->
138 `## Use with agent` -> `## Available tools` -> `## Configuration`
139 (optional) -> `## Additional resources`
140- **Section names**: prefer `## Use with agent` over `## Usage` or verbose
141 `## Example: ...` headings. Prefer `## Installation` for the install step.
142 Prefer specific names (`Available tools`, `Available methods`) over a bare
143 `## API`.
144- Flag **thin or over-fragmented sections** (many H2s that are each a single
145 code block); recommend consolidating into a `## Setup` with numbered steps. A
146 single copy-pasteable end-to-end code block is acceptable and often better for
147 the user than a split Setup/Observe.
148
149### 3. Code correctness
150
151- Model strings should be `gemini-flash-latest`, `gemini-pro-latest`, or other
152 valid `*-latest` aliases in sample code rather than specific versioned model
153 strings, which increase the maintenance burden when new model versions are
154 released.
155- Canonical imports: `from google.adk.agents import Agent` (short form), and for
156 MCP `from google.adk.tools.mcp_tool import McpToolset`.
157- Agent variable is `root_agent` (Python) / `rootAgent` (TypeScript); TypeScript
158 files end with `export { rootAgent };`.
159- MCP examples should use MkDocs Material tabs (`=== "Python"` / `===
160 "TypeScript"`, with nested sub-tabs like `=== "Local MCP Server"` where
161 relevant). Admonitions inside tabs use 8-space indentation.
162- Code must be complete and runnable, and must match the real ADK and vendor API
163 (see "Deep verification").
164
165### 4. Style and typography
166
167- **Little to no use of em dashes or other overly used AI-generated content.**
168 In `**term** — definition` bullets replace the em dash with a colon; in prose
169 split into two sentences or use commas / parentheses. On third-party-owned
170 content, flag but leave to the author; on anything you edit, remove them.
171- Agent Development Kit should be referred to as "ADK", never "Google ADK" or
172 "The ADK", in prose and code comments.
173- **Do not start a sentence with an inline-code word.** Rephrase (e.g. "The
174 `package-name` library adds..." rather than "`package-name` adds...").
175- **No marketing bias.** These are the ADK docs: remove copy that reads like
176 marketing and makes sweeping claims.
177
178### 5. Links and assets
179
180- Internal ADK-docs links should be **site-relative** (e.g.
181 `/sessions/memory/`), not absolute `https://adk.dev/...` or legacy
182 `https://google.github.io/...`. Relative links resolve in PR previews, survive
183 domain changes, and are caught by the link checker. This is a nit on
184 vendor-owned pages but generally fix it.
185- Image references from a page in `docs/integrations/` should use
186 `assets/<img>.png`, not `../assets/...` unless the image genuinely lives in
187 `docs/assets/`. Trace the path against what peer pages actually do; do not
188 theorize.
189- External links must resolve (HTTP 200). Hunt for **hallucinated links** to
190 nonexistent repos, samples, or docs. When you find one, suggest removing it or
191 ask the author for the real target rather than assuming.
192
193### 6. Catalog mechanics
194
195- Integration pages are **auto-discovered** by
196 `render_catalog('integrations/*.md')` in `docs/integrations/index.md`. **No
197 `mkdocs.yml` nav entry is needed**; adding one is an error.
198- Cards sort **alphabetically by filename**. Choose filenames that sort sensibly
199 and **drop package-name prefixes** (e.g. `mongodb.md`, not
200 `mongodb-mcp-server.md`; avoid `adk-`-prefixed names that float to the top).
201- Add a **redirect** in `mkdocs.yml` only when a page is renamed or moved from
202 an existing URL. Point redirects directly at the final destination; **never
203 chain** them.
204- Adding a new integration requires only the `.md` file with correct frontmatter
205 plus the icon asset in `assets/`.
206
207## Deep verification
208
209Verify all code samples against actual APIs and library code. The canonical
210source repositories are listed in `docs/community/contributing-guide.md`.
211
212- **Package reality**: confirm the PyPI (or npm) package exists and that any
213 stated version and Python requirement match the prose.
214- **ADK API**: verify every ADK symbol and pattern used in the code samples
215 against the canonical source repositories (listed in
216 `docs/community/contributing-guide.md`) for the relevant language SDK (e.g.
217 `Runner`, `run_async`, `create_session`, `append_event`, `save_artifact`,
218 session/artifact service URIs, `adk web` / `adk run` CLI flags, genai types).
219 Do not assume a local checkout: fetch the source with `gh` or `git` (or use a
220 local clone if one exists), and check the **released version** the docs target
221 rather than a main branch that may be ahead of or behind the release. Note the
222 version you verified against, and flag mismatches.
223- **Vendor SDK**: verify the vendor's classes, methods, and arguments against
224 the vendor SDK source or docs.
225- **Ownership of bugs**: distinguish ADK-owned issues from vendor-SDK-owned
226 issues (flag and leave for the author).
227- **Test by hand** when practical: run the example with a real ADK agent, or at
228 minimum `mkdocs serve` to confirm the card renders and the icon loads.
229
230## Developer value and maturity
231
232Integration pages are official ADK documentation, so an integration must earn
233its place by offering real, demonstrated value to developers. The goal here is
234to research and determine if the integration is for an established platform with
235genuine utility, a track record, and real adoption vs. for a brand-new or
236low-adoption project with little substance behind it. Do the research and report
237the evidence; do not infer value from the PR's own description or marketing.
238
239Gather objective, verifiable signals and cite each with a source:
240
241- **Package reality and age**: confirm a real published package exists. Query
242 the PyPI JSON API (`https://pypi.org/pypi/<pkg>/json`) or the npm registry
243 (`https://registry.npmjs.org/<pkg>`) for the first-release date, number of
244 releases, and latest version, and check download counts (pypistats or the npm
245 downloads API). A missing package, or one published the same day as the PR, is
246 a strong negative signal.
247- **Source repository signals**: use `gh api repos/<owner>/<repo>` to read
248 `created_at`, stars, forks, contributor count, commit count, releases,
249 license, and last-commit date. A repository created within the last few weeks,
250 with a handful of commits, a single author, or no license is a negative
251 signal.
252- **Adoption and track record**: gauge real usage from verifiable signals:
253 package download counts (see above), repository stars, forks, and dependent
254 projects, plus any documented production users, case studies, or independent
255 third-party coverage found via web search, and how long the product has
256 operated. Broad, verifiable usage is a positive signal; its absence across
257 every source is a negative one.
258- **Genuine ADK integration**: confirm the project actually uses ADK extension
259 points (callbacks, plugins, toolsets, MCP) rather than patching a dependency
260 such as `google-genai`, or wrapping a REST API with plain functions and
261 presenting that as an ADK integration (cross-check against "Deep verification"
262 and the scope trigger below).
263- **Website liveness**: confirm the linked site is a real, live product site,
264 not a parked domain or placeholder.
265
266**Weighing the evidence.** A new project is not automatically low-value: an
267established vendor shipping a brand-new package, or a project with clear utility
268plus a real source repository, tests, and a license, is credible and should not
269be treated as a value concern. Genuine concern is the accumulation of negative
270signals: brand-new and unpublished, no adoption or track record, no source or
271license, no real ADK extension use, and claims the page makes that your
272verification could not confirm. When the evidence is mixed, give the contributor
273the benefit of the doubt, lay out the facts, and recommend closing as a judgment
274call for the maintainer rather than asserting a verdict. Keep the write-up
275neutral and factual.
276
277## Acceptance and rejection
278
279**Rejection triggers (close the PR):**
280
281- Documents unreleased, unmerged, or fabricated APIs. We cannot document
282 functionality that does not exist yet.
283- Duplicates a page that already exists (vendor-specific features belong in the
284 vendor's own docs, with at most a one-line link from the existing ADK page).
285- Code that does not match the real ADK or vendor API.
286- Broken or hallucinated links.
287- Unsigned CLA.
288- Insufficient developer value or maturity: a brand-new repository, an
289 unpublished or same-day package, no adoption or track record, or no source
290 repository or license. Support this with the evidence from "Developer value
291 and maturity" and treat it as a maintainer judgment call, not an automatic
292 verdict.
293- Misrepresented integration: manual code that ignores ADK's extension points
294 while claiming to integrate with ADK.
295- Out of scope: a generic "wrap a REST API as a function tool" page with no
296 ADK-specific artifact. The ADK docs are not an API directory.
297- Spam signals (no connection to either project, no ADK-specific functionality,
298 contribution-graph padding, very new integrations with low usage).
299
300**A good page:** complete four-field frontmatter with a short verb-led
301description and a valid existing tag; correct H1 and single-line
302language-support div; the right category template with specific, non-fragmented
303sections; complete, runnable, hand-tested code using `gemini-flash-latest` (or a
304valid `*-latest` alias) and canonical imports (plus Python and TypeScript tabs
305for MCP); relative internal links, working external links, valid icon asset; no
306verbose AI-generated language, correct use when referring to "ADK", no
307overclaims or marketing bias; auto-discovered with no nav edits.
308
309## Report format
310
311Produce a Markdown report categorized by priority, each finding with an exact
312`file:line` and context. Derive line numbers from the file under review (the
313local page, or the PR via `gh pr diff` or a fetched copy) using a line-numbered
314read, `grep -n`, or the diff's hunk headers; never approximate (no `~`).
315**Always list all four tiers in order and print `None` under any tier with no
316findings**, so the absence of Critical issues is stated, not merely implied. A
317finding you consider genuinely take-or-leave belongs under 🔵 **Nits**; keep 🔴,
318🟠, and 🟡 reserved for items that must be fixed before merge.
319
320- 🔴 **Critical**: fabricated/unreleased APIs, non-working code, broken or
321 hallucinated links, unsigned CLA, wrong destination directory, duplicate page.
322- 🟠 **Quality**: structure or template mismatch, missing/misnamed sections,
323 overclaims, incorrect vendor/ADK API details.
324- 🟡 **Style**: verbose AI-generated language, improper usage of "ADK",
325 inline-code sentence starts, word-choice, model string, imports, description
326 length, marketing tone.
327- 🔵 **Nits**: tag comma spacing, absolute-vs-relative ADK links on vendor-owned
328 pages, image size, heading-capitalization variants.
329
330Every finding you list here must produce at least one line-anchored comment in
331output 3 (a finding that spans multiple locations gets one comment per
332location); the report and the comments must cover the same items.
333
334After the tiers, add a short **Developer value and maturity** narrative
335paragraph: summarize the evidence gathered in the "Research developer value and
336maturity" step (package age, adoption and track record, repository signals,
337genuine ADK extension use), cite each signal with a source link, and end with a
338provisional lean. When the research concludes value or maturity is insufficient,
339also record it as a 🔴 **Critical** finding tagged "judgment call" so it stays
340consistent with the approve gate.
341
342After the prioritized report, produce the outputs in "Review decision and
343response" below.
344
345## Review decision and response
346
347After the prioritized report, emit these three outputs in order. They map onto a
348GitHub PR review (review body + decision + inline comments). Everything here is
349a **draft**: do not post to GitHub, do not run `gh`, and do not edit files
350unless the user explicitly asks.
351
352### 1. Top-level review response
353
354A short review body (a few sentences), suitable to paste as the GitHub PR review
355summary. State what the integration is, the overall assessment, the headline
356reasons, and what needs to happen next. Use the "Feedback tone" below: short,
357direct, diplomatic, and actionable. For a Close PR outcome, adapt the matching
358snippet from "Decline response templates" and fill in the specific evidence.
359
360### 2. Decision
361
362Choose exactly one, justified by citing the specific findings from the report
363above it. Cross-reference the "Acceptance and rejection" criteria so the
364decision stays consistent with them.
365
366- **Approve**: the report shows no 🔴, 🟠, or 🟡 findings (all three are
367 `None`); at most 🔵 nits remain, and the page meets the "A good page" bar.
368- **Request changes** (the common case): a salvageable page with any 🔴/🟠/🟡
369 finding that must be fixed before it can merge. List the must-fix items.
370- **Close PR**: hits a rejection trigger from "Acceptance and rejection"
371 (fabricated/unreleased APIs, duplicate page, code that does not match the real
372 ADK or vendor API, broken or hallucinated links, unsigned CLA, misrepresented
373 integration, out of scope, insufficient value/maturity, spam signals).
374 Recommend the PR be closed and record the reason (link the superseding doc or
375 PR where relevant). When insufficient developer value/maturity is the *only*
376 concern (the code otherwise works), present it as a recommendation explicitly
377 flagged as a maintainer judgment call, backed by the "Developer value and
378 maturity" narrative, rather than an automatic hard blocker.
379
380Do not use a plain "comment" (no-decision) outcome unless there is a strong,
381stated reason the review genuinely cannot land on one of the three above.
382
383### 3. Line-anchored comments
384
385A copy-pasteable list of inline PR comments a maintainer can drop onto the diff.
386Cover **every finding in the report, across all four tiers (🔴 🟠 🟡 🔵)**. Do
387not filter by severity or decide that some categories are not worth commenting:
388every flagged item, down to the last nit, gets a comment so the maintainer can
389relay all of it and nothing is silently dropped.
390
391- **Format each comment to be pasted as-is** into a GitHub inline comment: a
392 `file:line` (or `file:start-end`) locator with the tier emoji on its own line,
393 then the one- to two-sentence suggestion as a blockquote so it copies cleanly.
394 For example:
395
396 `docs/integrations/weave.md:76` 🟡 Style
397
398 > Use `model="gemini-flash-latest"` instead of the pinned
399 > `model="gemini-2.5-flash"` to match repo convention and avoid
400 > model-version churn.
401
402- Use the exact `file:line` for the finding, taken from the file under review
403 (the local page or the PR diff), never approximated (no `~`). Only when a
404 finding genuinely maps to no line (for example, a missing section, or the
405 value and maturity judgment call) fall back to a page-level or
406 frontmatter-level comment, and say so explicitly.
407- Give the contributor an out where appropriate (e.g. "remove this link and the
408 page serves as the sample").
409- Group the comments by tier in the same order as the report.
410- One finding can produce more than one comment: a finding that spans multiple
411 locations (e.g. the same issue in the Python and TypeScript samples) gets one
412 comment per location.
413- Reconcile before finishing: every finding in the report has at least one
414 comment (so comments equal or outnumber findings). If any finding lacks one,
415 add it rather than shipping a partial list.
416
417These are drafts only; do not post them.
418
419After these three outputs, **stop**. Do not modify files unless the user
420explicitly asks.
421
422## Feedback tone (for PR comments you draft)
423
424- Short and direct. A couple of sentences per point.
425- Diplomatic and actionable; give the contributor an out (e.g. "Do you have a
426 sample agent in a repo? Otherwise you can remove this link and this page will
427 serve as the sample.").
428- Use precise, actionable terminology (e.g. "rename the catalog title" for the
429 frontmatter field, not "rename the page"). Reference the contributing guide
430 for mechanics instead of over-explaining.
431
432## Decline response templates
433
434When the decision is Close PR, adapt the matching template below for the
435top-level review response. These mirror the maintainer's established voice; keep
436them short and **replace every `[bracket]` with the specific, verified
437evidence** for this PR. Link the acceptance criteria
438(`https://github.com/google/adk-docs/blob/main/CONTRIBUTING.md#acceptance-criteria`).
439More than one may apply; combine the relevant paragraphs.
440
441- **Value for developers**: "Thank you for the PR! After reviewing it against
442 our [acceptance criteria], we're not able to accept this integration at this
443 time. **Value for developers:** We look for integrations that provide clear,
444 demonstrated value to developers building agents with ADK, and we evaluate
445 factors such as project maturity, active user base, and track record.
446 [evidence: e.g. the supporting repository was created within the last few
447 weeks, there is no published package to integrate against, and the project
448 does not yet have the community adoption or track record we look for.]"
449- **Completeness and testability**: "Thank you for the PR. After reviewing it
450 against our [acceptance criteria], we're not able to accept this integration
451 at this time. **Completeness and testability:** Code examples in our docs must
452 be functional and runnable by developers. [evidence: e.g. the ADK imports and
453 classes referenced do not exist / the `<pkg>` package is not published / the
454 example imports from an unmerged PR.]"
455- **Publishability**: "Thanks for the PR. However, we're unable to accept this
456 integration. Per our [acceptance criteria], we can't publish integrations for
457 services that may circumvent technical protection measures, violate terms of
458 service, or access services without authorization. [evidence]"
459- **Out of scope**: "Thanks for the PR! However, this integration page is out of
460 scope for the ADK docs. Integration pages are for third-party functionality
461 that extends or tightly integrates with ADK (tools, plugins, toolsets, MCP
462 servers, or observability platforms). [evidence: e.g. this defines plain
463 functions that call a REST API, the generic 'wrap a REST API as a function
464 tool' pattern, which is already documented and applies to any API. The ADK
465 docs are not an API directory.]"
466- **Duplicate / superseded**: "Thanks for the PR. This is superseded by #`<N>` /
467 duplicates the existing [`<page>`]. [Optional: vendor-specific features belong
468 in the vendor's own docs, with at most a one-line link from the existing ADK
469 page.]"