Ton

TON AI / AgentKit Documentation Audit

The TON AI docs are explicitly built for agent consumption — yet the machine-readable export drops the one safety warning that matters, the recommended network contradicts itself across three pages, and the at-rest key format the source code calls "obfuscation, not encryption" never appears in the docs at all.

1. Recommended network contradicts itself across three pages (critical)

Location: /overview/ai/quick-start, /overview/ai/mcp, /overview/ai/wallets

Problem: The quick start says "Fund the wallet with Toncoin. The recommended network is mainnet." The MCP page says @ton/mcp "is safe for use in mainnet." But the wallets page carries a Developer preview callout: "Agentic wallet contracts have not been audited. Use testnet for experiments." The FAQ (in the wallets Markdown export) confirms "a formal audit has not been completed." So one set of pages tells you to fund real money onto contracts that another page says are unaudited and should only be used on testnet.

Consequence: A developer (or an agent acting on the quick start) deposits real Toncoin into an unaudited smart contract that has full control of its own balance. The risk the wallets page is trying to cap — "Only fund agentic wallets with amounts and assets that they are allowed to risk" — is silently undone by the page most people read first.

The fix: Pick one stance for the preview period. If the contracts are unaudited, the quick start and MCP page must recommend testnet and drop "safe for use in mainnet." If mainnet is genuinely intended, the wallets page must explain why and remove "Use testnet for experiments."

2. AI-facing Markdown export omits the audit/safety warning entirely (critical)

Location: /llms.mdx/overview/ai/wallets.md (vs rendered /overview/ai/wallets)

Problem: The overview page advertises that "Documentation pages are available as raw Markdown through the https://docs.ton.org/llms.mdx page routes" for AI tools. The rendered wallets page shows a "Developer preview — Agentic wallet contracts have not been audited. Use testnet for experiments." callout. The raw Markdown export jumps straight from the intro line to "## Split-key architecture" — the callout is gone. The FAQ answers survive but the question text is missing, so the export contains the bare line "it can spend the entire wallet balance before the owner reacts" with no question framing it.

Consequence: This is the single worst defect here, because it targets the exact consumer the format exists for. An agent reading the recommended machine-readable surface — to operate a wallet that holds funds — never sees that the contracts are unaudited, and reads risk disclosures stripped of the questions that give them meaning. The safety rail exists only for humans.

The fix: Render admonition/callout blocks into the llms.mdx export (e.g. as a blockquote > **Developer preview:** ...), and emit FAQ question headings, not just answers. The AI export must be a superset of the safety-relevant content, never a subset.

3. Key-storage caveat ("not real cryptographic protection") is never surfaced (critical)

Location: /overview/ai/mcp, /overview/ai/wallets (vs github.com/ton-connect/kit packages/mcp README)

Problem: The @ton/mcp README warns plainly: wallet secrets at ~/.config/ton/config.json are "not stored as plain text, but the current protected-file format is only obfuscation-in-file, not real cryptographic protection with an external secret or password." The docs MCP page describes key handling only as "It handles private keys and signing internally" — there is no mention anywhere in the AI section that the at-rest format is obfuscation, not encryption, and no mention of the file path or its 0700/0600 permission model.

Consequence: Developers reasonably assume an on-disk wallet secret is encrypted. They aren't — anyone with read access to the file (malware, a shared machine, a synced backup, a leaked dotfiles repo) can recover operator keys. For a tool whose whole job is signing transactions, omitting this is a material security gap.

The fix: Mirror the README's caveat on the MCP and wallets pages, with the file path, the 0700/0600 permission notes, and explicit guidance (don't sync the config dir, treat the file as a plaintext secret).

4. The default npx @ton/mcp command pulls a stale version that rejects the documented flow (significant)

Location: /overview/ai/quick-start, /overview/ai/mcp (vs npmjs.com/package/@ton/mcp)

Problem: Every docs example pins npx -y @ton/mcp@alpha. The npm registry shows the default/latest as "0.1.13 • Published 4 months ago." That published version's README states: "We currently do not support launch without a mnemonic or private key." The entire quick start premise is the agentic-wallet mode, which is keyless by design. The 0.1.13 README also lists WALLET_VERSION as only v5r1 or v4r2 (no agentic) and exposes none of the agentic_* tools.

Consequence: Following the docs verbatim always yields @alpha and works. But a developer who drops the @alpha tag (or runs npx @ton/mcp) gets a four-month-old latest build that refuses to start without a mnemonic and cannot create agentic wallets at all. The failure is confusing because the docs never warn that the default npm tag is unusable for this workflow.

