BlackOps Center

Update Post

patch_posts_by_id

EDIT ONLY — modifies a post in-place. NEVER call for reading; use post_posts to create. Published edits go live immediately. Always pass base_updated_at (from get_post.updated_at); without it a concurrent edit is silently overwritten. Custom styled HTML needs a richembed fenced block; bare block HTML is escaped. Do NOT include the title in the content body. Response has links.review_url for drafts — give that link to the user.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "id": "<id>"
    },
    "name": "patch_posts_by_id"
  }
}

Input Schema

Name	Required	Description
`id`	Yes
`slug`	No
`tags`	No
`title`	No
`domain`	No
`status`	No
`content`	No
`site_id`	No
`featured`	No
`subtitle`	No
`seo_title`	No
`description`	No	The post's PUBLIC meta description shown in search results and link previews. Overwrites any stored value immediately. THIS IS NOT an edit-comment or reason-for-change field — omit this key entirely unless you explicitly intend to replace the current description.
`published_at`	No
`featured_image`	No
`base_updated_at`	No	ISO from preceding get_post.updated_at. Server returns 409 CONFLICT with current_updated_at + current_content if post was edited since read; re-read, merge, retry.
`seo_description`	No
`x_discussion_url`	No	X post permalink for the post's "Discuss on X" block. null removes it.
`hero_prompt_edited`	No	Custom prompt that will be used on the next hero image generation for this post.

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 8, 2026

TDQS

A4.4/5.0

Behavior4/5

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

With no annotations supplied, the description carries the load and does well: it discloses that published edits go live immediately, that omitting base_updated_at silently loses concurrent edits, that bare block HTML gets escaped, and that drafts return links.review_url. Gaps remain on undiscussed behavior — permissions/auth needs, whether omitting a field preserves or clears it (patch semantics), and reversibility of a published edit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense and front-loaded: the mode declaration comes first, then exclusions, then the behavioral gotchas in descending order of consequence. No sentence is filler, and each one carries a distinct constraint an agent would otherwise get wrong.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 18-parameter mutation tool with no annotations and no output schema, it covers the highest-risk behaviors (concurrency conflict, immediate publication, HTML escaping) and even documents the one important response field. It falls short of full completeness by never stating partial-update semantics for the remaining optional fields or the permission model.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 22% across 18 parameters, so more compensation was needed. The description adds real meaning for content (richembed fenced block), title (must not be repeated in body), and base_updated_at (conflict/retry semantics), but leaves slug, status, site_id, featured, subtitle, seo_title, published_at, featured_image, domain, and hero_prompt_edited entirely unexplained in both schema and prose.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with an explicit verb+resource+mode: 'EDIT ONLY — modifies a post in-place.' It proactively fences off the most likely confusion (reading) and names a sibling (post_posts) for the create case, so an agent can place it in the CRUD family without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-not ('NEVER call for reading'), an alternative for creation ('use post_posts'), and a hard precondition for correct use ('Always pass base_updated_at (from get_post.updated_at)'). It even names the source tool for the required value, which is exactly the routing an agent needs.

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

All BlackOps Center tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?