企业官网建设流程全解析

最近一直在做 Agent 工具层的接入工作，有个观察特别想拿出来聊聊：Agent 判断"要不要用你的软件"，根本不是我们想象中那样——它不会去读你的官网、翻你的 README、看你的教程。它只会把你暴露出来的那一小段描述放进上下文里，扫一眼，然后就用上了，或者转头去找别的工具。

这段描述有多短？按我这些天实际数 token 的经验，大概就是 500 个 Token 上下。

对，就是 500 个 Token。不到一屏文字。你的软件在 Agent 眼里的"第一印象"，就花在这 500 个 Token 上。理解了这个事实，你开发软件、写接口、做集成的思路会整个换一遍。这篇文章不聊大道理，就讲清楚这 500 Token 是怎么来的、里面该放什么、不该放什么，以及我踩过的那些坑。

1. Agent 是怎么"认识"一款软件的

1.1 两种主流的接入姿势

今天的 Agent 生态里，软件被"看见"的方式基本只有两类。

一类是给大模型做 Function Calling 的时候，你把自己软件的接口声明成一个个"工具函数"塞进对话上下文。比如你做了一个天气查询服务，Agent 决定要不要调度它，靠的是你在 tools 数组里写的那个 JSON 结构：函数名、描述、参数表。另一类是走 MCP（Model Context Protocol）这类工具协议，Agent 通过服务端暴露出来的工具列表去发现能力，本质还是把工具的"自我介绍"交给模型去读。

两类方式底层逻辑一样：你的软件能不能被 Agent 用上，取决于你有没有一份能被模型高效解析的"工具说明书"。这个东西长什么样、写得好不好，直接决定了 Agent 的选择。

1.2 工具发现不是"搜索"，而是"扫描"

我们人用软件的习惯是打开网页、看介绍、点注册、试用。Agent 不是这个流程。Agent 面对的是几十个甚至上百个工具同时摆在面前，它要做的是在有限的上下文窗口里快速扫描，挑出语义上最匹配的那一个。

做过 Function Calling 的朋友应该知道，所有工具的描述是拼在一起塞给模型的。这意味着 Agent 并不是"找到了你的工具然后仔细研究"，而是"顺手扫过你的工具然后立刻打分"。它没有耐心，也不允许有耐心——每次调用都在烧 Token，多看一眼都是在花用户的钱。所以它必须用极少的注意力做出一个高置信度的判断。

这就能解释一个现象：为什么有些功能明明很棒的工具，Agent 从来不用。不是它不够好，而是它在扫描阶段就被淘汰了。

1.3 500 Token 这个数字是怎么冒出来的

我在做工具选型评测的时候，做过一次挺粗但是很直观的统计。让 Claude 和 GPT 系的模型各自在一组工具里做选型任务，同时把它们的思考轨迹（reasoning trace）打出来看。绝大多数情况下，模型真正"研读"某个工具的时间很短：读完工具名、扫一眼描述里的前两句话、确认参数够不够用、看有没有示例——判定就结束了。

把这些被模型实际"消费"的内容单独拎出来数 token：

• 工具名：几个 token；
• 描述的前两三句：三十到八十个 token；
• 参数列表里的关键项：一百到两百个 token；
• 一个两到三行的示例调用：一百个 token 左右。

加起来，正好是 400 到 600 的区间。你说巧不巧，不管你给这个工具写了一千字还是五千字的文档，模型真正用来做决策的那部分信息，永远只有这 500 个 Token 左右。不是你不想让它多看，是架构上它就只能用这么多。

2. 500 Token 的信息预算到底有多大

2.1 先感受一下容积

在主流 tokenizer 下，500 个 Token 大约相当于 300 到 400 个汉字，或者 350 个左右的英文单词。就是一段正常博文的开头段落那么长。你想想，要把"我是谁、我能干什么、怎么调用我、什么情况下别用我"压缩进这么点空间里，信息密度得有多高。

这个容积决定了你必须做取舍。功能列表写不下，就提炼核心场景；完整参数表写不下，就只留高频参数；长篇注意事项写不下，就用一个示例暗示边界。

2.2 一份函数描述的实际构成

我把我自己项目里一份比较理想的工具声明拆开给你看：

