Skip to main content
Glama

update-page

Destructive

Updates an existing MediaWiki page by replacing, appending, prepending, or find-replacing whole-page or section content, with revision IDs to detect edit conflicts.

Instructions

Writes to an existing wiki page and returns the new revision ID. Fails if the page does not exist; for new pages, use create-page. operation says what the write does and section says where: omit section to act on the whole page, or set it to confine the write to one section. For changing part of a page, use operation='find-replace', which carries only the text being rewritten, so nothing outside find can be lost and the rest of the page never has to travel to or from the caller; a find that matches nothing, or more than one place, is refused without writing, which also makes it safe to resend a call whose result never arrived. For replacing a target outright, use operation='replace', whose source must carry every byte meant to survive; it is refused when source would shorten a target too large for one read to return whole, since the rest was never seen. With section set above 0 it also takes out that section's heading, so source begins with a heading unless it is empty, and takes out every subsection nested under that section, is refused when source would drop them, and needs latestId to say which revision the section number was read from. operation='append' and 'prepend' add a delta: a new section at the end of the page is an append whose source begins with the heading, and with section set a prepend inserts one immediately above that section. Pass latestId (reported as latestRevisionId by any get-page read that returns wikitext) for edit-conflict detection: the write is rejected rather than silently clobbering a concurrent change. Each call is a separate revision, and resending an append or prepend whose result never arrived adds the delta a second time.

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": {
      "title": "<title>"
    },
    "name": "update-page"
  }
}

Input Schema

