The Context

Thecontext Documentation Audit

Solid Mintlify-style docs with a clear concept model and broad framework coverage, but the reserved-metadata contract — the platform's central abstraction — drifts in type and placement across pages, the REST API has no schemas, and three API-key prefixes are documented with no single page that disambiguates them.

1. tcc.conversational type contradicts across pages (critical)

Location: /concepts, /frameworks/agno, /frameworks/langchain-langgraph

Problem: The reserved-metadata contract — Thecontext's central abstraction — is type-ambiguous on the source-of-truth page and contradicted by framework pages:

• /concepts lists tcc.conversational in the reserved-keys table with a Purpose column but no Type column; the prose says "set tcc.conversational to true in the run's metadata" (unquoted, type unclear).
• /frameworks/agno says: "Mark a run as conversational by setting tcc.conversational to \"true\" in metadata" (quoted string).
• /frameworks/langchain-langgraph's metadata table explicitly types tcc.conversational as boolean.

Consequence: A developer who copies the Agno snippet sends the string "true"; if the ingestion layer enforces the LangChain table's boolean type, conversational analysis silently never fires, and the user never knows their runs are being routed to the wrong analysis pipeline. This is the exact gating flag that decides whether the platform's marquee feature (frustration / confusion / custom-pattern detection on conversational runs) runs at all on a trace.

The fix: Add an explicit Type column to the reserved-keys table on /concepts, commit to one canonical type (boolean is the obvious choice), and fix the Agno page so it sends an unquoted true. Then framework pages can't drift from a single source of truth.

2. Three API-key prefixes documented, no single page explains which to use where (critical)

Location: /access-data/api, /environments, framework setup pages

Problem: The docs expose three distinct key prefixes with no unified guide:

• /access-data/api defines read-only keys prefixed tcc_key and ingestion keys prefixed tcc_prod.
• /environments says for dev mode, "Set the TCC_API_KEY environment variable to your user-level API key (begins with dev_)".
• Framework pages (e.g. /frameworks/vercel-ai-sdk: "Our SDKs default to using the TCC_API_KEY environment variable") just say "set TCC_API_KEY" without telling you which prefix belongs in there.

There is no page that lists all three prefixes side-by-side, says where each is generated, or explains that TCC_API_KEY is overloaded across tcc_prod (prod ingestion), dev_ (dev ingestion), and never tcc_key (which is read-only).

Consequence: A developer copies the framework quickstart, drops in a tcc_key read-only key by mistake, and gets a silent 401/403 on ingestion — or worse, drops in a dev_ key in production and traces flow to the wrong environment. Agents reading the docs to scaffold a setup have no way to know which prefix to demand from the user.

The fix: Add an "API keys" reference table on a single page (probably /environments or a new /access-data/keys) listing prefix, scope (read-only vs ingestion), environment (dev vs prod), where it's generated, and which env var consumes it. Link every framework setup page to that table.

3. REST API reference has no schemas, no error codes, no rate limits (critical)

Location: /access-data/api

Problem: The API page advertises programmatic access to runs, traces, metrics, patterns, failures, and sessions, then shows the entirety of the endpoint reference as bare bullet entries like "List failures / Get a failure" — no request parameters, no response schema, no example payloads, no status codes, no pagination semantics, no rate limits, no auth-failure behavior. There is no link to an OpenAPI / Swagger spec anywhere in the scraped content or the llms.txt index.

Consequence: A developer who wants to query their observability data programmatically (the entire stated use case of the page) cannot do so without reverse-engineering the API by trial and error. Agents reading the docs cannot generate a typed client, cannot validate request shapes, and cannot tell the user what fields a Failure actually contains. This is especially jarring because the product's own MCP server is "powered by insight search" — but third-party agents can't replicate that without a schema.

