为AI智能体设计可读文档：从Markdown规范到MCP协议集成-尧图网站建设

最近在尝试将公司内部的文档系统与AI智能体（AI Agents）进行集成，发现了一个普遍存在的痛点：我们为人类编写的文档，AI智能体往往“看不懂”或“用不好”。无论是API文档、配置说明还是操作指南，传统的文档格式在面向AI消费者时，常常因为结构模糊、意图不明或信息冗余而导致智能体调用失败或产生错误结果。本文将系统性地探讨如何为AI智能体设计文档（Docs for AI Agents），涵盖从核心概念、设计原则到具体的Markdown实践、llms.txt规范以及MCP（Model Context Protocol）协议集成，旨在提供一套可落地、可复现的完整方案。

无论你是希望让自家的API更易于被AI集成，还是正在构建基于大语言模型（LLM）的自动化工作流，理解并实践AI友好的文档设计，都将显著提升智能体的可靠性和效率。

1. 背景与核心概念：为什么AI需要专属文档？

在深入实践之前，我们首先要厘清一个根本问题：为AI设计文档和为人设计文档，究竟有何不同？

1.1 传统文档 vs. AI可读文档传统技术文档（如Readme、API Reference）的服务对象是开发者。其核心目标是传递知识、解释概念、指导操作。开发者具备理解上下文、处理模糊信息、进行逻辑推理的能力。例如，文档中一句“此参数可选，默认值为系统当前时间”，开发者能理解并正确应用。

然而，AI智能体（尤其是基于LLM的Agent）在“阅读”文档时，更像是一个严格遵守指令但缺乏背景常识的“高效执行者”。它严重依赖文档中清晰、结构化、无歧义的指令和信息。上述那句“默认值为系统当前时间”对AI来说就可能产生歧义：系统时间指服务器时间还是客户端时间？格式是Unix时间戳还是ISO 8601字符串？

因此，AI可读文档（AI-Friendly Docs）的核心设计原则是：最大化机器可解析性，最小化模糊性和二义性。它要求信息极度结构化、意图明确、格式规范。

1.2 核心应用场景为AI设计文档并非纸上谈兵，它在以下场景中至关重要：

AI Agent工具调用（Function Calling）：让AI能够准确理解如何调用你的API、CLI命令或内部函数，包括参数格式、返回值、错误处理。
检索增强生成（RAG）：构建高质量的知识库，让AI能精准检索到相关文档片段来回答问题或生成内容。
自动化工作流编排：在如LangChain、AutoGen、Dify等框架中，清晰的文档能帮助AI自主规划任务步骤。
智能代码助手：为Cursor、Copilot等工具提供项目上下文，使其能更好地理解代码库并进行智能补全或重构。

1.3 关键支撑技术与概念在实践过程中，我们会频繁接触到几个关键概念：

Markdown：轻量级标记语言，是编写结构化文档的基础。我们需要约定一套更严格的Markdown使用规范。
llms.txt：一个新兴的、用于向LLM描述项目上下文的文件规范（类似于robots.txt），旨在标准化项目信息的提供方式。
MCP（Model Context Protocol）：由Anthropic等公司推动的开放协议，用于标准化AI应用与各种数据源、工具之间的连接方式。设计良好的文档是构建MCP Server（提供上下文或工具）的基础。

理解了“为什么”和“是什么”，接下来我们进入实战环节，看看如何具体落地。

2. 环境与理念准备

在开始编写第一行文档之前，我们需要确立正确的设计理念，并准备好相应的工具环境。这并非关于某个具体的SDK版本，而是一套方法论和工具链。

2.1 核心设计理念

