Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 1 | # Toolkit Page Availability |
| 2 | |
| 3 | ## Decision |
| 4 | |
| 5 | Keep generated toolkit snapshots authoritative, but allow an individual toolkit |
| 6 | page to query production when its slug is absent from the snapshot. The fallback |
| 7 | is snapshot-first and limited to one validated slug. It is not a live catalog |
| 8 | and does not change how the toolkit landing page, sitemap, search, KB |
| 9 | verification, or `llms.mdx` resolve toolkit data. |
| 10 | |
| 11 | Keep the primary docs-sync GitHub App token limited to repository contents and |
| 12 | pull requests. It must not request `issues`. Steps that create, update, or close |
| 13 | issues in this repository use `github.token` under the workflow's job-level |
| 14 | `issues: write` permission. |
| 15 | |
| 16 | ## Context |
| 17 | |
| 18 | The toolkit pages were coupled to the freshness of |
| 19 | `public/data/toolkits.json`. When the docs data sync stopped before generation, |
| 20 | valid production toolkits added after the last snapshot returned 404. The |
| 21 | [toolkit page decisions](./toolkits.md) establish the generated snapshot as the |
| 22 | default data source, and the |
| 23 | [KB freshness decision](./kb-freshness-verification.md) relies on the same |
| 24 | snapshot architecture. The runtime fallback preserves those decisions while |
| 25 | removing snapshot freshness as an availability requirement for individual |
| 26 | toolkit pages. |
| 27 | |
| 28 | The sync failure came from requesting a GitHub App permission that the |
| 29 | installation did not grant. Issue tracking does not need the App token because |
| 30 | it only writes to the current repository. The KB freshness check is optional and |
| 31 | non-fatal. A failure there can reduce KB freshness evidence, but it cannot block |
| 32 | toolkit, OpenAPI, API index, or meta-tool generation. |
| 33 | |
| 34 | ## Consequences |
| 35 | |
| 36 | - A snapshot hit renders without a production catalog request. |
| 37 | - A snapshot miss may issue one production lookup for the validated slug. An |
| 38 | invalid, excluded, disabled, custom, or unknown slug still returns 404. The |
| 39 | fallback only publishes enabled, Composio-managed toolkits. |
| 40 | - Landing, sitemap, search, KB verification, and build behavior remain |
| 41 | snapshot-backed. |
| 42 | - `/llms.mdx/toolkits/<slug>` parity is deferred. A toolkit available only |
| 43 | through the page fallback can still return 404 from that route. |
| 44 | - `COMPOSIO_TOOLKIT_LIVE_FALLBACK=0` disables the production lookup and restores |
| 45 | snapshot-only page resolution. Changing this Vercel environment variable does |
| 46 | not affect the running production deployment. Create a new Vercel deployment |
| 47 | after changing it. Re-enable the fallback by removing the value or setting it |
| 48 | to a value other than `0`, then deploy again. |
| 49 | - The guaranteed code rollback is to revert the toolkit route integration and |
| 50 | deploy the reverted revision. |
| 51 | - Every docs catalog read (toolkits, tools, trigger types, and the toolkit |
| 52 | changelog) goes through `@composio/client` (v3.1), built in |
| 53 | `lib/composio-api.ts`. `scripts/fetch-openapi.mjs` and `app/api/proxy` keep |
| 54 | raw `fetch`: the first downloads OpenAPI documents, and the second forwards |
| 55 | arbitrary playground requests. The toolkit page, `/llms.mdx` and |
| 56 | `/api/tools/[slug]` use `Composio.fromEnv`, so `COMPOSIO_BASE_URL` selects |
| 57 | the API host; the toolkit generator, `/api/toolkits/instant` and the snapshot-miss |
| 58 | lookup always call production. Lists use its |
| 59 | helpers, which page with `@composio/client/pagination`: toolkit pages and |
| 60 | `/llms.mdx/toolkits/<slug>` at `TOOL_PAGE_SIZE`, `/api/toolkits/instant` at |
| 61 | `TOOLKIT_PAGE_SIZE`, and `generate:toolkits` at the API's per-endpoint cap |
| 62 | (1000 tools or toolkits, 50 trigger types). Live traversals during a page |
| 63 | render abort after `LIVE_TRAVERSAL_TIMEOUT_MS` and fall back to the snapshot. |
| 64 | A failed traversal fails `generate:toolkits` instead of publishing an empty |
| 65 | list. In |
| 66 | Next.js each page is its own Data Cache entry. Next.js does not cache an |
| 67 | entry over 2 MiB, and keeps serving the previous entry; an entry holds the body |
| 68 | base64-encoded, so a response must stay under about 1.5 MiB. The limit is |
| 69 | fixed in Next.js and lifted only by a custom `cacheHandler`. A single |
| 70 | unpaginated request froze `tableau.md` at 10 of 436 tools after the toolkit |
| 71 | grew, and the snapshot stopped `microsoft_365` at 1000 of 1208 tools. oxlint |
| 72 | rejects a raw `fetch`, `fetcher` or `fetchWithRetry` call to `/api/v3*`. |
| 73 | - Dropping response fields does not replace paging. The API has no field |
| 74 | selection and the Data Cache stores response bodies as received. Even reduced |
| 75 | to the fields the pages render, `microsoft_365` measured 2.25 MB. |
| 76 | - Run `bun run lint:links` from `docs/` after editing this record. |
| 77 | - Dispatch `Docs - Update Data` at the exact reviewed head after changing token |
| 78 | permissions. |
| 79 | - After deployment, verify one snapshot-backed slug and one valid production |
| 80 | slug absent from the committed snapshot both return 200. |
| 81 | - `Docs - Toolkit Parity` runs `bun run check:toolkit-parity` every six hours. |
| 82 | For the toolkits with the most tools, ranked by production count and by |
| 83 | snapshot count, it fails when a deployed `.md` page |
| 84 | lists a tool count matching neither production nor the snapshot, when the |
| 85 | snapshot stops at the 1000-item page cap below production, when |
| 86 | `/api/toolkits/instant` differs from production, or when a production |
| 87 | `/tools` or `/toolkits` page would make a cache entry over |
| 88 | `PAGE_BYTES_BUDGET` (85% of 2 MiB). A failure opens one |
| 89 | `docs-toolkit-parity` issue, posts it to Slack, and the next clean run |
| 90 | closes it. |