NameRequiredDescriptionDefault
botNoMarks the edit as a bot edit, which Special:RecentChanges hides by default. When omitted, the bot setting of the wiki decides; pass false to leave one edit unflagged. Applies only if the account has the `bot` right and, through a bot password or OAuth consumer, the High-volume (bot) access grant; otherwise the edit saves unflagged and the response reports botMarked: false. Use for bulk or automated edits, or when the user asks.
findNoThe existing wikitext to rewrite, matched in full and exactly, whitespace and template markup included. Required when operation is 'find-replace'. A find that matches nothing, or more than one place, is refused without writing: extend it with the text around it to name one occurrence.
modeNoDeprecated older spelling of operation='append' and operation='prepend'. Send operation instead.
wikiNoWiki to target, as a key from the mcp://wikis/ resources (e.g. en.wikipedia.org), or the full mcp://wikis/ URI. Omit to use the default wiki.
titleYesWiki page title
sourceNoThe content to write, in the existing page's content model. Required for every operation except find-replace, and refused for that one. An appended source that opens a new section must begin on its own line, as in "\n\n== History ==\n\nBody."; without the leading newline the heading runs on from the last line of the page and is not recognised as a heading.
commentNoSummary of the edit
sectionNoSection number (0 = lead; 1..N = heading sections), from the section list get-page reports. Confines the write to that section: omit it to act on the whole page. A replace also takes out every subsection nested under the section; see removeSubsections.
latestIdNoBase revision ID for edit-conflict detection; any get-page read that returns wikitext reports it as latestRevisionId. Required when section is set, because the wiki resolves a section number against this revision rather than against whichever is current. If omitted on a write that is not scoped to a section, the update is applied without conflict detection.
operationNoWhat the write does to the target: 'replace' overwrites it with source, 'append' and 'prepend' add source to it, and 'find-replace' rewrites only the text find names and leaves the rest of the target byte for byte. With section=N, 'append' writes at the end of that section and 'prepend' immediately above that section's heading, which inserts a new section before an existing one. Defaults to 'replace'.
replaceWithNoWhat find becomes. Required when operation is 'find-replace'; an empty string deletes the text find matched.
removeSubsectionsNoConfirms that replacing this section is meant to remove the subsections nested under it. Required only when section is set and source contains fewer subsection headings than the section currently has.
removeUnreadContentNoConfirms that replacing content larger than a single read returns is meant to discard the part that was never returned. Required only when the target holds more bytes than one response carries and source holds fewer.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.21.0
    • changedInput schema / properties / bot / description
      Previous value: -"Marks the edit as a bot edit, which Special:RecentChanges hides by default. Takes effect only when the authenticated account has the `bot` right (granted by the bot group, or by the high-volume grant on a bot password or OAuth consumer); without it the edit saves unflagged and the response reports botMarked: false. Use when performing bulk or automated edit runs, or when the user requests it."New value: +"Marks the edit as a bot edit, which Special:RecentChanges hides by default. When omitted, the bot setting of the wiki decides; pass false to leave one edit unflagged. Applies only if the account has the `bot` right and, through a bot password or OAuth consumer, the High-volume (bot) access grant; otherwise the edit saves unflagged and the response reports botMarked: false. Use for bulk or automated edits, or when the user asks."
  2. Changed15 schema fields changedv0.18.0
    • addedInput schema / properties / find
      Added value: +{
      +  "description": "The existing wikitext to rewrite, matched in full and exactly, whitespace and template markup included. Required when operation is 'find-replace'. A find that matches nothing, or more than one place, is refused without writing: extend it with the text around it to name one occurrence.",
      +  "minLength": 1,
      +  "type": "string"
      +}
    • changedInput schema / properties / latestId / description
      Previous value: -"Base revision ID for edit-conflict detection; obtain from get-page with metadata=true. If omitted, the update is applied without conflict detection."New value: +"Base revision ID for edit-conflict detection; any get-page read that returns wikitext reports it as latestRevisionId. Required when section is set, because the wiki resolves a section number against this revision rather than against whichever is current. If omitted on a write that is not scoped to a section, the update is applied without conflict detection."
    • changedInput schema / properties / mode / description
      Previous value: -"Adds source to the existing content instead of replacing it: 'append' to the end, 'prepend' to the start."New value: +"Deprecated older spelling of operation='append' and operation='prepend'. Send operation instead."
    • addedInput schema / properties / operation
      Added value: +{
      +  "description": "What the write does to the target: 'replace' overwrites it with source, 'append' and 'prepend' add source to it, and 'find-replace' rewrites only the text find names and leaves the rest of the target byte for byte. With section=N, 'append' writes at the end of that section and 'prepend' immediately above that section's heading, which inserts a new section before an existing one. Defaults to 'replace'.",
      +  "enum": [
      +    "replace",
      +    "append",
      +    "prepend",
      +    "find-replace"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / removeSubsections
      Added value: +{
      +  "description": "Confirms that replacing this section is meant to remove the subsections nested under it. Required only when section is set and source contains fewer subsection headings than the section currently has.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / removeUnreadContent
      Added value: +{
      +  "description": "Confirms that replacing content larger than a single read returns is meant to discard the part that was never returned. Required only when the target holds more bytes than one response carries and source holds fewer.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / replaceWith
      Added value: +{
      +  "description": "What find becomes. Required when operation is 'find-replace'; an empty string deletes the text find matched.",
      +  "type": "string"
      +}
    • removedInput schema / properties / section / anyOf
      Removed value: -[
      -  {
      -    "maximum": 9007199254740991,
      -    "minimum": 0,
      -    "type": "integer"
      -  },
      -  {
      -    "const": "new",
      -    "type": "string"
      -  }
      -]
    • changedInput schema / properties / section / description
      Previous value: -"Section to edit: 0 (lead), 1..N (existing heading sections), or 'new' to append a new heading section."New value: +"Section number (0 = lead; 1..N = heading sections), from the section list get-page reports. Confines the write to that section: omit it to act on the whole page. A replace also takes out every subsection nested under the section; see removeSubsections."
    • addedInput schema / properties / section / maximum
      Added value: +9007199254740991
    • addedInput schema / properties / section / minimum
      Added value: +0
    • addedInput schema / properties / section / type
      Added value: +"integer"
    • removedInput schema / properties / sectionTitle
      Removed value: -{
      -  "description": "Heading for a new section; required when section='new', rejected otherwise.",
      -  "type": "string"
      -}
    • changedInput schema / properties / source / description
      Previous value: -"The content to write, in the existing page's content model. Interpreted as the full page by default; as the given section's content when section is set; or as a delta (appended or prepended) when mode is set."New value: +"The content to write, in the existing page's content model. Required for every operation except find-replace, and refused for that one. An appended source that opens a new section must begin on its own line, as in \"\\n\\n== History ==\\n\\nBody.\"; without the leading newline the heading runs on from the last line of the page and is not recognised as a heading."
    • changedInput schema / required
      Previous value: -[
      -  "title",
      -  "source"
      -]New value: +[
      +  "title"
      +]
  3. Changed1 schema field changedv0.15.0
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
  4. Changed1 schema field changedv0.12.0
    • addedInput schema / properties / bot
      Added value: +{
      +  "description": "Marks the edit as a bot edit, which Special:RecentChanges hides by default. Takes effect only when the authenticated account has the `bot` right (granted by the bot group, or by the high-volume grant on a bot password or OAuth consumer); without it the edit saves unflagged and the response reports botMarked: false. Use when performing bulk or automated edit runs, or when the user requests it.",
      +  "type": "boolean"
      +}
  5. Changed1 schema field changedv0.10.0
    • addedInput schema / properties / wiki
      Added value: +{
      +  "description": "Wiki to target, as a key from the mcp://wikis/ resources (e.g. en.wikipedia.org), or the full mcp://wikis/ URI. Omit to use the default wiki.",
      +  "type": "string"
      +}
  6. Addedv1.0.2
  7. Removedv1.0.1
  8. Changed5 schema fields changedv1.0.0
    • removedInput schema / additionalProperties
      Removed value: -false
    • changedInput schema / properties / latestId / description
      Previous value: -"Identifier for the revision used as the base for the new source"New value: +"Revision ID used as the base for the new source"
    • addedInput schema / properties / latestId / exclusiveMinimum
      Added value: +0
    • addedInput schema / properties / latestId / maximum
      Added value: +9007199254740991
    • changedInput schema / properties / latestId / type
      Previous value: -"number"New value: +"integer"
  9. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already signal destructive/non-idempotent behavior, but the description goes well beyond them: conflict detection via latestId, re-application of append/prepend on resend, section heading and subsection removal side effects, and the removeSubsections/removeUnreadContent confirmation gates. These are exactly the failure modes an agent needs to know before calling a destructive tool.

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

Conciseness3/5

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

The core statement is front-loaded and no sentence is purely filler, but it is delivered as one dense paragraph of long compound sentences that are hard to scan, and a few clauses (e.g. find-replace requiring find) restate what the schema already enforces. The information density is justified by the tool's complexity, but the structure could be segmented for readability.

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 a 13-parameter destructive tool with no output schema, the description covers the operation matrix, section scoping, conflict handling, and refusal conditions thoroughly. It says the call returns the new revision ID but gives no further sense of the response (e.g. the botMarked flag mentioned in the schema), which is a minor gap rather than a blocking one.

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 100%, so baseline is 3, but the description adds cross-tool meaning the schema cannot: latestId is the value reported as latestRevisionId by any wikitext-returning get-page read, and it is required once a section number is used because the wiki resolves sections against that revision. It also explains the heading-newline requirement when appending a new section.

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?

The first sentence states a specific verb and resource ('Writes to an existing wiki page'), names the return value (new revision ID), and immediately distinguishes itself from the sibling create-page for new pages. An agent can identify the tool's role 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?

It explicitly routes between operations: find-replace for partial rewrites, replace for full replacement, append/prepend for deltas, plus a named alternative (create-page) and a deprecation note for 'mode'. Exclusions are concrete, e.g. find-replace with zero or multiple matches is refused, and replace is refused when source would truncate unseen content.

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