chore(toolkit-docs): restore lost summaries for 6 toolkits by jottakka · Pull Request #928 · ArcadeAI/docs

jottakka · 2026-04-17T23:54:54Z

Summary

Restores the summary field for github, googledocs, jira, salesforce, daytona, linear — all six had rich, hand-refined overviews that were silently wiped to null across recent [AUTO] Adding MCP Servers docs update merges.
Each summary was rewritten from the last known-good version in git history and then updated against the toolkit's current tool set so the overview is accurate, not just restored.
Format matches what LlmToolkitSummaryGenerator produces (60–140 words, Capabilities bullets, OAuth / Secrets sections) so future LLM regeneration stays on-style.

Capability drift accounted for

Toolkit	Notable update
`github`	Dropped notifications (no longer in toolkit). Dropped `CLASSIC_PERSONAL_ACCESS_TOKEN` (only `GITHUB_SERVER_URL` remains). Added Projects V2 fields/items and user-centric views (review workload, open items, recent activity).
`googledocs`	Clarified `SearchAndRetrieveDocuments` returns body content vs. `SearchDocuments` metadata-only. Kept File Picker recovery pattern.
`jira`	No capability drift. Tightened wording around single-call batching and name/key/email resolution.
`salesforce`	No capability drift. Added explicit mention of related-object enrichment (contact roles, line items).
`daytona`	Dropped abstract metadata framing. Added `ListRegions`, signed vs. standard port preview URLs, explicit snapshot lifecycle.
`linear`	Dropped stale comment-anchoring caveat. Added project/initiative description pagination and `ManageIssueSubscription`.

Why separate from the code fix

The regression fix (#927) lands code changes to data-merger.ts. This PR is content-only so reviewers can evaluate wording and truthfulness independently — and so either can merge without blocking the other. Without the code fix, the next auto-update run that changes a toolkit's tool signature will wipe these summaries again (signature mismatch → regen; if LLM unavailable/fails → wipe). Recommend merging #927 first.

Test plan

Word count between 60–140 for each summary (rendered via the same block as LlmToolkitSummaryGenerator).
OAuth scopes in summary match the aggregated scopes in .auth.allScopes.
Secrets section only mentions secrets actually present in the toolkit.
Preview the rendered overview on a Vercel deploy for at least one toolkit (e.g. /en/mcp-servers/development/github).

Refs #926
🤖 Generated with Claude Code

Note

Low Risk
Content-only changes that add back human-readable toolkit summary text; no runtime code paths or APIs are modified, so risk is limited to documentation accuracy.

Overview
Restores and adds rich summary blocks to six generated toolkit JSON descriptors (daytona, github, googledocs, jira, linear, salesforce), covering capabilities plus OAuth/secrets guidance.

Also updates the affected files’ generatedAt timestamps and fixes the JSON endings (adds trailing commas/newlines) so the summaries are persisted in the generated artifacts.

^{Reviewed by Cursor Bugbot for commit 3b7a17f. Bugbot is set up for automated code reviews on this repo. Configure here.}

The summary field for github, googledocs, jira, salesforce, daytona, and linear was silently wiped to null across recent [AUTO] docs update merges (see #926 for the root cause — regeneration fallback paths did not preserve the previous summary). Each restored summary was rewritten from the last known-good version in git history and then updated to reflect the toolkit's CURRENT tools. Notable capability drift accounted for: - github: drop notifications (no notification tools currently); drop CLASSIC_PERSONAL_ACCESS_TOKEN (only GITHUB_SERVER_URL remains); add explicit Projects V2 fields/items and user-centric views (review workload, open items, recent activity). - googledocs: clarify SearchAndRetrieveDocuments returns body content while SearchDocuments is metadata-only; keep File Picker recovery. - jira: no capability drift; tighten wording around single-call batching and name/key/email reference resolution. - salesforce: no capability drift; add explicit mention of related- object enrichment (contact roles, line items) visible in current descriptions. - daytona: drop abstract "metadata for coordination"; add ListRegions, signed vs. standard port preview URLs, snapshots as a separate lifecycle. - linear: drop the comment-anchoring caveat (no longer present in tool descriptions); add pagination for project/initiative descriptions and ManageIssueSubscription. This restoration is intentionally separate from #927 (the code fix) so content review can happen independently of the regression fix. Refs #926 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

vercel · 2026-04-17T23:54:58Z

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

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	Apr 20, 2026 5:30pm

…to Arcade auth provider docs Per follow-up feedback, summaries should not repeat OAuth scopes — they belong in the per-toolkit auth provider documentation, not the overview prose. Each of the six restored summaries now: - States whether OAuth is required and names the provider. - Links to the matching Arcade auth provider page under /en/references/auth-providers/<provider> instead of listing scopes. - Where applicable, adds explicit explanations for each secret plus a link to the Arcade Dashboard secret setup flow. The deterministic secret-coverage check in #932 is not changed here — that PR already accepts either the Arcade secret docs link or the Dashboard URL, both of which remain present in these summaries. Refs #926 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…cade auth provider docs Same follow-up as #928 applied to the five toolkits with brand-new summaries. Each OAuth section now states the provider and links to /en/references/auth-providers/<provider> instead of enumerating scopes. Secrets sections were also tightened with per-secret provenance and a link to the Arcade secret setup guide. Refs #926 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…scopes Per follow-up on PRs #928 and #929, the OAuth section of each summary should name the provider and link to the Arcade per-provider auth docs rather than enumerate scopes. Scopes already live on the provider reference page and repeating them in toolkit summaries creates drift every time a provider page updates. Changes: - Add ARCADE_AUTH_PROVIDERS_BASE_URL constant alongside the existing Arcade secret URLs in secret-coherence.ts. - Rewrite the OAuth bullet in toolkit-summary-generator.ts's prompt to require a link to {base}/<providerId> and explicitly forbid listing scopes. - Drop scopes from formatAuth's prompt payload so the model has no stray scope list to fall back on. - README: note the no-scopes-in-summary rule and point to the provider reference pages as the source of truth. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

torresmateo · 2026-04-20T16:00:44Z

  "subPages": [],
-  "generatedAt": "2026-04-02T11:25:02.814Z"
-}
+  "generatedAt": "2026-04-02T11:25:02.814Z",


This seems like the generation date is not taking the actual generation date, is this intentional?

Resolve linear.json: keep restored summary from PR with main's generatedAt. Made-with: Cursor

* chore(toolkit-docs): add missing summaries for 5 toolkits posthog, granola, microsoftoutlookcalendar, microsoftoutlookmail, and zohocreatorapi never received a summary — LLM generation was either skipped or failed on the first auto-update run and the null state has persisted ever since (see #926 for the underlying regression). Each summary is written from the actual tool list in the toolkit JSON, matching the structure the LLM prompt targets (60–140 words, Capabilities bullets, OAuth / Secrets sections) so the rendered overview looks consistent with LLM-generated peers. Refs #926 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore(toolkit-docs): drop OAuth scopes from new summaries, link to Arcade auth provider docs Same follow-up as #928 applied to the five toolkits with brand-new summaries. Each OAuth section now states the provider and links to /en/references/auth-providers/<provider> instead of enumerating scopes. Secrets sections were also tightened with per-secret provenance and a link to the Arcade secret setup guide. Refs #926 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

torresmateo noted daytona.json carried an older generatedAt than the actual edit. Refresh timestamps for toolkit JSON touched in this PR where dates were still from prior generator runs (Apr 2 / Apr 10). Made-with: Cursor

This was referenced Apr 17, 2026

chore(toolkit-docs): add missing summaries for 5 toolkits #929

Merged

Toolkit docs generator silently wipes summary on LLM unavailable / failure #926

Closed

vercel bot deployed to Preview April 17, 2026 23:58 View deployment

jottakka self-assigned this Apr 18, 2026

vercel bot deployed to Preview April 18, 2026 18:31 View deployment

jottakka marked this pull request as ready for review April 18, 2026 18:41

jottakka requested a review from a team April 18, 2026 20:26

torresmateo reviewed Apr 20, 2026

View reviewed changes

torresmateo approved these changes Apr 20, 2026

View reviewed changes

Merge branch 'main' into chore/restore-toolkit-summaries

d606620

Resolve linear.json: keep restored summary from PR with main's generatedAt. Made-with: Cursor

vercel bot deployed to Preview April 20, 2026 17:28 View deployment

vercel bot deployed to Preview April 20, 2026 17:30 View deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore(toolkit-docs): restore lost summaries for 6 toolkits#928

chore(toolkit-docs): restore lost summaries for 6 toolkits#928
jottakka wants to merge 4 commits intomainfrom
chore/restore-toolkit-summaries

jottakka commented Apr 17, 2026 •

edited by cursor bot

Loading

Uh oh!

vercel bot commented Apr 17, 2026 •

edited

Loading

Uh oh!

torresmateo Apr 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

jottakka commented Apr 17, 2026 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Capability drift accounted for

Why separate from the code fix

Test plan

Uh oh!

vercel bot commented Apr 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

torresmateo Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jottakka commented Apr 17, 2026 •

edited by cursor bot

Loading

vercel bot commented Apr 17, 2026 •

edited

Loading