Skip to main content
Glama
Sign In

sprkly

by app.sprkly
OverviewDiscussionsAdmin

Request human approval

sprkly_request_post_approval

Hold a draft or scheduled post for the owner's approval. Moves it to pending_approval, where it never publishes on its own, emails the owner an Approve link, and returns an approval id to poll with sprkly_get_post_approval_status. Asking again for a post that is already waiting returns the same request. Approved posts go back to scheduled (a post past its time goes out in about 2 minutes); rejected posts become drafts with the owner's notes. To hold a NEW post, pass requires_approval to sprkly_schedule_post instead. Brand, Pro, Agency and lifetime Tier 2 and up only (postApproval in sprkly_get_account_summary): other plans get upgrade_required.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "post_id": "<post_id>"
    },
    "name": "sprkly_request_post_approval"
  }
}

Input Schema

NameRequiredDescriptionDefault
noteNoOptional note to the owner, shown in the approval email.
post_idYesThe draft or scheduled post id to hold for approval.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedInput schema / properties / note / description
      Previous value: -"Optional context for the reviewer."New value: +"Optional note to the owner, shown in the approval email."
    • changedInput schema / properties / post_id / description
      Previous value: -"The draft post id to submit."New value: +"The draft or scheduled post id to hold for approval."
  2. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Far exceeds the supplied hints: it discloses the state transition to pending_approval, that such posts never publish on their own, the side effect of emailing the owner an Approve link, the returned approval id, the paused idempotency ('asking again ... returns the same request'), the ~2-minute publish latency for overdue approved posts, and the rejected-to-draft outcome. Only the minor tension between 'returns the same request' and idempotentHint=false is left implicit.

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?

Five dense sentences, each carrying distinct information (action, state, side effect, sibling routing, edge cases, gating) with the primary action front-loaded. No filler or redundant restatement of the title.

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 mutation with no output schema and only hint-level annotations, the description covers what an agent needs: the resulting state, how to poll the result, terminal outcomes for approve and reject, latency behavior, and the plan precondition with its error signal. Nothing material is missing.

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 coverage is 100%, so both parameters are already documented in structured data, and the description adds little param-specific detail beyond restating that the note appears in the approval email. Baseline 3 applies; the description's value here is in state outcomes rather than parameter meaning.

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?

Opens with a specific verb and resource ('Hold a draft or scheduled post for the owner's approval') and immediately names the resulting state (pending_approval), which separates it from siblings like sprkly_schedule_post and sprkly_get_post_approval_status. An agent can identify the tool without opening the schema.

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

Usage Guidelines5/5

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

Gives explicit routing rules: use sprkly_schedule_post with requires_approval for a NEW post, and poll the returned id with sprkly_get_post_approval_status. It also states the plan gate (Brand/Pro/Agency/lifetime Tier 2+, postApproval in sprkly_get_account_summary) and the upgrade_required failure, so when-not-to-use is covered too.

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

All sprkly toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources