更新文章

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

With no annotations provided, the description carries the full burden and handles it very well. It discloses that the underlying operation rewrites the whole record and merges omitted fields back, that published markdown is not updated by the API and only gets written to a draft copy, that the tool will state this in the return, and that omitted fields are preserved rather than cleared. These are exactly the non-obvious behaviors an agent needs to know before calling.

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?

The description is front-loaded with a strong one-sentence summary of the partial-update model, followed by the most important warning in bold. It is dense but every sentence adds behavioral or usage value. The implementation note about saveArticle rewriting the whole record is explanatory rather than redundant, though the paragraph is slightly long and could be broken into tighter points.

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?

For a mutation tool with no annotations and no output schema, the description covers the major risks: merge behavior, the live-markdown exception, mode defaults, and the empty-field trap. It also mentions that the return will explicitly state the published body outcome. It does not mention authentication/permission requirements or explicitly clarify what mode=draft does to a published article, which keeps it just short of complete.

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 description coverage is 0%, so the description must add meaning beyond field names and types. It does so by explaining the update contract across all parameters: only pass fields to change, omitted fields keep their original value, empty fields do not clear values, and mode has special default and publish-draft semantics. It does not provide per-field business meaning for title, tags, categories, cover_image, or description, but their names and schema constraints make them fairly self-explanatory.

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?

The description opens with '更新已有文章' (update existing article), naming a clear verb and resource, then immediately defines partial-update semantics: only changed fields need to be passed and unpassed fields retain their current values. It also calls out the surprising markdown behavior for published articles, which differentiates this tool from a simple 'edit article' sibling. The scope is unambiguous.

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?

The description gives explicit when-not guidance: do not pass empty fields to clear values, do not use this tool to correct live body content, and explicitly says omitting mode preserves current visibility while passing mode=publish publishes a draft. It does not name alternative sibling tools such as publish_article or get_article directly, but the behavioral instructions are specific enough for an agent to choose correctly in most cases.

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