Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

在 annotations 只提供 readOnlyHint/idempotentHint 等布尔提示的情况下，描述额外披露了需要登录、先过后审的异步风控、slug 全局唯一及 slug_taken 错误、description 影响内容质量。这些是调用方做决策和预期管理的重要行为信息，且与 idempotentHint=true 一致，无矛盾。

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

用三个短段落【需要登录】【发布】【提示】结构化呈现，第一句就点明核心用途，后续每句都携带独立信息，无冗余。

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

对于无 output schema 的创建类工具，描述覆盖了登录要求、幂等 upsert、唯一性错误、审核机制和后续动作，已经相当完整；唯一缺口是没有说明成功后的返回内容，但这个缺失不严重影响工具选择与调用。

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

schema 对 9 个参数覆盖 100%，已承担主要说明责任；描述额外补充了 slug 的全局唯一性与冲突错误，以及 description 越详细内容质量越高这一语义，提升了参数的理解价值。

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

明确说出“为当前用户创建一人公司主页”，动词+资源+归属都清楚；还补充“已存在则等价于更新”“每个用户最多一家”，把 create 工具的实际 upsert 行为讲明，能与其他 get/list 类公司工具区分开。

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

给出了明确使用场景：当前用户、最多一家、已存在则更新，并指示“建到了就可以在引导里 complete_onboarding”。虽然没有点名替换工具 update_my_company，但“已存在则等价于更新”已经隐含了覆盖更新场景的路由语义。

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.