[PR #2029] [MERGED] docs(install): explain Claude Code upfront tool loading on third-party endpoints #4973

New issue

Closed

opened 2026-10-31 00:57:34 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-31 00:57:34 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/2029
Author: @kaoru0822-kitauji
Created: 10/12/2026
Status: ✅ Merged
Merged: 10/12/2026
Merged by: @kaoru0822-kitauji

Base: main ← Head: docs/claude-code-upfront-tool-context

📝 Commits (1)

5c62d25 docs(install): explain Claude Code upfront tool loading on third-party endpoints

📊 Changes

1 file changed (+29 additions, -0 deletions)

View changed files

📝 docs/installation.md (+29 -0)

📄 Description

Summary

Fixes #2019.

In #2019, Claude Code with deepseek-v4-flash reports "Autocompact is thrashing" as soon as REA is enabled. The cause is client configuration, not a REA tool result:

Claude Code turns MCP tool search off when ANTHROPIC_BASE_URL points to a non-first-party host. DeepSeek's endpoint https://api.deepseek.com/anthropic is one. Claude Code then sends every MCP tool definition with every request.
Without the [1m] suffix that DeepSeek's Claude Code guide uses (deepseek-flash[1m]), Claude Code doesn't recognize the model ID and assumes a smaller window than the model has.
Compaction cannot remove tool definitions, so the context refills after every compaction.

Tool results are not the cause. REA declares no anthropic/maxResultSizeChars, so Claude Code's default 25k-token / 50k-character result limits still apply to it.

This PR adds a Claude Code paragraph to docs/installation.md next to the existing Copilot static-context guidance. It covers the cause and three remedies:

Declare the model's real window: deepseek-flash[1m], or CLAUDE_CODE_MAX_CONTEXT_TOKENS for other unrecognized IDs.
ENABLE_TOOL_SEARCH=true, but only when the endpoint forwards tool_reference blocks. DeepSeek's Anthropic API guide does not list them.
REA_MCP_INPUT_SCHEMA_PROFILE=compact in mcpServers.rea.env of ~/.claude.json (or $CLAUDE_CONFIG_DIR/.claude.json, the path setup writes). Setup already keeps this override.

It contains no code change. On #1669, the maintainer said clients now load tools lazily, so this documents how Claude Code's lazy loading gets turned off and what to do then, instead of adding server-side tool selection. Other catalog-size reductions remain #1065 territory.

Measurement

These are the tool definitions as Claude Code forwards them (name, description, input_schema), built from a real stdio tools/list on main at 04089d5be with 172 tools:

profile	bytes	o200k tokens	cl100k tokens
`full` (default)	496,147	122,789	119,975
`compact`	290,141	68,825	67,649

Claude's and DeepSeek's tokenizers differ, so the token counts are approximate.

Validation

npm run docs:check passed.
npm run format:check passed.

Not verified

A live Claude Code session against DeepSeek's API was not run. Nobody has tested whether DeepSeek's endpoint rejects ENABLE_TOOL_SEARCH=true; the docs only say it may.

🤖 Generated with Claude Code

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/2029 **Author:** [@kaoru0822-kitauji](https://github.com/kaoru0822-kitauji) **Created:** 10/12/2026 **Status:** ✅ Merged **Merged:** 10/12/2026 **Merged by:** [@kaoru0822-kitauji](https://github.com/kaoru0822-kitauji) **Base:** `main` ← **Head:** `docs/claude-code-upfront-tool-context` --- ### 📝 Commits (1) - [`5c62d25`](https://github.com/morluto/rea/commit/5c62d25f4dc9734160bde655e158be9b8f371970) docs(install): explain Claude Code upfront tool loading on third-party endpoints ### 📊 Changes **1 file changed** (+29 additions, -0 deletions) <details> <summary>View changed files</summary> 📝 `docs/installation.md` (+29 -0) </details> ### 📄 Description ## Summary Fixes #2019. In #2019, Claude Code with `deepseek-v4-flash` reports "Autocompact is thrashing" as soon as REA is enabled. The cause is client configuration, not a REA tool result: - Claude Code [turns MCP tool search off](https://code.claude.com/docs/en/mcp#configure-tool-search) when `ANTHROPIC_BASE_URL` points to a non-first-party host. DeepSeek's endpoint `https://api.deepseek.com/anthropic` is one. Claude Code then sends every MCP tool definition with every request. - Without the `[1m]` suffix that [DeepSeek's Claude Code guide](https://api-docs.deepseek.com/guides/coding_agents) uses (`deepseek-flash[1m]`), Claude Code doesn't recognize the model ID and assumes a smaller window than the model has. - Compaction cannot remove tool definitions, so the context refills after every compaction. Tool results are not the cause. REA declares no `anthropic/maxResultSizeChars`, so Claude Code's default 25k-token / 50k-character result limits still apply to it. This PR adds a Claude Code paragraph to `docs/installation.md` next to the existing Copilot static-context guidance. It covers the cause and three remedies: 1. Declare the model's real window: `deepseek-flash[1m]`, or `CLAUDE_CODE_MAX_CONTEXT_TOKENS` for other unrecognized IDs. 2. `ENABLE_TOOL_SEARCH=true`, but only when the endpoint forwards `tool_reference` blocks. DeepSeek's [Anthropic API guide](https://api-docs.deepseek.com/guides/anthropic_api) does not list them. 3. `REA_MCP_INPUT_SCHEMA_PROFILE=compact` in `mcpServers.rea.env` of `~/.claude.json` (or `$CLAUDE_CONFIG_DIR/.claude.json`, the path setup writes). Setup already keeps this override. It contains no code change. On #1669, the maintainer said clients now load tools lazily, so this documents how Claude Code's lazy loading gets turned off and what to do then, instead of adding server-side tool selection. Other catalog-size reductions remain #1065 territory. ## Measurement These are the tool definitions as Claude Code forwards them (`name`, `description`, `input_schema`), built from a real stdio `tools/list` on main at 04089d5be with 172 tools: | profile | bytes | o200k tokens | cl100k tokens | | --- | ---: | ---: | ---: | | `full` (default) | 496,147 | 122,789 | 119,975 | | `compact` | 290,141 | 68,825 | 67,649 | Claude's and DeepSeek's tokenizers differ, so the token counts are approximate. ## Validation - `npm run docs:check` passed. - `npm run format:check` passed. ## Not verified A live Claude Code session against DeepSeek's API was not run. Nobody has tested whether DeepSeek's endpoint rejects `ENABLE_TOOL_SEARCH=true`; the docs only say it may. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-31 00:57:34 +00:00