BlackOps Center

Generate Hero Image

post_posts_by_id_hero

Generate (or regenerate) a blog post's hero image, or its OG social card — works the same before and after the post exists. Returns the image inline plus its public URL. The fields below cover prompts, references, style, and the commit:false review flow. Rules that span fields: only the title and subtitle may ever appear on an OG card, because given anything else the generator invents its own tagline; an OG card takes NO references unless you name them, since auto-matching used to put a real face on social cards nobody asked to be in; for target:"og" prompt is the VISUAL DIRECTION and still gets OG framing; to anchor a face, mark the photo as a "headshot" via mark_reference_image first.

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": "post_posts_by_id_hero"
  }
}

Input Schema

Name	Required	Description
`id`	Yes	Post UUID
`style`	No	Visual style. Defaults to "modern".
`commit`	No	Default true: apply the image to the post immediately. False generates a review CANDIDATE (kind hero-candidate) and leaves the post untouched.
`domain`	No
`prompt`	No	Image prompt, auto-generated from the post if omitted. For target:"og", layered on the site share_card_style.
`target`	No	"hero" (default) sets featured_image; "og" makes the 1200x630 Open Graph card and sets og_image, leaving the hero untouched.
`site_id`	No
`alt_text`	No	ACCEPT mode: override the auto-generated alt text on the accepted asset. Applies to accept_asset_id; ignored on accept_image_url.
`subtitle`	No	OG only. Secondary line rendered verbatim beneath the title. Defaults to the post's own subtitle; nothing appears unless passed or stored.
`caller_name`	No	Optional self-reported label for who/what is generating (e.g. an agent name). Shows up in get_hero_history as caller_name — a label you provide, not a verified identity. Omit to default to your account id.
`accept_asset_id`	No	ACCEPT mode, no generation: promote a candidate and attach it. Sets og_image for an OG candidate (og-candidate kind), or featured_image + hero_asset_id for a hero candidate. The field_set key in the response says which field was written.
`accept_image_url`	No	ACCEPT fallback when only the URL is known — sets featured_image (or og_image when target: "og" is also passed) without asset promotion.
`include_subtitle`	No	OG only. Default true. False renders a title-only card even when the post has a subtitle.
`iteration_prompt`	No	Edit instruction for iterating on a previous hero (e.g. "make the background darker"). Requires source_image_url, which anchors composition.
`latest_candidate`	No	READ mode, no generation: returns the newest un-accepted hero candidate for the post.
`source_image_url`	No	URL of the hero to iterate on (a prior result's image_url). Used with iteration_prompt.
`include_title_text`	No	OG only. Default true: render the title as text on the card. False produces a purely visual card.
`reference_image_ids`	No	Curated reference IDs and/or media-library asset IDs (upload_media / list_media). Omitted: reuses the first hero's references, else auto-matches from the prompt. [] uses none.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 8, 2026

changedInput schema / properties / prompt / description

Previous value: -"Custom image generation prompt. If omitted, a prompt is auto-generated from the post title and content."New value: +"Image prompt, auto-generated from the post if omitted. For target:\"og\", layered on the site share_card_style."

First observedNov 8, 2026

TDQS

A4/5.0

Behavior4/5

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

With no annotations, the description carries the full burden and does meaningful work: it discloses the inline-plus-URL return, that commit:false leaves the post untouched and produces a candidate, and several non-obvious OG constraints (only title/subtitle may appear, no auto-matched references, prompt is treated as visual direction). Unaddressed are the accept/read modes' behavior, cost, and permission requirements.

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

Conciseness4/5

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

Purpose is front-loaded in the first clause and the remaining note is framed explicitly as cross-field rules, so structure is sound. Sentences are long and dense, and the return-value statement is somewhat buried mid-sentence rather than separated.

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, multi-mode tool with no output schema, the description covers the generation path and its edge cases well and even summarizes the return. The accept and read modes (accept_asset_id, latest_candidate) are only handled by the schema, which leaves the mode-selection picture slightly incomplete at the description level.

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

Parameters4/5

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

Schema coverage is 89%, so the baseline is 3; the description exceeds it by explaining cross-field rules the schema cannot express, such as OG cards taking no references unless named and prompt being visual direction for target:"og". It adds little about the many ID/domain/site_id fields, which the schema already covers thinly.

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

Purpose4/5

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

States a specific verb and resource: generate/regenerate a blog post's hero image or OG social card. It does not name a sibling it replaces or overlaps with (e.g. upload_media or patch_posts_by_id), so sibling differentiation is left implicit, but the purpose itself is unambiguous.

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

Usage Guidelines4/5

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

Gives real conditional guidance: works identically before and after the post exists, commit:false routes to a review flow, and anchoring a face requires marking the photo as a headshot via mark_reference_image first. It never states when NOT to call it or what the alternative is for adjacent tasks (uploading vs generating), leaving a gap.

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?