{ "name": "search_docs", "description": "在内部文档库中搜索相关内容，适合回答'如何使用XX功能'类问题。接收关键词返回匹配段落列表。", "parameters": { "type": "object", "properties": { "query": { "type": "string", "description": "搜索关键词，尽量用原文术语" }, "limit": { "type": "integer", "description": "返回条数，默认5", "default": 5 } }, "required": ["query"] } }

name 用了动作加名词的结构，一看就知道干什么；description 第一句直接说用途，第二句说适用场景，第三句说输入输出关系；参数只有两个，一个必填一个选填。全部加起来，大概 150 个 Token。

2.3 为什么是"500"而不是"5000"

很多人会疑惑：上下文窗口不是越来越大了吗？一百 K 都有，怎么会在意这五百还是一千？

问题在于工具列表是集体上场的。你有一百个工具，每个工具的描述如果写 2000 Token，那光工具定义就是二十万 Token，直接把窗口撑爆。即便窗口装得下，模型也不会雨露均沾——工具越多，平均到每个工具的注意力就越稀薄。我在评测里看到的真实情况是，当单个工具的描述超过一定长度，模型反而会忽略它的后半部分细节，只抓前面看得懂的。

所以"500"不是物理上限，而是注意力的经济规律。你的工具描述写得越短，被完整读完的概率越大；写得越长，越容易在注意力竞争中落败。

3. 决定"用与不用"的关键变量

3.1 描述质量直接改写选中率

我做了一组 A/B 测试，同一个天气查询工具，换两种描述让 Agent 在五个工具里选。

第一种："提供天气信息服务，包含全国城市天气查询，支持实时天气、未来预报、空气指数等功能，数据来源权威，接口稳定，支持多语言返回。"——很"官网"对不对？结果选中率惨不忍睹。

第二种："查询指定城市当前天气和未来3天预报。输入城市名，返回温度、天气现象、风力。下雨时 priority 字段为 high。"——选中率直接翻了一倍多。

为什么？模型做工具选择的依据是语义匹配度，不是产品力。它要找的是"能完成当前任务的那个函数"，不是"听起来很牛的那个服务"。第一种描述全是形容词，没有动词没有名词，模型没法把任务和工具之间的语义缺口补上。第二种描述每一句都在回应"我什么时候该用你"这个问题。

3.2 关键词过载与语义清晰度的平衡

有人会说，那我多堆点关键词，任务怎么描述都能命中我。实测下来这招很险。

堆关键词的副作用是稀释语义密度。描述里十个关键词，模型可能误解你的核心功能，把你当成一个"什么都能干但其实什么都没说清楚"的工具。更实际的问题是，你为堆词引入的那些措辞如果和实际参数不匹配，模型调用的时候就会产出不正确的入参，然后报错，然后重试，Token 全烧在返工上。

我的经验是：描述里用两到三个核心动词，加上适用场景的名词，就足够了。要克制。"支持、提供、高效、灵活、强大"这些词，一个都不要出现。

3.3 可信度信号比你想的更值钱

Agent 选工具不只看描述，还会看一些"信任信号"。我在无数次评测里观察到，以下三个信号对决策的影响非常大：

• 参数的完整性和默认值。一个有 default 的参数会让模型觉得这个工具是成熟的、为调用者想过的。一个参数表里全是 required 的工具，模型会本能地抗拒——出错风险太高。
• 枚举值和边界说明。描述里写清楚"只接受大写 ISO 代码"比在报错后才告诉模型要友好得多。模型会在调用前评估失败概率。
• 示例调用的存在。哪怕只有一行，也能让模型确认"我知道怎么和这个工具说话"。

说白了，Agent 也在做成本收益权衡。它选一个工具之前，心里是有"失败预期"的。你的配置让这个预期越低，它越愿意选你。

4. 把软件改造成"Agent 一眼就懂"的实操方法

4.1 函数描述改写清单

我给自己定了一个清单，每次给工具写 description 都过一遍：

• 第一句话用动词开头，说出核心动作。比如"搜索""发送""转换""查询"。
• 第二句话写输入和输出的对应关系。也就是"你给它什么，它还你什么"。
• 第三句话写典型使用场景。这能帮模型在模糊任务下做联想匹配。
• 最后一句写边界条件，什么时候不要用这个工具。
• 删掉所有形容词，删掉所有"平台""系统""服务""解决方案"这类无信息量名词。

拿一个真实例子演示。改写前：