The fix: Publish an OpenAPI 3 spec at a stable URL (e.g., https://api.thecontext.company/v1/openapi.json), link it from /access-data/api and /llms.txt, and render per-endpoint reference pages with request/response schemas, example payloads, and the error-code table.

4. Anchor conventions are inconsistent across framework pages (significant)

Location: /frameworks/openclaw, /frameworks/agno, /concepts

Problem: Different framework pages link into /concepts using different anchor conventions, and there is no single rule. OpenClaw links to /concepts#runs and /concepts#sessions — anchors that match the literal H3 headings on /concepts ("Runs", "Sessions"). Agno links to /concepts#conversational-runs, which also matches a real heading ("Conversational runs"). The concepts page itself uses heading text like "Runs", "Steps", "Tool calls", "Sessions", "Conversational runs" — not "Agent runs" or "Agent sessions". When framework pages prose-link "agent runs" / "agent sessions" but the destination headings drop the word "Agent", readers and agents have no consistent vocabulary to follow back to the source of truth.

Consequence: A developer (or coding agent) jumping from a framework page to "what is an agent run?" lands on a page whose headings use different language than the link text. Cross-page citation gets noisier than necessary, and any future page that copies OpenClaw's pattern vs. Agno's pattern will keep the inconsistency alive.

The fix: Pick one canonical vocabulary across the docs (probably "Run" / "Session", matching the concepts headings), normalize link text on every framework page to that vocabulary, and add a link-checker to CI — Mintlify can lint anchors on build.

5. Python vs TypeScript custom instrumentation diverge with no parity matrix (significant)

Location: /frameworks/custom-instrumentation/python/setup, /frameworks/custom-instrumentation/typescript/setup, plus the steps pages for each

Problem: Custom instrumentation is documented separately for Python and TypeScript, with separate method tables on separate pages. The Python Run methods table on /frameworks/custom-instrumentation/python/setup enumerates a specific method set (.prompt, .response, .metadata, .feedback, .status, .error, .step, .tool_call, .end); there is no equivalent comparison view for the TypeScript SDK and no callout flagging which methods exist in only one language. The Python steps page documents a "Set cost" affordance with no cross-link to or from the TypeScript steps page indicating whether the same affordance exists there.

Consequence: Teams with polyglot stacks (Python backend + TS frontend, common for agent products) have no way to confirm parity without scanning every method on every page in both SDK trees. Agents asked to port instrumentation from one SDK to the other will hallucinate parity that may not exist.

The fix: Add a parity matrix at the top of the custom-instrumentation index showing which methods/options exist in which SDK, with a "differs" badge linking to the relevant page section. At minimum, cross-link the Python and TypeScript versions of every page (setup, runs, steps, tool-calls) so a reader can flip between them in one click.

6. The Recaps page lives at a URL named weekly-insights (significant)

Location: /features/weekly-insights

Problem: The page is titled "Recaps" and describes a daily/weekly/monthly product, but its canonical URL is /features/weekly-insights — a stale URL from when the feature was weekly-only. The llms.txt index even labels it "Recaps" while pointing at weekly-insights.md.

Consequence: External links and agent-side citations land on a URL whose slug contradicts the page title and product framing. SEO and embedding-based retrieval (e.g., a coding agent asking "where are recaps configured?") gets noisier matches than necessary because the URL says one thing and the H1 says another.

The fix: Rename the page to /features/recaps and 301 the old slug. Update llms.txt and any internal links.

7. examples repo linked from docs is essentially empty (significant)

Location: https://github.com/The-Context-Company/examples (linked from framework pages)

Problem: The repository contains only an express folder, has 0 stars / 0 forks / 6 commits, and no examples for any of the frameworks the docs spend chapters on (Claude Agent SDK, Vercel AI SDK, Mastra, LangChain, CrewAI, Agno, Pi-Mono, OpenClaw). Meanwhile the observatory monorepo "contains multiple working examples across different frameworks," but the dedicated examples repo doesn't reflect that.

Consequence: A developer who clicks "see examples" expecting a copy-paste starter gets one Express scaffold and nothing else for the framework they actually use. For agent-driven scaffolding, this is worse — the agent can't pull a working reference repo per framework.

The fix: Either populate the examples repo with one runnable scaffold per framework (matching the framework-pages list), or stop linking it and point readers at the observatory monorepo's examples/ directories directly.

8. LiteLLM page puts tcc.runId on the step call, contradicting the concept-page rule that tcc.runId is a run metadata key (significant)

Location: /frameworks/custom-instrumentation/python/litellm, /concepts, /frameworks/pi-mono

Problem: /concepts defines tcc.runId as a key set in the run's metadata: "set tcc.runId in the run's metadata." The LiteLLM page tells you to do something different: "you must pass the run ID in the metadata parameter to associate the step with your run" — i.e., tcc.runId is now a step-level key whose job is to link a LiteLLM completion call back to its parent run. Pi-Mono goes the opposite direction: "Do not put tcc.runId here. Use instrumentation.setRunId(...) before each prompt to assign a per-run ID." Three pages, three placements for the same reserved key, with no unifying explanation.

Consequence: A developer copying the LiteLLM snippet has no signal that tcc.runId is being used differently here than on /concepts; the same key name carries two different semantics (run-identity assignment vs. step-to-run linkage) with no callout. Agents synthesizing config from any one page in isolation will mis-place the key when they switch frameworks.

The fix: On /concepts, explicitly note that tcc.runId has two roles: assigning a run ID when set in run metadata, and linking a step to its parent run when set in step-call metadata (LiteLLM-style). On the LiteLLM and Pi-Mono pages, add a one-line callout pointing back to that definition so the reader doesn't have to reverse-engineer the rule.

9. PII redaction example uses an OpenAI-style key, not Thecontext's own key formats (minor)

Location: /features/pii-redaction

Problem: The "What gets redacted" table shows API-key redaction with the example sk-test1234abcd5678efgh → [API_KEY]. Thecontext's own documented key formats are tcc_key, tcc_prod, and dev_ (per /access-data/api and /environments) — none of which match the sk-* shape. The docs never confirm whether the redactor also matches the company's own ingestion-key formats.

Consequence: A customer whose agent accidentally logs a Thecontext ingestion key (tcc_prod_...) into a trace argument has no documented assurance that the platform's own redactor will catch it before storage. The most consequential leak the redactor should prevent — the customer's ingestion key for this very product — isn't shown.

The fix: Add an example row to the redaction table covering tcc_prod_..., tcc_key_..., and dev_... prefixes, or state explicitly that the API-key matcher includes those formats. If it doesn't, fix the matcher.

10. Internal link to Local Mode points at /frameworks/vercel-ai-sdk/index, but the sitemap lists /frameworks/vercel-ai-sdk (minor)

Location: /environments

Problem: The Local Mode section on /environments links to [Local mode](/frameworks/vercel-ai-sdk/index). The sitemap lists the canonical page as /frameworks/vercel-ai-sdk (no /index suffix). Unless Mintlify silently rewrites /index to the canonical slug, this is a broken internal link from the page where most users will first read about Local Mode.

Consequence: A developer following the most prominent "Local mode" link on the environments page may land on a 404 (or be silently rewritten without any indication that the link was wrong). For agents that follow links to resolve concepts, an extra hop or a 404 breaks the chain.

The fix: Change the link to /frameworks/vercel-ai-sdk to match the sitemap, and add a link-check step to Mintlify CI.

11. llms.txt exists but no llms-full.txt (minor)

Location: /llms.txt

Problem: Thecontext ships an llms.txt that is a flat index of page titles and URLs, but there is no llms-full.txt containing the actual page contents. Coding agents that want to load the full doc corpus into context have to fetch each URL individually (28+ HTTP requests) instead of one bulk file.

Consequence: Slower agent-side onboarding to the platform; more cache misses on the agent's HTTP layer; harder to drop "all of Thecontext's docs" into a single prompt for offline reasoning.

The fix: Generate and publish llms-full.txt as a concatenation of every doc page's markdown (Mintlify supports this via its docs.json config). Link it from the docs index footer.

What they do well

• Reserved-metadata namespace is a strong design choice. tcc.* as a universal contract is exactly the kind of structure agents can latch onto — the failure is in type drift and placement drift across pages, not the model itself.
• Broad framework coverage. Eight named integrations plus custom instrumentation in two languages is genuinely good surface area.
• Concepts page does the right thing semantically. Defining runs, steps, sessions, tool calls, conversational runs, and silent failures up front gives the rest of the docs a vocabulary to reference.

Top 3 recommendations

1. Stabilize the tcc.* contract end-to-end. Add a Type column to the reserved-keys table on /concepts, fix the Agno page's string-vs-boolean drift, and write down the dual role of tcc.runId (run-level identity vs. step-call linkage) so LiteLLM and Pi-Mono stop looking like contradictions.
2. Publish an OpenAPI spec and disambiguate the three key prefixes. The schema-less REST reference and the overloaded TCC_API_KEY (which can be tcc_prod, dev_, but never tcc_key) are both one-PR fixes with outsized impact on both human and agent navigation.
3. Add Mintlify link-checking to CI. It would catch the /frameworks/vercel-ai-sdk/index link, normalize the framework-page anchor vocabulary against /concepts, and prevent the next regression of this kind.