The fix: State explicitly that @alpha is required and that the npm latest tag does not yet support agentic wallets. Better: promote a usable build to a stable tag, or publish the current feature set so latest matches the docs.

5. Install command conflicts with the official MCP portal it links to (significant)

Location: /overview/ai/quick-start, /overview/ai/mcp (vs mcp.ton.org)

Problem: docs.ton.org instructs npx skills add ton-connect/kit/packages/mcp. The official "TON MCP portal" (mcp.ton.org, authored by TON Foundation and linked from the docs as the canonical catalog) instructs npx skills add ton-org/skills -y, plus ton-org/skills/wallets and ton-org/skills/docs. Two different repositories/paths for the same install step.

Consequence: A developer comparing the docs to the linked portal can't tell which skills package is authoritative, or whether they're the same thing under two names. Agents that index both surfaces get conflicting setup instructions for one task.

The fix: Standardize on one skills identifier across docs and portal. If both packages exist for a reason, say what each contains and which the quick start should use.

6. Hosted "TON Documentation MCP" server is undocumented in the AI section (significant)

Location: /overview/ai/overview, /overview/ai/mcp (vs mcp.ton.org)

Problem: The official portal the docs link to documents a first-party hosted server: "A hosted Model Context Protocol server that lets your AI agent search and read the official TON documentation," installed with claude mcp add --transport http ton-docs https://docs.ton.org/mcp. The docs.ton.org AI pages — whose entire "Documentation" section is about making the docs AI-consumable — never mention this hosted endpoint.

Consequence: The most direct way for an agent to query TON docs is a hosted MCP server run by the same team, and a developer reading the AI overview would never know it exists. They fall back to scraping raw Markdown routes when a purpose-built search/read server is already available. Agents only use endpoints they're told about.

The fix: Document the hosted https://docs.ton.org/mcp documentation server in the AI overview alongside the llms.txt/llms.mdx surfaces, with the claude mcp add command and a note on what it indexes.

7. Serverless header name is wrong: TONCENTER_API_KEY vs TONCENTER_KEY (significant)

Location: /overview/ai/mcp (Serverless section) vs README (Serverless Deployment → Headers)

Problem: The docs serverless header table lists TONCENTER_API_KEY. The source README's serverless Headers table names the header TONCENTER_KEY. (Confusingly, the env-var form in both the npm and source README is TONCENTER_API_KEY, so the name legitimately differs between env-var mode and serverless-header mode — which makes documenting the wrong one in the serverless table especially easy to get wrong.)

Consequence: A developer deploying serverless sets TONCENTER_API_KEY per the docs; the server expects TONCENTER_KEY, ignores the unknown header, and silently falls back to unauthenticated TonCenter rate limits. Requests then throttle in production with no error pointing at the header name.

The fix: Correct the serverless table to TONCENTER_KEY, and add a one-line note that the serverless header name differs from the env-var name.

8. Shipping tools emulate_transaction and generate_ton_proof are undocumented (significant)

Location: /overview/ai/mcp#available-tools (vs README)

Problem: The README documents two tools the docs "Available tools" list omits: emulate_transaction (dry-run a raw transaction without broadcasting, returning expected balance changes and fees) and generate_ton_proof (TonProof proof-of-ownership for authenticating with third-party services).

Consequence: emulate_transaction is precisely the safety primitive that mitigates the "agent spends the entire balance" risk the FAQ raises — and developers/agents don't know it exists. generate_ton_proof is the only documented auth path for third-party services; its absence means TonProof flows are undiscoverable from the docs. Agents only call tools they're told about.

The fix: Add both tools to the Available tools list, including the README's note that imported read-only wallets must complete operator-key rotation before generate_ton_proof works.

9. "check the changelog before upgrading" — but no changelog link appears in the section (significant)

Location: /overview/ai/mcp

Problem: The MCP page states: "Pin a specific version for production use and check the changelog before upgrading." No changelog link appears in the scraped MCP page or anywhere else in the AI section (overview, quick-start, mcp, wallets).

Consequence: Because the package is explicitly alpha with APIs and behaviors that "may change between releases," the changelog is load-bearing advice — yet the reader is sent to a document with no link to it. Production users following the instruction have nowhere obvious to go.

The fix: Link the actual changelog (GitHub releases or a CHANGELOG.md) inline where the sentence appears.

10. The AI index is called llms.mdx but lives at /llms.txt (significant)

Location: /overview/ai/overview

Problem: The overview prose says "The llms.mdx file provides a machine-readable index of documentation pages," but the actual index is served at /llms.txt (confirmed by fetching /llms.txt) and the hyperlink points there. The per-page raw routes use a different scheme, /llms.mdx/.... So "the llms.mdx file" is a name that doesn't resolve — the index file is llms.txt; llms.mdx is only a route prefix for individual pages.

