Skip to main content
Glama

Add or remove handles

update_entry_handles
Destructive

Add handles to an entry, remove them, or move some to the front — a live edit. Only the handles named are sent (add_handles / remove_handles), and the server applies them to the entry’s list as it is when it saves: an added handle goes at the end, one the entry has already, or one to remove that it has not, changes nothing (the answer’s handle_ops says which), and nothing is read first, so a handle someone else saved meanwhile is never undone. first moves the handles it names to the front, in its order, the others keeping theirs: the tool reads the list and sends it whole, against the revision it read (a save in between is refused as a conflict; run it again), and a handle in first the entry has not is refused. A handle you remove that the Wikidata sync supplied is held back so the sync does not bring it back. Dry run by default. To ask a reviewer instead, use propose_entry_change.

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": {
      "entry": "<entry>"
    },
    "name": "update_entry_handles"
  }
}

Input Schema

NameRequiredDescriptionDefault
addNo
entryYesThe entry: its VHID (11 digits), its short name (as in verifiedhandles.org/<short>), or its Wikidata QID (Q42).
firstNoHandles to move to the front, in this order, each by its value (a masked email by its ref); the others keep their order after them. Each must be one of the entry’s handles (after add / remove); the entry then keeps its own order rather than the site’s.
removeNoHandles to take off, each by its value — or, for an email this key may not see, by {platform_id: "email", ref}.
dry_runNotrue (the default): write nothing — show the change and the exact request it would send. false: make the change.
summaryNoWhy you made this edit, in a few plain words; shown in the entry’s public history. At most 200 characters. Never an internal tracking ID (a backlog or ticket number); a VHID is fine.
idempotency_keyNoOptional: a key you choose (1–255 printable ASCII, e.g. a UUID), sent as the write’s Idempotency-Key. Calling again with the same key and the same change within 24 hours answers the first call’s result (replayed: true) and writes nothing; the same key with another change is refused (422).
base_revision_idNoOnly with `first` (left out: the revision the tool reads). Without it, not sent: handles are added and removed against the entry as it is when the edit is saved.

Output Schema

NameRequiredDescriptionDefault
noteNoA dry run: what to do next to make the change, in words.
resultNoA real run: the route’s own answer, where the tool adds facts of its own beside it.
confirmNoA dry run of a change that needs it: the exact target to send back as `confirm` with dry_run: false.
dry_runNotrue: a dry run, which wrote nothing. Absent from a real run.
replayedNoA real run with an idempotency_key already used for this change: the first call’s answer, given back; nothing was written now.
would_sendNoA dry run: the exact request the real run would send (`method`, `path`, any `headers` such as an Idempotency-Key, and its `body`, `form` or `query`), or the requests, in order.
may_edit_liveNoA dry run of a live edit: whether this key’s account may edit this entry live.
refused_becauseNoA dry run the real run would be refused for: why, in words.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedInput schema / properties / base_revision_id / description
      Previous value: -"Not needed, and not sent: handles are added and removed against the entry as it is when the edit is saved."New value: +"Only with `first` (left out: the revision the tool reads). Without it, not sent: handles are added and removed against the entry as it is when the edit is saved."
    • addedInput schema / properties / first
      Added value: +{
      +  "description": "Handles to move to the front, in this order, each by its value (a masked email by its ref); the others keep their order after them. Each must be one of the entry’s handles (after add / remove); the entry then keeps its own order rather than the site’s.",
      +  "items": {
      +    "anyOf": [
      +      {
      +        "properties": {
      +          "platform_id": {
      +            "description": "The platform id, e.g. \"twitter\": one the platform catalog has (get_entry with include_platforms lists the enabled ones; platform_catalog, every one). A new handle on an unknown or disabled platform is refused (400 invalid_platform).",
      +            "minLength": 1,
      +            "type": "string"
      +          },
      +          "value": {
      +            "description": "The handle as stored, e.g. \"nasa\".",
      +            "minLength": 1,
      +            "type": "string"
      +          }
      +        },
      +        "required": [
      +          "platform_id",
      +          "value"
      +        ],
      +        "type": "object"
      +      },
      +      {
      +        "properties": {
      +          "platform_id": {
      +            "description": "The masked handle’s platform: \"email\".",
      +            "minLength": 1,
      +            "type": "string"
      +          },
      +          "ref": {
      +            "description": "A masked handle’s `ref` (get_entry → editing.handles, where its value is null): it names the stored handle without its address.",
      +            "pattern": "^[0-9]{1,18}$",
      +            "type": "string"
      +          }
      +        },
      +        "required": [
      +          "platform_id",
      +          "ref"
      +        ],
      +        "type": "object"
      +      }
      +    ]
      +  },
      +  "maxItems": 50,
      +  "minItems": 1,
      +  "type": "array"
      +}
  2. Added

TDQS

A4.7/5.0
Behavior5/5

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

Goes well past the annotations (destructiveHint, non-idempotent) by disclosing that nothing is read before a save, that unknown adds/removes are silently no-ops reported via handle_ops, that `first` is revision-guarded and refuses on a concurrent save, and that removed sync-supplied handles are held back from the Wikidata sync. These are exactly the side effects an agent cannot infer from structured fields.

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 operation and the alternative, and every clause carries information. The single long paragraph packed with em-dashes and parentheticals is dense and slightly harder to scan than a short bulleted breakdown would be.

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?

An output schema covers handle_ops and replay results, and the description handles concurrency, ordering, sync protection, and dry run. The remaining gap is access prerequisites — it never says what role or permission an agent needs to make a live edit.

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 already 88%, so the baseline is 3; the description still adds real meaning — add lands at the end, `first` orders the named handles ahead of the rest and rewrites the whole list, and a `first` entry the record lacks is refused. It leaves base_revision_id and idempotency_key entirely to the schema, which is the only shortfall.

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 set and resource — "Add handles to an entry, remove them, or move some to the front" — and immediately labels it a live edit, which separates it from the propose_* siblings named at the end.

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 routing: "Dry run by default" tells the agent the safe path, and "To ask a reviewer instead, use propose_entry_change" names the alternative and the condition that selects it. It also states a retry rule for conflicts ("run it again").

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.