"本接口提供基于多维度规则的用户标签计算服务，支持自定义条件组合，覆盖电商、内容、社交等主流业务场景，可通过可视化配置实现百亿级用户的分群计算，助力运营精细化。"

改写后：

"计算满足指定条件的用户数量并返回分群结果。输入条件表达式，输出用户数和示例ID列表。适合运营查询'过去30天未登录的付费用户'这类问题。注意：单次最多计算1000万用户，更大规模请分批。"

后者不到 100 个 Token，但模型拿到它就知道：什么时候用、给什么、拿到什么、有什么限制。

4.2 OpenAPI / MCP 配置的瘦身与信息前置

如果你的软件通过 OpenAPI 或 MCP 暴露，层级会更复杂。最大的坑是：模型会先读你的 server 描述或者 API 概览，再决定要不要深入去看具体 endpoint。所以"信息前置"原则比什么都重要。

我在配置 MCP server 的时候，会在 server description 里直接写上"本服务提供以下能力：A、B、C。要实现X，请调用tool_Y。"这样模型一眼就知道这里有没有它要的东西，然后精准跳转。

OpenAPI 那边同理：summary 字段不要只写"查询接口"这种废话；tags 要认真起名；description 的前 50 个字符要包含最关键的信息。很多自动生成工具产的文档，summary 全是"API""endpoint"这种词，模型看半天不知道这个接口是干嘛的，结果当然不会用。

4.3 最小可调用示例的写法

给 Agent 准备示例，和给人写文档示例完全是两回事。人的示例要覆盖复杂场景，Agent 的示例只需要一个最简单、最直线的调用路径。

我做工具的 function schema 时，会在 description 里嵌入一个 mini 示例，格式上不需要标准的 code block，因为那会占用大量 token。我会写成一行：

示例：query="退款流程", limit=3

就这么简单。模型看到这行就知道参数怎么填、返回大概长什么样，调用意图瞬间清晰。如果你非得放正式示例，那就把系统提示词里其他的冗余清干净，给示例腾空间。

4.4 让 Agent 做"选择测试"：一套可复现的评测方法

改完描述之后，怎么验证真的有效？别靠感觉，跑选择测试。

我自己常用的做法是搭一个很小的评测集：

1. 准备 10 到 20 个任务描述，覆盖你的工具最想被调用的场景、容易混淆的相似场景、以及不该调用你的边界场景。
2. 把目标工具和 3 到 5 个"干扰工具"放进同一个 tools 列表。
3. 循环跑 N 次，统计目标工具被选中的比例，以及误选率。
4. 改描述，再跑同样的评测集，对比数字。

评测的时候务必把温度调低，并且固定模型版本，否则测出来的差异可能是噪声。这个法子听起来不高级，但真能测出问题来。我有一次发现某个工具的描述怎么改选中率都上不去，最后排查出来是工具名起得有问题——一个叫fetch_data的名字，让模型完全猜不到它是干嘛的，描述怎么救都救不回来。

5. 踩坑与反直觉发现

5.1 真正的 Token 消耗不在决策，而在返工

很多人纠结决策阶段那几百个 token，其实决策阶段的消耗根本不值一提。真正烧钱的是调用失败之后的反复重试。一个参数 schema 写得含糊，Agent 传了个错误类型，接口 400，Agent 读错误信息，再猜，再传，再错——一次失败的调用链能烧掉几千个 token，是决策阶段的好几倍。

所以面向 Agent 的软件，参数校验的错误信息同样是一种"工具文档"。错误信息如果写"参数错误"，Agent 完全不知道怎么改；如果写"query 字段必须为字符串，当前收到的是数组"，Agent 当场就能修正。把错误信息当成给 Agent 的调试提示来写，返工成本能降一大截。

5.2 枚举、默认值和错误码到底要不要写进描述

我的经验是：高频错误场景值得写，低频细节不值得。

描述里应该包含的信息是"对选择决策有影响"的信息：典型场景、输入输出、边界限制。而参数层的细节应该放在 JSON schema 里的 description 字段，不要堆到函数主描述里。如果你发现函数主描述已经超过 200 个 token，大概率是塞了太多不该塞的东西。

错误码列表这种就更别放进 schema 了。模型不会因为你在描述里写了"403 代表权限不足"就更愿意用你，它会在真实报错时通过错误信息学会补救。你把有限的 token 预算花在错误码上，等于把"什么时候该用我"的说明挤掉了一半。

