Skip to main content
Glama
Hermoso

Hermoso

Official

Publish a post to X (Twitter)

post_to_x
Destructive

Publish a single post, thread, reply, quote, or media post directly to a connected X (Twitter) account. Preview exact text and confirm cost before publishing.

Instructions

Use this when the user wants to post to X (Twitter) now. Publish to the user’s connected X (Twitter) account — a single post, a post with an image or video render attached, a reply to an existing post, or a whole THREAD (pass thread as an array and each part is posted as a reply to the one before). This PUBLISHES immediately and PUBLICLY — ALWAYS show the user the exact text and get an explicit yes BEFORE calling. Text is NEVER truncated. Write altText whenever you attach a render. COSTS CREDITS at X’s per-post price, every post in a thread billed: a post that contains a link (any web address, and every quote post) is X’s link rate, far higher than one without (hermoso_credits gives both figures). When the user asks what a post will cost, call this with dryRun:true: it posts NOTHING and returns that exact post’s costCredits. THIS TOOL POSTS ORGANICALLY — it does not create an ad campaign. Needs X connected (Connectors > X). Full rules: get_instructions({topic:'post_to_x'}).

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

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

Input Schema

NameRequiredDescriptionDefault
clipNoshare a CLIP of another post’s video. It is the post’s only attachment: no media, poll, quote, message-us link or thread. Link rate.
hookNoWHAT ANGLE this post is built on, recorded only at publish time. post_performance ranks hooks on it (a winner needs 5 posts sharing ONE hook), so pass a list_hooks id (e.g. "direct_callout", "before_after") or reuse your own wording EXACTLY across a campaign. Omit it and this post never votes on which hook works.
pollNorun a poll on the post. X does not allow a poll and media on the same post, and a poll cannot ride on a thread.
textNothe post text. 280 characters without X Premium, up to 25,000 with it — write the full thing, it is never truncated. With `thread` also set, this is the FIRST post and the thread entries follow it (a thread whose first entry is already this text is not posted twice).
brandNoWHICH PROFILE this post belongs to — id or exact name from list_brands (a shared workspace: its profile id). Beats the connection's pin for THIS CALL ONLY; a name that matches no profile, or two, is REFUSED and nothing is posted.
dryRunNotrue = post NOTHING and return what this exact post would cost (costCredits). Free.
ideaIdNoshort id of the content-plan idea this post came from
recipeNothe post's FORMAT id, e.g. "slideshow" or "imessage_chat" — post_performance groups by it, so reuse one id per format
threadNoa thread: each string is one post, published in order, each replying to the previous (if `text` is also set it is posted first and these follow). Max 25 including `text`. Each part follows the same length rule as `text`, and on an X Premium account ONE long post is usually both better reading and cheaper than a thread.
accountNoWHICH connected account of this channel to post as — its @handle or id from list_connector_accounts. Needed only when the profile has more than one x account connected (several and none named is refused by name, never guessed); omit when there is one.
altTextNoaccessibility description of the attached media, max 1000 characters — write one whenever you attach a render. Costs a small extra amount: X bills one metadata write PER media. With SEVERAL media, pass an ARRAY aligned to their order — X attaches alt text per media id, and a single string describes only the FIRST one (X renders up to four media as a GRID, not a carousel, so one sentence would be wrong for the other three).
subjectNoWHAT THIS POST IS ABOUT — product, feature, offer or theme (e.g. "winter coat", "free trial"). post_performance's second grouping axis: reuse the exact wording, as with hook.
imageUrlNoalias of mediaUrl for an IMAGE — same as passing it as mediaUrl
mediaUrlNoa Hermoso render (image or video) to attach to the first post — pass its served URL, or an upload_file url for external media; a URL, not a local file path; use upload_file for local files
videoCtaNoVIDEO posts only — a button on the video; needs videoCtaUrl (https)
videoUrlNoalias of mediaUrl for a VIDEO — same as passing it as mediaUrl
mediaUrlsNoUP TO FOUR Hermoso-hosted media attached to ONE post — X’s own schema caps media_ids at 4. X renders them as a GRID: every image visible at once, nothing to swipe to. That is NOT a carousel, and a numbered "1/6 · SWIPE" slide deck must still not be sent here — it would publish as a grid and the "swipe" instruction would make no sense. Order decides the layout. On a thread the media rides the FIRST post; give each later part its own post to attach more. Mutually exclusive with mediaUrl, and more than 4 is refused before anything is uploaded; a URL, not a local file path; use upload_file for local files
replyToIdNonumeric id of an existing X post to reply to. X ONLY ACCEPTS AN API REPLY TO A POST THAT MENTIONS THIS ACCOUNT OR THAT THIS ACCOUNT WROTE (X policy since Feb 2026, every tier below Enterprise): a cold reply under a stranger's post is refused by X with "You can only reply to or quote posts where you are mentioned or are the author" and nothing is posted. Reply to those from x.com itself; use this for replies in your own threads and to people who tagged you.
dmDeepLinkNoa "Message us" button: true for the connected account, or https://x.com/messages/compose?recipient_id=<id>. TEXT posts only — X refuses it alongside media.
videoTitleNoVIDEO posts only — a headline under the video, max 70 (measured: X drops it on an image post, so it is refused there)
communityIdNopublish into an X COMMUNITY instead of the main timeline — the number in the community’s own URL (x.com/i/communities/<id>). The connected account must be a MEMBER of it; X answers a non-member and a non-existent id with the same refusal and does not separate them.
quotePostIdNonumeric id of a post to QUOTE — X renders the quoted post inside yours. This is NOT replyToId: a reply sits under the original in its thread, a quote stands alone on your own timeline with the original embedded, which is the one you want for commentary. X makes a quote mutually exclusive with media and with a poll (their own schema), and a quote is billed at the higher LINK rate because X appends the quoted post’s t.co URL whatever your text says. Same X rule as replyToId: a quote of a post that does not mention this account is refused by X.
videoCtaUrlNohttps link the video button opens; used with videoCta
platformCoverNoVIDEO COVER. X has no cover setting and shows the video’s FIRST frame, so by default Hermoso checks it and, only when that frame is blank (a template ad’s empty opening card), sends X a copy with the first frame replaced by the video’s best frame. Your Library file is never changed. true = send the file exactly as it is.
replySettingsNorestrict who can reply — omit for everyone, which is the right default for a brand post
taggedUserIdsNotag up to 10 people (numeric X user ids, from x_user) in the post’s media
paidPartnershipNolabel the post a PAID PARTNERSHIP on X — the same disclosure Hermoso already ships for TikTok. OPT-IN ONLY: set it when the post is sponsored, gifted or otherwise paid for, and never assume it on the user’s behalf.
videoDescriptionNoVIDEO posts only — a line under the title, max 200

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.1.539
    • addedInput schema / properties / clip
      Added value: +{
      +  "description": "share a CLIP of another post’s video. It is the post’s only attachment: no media, poll, quote, message-us link or thread. Link rate.",
      +  "properties": {
      +    "endSeconds": {
      +      "anyOf": [
      +        {
      +          "maximum": 9007199254740991,
      +          "minimum": -9007199254740991,
      +          "type": "integer"
      +        },
      +        {
      +          "type": "string"
      +        }
      +      ],
      +      "description": "5 to 60 s after start, at most 30% of that video"
      +    },
      +    "postId": {
      +      "description": "id or x.com link of a post with ONE video over 2 minutes",
      +      "type": "string"
      +    },
      +    "startSeconds": {
      +      "anyOf": [
      +        {
      +          "maximum": 9007199254740991,
      +          "minimum": -9007199254740991,
      +          "type": "integer"
      +        },
      +        {
      +          "type": "string"
      +        }
      +      ],
      +      "description": "whole seconds or m:ss"
      +    }
      +  },
      +  "required": [
      +    "postId",
      +    "startSeconds",
      +    "endSeconds"
      +  ],
      +  "type": "object"
      +}
  2. Changed2 schema fields changedv0.1.525
    • changedInput schema / properties / mediaUrl / description
      Previous value: -"a Hermoso render (image or video) to attach to the first post — pass its served URL, or an upload_file url for external media"New value: +"a Hermoso render (image or video) to attach to the first post — pass its served URL, or an upload_file url for external media; a URL, not a local file path; use upload_file for local files"
    • changedInput schema / properties / mediaUrls / description
      Previous value: -"UP TO FOUR Hermoso-hosted media attached to ONE post — X’s own schema caps media_ids at 4. X renders them as a GRID: every image visible at once, nothing to swipe to. That is NOT a carousel, and a numbered \"1/6 · SWIPE\" slide deck must still not be sent here — it would publish as a grid and the \"swipe\" instruction would make no sense. Order decides the layout. On a thread the media rides the FIRST post; give each later part its own post to attach more. Mutually exclusive with mediaUrl, and more than 4 is refused before anything is uploaded."New value: +"UP TO FOUR Hermoso-hosted media attached to ONE post — X’s own schema caps media_ids at 4. X renders them as a GRID: every image visible at once, nothing to swipe to. That is NOT a carousel, and a numbered \"1/6 · SWIPE\" slide deck must still not be sent here — it would publish as a grid and the \"swipe\" instruction would make no sense. Order decides the layout. On a thread the media rides the FIRST post; give each later part its own post to attach more. Mutually exclusive with mediaUrl, and more than 4 is refused before anything is uploaded; a URL, not a local file path; use upload_file for local files"
  3. Changed3 schema fields changedv0.1.484
    • addedInput schema / properties / dryRun
      Added value: +{
      +  "description": "true = post NOTHING and return what this exact post would cost (costCredits). Free.",
      +  "type": "boolean"
      +}
    • changedInput schema / properties / text / description
      Previous value: -"the post text. 280 characters without X Premium, up to 25,000 with it — write the full thing, it is never truncated. Use this OR thread, not both."New value: +"the post text. 280 characters without X Premium, up to 25,000 with it — write the full thing, it is never truncated. With `thread` also set, this is the FIRST post and the thread entries follow it (a thread whose first entry is already this text is not posted twice)."
    • changedInput schema / properties / thread / description
      Previous value: -"a thread: each string is one post, published in order, each replying to the previous. Max 25. Each part follows the same length rule as `text`, and on an X Premium account ONE long post is usually both better reading and cheaper than a thread."New value: +"a thread: each string is one post, published in order, each replying to the previous (if `text` is also set it is posted first and these follow). Max 25 including `text`. Each part follows the same length rule as `text`, and on an X Premium account ONE long post is usually both better reading and cheaper than a thread."
  4. Changed6 schema fields changedv0.1.465
    • addedInput schema / properties / dmDeepLink
      Added value: +{
      +  "description": "a \"Message us\" button: true for the connected account, or https://x.com/messages/compose?recipient_id=<id>. TEXT posts only — X refuses it alongside media.",
      +  "type": [
      +    "string",
      +    "boolean"
      +  ]
      +}
    • addedInput schema / properties / taggedUserIds
      Added value: +{
      +  "description": "tag up to 10 people (numeric X user ids, from x_user) in the post’s media",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • addedInput schema / properties / videoCta
      Added value: +{
      +  "description": "VIDEO posts only — a button on the video; needs videoCtaUrl (https)",
      +  "enum": [
      +    "visit_site",
      +    "watch_now"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / videoCtaUrl
      Added value: +{
      +  "description": "https link the video button opens; used with videoCta",
      +  "type": "string"
      +}
    • addedInput schema / properties / videoDescription
      Added value: +{
      +  "description": "VIDEO posts only — a line under the title, max 200",
      +  "type": "string"
      +}
    • addedInput schema / properties / videoTitle
      Added value: +{
      +  "description": "VIDEO posts only — a headline under the video, max 70 (measured: X drops it on an image post, so it is refused there)",
      +  "type": "string"
      +}
  5. Changed2 schema fields changedv0.1.374
    • changedInput schema / properties / account / description
      Previous value: -"WHICH connected account of this channel to post as — its @handle or id from list_connector_accounts. Needed only when the brand has more than one x account connected (several and none named is refused by name, never guessed); omit when there is one."New value: +"WHICH connected account of this channel to post as — its @handle or id from list_connector_accounts. Needed only when the profile has more than one x account connected (several and none named is refused by name, never guessed); omit when there is one."
    • changedInput schema / properties / brand / description
      Previous value: -"WHICH BRAND this post belongs to — id or exact name from list_brands (a shared workspace: its profile id). Beats the connection's pin for THIS CALL ONLY; a name that matches no brand, or two, is REFUSED and nothing is posted."New value: +"WHICH PROFILE this post belongs to — id or exact name from list_brands (a shared workspace: its profile id). Beats the connection's pin for THIS CALL ONLY; a name that matches no profile, or two, is REFUSED and nothing is posted."
  6. Changed3 schema fields changedv0.1.320
    • changedInput schema / properties / brand / description
      Previous value: -"WHICH BRAND this post belongs to — the id or exact name from list_brands (a workspace shared with you: its profile id). Use it whenever the account has more than one brand and you are not certain which one this connection is pinned to: it beats the pin for THIS CALL ONLY and changes nothing about the connection. A name that matches no brand, or two brands, is REFUSED and nothing is posted — never resolved to the pin, which is the account you were guarding against."New value: +"WHICH BRAND this post belongs to — id or exact name from list_brands (a shared workspace: its profile id). Beats the connection's pin for THIS CALL ONLY; a name that matches no brand, or two, is REFUSED and nothing is posted."
    • changedInput schema / properties / hook / description
      Previous value: -"WHAT ANGLE THIS POST IS BUILT ON — the single most valuable field here, and the only moment it can ever be recorded. post_performance groups on it to answer \"which hooks work\", and it needs 5 posts sharing ONE hook before it will call anything a winner, so REUSE THE SAME WORDING across a campaign instead of rephrasing it every time. Best of all, pass a hook id from list_hooks (e.g. \"direct_callout\", \"mid_problem\", \"before_after\") — those fold onto a stable key however they are spelled, so a whole brand accumulates evidence on one row. Your own wording is fine too; it just only groups when you repeat it exactly. Omitting it means this post can never vote on which hook works."New value: +"WHAT ANGLE this post is built on, recorded only at publish time. post_performance ranks hooks on it (a winner needs 5 posts sharing ONE hook), so pass a list_hooks id (e.g. \"direct_callout\", \"before_after\") or reuse your own wording EXACTLY across a campaign. Omit it and this post never votes on which hook works."
    • changedInput schema / properties / subject / description
      Previous value: -"WHAT THIS POST IS ABOUT — the product, feature, offer or theme (e.g. \"winter coat\", \"free trial\", \"founder story\"). The second grouping axis in post_performance. Same rule as hook: reuse the exact wording so posts about one subject land in one group."New value: +"WHAT THIS POST IS ABOUT — product, feature, offer or theme (e.g. \"winter coat\", \"free trial\"). post_performance's second grouping axis: reuse the exact wording, as with hook."
  7. Changed2 schema fields changedv0.1.281
    • addedInput schema / properties / ideaId
      Added value: +{
      +  "description": "short id of the content-plan idea this post came from",
      +  "type": "string"
      +}
    • addedInput schema / properties / recipe
      Added value: +{
      +  "description": "the post's FORMAT id, e.g. \"slideshow\" or \"imessage_chat\" — post_performance groups by it, so reuse one id per format",
      +  "type": "string"
      +}
  8. Changed1 schema field changedv0.1.256
    • addedInput schema / properties / platformCover
      Added value: +{
      +  "description": "VIDEO COVER. X has no cover setting and shows the video’s FIRST frame, so by default Hermoso checks it and, only when that frame is blank (a template ad’s empty opening card), sends X a copy with the first frame replaced by the video’s best frame. Your Library file is never changed. true = send the file exactly as it is.",
      +  "type": "boolean"
      +}
  9. Changed1 schema field changedv0.1.251
    • addedInput schema / properties / brand
      Added value: +{
      +  "description": "WHICH BRAND this post belongs to — the id or exact name from list_brands (a workspace shared with you: its profile id). Use it whenever the account has more than one brand and you are not certain which one this connection is pinned to: it beats the pin for THIS CALL ONLY and changes nothing about the connection. A name that matches no brand, or two brands, is REFUSED and nothing is posted — never resolved to the pin, which is the account you were guarding against.",
      +  "type": "string"
      +}
  10. Changed4 schema fields changedv0.1.249
    • addedInput schema / properties / imageUrl
      Added value: +{
      +  "description": "alias of mediaUrl for an IMAGE — same as passing it as mediaUrl",
      +  "type": "string"
      +}
    • changedInput schema / properties / quotePostId / description
      Previous value: -"numeric id of a post to QUOTE — X renders the quoted post inside yours. This is NOT replyToId: a reply sits under the original in its thread, a quote stands alone on your own timeline with the original embedded, which is the one you want for commentary. X makes a quote mutually exclusive with media and with a poll (their own schema), and a quote is billed at the higher LINK rate because X appends the quoted post’s t.co URL whatever your text says."New value: +"numeric id of a post to QUOTE — X renders the quoted post inside yours. This is NOT replyToId: a reply sits under the original in its thread, a quote stands alone on your own timeline with the original embedded, which is the one you want for commentary. X makes a quote mutually exclusive with media and with a poll (their own schema), and a quote is billed at the higher LINK rate because X appends the quoted post’s t.co URL whatever your text says. Same X rule as replyToId: a quote of a post that does not mention this account is refused by X."
    • changedInput schema / properties / replyToId / description
      Previous value: -"numeric id of an existing X post to reply to"New value: +"numeric id of an existing X post to reply to. X ONLY ACCEPTS AN API REPLY TO A POST THAT MENTIONS THIS ACCOUNT OR THAT THIS ACCOUNT WROTE (X policy since Feb 2026, every tier below Enterprise): a cold reply under a stranger's post is refused by X with \"You can only reply to or quote posts where you are mentioned or are the author\" and nothing is posted. Reply to those from x.com itself; use this for replies in your own threads and to people who tagged you."
    • addedInput schema / properties / videoUrl
      Added value: +{
      +  "description": "alias of mediaUrl for a VIDEO — same as passing it as mediaUrl",
      +  "type": "string"
      +}
  11. Changed1 schema field changedv0.1.189
    • addedInput schema / properties / account
      Added value: +{
      +  "description": "WHICH connected account of this channel to post as — its @handle or id from list_connector_accounts. Needed only when the brand has more than one x account connected (several and none named is refused by name, never guessed); omit when there is one.",
      +  "type": "string"
      +}
  12. Addedv0.1.161

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=false, destructiveHint=true, openWorldHint=true and idempotentHint=false, so the safety profile is known; the description still adds genuinely new behavior: immediate public publication, credit cost at X's per-post price, the much higher link rate for any URL or quote post, and the dryRun escape hatch that posts nothing. It also discloses prerequisites ('Needs X connected (Connectors > X)') and non-obvious side effects like altText incurring a per-media metadata charge. It stops short of describing failure/partial-failure behavior for a mid-thread abort, which keeps it off 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?

Content is front-loaded with the trigger and the confirm-before-calling rule, and the capitalized keywords (THREAD, PUBLISHES, COSTS CREDITS) make skimming effective. It is dense to the point of being crowded — confirm-to-user, altText advice, credit pricing and the instructions pointer all compete in one paragraph — but nearly every clause carries decision-relevant information rather than filler.

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?

For a 28-parameter, nested-object mutation with no output schema, the description covers what an agent most needs before calling: it is irreversible and public, it costs money with a rate that varies by link presence, how to price without posting, and the auth prerequisite. The remaining detail is delegated coherently to the schema and to get_instructions({topic:'post_to_x'}), which is an explicit and discoverable escape hatch rather than an omission.

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% and the per-parameter descriptions are themselves unusually rich, so the baseline is 3; the tool description nonetheless adds cross-parameter meaning the schema can't express, notably that passing `thread` as an array posts each entry as a reply to the one before, and that dryRun:true returns the exact post's costCredits. That ordering/precedence logic is real added value beyond the field-by-field docs.

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 ('Publish to the user's connected X (Twitter) account') and enumerates the concrete shapes it takes: single post, post with media render, reply, or thread. It also draws an explicit boundary against a sibling behavior ('THIS TOOL POSTS ORGANICALLY — it does not create an ad campaign'), so an agent can separate it from click_to_ad without opening a 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?

Opens with the triggering condition ('Use this when the user wants to post to X (Twitter) now') and supplies a mandatory precondition workflow ('ALWAYS show the user the exact text and get an explicit yes BEFORE calling'). It also names a distinct mode for cost questions (dryRun:true) and an escalation path (get_instructions), so both when-to-use and when-to-use-differently are covered.

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

Deploy Server

Other Tools