Skip to main content
Glama

Propose a Correction

propose_correction

During a review shift, propose a correction to a page's transcription (field "ocr") or English (field "translation"). A correction is a list of exact span edits: each "find" must be copied exactly from the text the shift returned and occur once on the page (add surrounding words if it repeats); "replace" is the corrected text ("" deletes). Fix only what the scan or the original shows is wrong: misread letters, dropped or added words, a sentence the English skips. Do not restyle or modernise. Propose transcription fixes before translation fixes, as separate calls. Pass base_hash = page.text_version for that field. A proposal does NOT change the page: it is applied only after a second reader agrees, and the volunteer is credited. If the call says the page changed since it was loaded, say so and move on. drafted_by: "assistant" if you found and worded it in a book run, "volunteer" if the user supplied the wording, "assistant_accepted" if you drafted it and the user approved it specifically, "mixed" otherwise.

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": {
      "item_id": "<item_id>",
      "field": "<field>",
      "base_hash": "<base_hash>",
      "edits": "<edits>",
      "volunteer_code": "<volunteer_code>",
      "drafted_by": "<drafted_by>",
      "assistant_model": "<assistant_model>"
    },
    "name": "propose_correction"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameNoHow the user wants to be credited (optional)
noteNoAnything the second reader should know (optional)
editsYesSpan edits (1-30).
fieldYes"ocr" for the transcription, "translation" for the English
item_idYespage.item_id from the shift
shift_idNo
base_hashYestext_version.ocr or text_version.translation from the page
drafted_byYes
volunteer_codeYes
assistant_modelYesYour own model name and version, copied exactly as your instructions or system prompt give it, and whether extended thinking is on. Write "unknown" rather than guess; a wrong name is worse than none.
user_agreed_to_termsNotrue if the user said yes when you asked whether their findings may be licensed to Source Library under https://sourcelibrary.org/terms. Pass it on every proposal of the shift.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / user_agreed_to_terms
      Added value: +{
      +  "description": "true if the user said yes when you asked whether their findings may be licensed to Source Library under https://sourcelibrary.org/terms. Pass it on every proposal of the shift.",
      +  "type": "boolean"
      +}
  2. Changed6 schema fields changed
    • changedInput schema / properties / assistant_model / description
      Previous value: -"Your model name, if known"New value: +"Your own model name and version, copied exactly as your instructions or system prompt give it, and whether extended thinking is on. Write \"unknown\" rather than guess; a wrong name is worse than none."
    • changedInput schema / properties / base_hash / description
      Previous value: -"text_version.ocr or text_version.translation from the item"New value: +"text_version.ocr or text_version.translation from the page"
    • changedInput schema / properties / drafted_by / enum
      Previous value: -[
      -  "volunteer",
      -  "assistant_accepted",
      -  "mixed"
      -]New value: +[
      +  "assistant",
      +  "volunteer",
      +  "assistant_accepted",
      +  "mixed"
      +]
    • changedInput schema / properties / item_id / description
      Previous value: -"item_id from start_review_shift"New value: +"page.item_id from the shift"
    • removedInput schema / properties / volunteer_code / description
      Removed value: -"volunteer_code from start_review_shift"
    • changedInput schema / required
      Previous value: -[
      -  "item_id",
      -  "field",
      -  "base_hash",
      -  "edits",
      -  "volunteer_code",
      -  "drafted_by"
      -]New value: +[
      +  "item_id",
      +  "field",
      +  "base_hash",
      +  "edits",
      +  "volunteer_code",
      +  "drafted_by",
      +  "assistant_model"
      +]
  3. Added

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description goes much further by stating that a proposal does NOT change the page and is applied only after a second reader agrees, with the volunteer credited. It also discloses the stale-page conflict case and its required response, which is exactly the kind of behaviour an agent could not infer from the schema or annotations.

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 with the action, then the edit rules, then the workflow and drafted_by semantics; every sentence carries operational content. It is dense and long for a single paragraph, and the drafted_by enumeration could be broken out, but there is no filler to cut.

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

Completeness4/5

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

For an 11-parameter, 7-required mutation tool with no output schema, the description covers the edit contract, ordering, version pinning, conflict handling, and the drafting-attribution taxonomy. The remaining gap is the return value: with no output schema, it never says what a successful proposal returns (e.g. an id or status) beyond the failure case.

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

Parameters5/5

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

Well above the 73% schema-coverage baseline: it explains that each "find" must be copied exactly, must occur once on the page, and that surrounding words should be added if the string repeats — a constraint the schema's 'Exact text currently on the page' does not convey. It also states that an empty "replace" deletes, maps base_hash to page.text_version for the chosen field, and defines all four drafted_by enum values with the conditions that distinguish them.

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 — proposing a correction to a page's "ocr" (transcription) or "translation" (English) field — and scopes it to a review shift, which separates it from siblings like propose_collection and the read-only get_* tools. The definition of a correction as a list of exact span edits makes the operation concrete before any schema is opened.

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/when-not guidance: fix only what the scan or original shows is wrong (misread letters, dropped/added words, skipped sentences), and explicitly do not restyle or modernise. It also orders the work — transcription fixes before translation fixes, as separate calls — and gives the fallback behaviour when the page has changed (say so and move on).

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.