worklore

suggest_edit

Idempotent

Propose a revision of a worklore story written by SOMEONE ELSE, for its author to accept or decline — worklore's pull request. Use it when, while reproducing a story, a step turned out wrong, outdated or missing (a library changed, the docs caught up, a command no longer exists). Call get_story first, make the change in the COMPLETE markdown (frontmatter + '# title' + narrative + '## Reproduce this'; keep the frontmatter date exactly as it is), show the human a before/after diff and the rationale, and send it only with their EXPLICIT approval. The story does NOT change: the author is notified, reviews the diff, and either accepts it as a revision (the signed-in account is credited on the story) or declines it, in which case they may hand the text back as a draft of the signed-in account's own, adapted from theirs. One open suggestion per person per story; sending another replaces it. For the user's OWN story use edit_story 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": {
      "slug": "<slug>",
      "markdown": "<markdown>",
      "rationale": "<rationale>"
    },
    "name": "suggest_edit"
  }
}

Input Schema

Name	Required	Description
`slug`	Yes	The slug of the story (by another author) to propose a revision of.
`markdown`	Yes	The complete story markdown as you propose it, frontmatter included, with the original `date` unchanged.
`rationale`	Yes	One or two lines (max 500 chars): what was wrong or outdated, and what you changed. The author reads this first.

Output Schema

Name	Required	Description	Default
`id`	No
`url`	No
`note`	No
`status`	Yes
`replaced`	No

Schema Changelog

Changes observed during successful MCP inspections.

AddedOct 23, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Goes far beyond the annotations: describes that the story does not change, the author is notified and reviews the diff, the accept path credits the signed-in account, the decline path returns the text as an adapted draft. Also discloses the one-open-suggestion-per-person rule and that a new suggestion replaces the prior one, plus an explicit human-approval gate.

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?

Dense and front-loaded with the core framing ahead of the workflow detail. Slightly long, but nearly every clause carries operative information (workflow, approval, replacement rule, sibling routing) rather than redundancy.

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?

Given a multi-step, human-in-the-loop mutation with an output schema present, the description supplies the full workflow, the approval requirement, the accept/decline outcomes, the replacement rule, and the sibling alternative. Nothing an agent needs to invoke it correctly is 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?

With 100% schema coverage, baseline is 3; the description adds real value by specifying the markdown must be COMPLETE (frontmatter + '# title' + narrative + '## Reproduce this') and that the frontmatter `date` must be kept unchanged, and by noting the rationale is read first by the author.

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 ('Propose a revision'), the exact resource ('a worklore story written by SOMEONE ELSE'), and frames it with a clear analogy ('worklore's pull request'). The closing sentence explicitly distinguishes it from sibling edit_story.

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?

Explicit when-to-use conditions are given ('while reproducing a story, a step turned out wrong, outdated or missing') with concrete examples (library changed, docs caught up, command gone). It names the alternative for the user's own story (edit_story) and prescribes the prerequisite call (get_story first).

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

All worklore 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.