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

Adds substantial behavior beyond annotations: login requirement, ownerId-based upsert, schema validation on optional fields, slug conflict error, and especially the publish flow ('先过后审：立即生效，后台异步风控审计'). This gives the agent real operational expectations.

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?

Two tightly structured paragraphs with no filler. The most important facts—login, upsert, pre-read, validation, error, and moderation—are all included in a compact, scannable format.

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?

Despite no output schema, the description covers the critical operational context: who it affects, how upsert behaves, what to do first, a known error, and the post-moderation publishing model. This is complete enough for an agent to safely invoke the tool.

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?

With 100% schema description coverage, the schema already documents parameters. The description adds useful extra meaning: all fields are optional but validation still applies, and slug conflicts surface as slug_taken. This goes slightly beyond the baseline.

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?

Description states a specific action ('更新当前用户名下的公司主页') with clear resource and owner scoping ('当前用户名下', '按 ownerId upsert'). It distinguishes itself from generic company tools by clarifying upsert semantics rather than just 'update'.

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?

Clearly instructs the agent to call get_my_company first to read current state, and documents the slug_taken error condition. It implies when-not-to-use by restricting to the current user's own company, but does not explicitly contrast with create_company as an alternative.

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