excalibur-mcp

excalibur_create_post

Store a new post (draft or scheduled). Returns its post_id.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`doc`	Yes	The editable Doc — a JSON object whose consumed key is ``blocks``, a list of block objects. A minimal static post is one block: ``{"blocks": [{"text": "gm. stack sats.", "flags": []}]}``. Blocks are joined with a blank line between them to form ``text_cache``. Each block: - ``text`` (str): the block's copy (for a dynamic block, a prompt). - ``flags`` (list): editor highlight regions, each ``{"start": int, "end": int, "note": str, "colorIdx": int}`` (char offsets into ``text``) — pass ``[]`` when there are none. - ``dynamic`` (bool, optional): when true ``text`` is a prompt the server resolves with an LLM at post time; ``fallback`` (str) is posted if it fails, and ``domains``/``maxFetches``/``runtimeLimit`` bound its web access. Voice/bans live in your separate Voice profile and the schedule in ``publish_at``/``recurrence``/``cease_at`` — neither belongs in ``doc``.
`npub`	No	Required. Your Nostr public key (npub1...) for credit billing.
`title`	No	Optional human label for the post; the list falls back to the first body line when it is blank.
`status`	No	``draft`` or ``scheduled``.	draft
`cease_at`	No	ISO-8601 stop time for recurrence; null = open-ended.
`tweet_url`	No
`dpop_token`	No
`publish_at`	No	ISO-8601 first/next publish time; required when status='scheduled'.
`recurrence`	No	``{"freq": "daily\|weekly\|monthly", "interval": n}`` or null.
`text_cache`	No	Composed text (blocks joined) for scheduler + list excerpts.
`client_req_id`	No	Idempotency key — re-sending the same id returns the same post without a second charge.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed8 schema fields changedAug 17, 2026

addedInput schema / properties / cease_at / description

Added value: +"ISO-8601 stop time for recurrence; null = open-ended."

addedInput schema / properties / client_req_id / description

Added value: +"Idempotency key — re-sending the same id returns the same\npost without a second charge."

addedInput schema / properties / doc / description

Added value: +"The editable Doc — a JSON object whose consumed key is ``blocks``,\na list of block objects. A minimal static post is one block:\n``{\"blocks\": [{\"text\": \"gm. stack sats.\", \"flags\": []}]}``. Blocks\nare joined with a blank line between them to form ``text_cache``.\nEach block:\n  - ``text`` (str): the block's copy (for a dynamic block, a prompt).\n  - ``flags`` (list): editor highlight regions, each\n    ``{\"start\": int, \"end\": int, \"note\": str, \"colorIdx\": int}``\n    (char offsets into ``text``) — pass ``[]`` when there are none.\n  - ``dynamic`` (bool, optional): when true ``text`` is a prompt the\n    server resolves with an LLM at post time; ``fallback`` (str) is\n    posted if it fails, and ``domains``/``maxFetches``/``runtimeLimit``\n    bound its web access.\nVoice/bans live in your separate Voice profile and the schedule in\n``publish_at``/``recurrence``/``cease_at`` — neither belongs in ``doc``."

addedInput schema / properties / publish_at / description

Added value: +"ISO-8601 first/next publish time; required when status='scheduled'."

addedInput schema / properties / recurrence / description

Added value: +"``{\"freq\": \"daily|weekly|monthly\", \"interval\": n}`` or null."

addedInput schema / properties / status / description
```
Added value: +"``draft`` or ``scheduled``."
```

addedInput schema / properties / text_cache / description

Added value: +"Composed text (blocks joined) for scheduler + list excerpts."

addedInput schema / properties / title / description

Added value: +"Optional human label for the post; the list falls back to the\nfirst body line when it is blank."

First observedJul 16, 2026

TDQS

C2.9/5.0

Behavior2/5

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

With no annotations, the description carries the full burden. It only says 'Store a new post' and returns post_id, but does not disclose potential credit charges, the need for authentication via npub, idempotency behavior, or side effects beyond storing.

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

Conciseness5/5

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

The description is a single, front-loaded sentence that clearly conveys the primary action and return value. No unnecessary words.

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

Completeness2/5

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

Despite a rich schema, the minimal description omits critical context such as the need for npub for credit billing, the requirement of publish_at for scheduled posts, and idempotency via client_req_id. The output schema exists, but the description itself is too sparse for a complex creation tool.

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

Parameters3/5

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

Schema description coverage is 82%, so most parameters have detailed descriptions. The tool description itself adds no parameter semantics, so the baseline of 3 is appropriate.

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?

The description clearly states the tool stores a new post (draft or scheduled) and returns the post_id. The word 'new' distinguishes it from update_post, though it does not explicitly name sibling alternatives.

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

Usage Guidelines2/5

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

No guidance is given on when to use this tool versus alternatives like excalibur_post_nostr_message or excalibur_update_post. It does not mention prerequisites such as npub being required or that scheduled posts need publish_at.

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

All excalibur-mcp 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.