tool_write_blog

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

With no annotations, the description carries the full behavioral burden and largely does so: it discloses the front-matter fields written, that existing front-matter is merged with argument overrides, that empty summary is auto-extracted from the first paragraph, and that overwrite controls clobbering an existing draft. It does not discuss permissions or whether writes are reversible, but for a local draft write the disclosed behavior is substantial.

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 purpose is front-loaded in the first sentence, followed by behavioral rules, then a clean Args/Returns breakdown. Each sentence carries information an agent needs, and with no output schema present the Returns block is justified rather than redundant.

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 10-parameter tool with 0% schema description coverage, no annotations, and no output schema, the description covers purpose, every parameter, merge/auto-extraction behavior, and the return shape. Nothing an agent needs in order to invoke this correctly appears to be missing.

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 Args section is doing all the work, and it documents all 10 parameters with real meaning: topic as H1 and filename slug, content possibly carrying front-matter, tags 3-5 recommended, category examples, filename without .md, and overwrite semantics. It also supplies the visibility values ('public'/'private'/'fans') that the schema fails to enumerate.

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 first sentence states a specific verb and resource ('Package blog content into a CSDN-ready markdown file and save it'), and it distinguishes itself from the downstream publish_csdn tool by noting that publish_csdn reads the same file. An agent can tell exactly what this tool produces and where it sits in the pipeline.

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 places the tool clearly in a workflow ('The publish_csdn tool reads this same file later'), which tells the agent this is the pre-publish drafting step. It stops short of naming exclusions or contrasting with near-siblings like tool_generate_blog_scaffold or tool_read_draft, so it is clear context without explicit when-not guidance.

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