Skip to main content
Glama

Approve, revise, plan, restore, or discard a draft

revise_content_draft
Destructive

Act on one draft in the user's queue. stage = the user approved it (mark ready to publish; publishing itself happens in the web tool). discard drops it. revise rewrites it in the brand voice per a one-click preset — shorter, longer, punchier, deeper, simpler, more_specific, less_salesy, more_casual, more_formal — and/or a typed instruction (2 credits). fix makes the surgical change the reviewer's notes asked for (2). humanize strips the AI feel and keeps everything else (2). review scores it against the brand voice (2). edit replaces the text with what you or the user wrote (free) — when you can write the better version yourself, prefer edit over revise. plan puts it on the calendar for planned_at (YYYY-MM-DD or ISO time; null unplans; free; a plan, not a schedule). restore brings back an earlier version by version_id from get_content_draft (free; its old score returns when the filing is unchanged). Every text change saves the previous text as a version, so any step can be undone with restore. Any text change clears the old score. A scheduled or live draft cannot be changed (error draft_locked) — tell the user to change it in their scheduler. Stage and discard are the USER's decisions — act on their say-so, never on your own judgment. If the user's reaction should apply to every future draft (not just this one), use teach_content_voice instead.

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": {
      "space_id": "<space_id>",
      "draft_id": "<draft_id>",
      "action": "<action>"
    },
    "name": "revise_content_draft"
  }
}

Input Schema

NameRequiredDescriptionDefault
textNoedit: the replacement text.
actionYes
presetNorevise: the calibration chip the user clicked.
draft_idYesFrom get_content_queue or a write_content_candidates result.
space_idYes
planned_atNoplan: the day (YYYY-MM-DD) or ISO time to plan it for; null removes it from the calendar.
version_idNorestore: a version_id from get_content_draft.
instructionNorevise / fix / humanize: the user's note in their words.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • changedInput schema / properties / action / enum
      Previous value: -[
      -  "stage",
      -  "discard",
      -  "revise",
      -  "fix",
      -  "humanize",
      -  "review",
      -  "edit"
      -]New value: +[
      +  "stage",
      +  "discard",
      +  "revise",
      +  "fix",
      +  "humanize",
      +  "review",
      +  "edit",
      +  "plan",
      +  "restore"
      +]
    • addedInput schema / properties / planned_at
      Added value: +{
      +  "description": "plan: the day (YYYY-MM-DD) or ISO time to plan it for; null removes it from the calendar.",
      +  "type": [
      +    "string",
      +    "null"
      +  ]
      +}
    • addedInput schema / properties / version_id
      Added value: +{
      +  "description": "restore: a version_id from get_content_draft.",
      +  "type": "string"
      +}
  2. Added

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only say this is a non-read-only, destructive, closed-world tool; the description goes far beyond by disclosing credit costs per action (2 vs free), that every text change snapshots the prior text as a version, that any text change clears the old score, and that stage/discard are the user's decisions and must never be taken on the agent's own judgment. It also names the concrete error condition (draft_locked) and its remedy, which the annotations cannot express.

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

Conciseness4/5

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

Front-loaded and nearly every clause carries distinct information (cost, side effect, or routing rule), with backticked action names aiding scanability. It is a single dense block though — for nine actions a short structured list would be easier for an agent to parse than one long paragraph.

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 nine-action multiplex tool with no output schema, the definition covers the full lifecycle an agent needs: what each action changes, cost, reversibility via versioning, score invalidation, lock errors, and when to escalate to the user or to a sibling tool. Nothing material for correct invocation appears to be missing.

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 75%, so a 3 is the baseline, but the description adds real meaning: which parameters belong to which action, that planned_at null unplans and that a plan is not a schedule, that a restored version's old score returns when the filing is unchanged, and that instruction must be in the user's own words. It stops short of restating every one of the eight parameters, which the schema already covers.

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+resource ('Act on one draft in the user's queue') and then enumerates all nine action values with the exact effect of each (stage marks ready to publish, discard drops it, revise rewrites, plan schedules, restore reverts, etc.). An agent can distinguish this from get_content_draft, teach_content_voice, or the write tools 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?

Gives explicit routing rules: 'when you can write the better version yourself, prefer edit over revise', and 'If the user's reaction should apply to every future draft (not just this one), use teach_content_voice instead.' It also states a hard exclusion — a scheduled or live draft cannot be changed and the user must go to their scheduler.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.