Skip to main content
Glama

update_document

Replace an existing document's full content in the knowledge base and re-index it immediately, so updated information becomes searchable without manual reindexing.

Instructions

Update the content of an existing document in the knowledge base.

Mutating — overwrites the file on disk and re-indexes immediately. Old chunks are removed and replaced with new ones. Full content replacement, not a patch. The category is detected again from the path through category_mappings (general when none matches), so a category stored by add_document() or add_from_url() is not kept.

Args: filepath: Full or relative path to the document file. Must be an already-indexed file — list_documents() lists indexed paths, one page at a time. content: New full-text content to replace the existing content entirely

Returns: JSON string with update results (old chunk count, new chunk count, status).

Usage: Use to replace a document's content completely. Use add_document() to create a new file instead. Use remove_document() to delete without replacing. Changes are immediately searchable — no manual reindex needed.

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": {
      "filepath": "<filepath>",
      "content": "<content>"
    },
    "name": "update_document"
  }
}

Input Schema

NameRequiredDescriptionDefault
contentYes
filepathYes

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv3.0.0

TDQS

A4.6/5.0
Behavior4/5

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

With no annotations supplied, the description carries the full burden and does so well: it discloses that the file on disk is overwritten, that re-indexing is immediate, that old chunks are discarded, and that this is a full replacement rather than a patch. It also flags a genuinely non-obvious side effect — the category is re-derived from the path via category_mappings, so a category set by add_document() or add_from_url() is lost. It stops short of stating reversibility/no-undo or what error surfaces when the path is not indexed, which keeps it below a 5.

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?

It is front-loaded with the mutating/re-indexing behavior first, then Args, Returns, and Usage — a predictable structure that scans well. There is mild redundancy between "Full content replacement, not a patch" in the body and "Use to replace a document's content completely" in the Usage block, and the Returns block restates what the output schema already declares.

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 two-parameter mutation tool with no annotations, the description covers everything an agent needs: the mutation's on-disk effect, the immediate re-index, the category side effect, sibling routing, and parameter constraints. Return values are also covered even though an output schema exists, so there is no information gap.

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 description coverage is 0% (bare string properties), so the description must compensate, and it does: filepath is defined as full or relative, constrained to an already-indexed file, with list_documents() pointed to as the discovery path; content is defined as the full replacement text. The gap is that it never clarifies the base directory relative paths resolve against or how path normalization is handled.

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 description opens with a specific verb and resource ("Update the content of an existing document in the knowledge base") and immediately contrasts itself with add_document() for creation and remove_document() for deletion. An agent can distinguish it from all listed siblings 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?

The Usage block explicitly names both alternatives and the condition that selects each: add_document() to create a new file, remove_document() to delete without replacing, and this tool to replace content completely. It also notes changes are immediately searchable, removing a common ambiguity about whether a follow-up reindex is needed.

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