Skip to main content
Glama
safiyu

kontexta

by safiyu
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript

files.read

Retrieve file contents from the Kontexta vault by ID or path, read full files, batch up to 200, or extract specific sections or line ranges for token-efficient access.

Instructions

Read one or more files, in full or in part. Modes: single-by-id (id), single-by-path (path, absolute on-disk path — must be exactly as indexed), batch-by-id (ids, up to 200), partial-by-heading (id+section), partial-by-line-range (id+lines). Exactly one of id/path/ids is required. section and lines are mutually exclusive and only valid with id (not ids or path). Read-only; no side effects, auth, or rate limits. Response shape: a single file object (with content, tags, est_tokens) for id/path; a partial-content object for section/lines; {files, total_est_tokens, error_count, errors} for ids (per-ID failures isolated, batch never partial-throws). Prefer files.describe to inspect without paying body tokens.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
idNoSingle file by ID.
idsNoBatch mode: multiple file IDs (max 200 per call); returns an array plus aggregate token cost.
pathNoSingle file by absolute on-disk path (must match exactly what Kontexta indexed).
linesNoPartial read: 1-indexed inclusive line range. Requires `id`; mutually exclusive with `section`.
sectionNoPartial read: return only this heading's body (case-insensitive exact-string after trim). Requires `id`; mutually exclusive with `lines`.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed8 schema fields changedv5.0.0
    • changedInput schema / properties / id / description
      Previous value: -"File ID"New value: +"Single file by ID."
    • addedInput schema / properties / id / exclusiveMinimum
      Added value: +0
    • changedInput schema / properties / id / type
      Previous value: -"number"New value: +"integer"
    • addedInput schema / properties / ids
      Added value: +{
+  "description": "Batch mode: multiple file IDs (max 200 per call); returns an array plus aggregate token cost.",
+  "items": {
+    "type": "number"
+  },
+  "maxItems": 200,
+  "minItems": 1,
+  "type": "array"
+}
    • addedInput schema / properties / lines
      Added value: +{
+  "additionalProperties": false,
+  "description": "Partial read: 1-indexed inclusive line range. Requires `id`; mutually exclusive with `section`.",
+  "properties": {
+    "from": {
+      "description": "First line (1-indexed, inclusive)",
+      "exclusiveMinimum": 0,
+      "type": "integer"
+    },
+    "to": {
+      "description": "Last line (1-indexed, inclusive)",
+      "exclusiveMinimum": 0,
+      "type": "integer"
+    }
+  },
+  "required": [
+    "from",
+    "to"
+  ],
+  "type": "object"
+}
    • addedInput schema / properties / path
      Added value: +{
+  "description": "Single file by absolute on-disk path (must match exactly what Kontexta indexed).",
+  "type": "string"
+}
    • addedInput schema / properties / section
      Added value: +{
+  "description": "Partial read: return only this heading's body (case-insensitive exact-string after trim). Requires `id`; mutually exclusive with `lines`.",
+  "type": "string"
+}
    • removedInput schema / required
      Removed value: -[
-  "id"
-]
  2. Addedv4.7.2

TDQS

A5/5.0
Behavior5/5

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

No annotations are provided, so the description carries full responsibility – and it delivers: it declares read-only semantics, no side effects, auth, or rate limits, explains batch error isolation ('per-ID failures isolated, batch never partial-throws'), and gives per-mode response shapes.

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

Conciseness5/5

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

A dense but efficiently structured description that front-loads the purpose and modes, then uses semicolons to compactly convey constraints and response shapes. No filler; every clause carries operational information.

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 tool with 5 parameters, multiple interacting modes, no annotations, and no output schema, the description covers all decision points: which id/path/ids to pass, how to combine section/lines, what responses look like, and how errors behave. The only omission is the exact structure of tags/est_tokens, but that's minor.

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?

Although the input schema already documents every parameter, the description adds combinatory semantics not in the schema: exactly-one-of requirement, mutual exclusion of section/lines, validity restricted to id, and response-shape implications per mode. This is additive value beyond structured fields.

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 ('Read') on a specific resource (files) and enumerates the five access modes. Explicitly contrasts with files.describe for inspection, so an agent can distinguish it from the sibling that shares the 'files' domain.

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?

Explicitly identifies when to prefer an alternative ('Prefer files.describe to inspect without paying body tokens') and structures usage by mode. The mutual-exclusion and requirement rules tell the agent exactly which parameter combination to assemble.

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

Deploy Server

Other Tools