update_article

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

With no annotations present, the description carries the full burden of behavioral disclosure, and it delivers substantial value: 'Set or replace' reveals overwrite semantics, and the extensive DayBy HTML rules (clean fragments, no wrapper divs, no CSS classes, target length 600-1000 words, preserve author voice) define exactly what the tool expects and enforces. It does not disclose what happens to the post's publication state, whether the operation is reversible, or what the response contains, but the input-format contract is unusually specific.

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 sentence is front-loaded, followed by a dense, scannable rule list where every line earns its place as an operational constraint (allowed tags, forbidden classes, length target, voice guidance). Nothing is redundant or filler, and the formatting rules are structured as a clear checklist rather than prose.

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?

The description is complete for input formatting but silent on the post lifecycle: it never says whether the slug must reference an existing post, whether the tool works on drafts or published posts, how it interacts with the draft→publish flow represented by siblings like draft_post, edit_draft, and publish_post, or what the tool returns (no output schema exists to compensate). An agent could invoke it correctly but wouldn't know the downstream effect or validation outcomes.

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 coverage is 100%: slug is described as 'The post slug to update' and html_article as 'The HTML article content.' At the baseline of 3 for high coverage, the description still adds meaningful depth by fully specifying the HTML contract for the html_article parameter, which the schema only references indirectly. The slug parameter gains nothing beyond the schema, keeping this at baseline rather than above.

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 action and resource: 'Set or replace the HTML article for a DayBy post.' This clearly identifies the tool's job and distinguishes it from lifecycle siblings like list_posts, get_post, and delete_post. However, it doesn't explicitly differentiate from the closely related update_post or edit_draft siblings, leaving some ambiguity about when the article-specific tool wins over the generic update tool.

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?

'Use this to write custom articles with CTAs, rich formatting, or any content the user wants' is an explicit when-to-use directive that gives the agent a concrete trigger condition. It provides clear context but stops short of stating exclusions or naming alternatives (e.g., 'use update_post for metadata changes' or 'use draft_post if no post exists yet').

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