Keytomic

Generate hero image

generate_hero_image

Destructive

Generates a new hero image for the article of one content calendar topic of a site with Image Studio, and replaces the article’s hero image with it. Keytomic uses the article, the site’s Image Studio settings and its default brand assets; creativeDirection and exclusions guide the image. Each image uses 1 Blog Hero Credit. Without confirm, returns the plan and starts nothing (status plan): the article title and the Blog Hero Credits left. Show the plan to the user, and call again with confirm: true only after the user agrees. With confirm: true, reads the plan again, generates the image and attaches it to the article (status attached). When Keytomic generates the image but cannot attach it, the result says so (status generated_not_attached): the image is in the Image Studio Media Library, the credit is used, and the user can attach it in Content Studio. If the call with confirm: true times out, read the article with get_draft (or the topic with list_calendar_topics with topicId) before you call this tool again: the image can still finish and attach on the server, and a second call uses a second Blog Hero Credit. When the site cannot generate an image now, both calls answer a tool error and use nothing: a topic without an article (draft_not_found), a topic the workspace cannot open (topic_not_in_plan), missing Image Studio settings, a Spend Lock, or no Blog Hero Credits left.

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": {
      "projectId": "<projectId>",
      "topicId": "<topicId>"
    },
    "name": "generate_hero_image"
  }
}

Input Schema

Name	Required	Description
`confirm`	No	true starts the image generation. Send it only after the user saw the plan this tool returns without confirm and agreed. Without it, the tool returns the plan and starts nothing.
`topicId`	Yes	Topic whose article gets the hero image, from list_calendar_topics.
`projectId`	Yes	Site to act on, from list_sites.
`exclusions`	No	What the image must not show, up to 2,000 characters, such as "no text, no people".
`creativeDirection`	No	What the image shows or how it looks, up to 2,000 characters, such as "a baker shaping dough at sunrise". Without it, Keytomic takes the direction from the article and the site’s Image Studio settings.

Schema Changelog

Changes observed during successful MCP inspections.

No schema history has been recorded yet.

TDQS

A4.6/5.0

Behavior4/5

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

Annotations declare a destructive, non-idempotent, open-world write; the description goes well beyond them by disclosing credit consumption (1 Blog Hero Credit per call, and a retry after timeout burns a second one), the plan/confirm gating, and the partial-failure state generated_not_attached where the credit is spent but the image stays in the Media Library. It does not state permission or spend-lock remediation steps beyond naming them, so it falls just short of a 5.

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?

Front-loaded with the core action and side effect, then arranged by scenario (plan path, confirm path, partial failure, timeout, error cases). It is a single dense block and the timeout paragraph is long, but nearly every sentence carries distinct operational value.

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

Completeness5/5

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

With no output schema, the description carries the return contract itself: status plan with article title and credits remaining, status attached, status generated_not_attached, and the named tool errors. That is enough for an agent to call it, interpret every result, and decide whether to retry.

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 100%, so the baseline is 3, but the description adds real meaning: confirm is a no-op plan request unless the user has agreed, and creativeDirection/exclusions are optional guidance layered over the article and Image Studio defaults. It does not add format or length detail beyond what the schema already documents.

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?

States a specific verb and resource ('Generates a new hero image for the article of one content calendar topic') plus the side effect ('replaces the article's hero image'). An agent can distinguish it from generate_article or publish_draft without opening any 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 an explicit two-step protocol: call without confirm to get a plan, show it to the user, then call again with confirm: true only after agreement. It also covers edge routing — on timeout, check get_draft or list_calendar_topics before retrying — and enumerates the conditions under which the tool is unavailable.

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

All Keytomic 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?