update_acf_fields

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

No annotations are provided, so the description carries the full burden. While 'DEPRECATED' signals that it should not be used, the description provides no behavioral details: whether it still functions, whether it will fail, whether it maps identically to the alias target, or what side effects occur on invocation. The agent cannot infer the operational behavior from this.

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?

A single terse sentence that fully conveys the essential information (deprecated, alias target). Zero waste, perfectly front-loaded with the DEPRECATED signal at the very start. Though minimal to the point of sparseness, this is high-value efficiency for a tool that should simply route elsewhere.

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 that this tool is a deprecated alias with an output schema present, the description is arguably adequate to route users away. The output schema covers return-value expectations. However, nothing documents the update semantics, partial-update behavior, or error conditions. For a tool flagged as deprecated, completeness relative to need is moderate — it fulfills the disambiguation role but lacks behavioral depth.

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 0% schema description coverage and 2 undocumented parameters (post_id as number, fields as free-form object), neither the schema nor description provides type-specific context. The field names themselves (post_id, fields) are suggestive but the description adds nothing beyond the schema. Baseline 3 is warranted since the parameter names are reasonably self-explanatory but no semantic refinement is provided.

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 'DEPRECATED alias for content.update_fields.v1' clearly states the tool's purpose: it updates fields, and specifically identifies it as a deprecated alias pointing to the canonical sibling content.update_fields.v1. This gives good verb+resource clarity and immediately differentiates it from siblings by instructing users to use the non-deprecated version instead.

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 explicitly directs users to the replacement tool (content.update_fields.v1), which serves as an exclusion/alternative guidance. However, it does not explicitly state 'do not use this' beyond the DEPRECATED marker, nor describe when one might still need it (if ever), leaving slight ambiguity about whether it remains functional.

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