结构化优先：信息必须拥有清晰的层级和归属。使用标题、列表、表格、代码块等元素强制结构化。
意图明确：每个章节、每段话、每个参数描述都应直接阐明其目的。避免含蓄、比喻或需要推理的表达。
实例驱动：对于任何接口、配置或操作，必须提供最少一个完整、可运行的正面示例，以及常见的错误示例。
上下文完整：避免使用“如上所述”、“前者后者”等需要回溯的指代。确保每个部分尽可能自包含。
版本与变更透明：清晰标注文档适用的版本，并对重大变更提供显眼的说明。

2.2 工具链准备工欲善其事，必先利其器。以下工具能极大提升AI文档的编写和维护效率：

编辑器：Visual Studio Code。推荐安装以下插件：
- Markdown All in One：提供强大的Markdown编写支持（快捷键、目录等）。
- markdownlint：强制执行Markdown风格规则，保证格式一致性。
- Prettier：代码格式化工具，可配置用于格式化Markdown。
校验工具：
- markdownlint-cli：在CI/CD流水线中自动检查Markdown文件规范。
- 自定义脚本：用于验证代码示例的语法或简单运行。
文档生成器（可选）：如果你从代码注释生成API文档（如Swagger/OpenAPI、JSDoc、Sphinx），确保生成器的模板输出符合AI可读原则。

理念和工具就绪后，我们从最基础的文档格式——Markdown开始，学习如何将其强化为AI友好的格式。

3. AI友好的Markdown强化实践

Markdown是起点，但普通的Markdown远不够。我们需要一套强化规范。

3.1 标题层级的严格使用标题是文档最重要的结构骨架。AI（以及RAG系统）常利用标题来理解文档脉络和检索片段。

# 项目名称或主标题（通常用于`llms.txt`或README） ## 1. 概述 ### 1.1 设计目标 ### 1.2 核心概念 ## 2. 快速开始 ### 2.1 前提条件 ### 2.2 安装步骤 #### 2.2.1 使用npm安装 #### 2.2.2 使用源码构建 ## 3. API参考 ### 3.1 `UserService` 类 #### 方法：`getUser(id: string): Promise<User>`

规范：

从#（H1）开始，按顺序使用##（H2）、###（H3）、####（H4）。不要跳级。
H1通常只出现一次。在llms.txt中，H1可用于描述项目整体。
标题应使用名词或动宾短语，清晰概括其下内容，例如“## 3. 错误代码说明”优于“## 问题”。

3.2 列表与表格的规范化

有序列表：用于描述有严格顺序的步骤。

1. 克隆仓库：`git clone <repo-url>` 2. 安装依赖：`npm install` 3. 配置环境变量：复制 `.env.example` 到 `.env` 并填写。 4. 启动服务：`npm start`

无序列表：用于描述并列的特性、选项或要点。

表格：用于展示参数、返回值、枚举值等结构化数据。务必包含表头。

| 参数名 | 类型 | 必填 | 默认值 | 描述 | | :--- | :--- | :--- | :--- | :--- | | `userId` | `string` | 是 | 无 | 用户的唯一标识符，格式为UUID v4。 | | `includeProfile` | `boolean` | 否 | `false` | 为`true`时，响应中将包含`userProfile`字段。 | | `timeout` | `number` | 否 | `5000` | 请求超时时间，单位：毫秒。必须大于0。 |

3.3 代码块的精确标注代码块是AI学习如何调用接口的直接教材。

