Update an article

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

The description discloses auth requirements ('Needs a secret key (wv_sk_) carrying the articles:write scope'), clarifies side effects ('Changes content on the customer's Site'), and states non-publishing behavior ('Nothing becomes public'). It adds nuance about null vs omission, which is beyond annotations. No contradiction with annotations (readOnly=false, openWorld=true, idempotent=true, destructive=false).

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?

Five short sentences, each carrying distinct information: operation, partial-update semantics, null handling, site impact, publishing separation, and auth. No redundant phrases; front-loaded with the tool's purpose.

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?

Given 18 parameters, the schema handles individual param documentation. The description covers the high-level contract: partial update, auth, non-publication, and site-side effects. It does not mention return value or error cases, but no output schema exists and these are not critical for an update 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 coverage, each parameter is already documented. The description adds a global rule: 'Send null to clear a nullable field; omit it to leave it alone,' which applies to all nullable fields and clarifies the schema's repetitive 'Send null to clear it.' This is meaningful added context that simplifies parameter understanding.

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 an article' (specific verb+resource), and clarifies 'partial update' to distinguish from full replacement. It also states 'Nothing becomes public: publishing is always a separate call,' which differentiates from sibling publish_article.

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?

It doesn't explicitly name alternatives, but the phrase 'publishing is always a separate call' tells the agent when not to use this tool (i.e., for publishing, use publish_article). The partial update semantics imply use for modifications rather than creation or deletion. It also specifies the required auth scope, giving a precondition.

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