diff --git a/docs/claude-code-integration.md b/docs/claude-code-integration.md
new file mode 100644
index 0000000..4c26ad1
--- /dev/null
+++ b/docs/claude-code-integration.md
@@ -0,0 +1,59 @@
+# Claude Code 集成指南
+
+将 EVE-MCP 接入 Claude Code，让 AI 助手直接调用地球科学知识库。
+
+## 配置
+
+编辑 `~/.claude/settings.json`，添加到 `mcpServers`：
+
+```json
+{
+  "mcpServers": {
+    "eve": {
+      "command": "python",
+      "args": ["-m", "eve_mcp.server"],
+      "env": {
+        "EVE_EMAIL": "your-email@example.com",
+        "EVE_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
+如果使用 Poetry 安装：
+
+```json
+{
+  "mcpServers": {
+    "eve": {
+      "command": "poetry",
+      "args": ["run", "python", "-m", "eve_mcp.server"],
+      "env": {
+        "EVE_EMAIL": "your-email@example.com",
+        "EVE_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
+## 注册账号
+
+EVE 需要注册账号才能使用。访问 [eve-chat.chat](https://eve-chat.chat) 注册。
+
+## 在 Claude Code 中使用
+
+配置完成后重启 Claude Code，五個 MCP 工具自动可用：
+
+```
+用户: 帮我查一下 NDVI 的官方定义
+
+Claude (调用 query_eve): NDVI（归一化植被指数）...
+```
+
+## 注意事项
+
+- 需要 EVE 账号才能调用需要认证的工具（query_eve、list_eve_collections）
+- check_eve_health 不需要认证，可用于调试连接
+- 首次调用工具时会自动登录，token 在会话期间缓存
diff --git a/docs/tool-examples.md b/docs/tool-examples.md
new file mode 100644
index 0000000..fa50409
--- /dev/null
+++ b/docs/tool-examples.md
@@ -0,0 +1,91 @@
+# 工具调用示例
+
+五个 MCP 工具的使用场景和预期输出。
+
+## query_eve
+
+RAG 查询，检索地球科学文献后生成回答。
+
+**输入：**
+```
+question: "What is the NDVI formula and which bands are used?"
+collections: "eve-public"
+k: 5
+```
+
+**预期输出：**
+```
+NDVI (Normalized Difference Vegetation Index) is calculated as:
+NDVI = (NIR - Red) / (NIR + Red)
+
+It uses two spectral bands:
+- NIR (Near-Infrared): typically Sentinel-2 Band 8 (842 nm) or Landsat Band 5 (865 nm)
+- Red: typically Sentinel-2 Band 4 (665 nm) or Landsat Band 4 (660 nm)
+
+The resulting values range from -1 to +1, where values above 0.3 generally
+indicate healthy vegetation.
+```
+
+## list_eve_collections
+
+列出可用的公共知识库。
+
+**输入：** 无参数
+
+**预期输出：**
+```
+Available collections:
+- eve-public: General Earth Observation knowledge base
+- esa-satellite: ESA satellite mission documentation  
+- climate-reports: Climate and environmental reports
+```
+
+## check_eve_health
+
+健康检查，验证 API 连接。不需要认证。
+
+**输入：** 无参数
+
+**预期输出：**
+```
+EVE API is healthy. Status: OK.
+```
+
+## extract_factuality_issues
+
+分析 Google Earth Engine Python 脚本，提取其中隐含的科学假设。适合审查地学分析代码。
+
+**输入：** 一段 GEE Python 代码
+
+**预期输出：**
+```
+Issues found:
+1. Line 12: NDVI threshold of 0.3 assumes temperate vegetation — 
+   may not generalize to arid regions
+2. Line 25: Cloud masking uses QA60 band only — 
+   misses thin cirrus clouds detectable in QA10
+3. Line 38: Temporal aggregation over calendar year — 
+   growing season definition varies by hemisphere
+```
+
+## assess_factuality_issue
+
+对 extract_factuality_issues 发现的某个问题进行专家级评估。
+
+**输入：** 问题描述 + 上下文
+
+**预期输出：**
+```
+Assessment of Issue #1 (NDVI threshold = 0.3):
+
+The threshold of 0.3 is widely cited in literature for temperate forests
+(Tucker 1979, Myneni et al. 1997). However:
+
+- In semi-arid regions (e.g. Sahel), NDVI rarely exceeds 0.2 even for
+  healthy vegetation
+- In dense tropical forests, NDVI saturates above 0.7 and becomes
+  unreliable as a health indicator
+
+Recommendation: Use region-specific thresholds or switch to EVI
+(Enhanced Vegetation Index) which reduces saturation effects.
+```
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
new file mode 100644
index 0000000..699d50d
--- /dev/null
+++ b/docs/troubleshooting.md
@@ -0,0 +1,61 @@
+# 常见问题
+
+## 启动时报 "ModuleNotFoundError: No module named 'eve_api'"
+
+EVE-MCP 依赖 eve-api 子模块，需要单独拉取：
+
+```bash
+git submodule update --init --recursive
+```
+
+如果仍失败，手动安装：
+
+```bash
+cd lib/eve-api
+pip install -e .
+```
+
+## 首次调用工具时超时
+
+首次调用需要登录认证，可能耗时 5-10 秒。token 缓存后后续调用正常。
+
+如果持续超时，检查：
+1. 网络是否能访问 `api.eve-chat.chat`
+2. `EVE_EMAIL` / `EVE_PASSWORD` 环境变量是否正确
+
+## Poetry 安装慢或失败
+
+Poetry 锁定 Python 版本为 3.11–3.14。如果用系统 Python 版本不匹配：
+
+```bash
+# 检查 Python 版本
+python --version
+
+# 如版本不对，用 conda 创建匹配环境
+conda create -n eve python=3.12
+conda activate eve
+pip install poetry
+poetry install
+```
+
+## Claude Code 中工具不显示
+
+确认 settings.json 中 `mcpServers` 配置正确。查看 Claude Code 的 MCP 工具列表：
+
+- Claude Code: 检查 `/mcp` 命令是否列出了 `eve` 服务器
+- 如果未列出，重启 Claude Code 或检查 `command` 路径是否正确
+
+## 不用 Poetry 怎么装
+
+```bash
+git clone --recurse-submodules https://github.com/FrontierDevelopmentLab/eve-mcp.git
+cd eve-mcp
+pip install -e lib/eve-api
+pip install -e .
+```
+
+然后直接：
+
+```bash
+python -m eve_mcp.server
+```