5.3 别把整个文档塞进上下文

还有一个我很想吐槽的倾向：有些团队的 MCP server 把工具描述当成 README 写，动辄一两千 token，还有的专门搞了个"工具说明文档工具"，让 Agent 先用它看完所有文档再决定调哪个方法。

实测效果都很差。不是说信息没用，而是 Agent 的决策机制决定了它不会线性地把这些文档读完再思考。它会在有限的注意力里抓关键词，然后产生错误的预判。文档越长，越容易抓错。我见过一个 case，某工具描述里写了支持 XX 格式，模型就真以为它会自动转换，结果传了错误格式，来回折腾好几轮。

记住：给 Agent 的信息是"够用就好"而不是"详尽就好"。多出来的部分不是冗余，是噪音。

6. 500 Token 背后的行业连锁反应

6.1 从"给人看的落地页"到"给 Agent 看的 manifest"

这个现象往深了想，其实是软件分发的规则变了。过去我们做营销是做 landing page，做 SEO，让人搜索到你、点进你的网站、被你吸引。现在 Agent 开始成为新的软件消费入口，它不看你的页面设计，只看你的机器可读描述。这相当于每个软件都要准备一份"给机器看的前 500 个 Token"，而且这份东西的质量直接决定你在 Agent 生态里的曝光率。

我有预感，接下来会出现一批专注"工具描述优化"的实践，就像当年有人专门做 SEO 一样。函数描述、API 摘要、MCP 配置、schema 设计，这些在传统软件开发里被当成"工程文档"的部分，会变成产品竞争力的一部分。

6.2 工具即产品，可被发现性成为核心能力

另一个变化是：工具本身开始变成产品，而不是产品的附属接口。如果一个 Agent 用你的工具用得顺手，它会反复调度；如果用不顺，它会当场转向竞争对手。Agent 不会给你第二次机会去"解释"你的软件。这意味着，你软件的"可用性"竞争从"用户愿不愿意学"变成了"模型能不能直接上手"。所有语义不清、参数复杂、边界模糊的设计，在 Agent 面前都会被迅速淘汰。

对小团队和独立开发者来说，这反而是个机会。大厂的软件功能全但接口臃肿，Agent 反倒更愿意选那些描述清爽、schema 简洁、调用一次就能成功的小工具。我在实际测试里多次看到这个规律：一个单功能小工具的描述清晰度足够高时，击败大而全的竞品是很容易的事。

6.3 给独立开发者和团队的落地建议

最后给几条可以直接执行的建议。这些是我自己做完整个工具层改造后总结出来的：

先做减法。把你软件暴露给 Agent 的所有工具列出来，看看是不是每个都有必要暴露。少一个工具，整个工具列表就瘦一圈，剩下工具的注意力就多一分。

再改描述。按上面那个清单过一遍，控制每个工具的描述在 150 token 以内，让工具名和首句就足够让 Agent 做出正确选择。

而后补错误信息。把接口的错误返回补全成"人话+修正指引"，让 Agent 一次失败后能自我修复。

最后做评测。搭一套最简单的选型评测，每次改动都跑一遍，用数据而不是感觉来优化。

你会发现，整个过程花不了多少时间，但你的软件在 Agent 视野里的存在感会完全不一样。

7. 最后一个经验：把这 500 Token 当成产品来做

说真的，我第一次意识到这个规律的时候是有点震惊的。我们花了那么多精力做 UI、做文档、做官网，最后在 Agent 世界里决定生死的，居然只是一段不到半屏文字的"自我介绍"。但换个角度想，这也是一种公平：Agent 不看虚的，只看你"能不能把一件事用最少的字说清楚"。

这其实和我们做人做事的道理是一样的。能在三句话内让别人明白你的价值，本身就代表你想清楚了。写工具描述的过程，逼着我重新审视了自己软件里那些冗余的接口、模糊的命名、不必要的复杂度——这些东西以前藏在文档深处没人看得见，现在全被这 500 Token 挖出来了。

如果你现在正在开发任何有可能被 Agent 调用的软件，我强烈建议你今天就做一件事：把你最核心的那个接口，用上面那个清单重写一遍描述，然后让一个 Agent 试试能不能在完全不看你其他文档的情况下正确调用它。如果它做到了，你的软件才算真正做好了迎接 Agent 时代的准备。如果没做到，恭喜你，你现在就知道该改哪里了。