以下示例展示了如何调用 `createPost` 接口： ```javascript // 文件名：example_create.js const apiClient = require('./client'); async function createSamplePost() { try { const response = await apiClient.createPost({ title: 'Hello AI Docs', // 字符串类型，文章标题 content: 'This is a sample content.', // 字符串类型，文章正文 tags: ['ai', 'docs'], // 字符串数组，可选的文章标签 isPublished: false // 布尔值，是否立即发布 }); console.log('创建成功，文章ID:', response.data.id); // 响应中包含生成的ID } catch (error) { console.error('创建失败:', error.message); // 明确捕获并打印错误信息 } } createSamplePost();

**规范**： * **必须指定语言**（如`javascript`， `python`， `bash`， `json`），这有助于AI进行语法理解。 * **提供上下文**：在代码块前后用文字说明该示例的目的、前置条件和预期输出。 * **注释是关键**：在代码内部，使用注释解释关键参数、返回值和处理逻辑。这是给AI的“行内文档”。 * **展示错误处理**：包含`try-catch`或错误判断逻辑，教导AI如何应对异常。 **3.4 链接与图片的替代文本** * **链接**：避免使用“点击这里”这样的模糊文本。应描述链接目标。 * **不佳**：有关配置详情，请[点击这里](config.md)。 * **推荐**：详细配置选项请参阅[配置文件说明](config.md)。 * **图片**：AI无法理解图片内容，因此`alt`文本（替代文本）至关重要，应准确描述图片中的信息。 ```markdown ![系统架构图：用户请求通过API网关进入，分发到认证、业务逻辑和数据存储三个微服务](architecture.png) ``` 掌握了强化版Markdown，我们就可以创建一个专门面向AI的项目入口文件——`llms.txt`。 ## 4. 创建标准的 `llms.txt` 文件 `llms.txt`是一个构想中的规范，旨在为LLM提供一个标准化的项目入口点。你可以将其视为面向AI的“超级README”。 **4.1 `llms.txt` 的核心目标** * **项目自述**：用最精炼的语言告诉AI这个项目是什么、能做什么。 * **关键路径指引**：明确指出最重要的文件（如入口文件、核心配置、主要API文档）的位置。 * **环境与依赖说明**：清晰列出运行所需的环境、工具和依赖。 * **快速启动指南**：提供一个绝对可行的、最小的启动范例。 **4.2 `llms.txt` 内容示例** 假设我们有一个名为“AI文档助手”的Node.js项目。 ```markdown # AI文档助手 (AI Doc Assistant) ## 项目概述 这是一个用于自动检查和优化项目文档AI可读性的Node.js工具。它能分析Markdown文件的结构、代码块和术语清晰度，并给出改进建议。 **核心能力**： 1. 扫描指定目录下的Markdown文件。 2. 检查标题层级结构是否合理。 3. 验证代码块是否包含语言标签和必要注释。 4. 检测模糊术语并提供改写建议。 5. 生成符合`llms.txt`规范的初始文件。 ## 关键文件索引 * **项目入口**：`src/index.js` * **核心逻辑**：`src/core/analyzer.js` * **主配置文件**：`config/default.json` * **完整API文档**：`docs/api-reference.md` * **使用示例**：`examples/basic-usage.js` ## 环境要求 * **Node.js**: 版本 >= 18.0.0 * **包管理器**: npm 或 yarn * **操作系统**: Linux, macOS, Windows (WSL2推荐) ## 快速开始 请严格按照以下步骤操作，即可启动本工具： 1. **克隆项目**： ```bash git clone https://github.com/your-org/ai-doc-assistant.git cd ai-doc-assistant ``` 2. **安装依赖**： ```bash npm install ``` 3. **基础配置**： ```bash # 复制配置文件模板 cp config/default.json.example config/default.json # 请根据注释编辑 config/default.json 中的必要选项 ``` 4. **运行示例**： ```bash # 分析当前目录下的所有Markdown文件 node examples/basic-usage.js ./ ``` 如果成功，你将看到终端输出分析报告。 ## 如何获取帮助 * 查看详细教程：`docs/tutorial.md` * 查阅API所有选项：`docs/api-reference.md` * 报告问题：请在GitHub仓库提交Issue。

这个llms.txt文件为AI提供了一个结构化的“地图”，使其能快速理解项目脉络并找到关键信息。接下来，我们将视角提升到协议层，看看如何通过MCP让AI更深度地“使用”而不仅仅是“阅读”你的文档和工具。

5. 集成MCP（Model Context Protocol）：从文档到工具

