Allows publishing social posts to Facebook accounts connected to PosteAhora.
Allows publishing social posts to Instagram accounts connected to PosteAhora.
Allows publishing social posts to Threads accounts connected to PosteAhora.
Allows publishing social posts to TikTok accounts, with support for media uploads to a verified CDN domain.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@@posteahora/mcp List my connected social accounts"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server for PosteAhora — let AI agents add ideas, create, schedule, and publish social posts across Instagram, X/Twitter, LinkedIn, Threads, Facebook (and more) straight from a chat.
It's a thin wrapper over the PosteAhora public REST API: every call is authenticated with your API key and goes through the same quota, ownership, and publishing pipeline as the web app.
Open PosteAhora → Settings → API & integrations.
Create a key and copy it (it's shown once). It looks like pah_live_….
Related MCP server: @posteverywhere/mcp
A key (and a hosted connector) is bound to one workspace — the one that was
active when you created it. So list_accounts, list_posts, list_ideas and
get_analytics return that workspace's data, not everything you own. To work
in another workspace, create a separate key/connector there. Writes are
role-gated: a viewer key can read but not create_post, schedule_post,
update_post, delete_post or publish_post_now (those return 403).
Add to your MCP client config:
{
"mcpServers": {
"posteahora": {
"command": "npx",
"args": ["-y", "@posteahora/mcp"],
"env": {
"POSTEAHORA_API_KEY": "pah_live_xxxxxxxx",
"POSTEAHORA_API_URL": "https://api.posteahora.com/functions/v1/api"
}
}
}
}Claude Code: claude mcp add posteahora -e POSTEAHORA_API_KEY=pah_live_… -e POSTEAHORA_API_URL=https://api.posteahora.com/functions/v1/api -- npx -y @posteahora/mcp
Cursor / Windsurf: add the JSON above to the MCP settings file.
Tool | What it does |
| List connected social accounts. Call first — you need each |
| Read / add backlog ideas (no publishing). |
| Create a draft, or publish now ( |
| Publish at a future time ( |
| Inspect posts and per-platform results. |
| Upload a local image/video from the machine running this server, returns a public URL for |
| Return a short-lived presigned URL so the client uploads a file directly to storage. Use in remote/hosted mode, where the server can't read your local files. |
list_accounts → grab the id for each platform you want to post to.
(optional) get a publicUrl for your media:
Local mode: upload_media with an absolute filePath → publicUrl.
Remote/hosted mode: create_upload_url with filename/sizeBytes →
uploadUrl + publicUrl; then HTTP PUT the raw bytes to uploadUrl with
the matching Content-Type header
(e.g. curl -T ./slide.jpg "<uploadUrl>" -H 'Content-Type: image/jpeg').
This works for any size, including video, and is required for TikTok photos
(they must be served from our verified cdn.posteahora.com domain).
create_post with accountMappings: [{ platform, accountId }], mediaUrls,
and status: "published" (or schedule_post with scheduledAt).
npm run start:http starts a stateless Streamable HTTP server on /mcp
(PORT, default 8787). The caller's Authorization: Bearer pah_… header is used
as the API key (falls back to POSTEAHORA_API_KEY). Put OAuth in front for a
production multi-tenant connector.
npm install
npm run build
POSTEAHORA_API_KEY=pah_live_… POSTEAHORA_API_URL=https://api.posteahora.com/functions/v1/api npm startAdd a lightweight idea to the backlog. Use this for brainstorming — it does NOT publish anything. Promote to a real post later with create_post.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Freeform tags | |
| title | No | Short title for the idea | |
| status | No | Kanban column; defaults to unassigned | |
| caption | No | Draft caption / body text | |
| mediaUrls | No | Public media URLs (from upload_media) |
| Name | Required | Description |
|---|---|---|
| idea | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide false hints for readOnly, idempotent, and destructive, which convey little. The description adds meaningful behavior: it is a lightweight insertion into a backlog and does NOT publish anything, which goes beyond the structured data.
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?
Two tight sentences, front-loaded with the action and resource, and every word contributes value. No redundancy or filler.
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?
For a simple creation tool with output schema and fully described parameters, the description covers the core purpose, usage context, and relationship to the key sibling tool (create_post). It doesn't mention update_idea or delete_idea, but that is not essential for basic use.
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?
The input schema covers all five parameters with individual descriptions (100% coverage), so the description does not need to add parameter details. The schema already provides semantic meaning for each property.
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 clearly states 'Add a lightweight idea to the backlog' with a specific verb and resource, and explicitly distinguishes from create_post by noting it does not publish anything and is later promoted via create_post.
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?
It explicitly says 'Use this for brainstorming' and contrasts with the alternative create_post, explaining that this tool does not publish and that promotion happens later. This gives clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a post. With status 'draft' it's saved only. With status 'published' it is published immediately to every channel in accountMappings. ALWAYS call list_accounts first to get accountId for each platform. Upload media via upload_media and pass the returned public URL in mediaUrls.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Optional title (used by YouTube etc.) | |
| status | No | Defaults to 'draft'. Use 'published' to post now. | |
| caption | No | Caption / body text (shared across platforms unless overridden) | |
| hashtags | No | ||
| postType | No | Defaults to 'post'. Pass 'reel' for videos (feed video vs Reel on Facebook/Instagram). TikTok routes by mediaType (falling back to the media URL extension), not postType. | |
| mediaType | No | Media kind. Strongly recommended for TikTok: it decides the video vs photo endpoint. If omitted it's inferred from the first mediaUrl's extension, but pass it explicitly to be safe. | |
| mediaUrls | No | Public media URLs (upload local files via upload_media first) | |
| accountMappings | Yes | One entry per channel: which connected account to post to for each platform. Get ids from list_accounts. | |
| platformOptions | No | Per-platform options, keyed by platform id (e.g. { tiktok: {...}, instagram: {...} }) | |
| platformCaptions | No | Per-platform caption overrides, keyed by platform id |
| Name | Required | Description |
|---|---|---|
| status | Yes | |
| postIds | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behavioral traits: published status publishes immediately to every channel, while draft only saves. Also reveals the requirement to call list_accounts first. This complements annotations by adding concrete side effects, though it doesn't detail the return value or error handling.
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?
Three sentences, front-loaded with the core action, and each sentence earns its place: purpose, status behavior, and prerequisites. No fluff.
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 10 parameters, nested objects, and an output schema, the description covers the essential workflow and prerequisites. Optional params are adequately described in the schema, so the description need not repeat them. A minor gap is no mention of how platformOptions/platformCaptions interplay, but schema handles that.
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?
Schema already covers 90% of parameters with detailed descriptions. The tool description adds extra meaning for status (draft vs published behavior) and accountMappings (calling list_accounts first), which enriches the schema.
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 clearly states the tool creates a post, and distinguishes between draft and published states with immediate publishing to all mapped channels. This differentiates it from sibling tools like schedule_post and publish_post_now.
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?
Explicit guidance is provided: ALWAYS call list_accounts first, upload media via upload_media before passing URLs. It clarifies when to use draft vs published. However, it does not explicitly mention alternatives for scheduling or when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a short-lived presigned URL to upload a local media file directly to storage from THIS client. Use this instead of upload_media when the MCP server runs remotely and cannot read your local files. Steps: (1) call this with filename, sizeBytes (exact byte length of the file) and optionally contentType; (2) HTTP PUT the raw file bytes to the returned uploadUrl with header 'Content-Type' set to the same contentType (e.g. curl -T ./slide.jpg "" -H 'Content-Type: image/jpeg') and expect HTTP 200; (3) put the returned publicUrl into mediaUrls of create_post / create_idea. Do NOT pass a filePath here — you upload the bytes yourself. The uploadUrl expires quickly, so upload right after calling this.
| Name | Required | Description | Default |
|---|---|---|---|
| filename | Yes | Original filename, e.g. slide-1.jpg — used to derive the extension | |
| sizeBytes | Yes | Exact byte size of the file you will upload | |
| contentType | No | MIME type; inferred from the filename extension when omitted |
| Name | Required | Description |
|---|---|---|
| method | Yes | |
| publicUrl | Yes | |
| uploadUrl | Yes | |
| expiresInSeconds | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal (readOnlyHint=false, openWorldHint=true, destructiveHint=false) and the description adds rich behavioral detail: the URL expires quickly, requires an HTTP PUT with Content-Type header, expects HTTP 200, and returns both uploadUrl and publicUrl. It also explains that the client must upload the bytes itself. No contradiction with annotations.
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?
The description is appropriately sized for a multi-step tool and is well-structured with numbered steps and a practical curl example. Every sentence contributes information, and the purpose and usage are front-loaded for quick scanning.
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?
The description covers the full workflow required for this presigned-URL tool: calling with parameters, uploading bytes via HTTP PUT, using the returned publicUrl in other tools, and the expiration constraint. With an output schema present, it doesn't need to explain return values in detail, and it directly addresses the sibling upload_media.
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?
Schema coverage is 100% (baseline 3), but the description adds value by emphasizing that sizeBytes must be the exact byte length, explaining contentType is optional and inferred from filename extension, and explicitly warning not to pass a filePath. These clarifications go beyond the schema descriptions.
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 clearly states the tool creates a short-lived presigned URL for uploading a local media file to storage, with the specific verb 'Get' and resource 'presigned URL'. It explicitly differentiates from upload_media by noting the remote-server scenario, so purpose and sibling differentiation are both strong.
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 when to use this tool instead of upload_media (when the MCP server runs remotely and cannot read local files) and gives a numbered step-by-step workflow including HTTP PUT and using the returned publicUrl in create_post/create_idea. It also warns against passing a filePath, providing clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete an idea from the backlog. Get ids from list_ideas.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Idea id (from list_ideas) |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| deleted | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds 'Permanently' to convey irreversibility, which goes beyond the destructiveHint annotation's generic 'destructive' flag. It also notes the resource is 'from the backlog,' adding context. No contradiction with annotations; idempotentHint is consistent with the permanent-deletion semantics.
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?
Two short sentences: the first declares the core purpose, the second provides the key usage hint. Every word earns its place; no redundancy or filler. Front-loaded and efficient.
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 the simplicity (one parameter, clear annotations, and an output schema), the description fully covers the essential context: what is deleted, permanence, and where to get the id. No additional details are needed for correct usage.
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?
Schema coverage is 100% and the only parameter 'id' already has the description 'Idea id (from list_ideas).' The tool description repeats 'Get ids from list_ideas' but adds no new meaning beyond the schema. Baseline 3 applies due to high schema coverage.
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 states the exact action: 'Permanently delete an idea from the backlog.' The verb 'delete' is specific, the resource is an 'idea,' and it differentiates from sibling tools like delete_post by targeting backlog ideas. This is unambiguous and distinguishes from create_idea/update_idea as well.
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 instruction 'Get ids from list_ideas' gives clear guidance on obtaining the required parameter. It implies this tool is for deleting ideas (not posts), distinguishing it from delete_post, though it does not explicitly state when not to use it or name alternatives directly. This is clear context without exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a post (soft delete — it stops appearing in listings). Get ids from list_posts.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Post id (from list_posts) |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| deleted | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the delete is a soft delete (post stops appearing in listings), which adds nuance beyond the annotations (e.g., destructiveHint=true). It also references list_posts as the id source. This informs the agent about the actual impact without contradicting the annotations.
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?
Two concise sentences that front-load the action and effect; no wasted words.
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?
For a simple one-param tool with annotations and an output schema, the description covers purpose, effect, and input source. It is complete enough for an agent to correctly use it.
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?
The schema already fully documents the single 'id' parameter (100% coverage), and the description repeats the source from list_posts, reinforcing but not adding new meaning beyond the schema. Baseline of 3 applies.
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 clearly states the verb 'Delete' and the resource 'post', and clarifies the soft-delete behavior (stops appearing in listings). It is unambiguous and distinguishes from sibling tools like delete_idea by specifying 'post'.
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 provides clear context by stating the effect (soft delete) and instructs to get ids from list_posts, which helps the agent know how to obtain the required input. It doesn't explicitly exclude alternatives, but for a single-purpose tool, that's not necessary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read performance metrics (views, likes, comments, shares, reach, saves, impressions, reposts, interactions) for the user's published posts, with aggregated totals and a per-platform breakdown. Data is synced from each platform hourly. Use it to analyze what performed well and to generate new ideas with create_idea.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max metric rows to scan (default 200) | |
| period | No | Window by published date; defaults to 30d | |
| platform | No | Filter to a single platform id (e.g. instagram) |
| Name | Required | Description |
|---|---|---|
| posts | Yes | |
| period | Yes | |
| summary | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and openWorldHint=true, and the description adds valuable context: data is synced hourly (so results may be slightly stale) and includes aggregated totals plus per-platform breakdown. This goes beyond annotations to explain freshness and output shape without contradicting them.
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?
The description is two well-structured sentences: the first front-loads what the tool does and what it returns, the second adds data freshness and a usage pointer. Every sentence adds value, with no wasted words.
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?
With 3 optional parameters, an output schema, and readOnlyHint/openWorldHint annotations, the description covers the essential behavioral context: scope, data freshness, and a typical use case. No critical information is missing that isn't already in the schema or annotations.
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?
Schema description coverage is 100%, with detailed descriptions for limit, period, and platform. The tool description itself does not add additional parameter semantics, and per the rubric, a baseline of 3 is appropriate when the schema already documents parameters thoroughly.
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 clearly states the tool reads performance metrics (specific verb 'Read') for published posts, with aggregated totals and per-platform breakdown. This distinguishes it from all siblings (none other cover analytics), making the purpose unambiguous.
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 suggests when to use it ('Use it to analyze what performed well') and even points to a following action ('generate new ideas with create_idea'). However, it does not explicitly state when not to use it or mention alternative tools for non-analytics needs, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one post by id, including its per-platform publish results (platform_results).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Post id |
| Name | Required | Description |
|---|---|---|
| post | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already confirms this is a safe read operation. The description adds context that the response includes platform_results, which is a meaningful behavioral detail. It does not over-explain or contradict the annotation.
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?
The description is a single, efficiently-worded sentence that immediately states the action, target, and key content. No filler or redundancy.
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?
For a single-parameter, read-only tool with an output schema, the description fully covers what the tool does and highlights the distinguishing output field (platform_results). The sibling names provide context for differentiation.
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?
The single required parameter 'id' is already fully described in the schema as 'Post id' with 100% coverage. The description repeats 'by id' but does not add new semantics beyond the schema.
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 clearly states a specific action — 'Fetch one post by id' — and identifies the unique value of the tool: including per-platform publish results (platform_results). This distinguishes it from sibling tools like list_posts or get_analytics.
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 clearly implies this is the tool for retrieving a single post's status with platform_results, but it does not explicitly name alternatives or exclusions. The context provides enough clarity to select it over list_posts, but explicit when-not-to-use guidance is absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the connected social accounts in this key/connector's workspace (a key or connector is bound to one workspace, so this returns that workspace's accounts, not every account you own). ALWAYS call this first before create_post or schedule_post: you need each account's id to target the right channel (the API refuses to publish without an explicit accountId).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| accounts | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and openWorldHint=true, so the agent knows it's a read-safe operation. The description adds valuable context about workspace binding and that the list is limited to the bound workspace, which is beyond the annotations. It doesn't contradict the annotations, and the added scope detail helps avoid misinterpretation.
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?
The description is two sentences: first states what the tool does and its scope, second gives a critical usage prerequisite. No filler words; every sentence earns its place. It is front-loaded with the purpose and immediately provides actionable guidance.
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?
With zero parameters, an output schema present, and read-only annotations, the tool's complexity is low. The description covers the purpose, scope, and a critical workflow rule. Since the output schema is available, the lack of detailed return descriptions is acceptable. The description is fully sufficient for an agent to use this tool correctly.
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?
The tool has zero parameters, so the baseline is 4. The description doesn't need to explain parameter meanings; the schema fully covers the (empty) parameter set. The mention of account ids in the context of the output (not parameters) provides useful related context without confusing the parameter story.
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 uses the specific verb 'List' and clearly identifies the resource as 'connected social accounts' in the key/connector's workspace. It distinguishes from other tools by clarifying scope: 'not every account you own' and explicitly ties to the workspace. This clearly sets it apart from siblings like list_ideas or list_posts.
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 gives an explicit directive: 'ALWAYS call this first before create_post or schedule_post' and explains why (need account id for targeting; API refuses without explicit accountId). This provides clear when-to-use guidance and the consequence of not using it, making it highly actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List your workspace's post ideas (the kanban backlog of drafts to iterate on).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| ideas | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already signals safe read behavior. The description adds useful context about the nature of the items (kanban backlog of drafts), but does not disclose additional behavioral details such as pagination, ordering, or limits. Since an output schema exists, return format is covered externally, so the description's contribution is modest.
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?
The description is a single, front-loaded sentence with no wasted words. Every part adds value: 'List', 'workspace's post ideas', and the parenthetical clarification of what post ideas are.
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?
For a simple read-only list tool with no parameters and an output schema, the description is complete. It clarifies the domain (post ideas as backlog) and works well with existing annotations and schema.
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?
The tool has zero parameters and the schema description coverage is 100% (empty properties). The baseline for no parameters is 4, and the description does not need to explain parameter syntax since there are none.
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 uses the specific verb 'List' with the resource 'your workspace's post ideas', and clarifies that these are 'the kanban backlog of drafts to iterate on'. This clearly distinguishes it from list_posts (actual posts) and other siblings like create_idea or update_idea.
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 provides clear context on what the tool does (listing post ideas) and implicitly when to use it. However, it does not explicitly mention alternatives or when not to use it, such as 'for published posts, use list_posts instead.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List your workspace's posts, newest first. Optionally filter by status.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max rows (default 50) | |
| status | No |
| Name | Required | Description |
|---|---|---|
| posts | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. The description adds ordering (newest first) and workspace scope, which is useful context. However, it does not disclose return format or pagination behavior. This aligns with annotations and adds moderate value beyond the structured data.
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?
The description is a single, well-structured sentence that conveys the core purpose with no redundancy or filler. It is appropriately concise for a simple list tool.
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?
For a simple read-only list tool with an output schema, the description covers the main purpose, scope, ordering, and filtering. It does not mention pagination or default values, but these are likely covered by the schema or output. Overall, it provides sufficient context.
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?
Schema description coverage is 50%; limit has a description, status only has an enum. The description clarifies that status is an optional filter, but does not elaborate on status meanings or limit defaults beyond the schema. It adds some meaning but relies on schema for parameter details.
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?
Description clearly states the tool lists workspace posts, with ordering and optional filtering. It distinguishes from siblings like list_ideas (different resource) and mutation tools (create/update/delete).
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 implies usage for browsing posts (list operation) and mentions optional status filtering, but does not explicitly state when to prefer this over sibling tools like get_post_status or list_ideas. No exclusions or alternative guidance provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Publish a saved draft or scheduled post immediately to its channels. A multi-channel draft is fanned out into one post per platform (each returned in postIds); the original draft id is retired. The post must already have a connected account selected per channel (set it with update_post if needed). Use get_post_status on the returned ids to check the per-platform result.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Post id (from list_posts) |
| Name | Required | Description |
|---|---|---|
| status | Yes | |
| postIds | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behavioral traits beyond annotations: multi-channel fan-out into one post per platform, the return of postIds, and the retirement of the original draft id. This adds significant transparency about side effects that the annotations (readOnlyHint=false, destructiveHint=false) do not cover.
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?
The description is three sentences long, each providing distinct value: the core action, the fan-out/id retirement behavior, and the prerequisites/follow-up. It is front-loaded with the primary purpose and contains no redundant or irrelevant information.
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?
The tool is simple (single parameter) and has an output schema, so the description doesn't need to explain return values. It covers prerequisites, the main behavior, and how to check results. This is complete for the tool's complexity.
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?
Schema coverage is 100% with the id parameter described as 'Post id (from list_posts)'. The description does not add additional parameter semantics beyond the schema, so the baseline score of 3 applies. No extra context or usage details are provided for the parameter.
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 uses a specific verb ('publish'), names the resource ('saved draft or scheduled post'), and clarifies the immediate action ('now'). It also explains the fan-out behavior, distinguishing it from a simple single-post publish. This makes the tool's purpose clear and distinct from siblings like schedule_post.
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?
Provides explicit prerequisites: the post must have a connected account per channel, with a pointer to update_post if needed. Also gives explicit post-action guidance to use get_post_status on returned ids. It doesn't explicitly state when not to use this tool, but the context is clear enough that it's intended for immediate publishing of drafts/scheduled posts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Schedule a post to publish at a future time. Same as create_post but requires scheduledAt (ISO 8601). Call list_accounts first.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Optional title (used by YouTube etc.) | |
| caption | No | Caption / body text (shared across platforms unless overridden) | |
| hashtags | No | ||
| postType | No | Defaults to 'post'. Pass 'reel' for videos (feed video vs Reel on Facebook/Instagram). TikTok routes by mediaType (falling back to the media URL extension), not postType. | |
| mediaType | No | Media kind. Strongly recommended for TikTok: it decides the video vs photo endpoint. If omitted it's inferred from the first mediaUrl's extension, but pass it explicitly to be safe. | |
| mediaUrls | No | Public media URLs (upload local files via upload_media first) | |
| scheduledAt | Yes | When to publish, ISO 8601 (e.g. 2026-06-01T14:30:00Z). Must be in the future. | |
| accountMappings | Yes | One entry per channel: which connected account to post to for each platform. Get ids from list_accounts. | |
| platformOptions | No | Per-platform options, keyed by platform id (e.g. { tiktok: {...}, instagram: {...} }) | |
| platformCaptions | No | Per-platform caption overrides, keyed by platform id |
| Name | Required | Description |
|---|---|---|
| status | Yes | |
| postIds | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint: false) and not destructive (destructiveHint: false). The description adds that publishing happens at a future time and requires ISO 8601 formatting, but does not disclose other behavioral nuances such as reversibility, validation behavior, or post-scheduling side effects. There is no contradiction with annotations.
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?
Two concise sentences, front-loaded with the core purpose and then the key differentiator and prerequisite. Every word earns its place with no redundancy or fluff.
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?
For a tool with 10 parameters, nested objects, and an output schema, the description efficiently points to the sibling create_post for shared nuances and highlights the critical scheduledAt requirement. It relies on the well-covered schema for parameter details, which is acceptable, though it could have briefly mentioned cancelation or status behavior.
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?
The schema already covers 90% of parameter descriptions, so the baseline is 3. The description adds meaningful semantics by specifying the ISO 8601 format for scheduledAt and directing the agent to call list_accounts first for accountMappings, which aids correct invocation beyond schema text alone.
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 uses a specific verb and resource ('Schedule a post to publish at a future time'), clearly distinguishing it from create_post by highlighting the scheduledAt requirement. This makes the tool's purpose immediately clear and unique among siblings.
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 names the alternative (create_post) and states the key difference (requires scheduledAt), and provides a concrete prerequisite: 'Call list_accounts first.' This gives clear when-to-use and setup guidance beyond the schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Edit an existing idea in the backlog. Only the fields you pass are changed. Use status to move it between kanban columns. Get ids from list_ideas.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Idea id (from list_ideas) | |
| tags | No | Freeform tags (replaces the existing list) | |
| title | No | Short title for the idea | |
| status | No | Move the idea to this kanban column | |
| caption | No | Draft caption / body text | |
| position | No | Sort position within the column (fractional indexing) | |
| mediaUrls | No | Public media URLs (replaces the existing list) |
| Name | Required | Description |
|---|---|---|
| idea | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal a non-read-only, idempotent, non-destructive operation. The description adds key behavioral semantics: partial field updates ('Only the fields you pass are changed') and the role of status in moving between kanban columns, which goes beyond the schema. It does not contradict annotations.
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?
Three short sentences, front-loaded with purpose, each adding distinct value: purpose, update semantics, and prerequisite (list_ideas). No filler or redundancy.
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 output schema and annotations cover return values and safety, the description sufficiently covers core usage for a 7-parameter update tool. It could mention array-replacement semantics for tags/mediaUrls, but those are already documented in the schema, and the description stays focused on the most decision-relevant behaviors.
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?
Schema covers 100% of parameters with descriptions, providing baseline 3. The description elevates this by clarifying partial-update semantics (omitted fields remain unchanged) and singling out status for column moves, giving contextual meaning across parameters.
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?
Description opens with 'Edit an existing idea in the backlog,' immediately distinguishing from create_idea/delete_idea and the post-related siblings. It also specifies scope (backlog) and the concrete resource (idea), making the tool's purpose unmistakable.
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?
Provides clear context: it targets existing ideas, supports partial updates, and explicitly directs users to list_ideas for ids and to use status for kanban column moves. However, it does not explicitly name alternatives like create_idea or update_post, so it stops short of full when-to-use vs when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Edit a draft or scheduled post. Only the fields you pass are changed. Status can be 'draft' or 'scheduled' (with scheduledAt) — to publish an existing post immediately use publish_post_now instead. Get ids from list_posts.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Post id (from list_posts) | |
| title | No | ||
| status | No | ||
| caption | No | ||
| hashtags | No | ||
| postType | No | ||
| mediaType | No | ||
| mediaUrls | No | Public media URLs (replaces the existing list) | |
| platforms | No | Platform ids this post targets | |
| scheduledAt | No | When to publish, ISO 8601. Required-in-future when status is 'scheduled'. | |
| platformOptions | No | Per-platform options, keyed by platform id | |
| connectedAccountId | No | connected_accounts.id to target (from list_accounts) |
| Name | Required | Description |
|---|---|---|
| post | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate mutation (readOnlyHint=false), idempotent (idempotentHint=true), and non-destructive (destructiveHint=false). The description adds partial-update semantics ('Only the fields you pass are changed') and scope restriction (draft/scheduled only), which are valuable beyond what annotations state. No contradiction found.
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?
Three sentences, front-loaded with the primary action, and each sentence adds value: scope, partial-update behavior, and alternative guidance. No filler or redundancy.
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 the tool has 12 parameters, nested objects, and an output schema, the description covers key usage context: what can be edited, how updates work, and when to use a different tool. It doesn't explain every parameter group, but with schema descriptions and output schema, the description is sufficiently complete for a complex tool.
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 50% schema description coverage, the description compensates by explaining that only passed fields change, which is crucial for all parameters. It also clarifies the status-scheduledAt relationship and excludes 'published' status. However, it doesn't detail other parameters like platformOptions or connectedAccountId, relying on the schema for those.
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 clearly states 'Edit a draft or scheduled post,' specifying the verb and resource, and differentiates from publish_post_now by explicitly directing immediate publishing there. It also implies 'existing' post, distinguishing from create_post.
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?
Provides explicit when-to-use ('Edit a draft or scheduled post'), a clear alternative ('to publish an existing post immediately use publish_post_now instead'), and a prerequisite ('Get ids from list_posts'). This gives solid guidance on when to invoke this tool versus siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload a local image or video file to media storage and get back a public URL to use in mediaUrls of create_post / create_idea. Provide an absolute filePath on the machine running this MCP server.
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | Absolute path to the local image/video file | |
| contentType | No | MIME type; inferred from the extension when omitted |
| Name | Required | Description |
|---|---|---|
| publicUrl | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only, non-destructive external interaction (openWorldHint=true). The description adds that the file is local and returns a public URL, but does not detail side effects like file lifecycle, permissions, or overwrite behavior. This is adequate given annotations but not rich.
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?
The description is two sentences, front-loaded with the action and result, followed by the key usage directive. Every sentence earns its place with no redundant information.
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?
The description covers purpose, local file requirement, and intended use of the public URL. Since an output schema exists, it need not explain return values. It could mention size limits or the alternative create_upload_url, but it is largely complete for a straightforward upload tool.
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?
Both parameters are fully described in the schema (100% coverage), so the baseline is 3. The description repeats the filePath requirement but adds no new semantics beyond what the schema already provides.
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 clearly states the action (Upload), the target (media storage), and the outcome (public URL), and explicitly ties it to create_post/create_idea mediaUrls. This distinguishes it from sibling tools like create_upload_url, which likely handles remote uploads.
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 specifies that the file must be local and provides an absolute filePath on the server, giving clear context for when to use this tool. It does not explicitly name alternatives, but the local-file requirement implies its scope, which is sufficient guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0create_ideacreate_postcreate_upload_urldelete_ideadelete_postget_analyticsget_post_statuslist_accountslist_ideaslist_postspublish_post_nowschedule_postupdate_ideaupdate_postupload_mediaScored across 15 tools
Each tool targets a distinct resource and action. Even the three publishing-related tools (create_post, schedule_post, publish_post_now) are clearly separated by their purpose: create, schedule, and publish existing. No two tools are likely to be confused.
All tool names use lowercase snake_case with a verb_noun pattern (list_ideas, create_post, upload_media). Exceptions like publish_post_now and get_post_status still adhere to the verb-first structure, making the namespace predictable.
With 15 tools, the server covers the full social media management workflow without redundancy or bloat. Each tool has a clear role, and the count is within the ideal range.
The server provides complete CRUD for ideas and posts, multiple publishing options, media upload, account listing, and analytics. It covers the entire lifecycle from brainstorming to performance review, with no obvious dead ends.
Draft, schedule and publish social posts to nine platforms from any AI agent.
Schedule and publish social media posts to 10 platforms from your AI agent
Draft, schedule, and publish social posts for your workspace straight from your AI.
Post, schedule, and track social posts on X, Bluesky, LinkedIn, Instagram and more from AI agents.
