diff --git a/xiaoqu-franchisee/doc/agent-mcp-service-design.md b/xiaoqu-franchisee/doc/agent-mcp-service-design.md
index 64abada..730fbb8 100644
--- a/xiaoqu-franchisee/doc/agent-mcp-service-design.md
+++ b/xiaoqu-franchisee/doc/agent-mcp-service-design.md
@@ -246,4 +246,5 @@ xiaoqu-agent-service/
 - **一律用 git worktree 开发**：每个需求从 main 拉分支到 `../oldproject-worktrees/<feature>/`，在 worktree 里改代码、跑测试；验证通过后合并回 main 再推送远程。主检出（本目录）保持可随时部署的干净状态。
 - 合并回 main 后用 `xiaoqu-agent-service/deploy/deploy.sh restart` 完成构建+重启，接口实测通过再 `git push`。
 - 后台列表页统一服务端分页（page 从 1 开始，pageSize 默认 20、上限 100）；MCP 工具 `rows` 同样上限 100，超出截断并在 `notice` 字段提示。
+- **新增/修改 MCP 工具必须同步更新 `doc/agent-mcp-tools-reference.md`**（入参、出参、权限语义、示例），工具对外契约以该文档为准。
 
diff --git a/xiaoqu-franchisee/doc/agent-mcp-tools-reference.md b/xiaoqu-franchisee/doc/agent-mcp-tools-reference.md
new file mode 100644
index 0000000..3f42652
--- /dev/null
+++ b/xiaoqu-franchisee/doc/agent-mcp-tools-reference.md
@@ -0,0 +1,153 @@
+# xiaoqu-agent-service MCP 工具接口文档
+
+> 本文档是 MCP 服务**对外暴露工具**的接口契约。新增/修改工具时必须同步更新本文档（开发约定见 `agent-mcp-service-design.md` §12）。
+> 文档中的入参与代码 `@ToolParam`、出参与工具实际返回保持一致；在线验证方式见文末附录。
+
+## 0. 调用约定（所有工具共用）
+
+| 项 | 说明 |
+|---|---|
+| 端点 | `POST http://<host>:8088/mcp`（MCP Streamable HTTP） |
+| 认证 | Header `Authorization: Bearer xqak_xxx`，ak 在管理后台「用户与 Token」签发，服务端只存 SHA-256 |
+| 工具可见性 | 按 ak 绑定的作用域过滤，`tools/list` 只返回该 ak 可用的工具 |
+| 行级数据权限 | 跟 ak 所属人走，照搬老系统 `getByIsAgent` 语义（见设计文档 §3.3），与作用域无关 |
+| 分页 | 列表类工具统一 `page`（从 1 开始，默认 1）、`rows`（默认 20，**上限 100**，超出截断为 100 并在返回 `notice` 字段提示） |
+| 分页出参 | 统一含 `total`（总数）、`page`、`rows`、`records`（本页记录）、`notice`（仅截断时出现） |
+
+---
+
+## 1. agent.count
+
+统计代理商总数（demo 工具）。
+
+- 分类：system ｜ 类型：读
+- 数据来源：m0 库 `agent` 表，固定条件 `soft_delete = 0`
+
+**入参**：无
+
+**出参**：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| count | number | 代理商总数 |
+
+```json
+{ "count": 62 }
+```
+
+---
+
+## 2. agent.list.query
+
+查询代理商列表（分页），对应老系统 `/agent/listByPage`。
+
+- 分类：customer ｜ 类型：读
+- 数据来源：m0 库 `agent` 表
+- 行级权限：权限组 `isagent=1`（代理商身份）只查自己名下直属下级（`supervisor_id = 自己agentId`）；`isagent=0`（总部）看全部。传 `id` 精确查询时：代理商仅限自己或直属下级，总部可传任意合法 id，且其余过滤条件失效。
+
+**入参**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| id | number | 否 | 代理商 id，精确查询；传入后忽略其他过滤条件 |
+| name | string | 否 | 代理商名称，模糊匹配 |
+| level | number | 否 | 级别：0=总部 1=一级 2=二级 |
+| channelNo | string | 否 | 渠道编号：Z=总部 F=分公司 D=代理 |
+| province | string | 否 | 省份，精确匹配，如 `北京市` |
+| city | string | 否 | 城市，精确匹配，如 `北京市` |
+| serialnumber | string | 否 | 代理商编号，精确匹配 |
+| page | number | 否 | 页码，从 1 开始，默认 1 |
+| rows | number | 否 | 每页条数，默认 20，上限 100 |
+
+**出参 records 字段**：
+
+| 字段 | 说明 |
+|---|---|
+| id / name | 代理商 id / 名称 |
+| level / channelNo / serialnumber | 级别 / 渠道编号 / 代理商编号 |
+| supervisorName | 上级代理名称（无上级为 `-`，批量富化） |
+| province / city / countyseat | 省 / 市 / 区县 |
+| contact / phone | 联系人 / 电话 |
+| agencyarea / memo | 代理区域 / 备注 |
+| createTime | 创建时间，`yyyy-MM-dd HH:mm:ss` |
+
+```json
+{
+  "total": 62, "page": 1, "rows": 20,
+  "records": [ { "id": 19, "name": "北京D类代理", "level": 2, "channelNo": "D", "...": "..." } ]
+}
+```
+
+---
+
+## 3. property.list.query
+
+查询物业（客户）列表（分页），对应老系统 `/property/listByPage`。
+
+- 分类：customer ｜ 类型：读
+- 数据来源：m0 库 `properyt` 表
+- 行级权限（完整版 `getByIsAgent` 语义）：
+  - 总部（isagent=0）：全部；
+  - 代理商（isagent=1）：自己 + 直属下级代理 + `warehouse_agent_auth` 代管代理 名下物业，及 `agent_manage_district_auth` 授权代管的物业；
+  - 销售部门非负责人：自己创建的物业 ∪ 代管授权代理名下物业（`id IN (...)` 结构，与其余规则互斥，1:1 复刻老代码 saleFlag 分支）。
+  - **不含** enterprise_type=2 物业用户限自己物业的规则（物业用户不查此列表）。
+
+**入参**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| name | string | 否 | 物业名称，模糊匹配 |
+| agentId | number | 否 | 所属代理商 id，精确匹配 |
+| serialnumber | string | 否 | 物业编号，精确匹配 |
+| province | string | 否 | 省份，精确匹配 |
+| city | string | 否 | 城市，精确匹配 |
+| contact | string | 否 | 联系人，精确匹配 |
+| phone | string | 否 | 联系电话，精确匹配 |
+| page | number | 否 | 页码，从 1 开始，默认 1 |
+| rows | number | 否 | 每页条数，默认 20，上限 100 |
+
+**出参 records 字段**：
+
+| 字段 | 说明 |
+|---|---|
+| id / name / serialnumber | 物业 id / 名称 / 编号 |
+| agentName | 所属代理商名称（查不到为 `未查询到`） |
+| createName | 创建人/销售姓名（未分配为 `未分配`） |
+| province / city / countyseat / address | 省 / 市 / 区县 / 详细地址 |
+| contact / phone | 联系人 / 电话 |
+| createTime | 创建时间，`yyyy-MM-dd HH:mm:ss` |
+
+---
+
+## 4. sys.ping
+
+服务自检（demo 工具，证明链路连通）。
+
+- 分类：system ｜ 类型：读
+
+**入参**：无
+
+**出参**：
+
+| 字段 | 说明 |
+|---|---|
+| service | 服务名（spring.application.name） |
+| version | 服务版本 |
+| time | 服务器当前时间 |
+| redis | `PONG` 表示 Redis 连通；否则为 `ERROR: ...` |
+
+---
+
+## 附录：在线查看工具清单
+
+```bash
+AK=xqak_xxx; H=http://localhost:8088/mcp
+# 1) initialize，从响应头取 mcp-session-id
+# 2) 带 mcp-session-id 发 notifications/initialized
+# 3) 带 mcp-session-id 调用 tools/list
+curl -X POST $H -H "Authorization: Bearer $AK" -H "mcp-session-id: $SID" \
+  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
+  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
+```
+
+也可在管理后台「工具管理」页查看全量注册工具（不受作用域过滤）。