Skip to main content
Glama
token-context-mcp

token-context-mcp

Index status

get_index_status
Read-onlyIdempotent

Check repository index freshness, counts, and pending paths after listing repositories before trusting repo maps or graph edges; treat stale spans cautiously.

Instructions

Check snapshot freshness ('fresh', 'stale', 'pending', 'unknown'), counts, and pending_paths after list_repositories. Run before trusting get_repo_map or graph edges; treat stale spans cautiously.

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": {
      "repo_id": "<repo_id>"
    },
    "name": "get_index_status"
  }
}

Input Schema

NameRequiredDescriptionDefault
repo_idYesRegistered repository ID from list_repositories (never a filesystem path; returns unknown_repo_id if unregistered).
verboseNoInclude full diagnostic metadata (role_counts, entry_points, derived_defaults, added_paths, edge_precision); defaults to False for compact status.

Output Schema

NameRequiredDescriptionDefault
dataNoSnapshot metadata, counts, role breakdown, and paths modified since indexing.
errorNoPresent when the tool call fails (either a structured {code, message, details} object or a diagnostic string).
budgetNoToken budget accounting for this response.
repo_idNoRegistered repository identifier.
evidenceNoSource-verified file line spans and SHA-256 hashes backing the response.
warningsNoFreshness, ambiguity, redaction, or security warnings.
freshnessNoIndex freshness state ('fresh', 'pending', 'stale', or 'unknown').
truncatedNoTrue if items were omitted due to budget or node limits.
ledger_revNoCurrent evidence ledger revision for repo_id.
completenessNoCoverage/resolution completeness indicator.
index_run_idNoIdentifier of the active index snapshot run.
edge_precisionNoResolved vs. ambiguous edge ratio summary.
schema_versionNoEnvelope schema version ('1.0').
untrusted_repository_contentNoTrue when payload embeds raw repository text.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • addedInput schema / properties / verbose
      Added value: +{
      +  "default": false,
      +  "description": "Include full diagnostic metadata (role_counts, entry_points, derived_defaults, added_paths, edge_precision); defaults to False for compact status.",
      +  "title": "Verbose",
      +  "type": "boolean"
      +}
    • addedOutput schema / properties / data / properties / added_path_count
      Added value: +{
      +  "description": "Total number of new untracked/unindexed paths detected on disk.",
      +  "type": "integer"
      +}
    • changedOutput schema / properties / data / properties / pending_paths / description
      Previous value: -"Up to 100 indexed paths modified on disk since indexing."New value: +"Up to 100 indexed paths modified on disk since indexing (up to 25 when verbose=False)."
  2. Changed2 schema fields changedv0.3.8
    • changedInput schema / properties / repo_id / description
      Previous value: -"Registered repository ID from list_repositories (never a filesystem path)."New value: +"Registered repository ID from list_repositories (never a filesystem path; returns unknown_repo_id if unregistered)."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "additionalProperties": true,
      +  "properties": {
      +    "budget": {
      +      "additionalProperties": true,
      +      "description": "Token budget accounting for this response.",
      +      "properties": {
      +        "envelope_reserve": {
      +          "description": "Wire-framing token reserve when budget >= 512.",
      +          "type": "integer"
      +        },
      +        "estimated_tokens": {
      +          "description": "Estimated serialized response tokens.",
      +          "type": "integer"
      +        },
      +        "requested_tokens": {
      +          "description": "Requested or profile-default token budget.",
      +          "type": "integer"
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "completeness": {
      +      "additionalProperties": true,
      +      "description": "Coverage/resolution completeness indicator.",
      +      "properties": {
      +        "basis": {
      +          "description": "How completeness was computed.",
      +          "type": "string"
      +        },
      +        "value": {
      +          "description": "Completeness ratio in [0.0, 1.0], or null if N/A.",
      +          "type": [
      +            "number",
      +            "null"
      +          ]
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "data": {
      +      "additionalProperties": true,
      +      "description": "Snapshot metadata, counts, role breakdown, and paths modified since indexing.",
      +      "properties": {
      +        "added_paths": {
      +          "description": "Up to 100 new untracked/unindexed paths detected on disk.",
      +          "items": {
      +            "type": "string"
      +          },
      +          "type": "array"
      +        },
      +        "changed_non_indexed": {
      +          "description": "Up to 100 modified non-indexed paths.",
      +          "items": {
      +            "type": "string"
      +          },
      +          "type": "array"
      +        },
      +        "commit_sha": {
      +          "description": "Git HEAD commit SHA recorded when snapshot was built.",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "edges_indexed": {
      +          "description": "Total extracted call/reference edges.",
      +          "type": [
      +            "integer",
      +            "null"
      +          ]
      +        },
      +        "entry_points": {
      +          "description": "Detected entry-point symbol IDs or paths.",
      +          "items": {
      +            "type": "string"
      +          },
      +          "type": "array"
      +        },
      +        "files_indexed": {
      +          "description": "Total indexed source files.",
      +          "type": [
      +            "integer",
      +            "null"
      +          ]
      +        },
      +        "generated_at": {
      +          "description": "ISO timestamp when snapshot was built.",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "head_changed_since_index": {
      +          "description": "True if repository HEAD moved after indexing.",
      +          "type": [
      +            "boolean",
      +            "null"
      +          ]
      +        },
      +        "imported_by": {
      +          "description": "Total distinct imported module targets.",
      +          "type": "integer"
      +        },
      +        "imports": {
      +          "description": "Total recorded lexical import edges.",
      +          "type": "integer"
      +        },
      +        "index_schema_version": {
      +          "description": "SQLite index schema version.",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "index_warnings": {
      +          "description": "Warnings recorded during snapshot build.",
      +          "items": {
      +            "type": "string"
      +          },
      +          "type": "array"
      +        },
      +        "network_policy_status": {
      +          "description": "Declared network policy status.",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "pending_path_count": {
      +          "description": "Total number of modified indexed paths.",
      +          "type": "integer"
      +        },
      +        "pending_paths": {
      +          "description": "Up to 100 indexed paths modified on disk since indexing.",
      +          "items": {
      +            "type": "string"
      +          },
      +          "type": "array"
      +        },
      +        "role_counts": {
      +          "additionalProperties": {
      +            "type": "integer"
      +          },
      +          "description": "Symbol count grouped by role name.",
      +          "type": "object"
      +        },
      +        "symbols_indexed": {
      +          "description": "Total indexed symbols.",
      +          "type": [
      +            "integer",
      +            "null"
      +          ]
      +        },
      +        "symbols_with_roles": {
      +          "description": "Count of symbols assigned architectural roles.",
      +          "type": "integer"
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "edge_precision": {
      +      "additionalProperties": true,
      +      "description": "Resolved vs. ambiguous edge ratio summary.",
      +      "properties": {
      +        "ambiguous_rate": {
      +          "description": "Fraction of edges marked ambiguous.",
      +          "type": [
      +            "number",
      +            "null"
      +          ]
      +        },
      +        "basis": {
      +          "description": "Measurement basis.",
      +          "type": "string"
      +        },
      +        "resolved_rate": {
      +          "description": "Fraction of edges resolved unambiguously.",
      +          "type": [
      +            "number",
      +            "null"
      +          ]
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "error": {
      +      "additionalProperties": true,
      +      "description": "Present when the tool call fails (either a structured {code, message, details} object or a diagnostic string).",
      +      "properties": {
      +        "code": {
      +          "description": "Machine-readable error code.",
      +          "type": "string"
      +        },
      +        "details": {
      +          "description": "Optional structured metadata for the error.",
      +          "type": "object"
      +        },
      +        "message": {
      +          "description": "Human-readable error explanation.",
      +          "type": "string"
      +        }
      +      },
      +      "type": [
      +        "object",
      +        "string"
      +      ]
      +    },
      +    "evidence": {
      +      "description": "Source-verified file line spans and SHA-256 hashes backing the response.",
      +      "items": {
      +        "additionalProperties": true,
      +        "properties": {
      +          "end_line": {
      +            "description": "1-based end line in source.",
      +            "type": "integer"
      +          },
      +          "path": {
      +            "description": "Repository-relative file path.",
      +            "type": "string"
      +          },
      +          "sha256": {
      +            "description": "12-character hex prefix of indexed file SHA-256.",
      +            "type": "string"
      +          },
      +          "start_line": {
      +            "description": "1-based start line in source.",
      +            "type": "integer"
      +          }
      +        },
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "freshness": {
      +      "description": "Index freshness state ('fresh', 'pending', 'stale', or 'unknown').",
      +      "type": "string"
      +    },
      +    "index_run_id": {
      +      "description": "Identifier of the active index snapshot run.",
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    },
      +    "ledger_rev": {
      +      "description": "Current evidence ledger revision for repo_id.",
      +      "type": "integer"
      +    },
      +    "repo_id": {
      +      "description": "Registered repository identifier.",
      +      "type": "string"
      +    },
      +    "schema_version": {
      +      "description": "Envelope schema version ('1.0').",
      +      "type": "string"
      +    },
      +    "truncated": {
      +      "description": "True if items were omitted due to budget or node limits.",
      +      "type": "boolean"
      +    },
      +    "untrusted_repository_content": {
      +      "description": "True when payload embeds raw repository text.",
      +      "type": "boolean"
      +    },
      +    "warnings": {
      +      "description": "Freshness, ambiguity, redaction, or security warnings.",
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    }
      +  },
      +  "type": "object"
      +}
  3. Changed1 schema field changedv0.3.7
    • addedInput schema / properties / repo_id / description
      Added value: +"Registered repository ID from list_repositories (never a filesystem path)."
  4. First observedv0.1.0

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), and the description adds genuine semantic context beyond them: the status vocabulary and the instruction that stale results should reduce trust in derived graph data. It does not say what happens on a pending index or whether the call triggers indexing, which is the remaining gap.

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?

Two compact clauses with the action and status values front-loaded, no filler. The bare word 'counts' is slightly underspecified (counts of what) and the second sentence is telegraphic, but nothing is wasted.

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 exists, so return values need not be spelled out, and the description still surfaces the status enums an agent needs to branch on. Combined with sequencing guidance, this is nearly complete for a two-parameter read-only status check; only failure/pending behavior is left implicit.

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

Parameters3/5

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

Schema coverage is 100%, and the schema itself documents repo_id's registry semantics and the unknown_repo_id error as well as verbose's diagnostic fields, so the description adds nothing on parameters. Baseline 3 is appropriate when the schema does all the work.

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 concrete verb and resource (check index/snapshot status) and enumerates the actual status values ('fresh', 'stale', 'pending', 'unknown') plus the payload elements counts and pending_paths. It also implicitly distinguishes itself from get_repo_map by positioning this as the pre-check before trusting it.

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?

Gives explicit sequencing ('after list_repositories', 'run before trusting get_repo_map or graph edges') and a conditional caution ('treat stale spans cautiously'), so an agent knows both when to call it and how to act on the result. The prerequisite on repo_id is implied by naming list_repositories as the prior step.

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