MCP协议的核心思想是让AI应用能够通过标准化的方式“连接”到任何数据源或工具。为AI设计好的文档，是构建一个易于理解的MCP Server的基础。

5.1 MCP Server与AI文档的关系你可以将你的文档系统、API接口甚至数据库，通过一个MCP Server暴露给AI。AI通过MCP协议查询（Read）你的文档作为上下文，或调用（Call）你声明的工具函数。因此，MCP Server的“工具描述”（Tool Definition）本身就是一份需要精心设计的、机器可读的“API文档”。

5.2 设计MCP Server的工具描述以下是一个示例，展示如何将一个“查询用户信息”的API，通过MCP Server暴露为一个AI可调用的工具。重点在于description和parameters的编写。

# 文件：mcp_server_user_tools.py from mcp.server import Server, Tool from pydantic import BaseModel, Field import httpx # 定义输入参数的模型，这本身就是一种强类型文档 class GetUserInput(BaseModel): user_id: str = Field( ..., description="用户的唯一标识符。必须是有效的UUID v4格式字符串。", examples=["123e4567-e89b-12d3-a456-426614174000"] ) include_profile: bool = Field( default=False, description="是否在返回结果中包含用户的详细资料信息。设置为`true`将增加响应数据量。", examples=[True, False] ) # 创建MCP Server app = Server("user-api-server") # 声明工具 @app.tool( name="get_user_by_id", description="根据用户ID获取用户的基本信息。此工具调用内部用户服务API，需要网络连接。", input_model=GetUserInput ) async def get_user_tool(input: GetUserInput) -> str: """ 工具的具体实现。 注意：此处的docstring也会被AI看到，应保持清晰。 """ # 构建API请求参数 params = {"includeProfile": input.include_profile} async with httpx.AsyncClient() as client: try: # 调用真实的内部API resp = await client.get( f"https://internal-api.example.com/users/{input.user_id}", params=params, timeout=10.0 ) resp.raise_for_status() return resp.text # 返回JSON字符串 except httpx.HTTPStatusError as e: # 明确的错误处理和信息返回 return f"API请求失败，状态码：{e.response.status_code}， 错误信息：{e.response.text}" except Exception as e: return f"请求发生未知错误：{str(e)}" # 另一个工具示例：搜索文档 @app.tool( name="search_project_docs", description="在全项目文档中搜索包含特定关键词的章节。返回匹配的章节标题和片段。", ) async def search_docs_tool(keyword: str) -> str: """ 模拟一个简单的文档搜索功能。 """ # 这里可以接入真实的文档检索逻辑（如RAG） simulated_results = [ {"title": "安装指南", "snippet": f"在安装过程中，请确保你的系统满足以下**{keyword}**要求..."}, {"title": "API配置", "snippet": f"核心配置项`api_key`用于处理`{keyword}`相关的请求..."}, ] import json return json.dumps({"keyword": keyword, "results": simulated_results}, ensure_ascii=False)

关键设计点：

工具名（name）：使用动词+名词的清晰结构，如get_user_by_id。
描述（description）：第一句话概括工具功能。第二句话说明重要前提、副作用或限制（如“需要网络连接”）。
参数（通过input_model定义）：
- 每个参数必须有清晰的description。
- 使用Field(..., examples=[...])提供示例值，这是AI理解参数格式的绝佳途径。
- 使用default值标明可选参数。
错误处理：在工具实现中，必须捕获异常并以清晰的结构化格式（如JSON字符串）返回错误原因，帮助AI理解失败情况。

当AI连接到这个MCP Server后，它能直接看到get_user_by_id和search_project_docs这两个工具的描述和参数格式，并能够自主、正确地调用它们。这比让AI去阅读理解一篇传统的API文档并自行构造HTTP请求要可靠得多。

6. 完整实战案例：构建一个AI可读的天气查询服务文档