Consequence: An agent or developer told to fetch "the llms.mdx file" requests the wrong path. The naming collision between the index file (/llms.txt) and the per-page prefix (/llms.mdx/...) is exactly the kind of ambiguity that breaks automated indexing.

The fix: Call the index "the llms.txt file" in prose, and clearly distinguish it from the /llms.mdx/<path>.md per-page raw routes.

11. Broken in-page anchor link "manage them" points to a nonexistent id (minor)

Location: /overview/ai/quick-start (confirmed in /llms.mdx/overview/ai/quick-start.md)

Problem: The body contains [manage them](#manage-wallets), but the target heading is ## 5. Manage wallets [#5-manage-wallets]. The anchor #manage-wallets does not exist on the page; the real id is #5-manage-wallets.

Consequence: Clicking "manage them" jumps nowhere (or to the top of the page), and the cross-reference is dead for anyone navigating to the wallet-management section.

The fix: Change the link target to #5-manage-wallets, or give the heading a stable, name-based id and link to that.

12. Orphan link-reference [skills-spec] defined but never used (minor)

Location: /llms.mdx/overview/ai/quick-start.md

Problem: The quick-start Markdown export ends with a trailing reference definition [skills-spec]: https://agentskills.io/specification, but the token [skills-spec] is never referenced anywhere in the page body — it is a dangling/orphan link reference.

Consequence: The reference renders as nothing for a human reader, and for an agent parsing the Markdown it's a defined-but-unused link target that points to a spec the page presumably meant to cite. Either a citation was dropped or dead boilerplate is shipping in the AI-facing export.

The fix: Either wire [skills-spec] into the relevant sentence (e.g. where the skills install step is described) or remove the unused definition.

13. Multiple typos, including a Cyrillic character in agent-facing text (minor)

Location: /overview/ai/quick-start, /overview/ai/mcp, /overview/ai/overview

Problem: Quick start: "manage them form the dashboard" (should be "from"). MCP page: "use a diffent wallet version" (should be "different"). Overview page: "the raw conteе of this page" — missing a "t" and ending in a Cyrillic "е" (U+0435), not a Latin "e".

Consequence: The Cyrillic homoglyph is the consequential one: any agent or script doing exact-string matching on "content" will silently fail to match conteе, and the word renders as a non-word. The others are polish issues but appear in a doc set whose selling point is machine-readability.

The fix: Fix "form"→"from" and "diffent"→"different"; replace the Cyrillic е and restore the missing t so it reads "content". Add a homoglyph/lint check to CI given the AI-facing claims.

14. Quick start advertises a "buy/sell Backed's xStocks" capability with no backing tool (minor)

Location: /overview/ai/quick-start ("Use the wallet with AI")

Problem: The capabilities bullet lists "Swap assets, manage NFTs, buy/sell Backed's xStocks." No tool in the Available tools list, and no feature elsewhere in the AI section, corresponds to buying or selling xStocks — the documented tools cover balances, transfers, swaps, NFTs, and DNS only.

Consequence: A developer or agent prompts the wallet to "buy xStocks" on the strength of this bullet and finds no tool can do it, with no example, contract, or pointer explaining the gap. It reads as a feature that's either unshipped or undocumented.

The fix: Either document the tool/flow that performs xStocks buy/sell (with the relevant tool name and an example prompt) or remove the capability from the list until it ships.

What they do well

• The split-key/SBT architecture and funding model on the wallets page are explained clearly, including a concrete risk framing ("Only fund agentic wallets with amounts and assets that they are allowed to risk").
• Per-tool descriptions in the Available tools section are precise and parseable (return types, normalizedHash, pagination notes), which is genuinely useful for agents.
• Shipping a raw-Markdown route per page and an llms.txt index is the right instinct for AI consumers — the structure exists; it just needs to carry the safety content too.

Top 3 recommendations

1. Resolve the mainnet-vs-testnet contradiction first, and make the llms.mdx export a strict superset of safety content — render audit warnings and FAQ questions into the Markdown agents actually read (Issues 1, 2).
2. Close the security and implementation-vs-docs gaps: surface the key-storage "obfuscation, not encryption" caveat, document emulate_transaction, generate_ton_proof, and the hosted docs.ton.org/mcp server, and link the changelog you tell people to read (Issues 3, 6, 8, 9).
3. Fix the install/version truth: require or stabilize @alpha, reconcile the ton-connect/kit vs ton-org/skills install commands with the official portal, and correct the TONCENTER_KEY header (Issues 4, 5, 7).