让我们综合运用以上所有知识，为一个简单的天气查询CLI工具编写一套完整的AI友好文档。这个工具可以通过城市名查询天气。

6.1 项目结构与llms.txt首先，创建项目根目录下的llms.txt。

# 天气查询CLI工具 (Weather Query CLI) ## 项目概述 这是一个命令行工具，通过调用公开的天气API，查询指定城市的当前天气信息。输出格式为JSON或易读的表格。 **主要功能**： 1. 查询指定城市的实时天气。 2. 支持JSON原始输出和美化表格输出。 3. 可配置温度单位（摄氏度/华氏度）。 ## 关键文件 * **主程序入口**：`src/cli.js` * **核心天气获取逻辑**：`src/weatherService.js` * **配置文件**：`config.js` * **完整使用文档**：`docs/usage.md` ## 环境要求 * **Node.js**: 版本 >= 16.0.0 * **依赖包**: `axios`, `commander`, `chalk` ## 快速开始 1. **安装**： ```bash npm install -g weather-query-cli ``` 2. **获取API密钥（必需）**： * 访问 [WeatherAPI.com](https://www.weatherapi.com) 注册并获取免费API密钥。 * 设置环境变量：`export WEATHER_API_KEY='your_api_key_here'` (Linux/macOS) 或 `set WEATHER_API_KEY=your_api_key_here` (Windows)。 3. **基本查询**： ```bash weather-query --city "Beijing" ```

6.2 核心API文档 (docs/api-reference.md)接下来，编写详细的、AI友好的API文档。

# 天气查询服务 API 参考 ## 模块：`weatherService` 位于 `src/weatherService.js`。提供核心的天气数据获取功能。 ### 函数：`getCurrentWeather(cityName, options)` 获取指定城市的当前天气。 **参数**： | 参数名 | 类型 | 必填 | 默认值 | 描述 | | :--- | :--- | :--- | :--- | :--- | | `cityName` | `string` | 是 | 无 | 城市名称，支持英文名或拼音。例如：`"London"`, `"Beijing"`。不支持模糊查询。 | | `options` | `object` | 否 | `{}` | 配置选项。 | | `options.unit` | `string` | 否 | `'c'` | 温度单位。可选值：`'c'`（摄氏度）， `'f'`（华氏度）。 | | `options.lang` | `string` | 否 | `'en'` | 返回数据的语言代码。例如：`'en'`（英语）， `'zh'`（中文）。 | **返回值**： * 类型：`Promise<object>` * 成功时，返回包含天气数据的对象。 * 失败时，抛出 `Error` 对象，其 `message` 属性包含错误原因。 **成功响应数据结构示例**： ```json { "location": { "name": "Beijing", "country": "China" }, "current": { "temp_c": 22.0, "temp_f": 71.6, "condition": { "text": "Sunny", "icon": "//cdn.weatherapi.com/weather/64x64/day/113.png" }, "wind_kph": 15.0, "humidity": 45 } }

错误处理：函数可能抛出以下类型的错误：

InvalidCityError: 城市名称无效或未找到。
ApiKeyError: API密钥未设置或无效。
NetworkError: 网络请求失败。

代码调用示例：

// 文件：example_usage.js const weatherService = require('./src/weatherService'); async function main() { try { const weather = await weatherService.getCurrentWeather('Shanghai', { unit: 'c', lang: 'zh' }); console.log(`上海当前温度：${weather.current.temp_c}°C`); console.log(`天气状况：${weather.current.condition.text}`); } catch (error) { // 根据错误类型进行不同处理 if (error.name === 'InvalidCityError') { console.error('错误：城市名称有误，请检查拼写。'); } else if (error.name === 'ApiKeyError') { console.error('错误：API密钥配置不正确。请设置WEATHER_API_KEY环境变量。'); } else { console.error('查询失败：', error.message); } process.exit(1); // 非零退出码表示失败 } } main();

**6.3 为MCP Server包装工具** 最后，我们创建一个MCP Server，将天气查询功能暴露给AI。 ```python # 文件：mcp_weather_server.py from mcp.server import Server, Tool from pydantic import BaseModel, Field import os import httpx import json class WeatherQueryInput(BaseModel): city_name: str = Field( ..., description="要查询天气的城市名称。必须使用明确的英文名或拼音，例如：'London', 'Beijing'。", examples=["New York", "Tokyo"] ) unit: str = Field( default="c", description="温度单位。'c' 表示摄氏度，'f' 表示华氏度。", examples=["c", "f"] ) app = Server("weather-service-mcp") @app.tool( name="query_current_weather", description="查询指定城市的实时天气信息。需要有效的WeatherAPI.com的API密钥，通过环境变量`WEATHER_API_KEY`设置。", input_model=WeatherQueryInput ) async def query_weather_tool(input: WeatherQueryInput) -> str: """ 调用外部天气API获取数据。 """ api_key = os.getenv("WEATHER_API_KEY") if not api_key: return json.dumps({"error": "API密钥未配置。请设置WEATHER_API_KEY环境变量。"}, ensure_ascii=False) url = "http://api.weatherapi.com/v1/current.json" params = { "key": api_key, "q": input.city_name, "lang": "en" # 固定为英文，简化示例 } async with httpx.AsyncClient() as client: try: resp = await client.get(url, params=params, timeout=10.0) resp.raise_for_status() data = resp.json() # 处理并简化返回数据，便于AI理解 result = { "location": f"{data['location']['name']}, {data['location']['country']}", "temperature_c": data['current']['temp_c'], "temperature_f": data['current']['temp_f'], "condition": data['current']['condition']['text'], "wind_kph": data['current']['wind_kph'], "humidity": data['current']['humidity'] } # 根据选择的单位调整输出 if input.unit == 'c': output = f"{result['location']}: {result['temperature_c']}°C, {result['condition']}, Wind: {result['wind_kph']} kph, Humidity: {result['humidity']}%" else: output = f"{result['location']}: {result['temperature_f']}°F, {result['condition']}, Wind: {result['wind_kph']} kph, Humidity: {result['humidity']}%" return output except httpx.HTTPStatusError as e: if e.response.status_code == 400: return json.dumps({"error": "请求参数无效，可能是城市名称错误。"}, ensure_ascii=False) elif e.response.status_code == 403: return json.dumps({"error": "API密钥无效或已过期。"}, ensure_ascii=False) else: return json.dumps({"error": f"API请求失败，状态码：{e.response.status_code}"}, ensure_ascii=False) except Exception as e: return json.dumps({"error": f"请求发生未知错误：{str(e)}"}, ensure_ascii=False) # 运行服务器（示例） if __name__ == "__main__": import uvicorn uvicorn.run(app, host="0.0.0.0", port=8000)

通过这个实战案例，我们展示了从项目入口（llms.txt）、详细API文档到MCP Server工具的完整链路。AI可以阅读llms.txt了解项目，查阅api-reference.md理解细节，并通过MCP Server直接调用query_current_weather工具，无需自行解析文档和构造请求。

7. 常见问题与排查思路

在实际设计和应用过程中，你可能会遇到以下典型问题。

问题现象	可能原因	排查与解决思路
AI智能体调用工具时参数格式错误	1. 工具描述中参数类型不清晰。 2. 未提供参数示例。 3. 参数约束（如枚举值）未说明。	1. 检查MCP工具定义的`input_model`，确保使用`pydantic`等库明确定义类型（`str`,`int`,`bool`,`List[str]`等）。 2. 为每个参数添加`examples`。 3. 使用`Field`的`regex`或自定义验证器描述复杂约束。
RAG系统检索文档片段不准确	1. 文档标题结构混乱，导致分块（chunking）错误。 2. 关键信息埋没在长段落中。 3. 缺少术语定义。	1. 使用`markdownlint`检查标题层级是否规范。 2. 将重要信息（如参数表、代码示例）放在独立的小节或使用列表、表格突出显示。 3. 在文档开头或独立章节建立“术语表”。
AI无法理解文档中的“默认行为”或“隐式规则”	文档依赖人类的常识或上下文。	显式化所有规则。例如，将“默认超时为5秒”改为“`timeout`参数：类型`number`，单位毫秒，默认值为`5000`。当设置为`0`或负数时，系统将抛出`InvalidArgumentError`。”
代码示例无法运行	1. 示例代码片段不完整。 2. 缺少必要的导入或依赖说明。 3. 环境变量或配置未说明。	1. 提供完整的、可独立运行的小文件示例。 2. 在示例文件开头注释中列出所有依赖。 3. 清晰说明运行示例前需要设置的配置项或环境变量。
MCP Server工具被调用但返回意外结果	1. 工具内部逻辑错误。 2. 错误信息格式不友好，AI无法解析。 3. 网络或依赖服务异常。	1. 为工具函数编写单元测试。 2. 确保错误返回也是结构化的（如JSON），包含`error`或`message`字段。 3. 在工具描述中注明外部依赖和可能的失败模式。

8. 最佳实践与工程建议

将AI文档设计融入开发流程，需要从团队协作和工程化角度考虑。

8.1 文档即代码（Docs as Code）

版本控制：将llms.txt、Markdown文档与源代码一同纳入Git管理。
代码审查：将文档变更纳入Pull Request审查范围，检查其AI可读性。
持续集成：在CI流水线中集成markdownlint和自定义脚本，自动检查文档规范（如标题层级、代码块语言标签、死链等）。

8.2 设计统一的参数描述模板为团队创建参数描述的模板，确保一致性：

`<参数名>` (`<类型>`， <必填/可选>， 默认值：`<默认值>`): <功能描述>。约束条件：<约束>。示例：`<示例值>`。

例如：

`pageSize` (`number`， 可选， 默认值：`20`): 指定每页返回的数据条数。约束条件：必须为大于0且小于等于100的整数。示例：`50`。

8.3 为MCP工具编写“契约测试”MCP工具的描述（名称、参数、返回类型）就是一份契约。可以为此编写简单的契约测试，确保描述与实际实现一致。

# 伪代码示例：契约测试思路 def test_tool_contract(): tool = get_tool_definition("query_current_weather") # 获取工具定义 assert tool.name == "query_current_weather" assert "city_name" in tool.input_schema["properties"] assert tool.input_schema["properties"]["city_name"]["type"] == "string" # 调用工具实现，验证输入输出是否符合schema ...

8.4 维护一个“AI视角”的检查清单在发布文档或MCP Server前，用以下清单进行自查：

[ ]清晰性：是否避免了“通常”、“可能”、“应该”等模糊词汇？
[ ]结构：标题层级是否清晰？是否使用了列表和表格组织复杂信息？
[ ]示例：每个主要功能/接口是否都提供了至少一个正确示例和一个常见错误示例？
[ ]完整性：所有输入参数、输出字段、错误码是否都有定义？
[ ]可执行性：提供的代码示例能否在指定环境中复制粘贴后运行？
[ ]无歧义：所有术语、缩写是否都有解释？是否存在指代不明（“这个”、“那个”）？
[ ]MCP工具描述：工具描述是否一句话概括功能？参数是否有类型、描述、示例和默认值？

为AI智能体设计文档，本质上是在进行一场“精确的沟通”。它要求我们从机器的思维出发，追求极致的清晰、结构和无歧义。通过遵循强化Markdown规范、编写标准的llms.txt、以及精心设计MCP Server的工具接口，我们可以大幅降低AI集成与使用的认知负荷和错误率。

资讯详情

为AI智能体设计可读文档：从Markdown规范到MCP协议集成