Skip to main content
Glama
turbyho

fw-context-mcp

by turbyho
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

reindex_file_impl

Re-parse a single source file after edits to update its symbols in the C/C++ index, avoiding a full rebuild.

Instructions

Re-parse a single source file with libclang and update its symbols in the index.

Not read-only — uses the exact compiler flags from compile_commands.json. Use after editing a file to keep the index current without a full rebuild.

A source file must be listed in compile_commands.json. A header is not listed there — compile_commands.json names translation units — so it is re-parsed through one unit that includes it, taken from the manifest. That answer describes a single compilation context, thus the result carries a warning: another unit can see the header under a different set of #define values and still hold stale symbols. Only a full fw-context index covers every context. One unit and not all of them is a cost decision — an application header reaches a median of 3 units but as many as 266 on a real project, at tens of seconds each.

Also regenerates LLM analysis and method override relationships for affected symbols when with_analysis=True. The analysis is content-addressed, thus an unchanged symbol is never re-analysed.

Args: file_path: Path to the file to re-parse. A source file must be in compile_commands.json; a header goes through one including unit. project_root: Project root directory. Auto-detected if omitted. project: Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both. with_analysis: When True (default), also regenerates LLM symbol analysis, method override relationships, PageRank, and embeddings. Set False for a fast symbol-only update (used by background auto-reindex).

Returns: dict: {file, translation_units, symbols_updated, elapsed_s, analysis_updated (if LLM enabled with analysis), or error}.

On failure the dict holds only ``error`` with the reason.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
projectNoProject name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both.
file_pathYesAbsolute or project-relative path to the file to re-parse. A source file must have an entry in compile_commands.json. A header is re-parsed through one translation unit that includes it, and the result then carries a warning that other units can still hold stale symbols.
project_rootNoProject root directory. Auto-detected from cwd if omitted. This field also accepts a project name or a project_id, but project is the clear field for those.
with_analysisNoWhen True (default), also regenerates LLM symbol analysis and method override relationships — slower but produces a fully up-to-date index. Set False for a fast symbol-only update (used by background auto-reindex).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.32.0
    • addedInput schema / properties / file_path / minLength
      Added value: +1
  2. Changed4 schema fields changedv0.30.0
    • addedInput schema / additionalProperties
      Added value: +false
    • changedInput schema / properties / file_path / description
      Previous value: -"Absolute or project-relative path to the source file to re-parse. Must have a matching entry in compile_commands.json."New value: +"Absolute or project-relative path to the file to re-parse. A source file must have an entry in compile_commands.json. A header is re-parsed through one translation unit that includes it, and the result then carries a warning that other units can still hold stale symbols."
    • addedInput schema / properties / project
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both.",
+  "title": "Project"
+}
    • changedInput schema / properties / project_root / description
      Previous value: -"Project root directory. Auto-detected from cwd if omitted."New value: +"Project root directory. Auto-detected from cwd if omitted. This field also accepts a project name or a project_id, but project is the clear field for those."
  3. Changed3 schema fields changedv0.13.1
    • addedInput schema / properties / file_path / description
      Added value: +"Absolute or project-relative path to the source file to re-parse. Must have a matching entry in compile_commands.json."
    • addedInput schema / properties / project_root / description
      Added value: +"Project root directory. Auto-detected from cwd if omitted."
    • addedInput schema / properties / with_analysis / description
      Added value: +"When True (default), also regenerates LLM symbol analysis and method override relationships — slower but produces a fully up-to-date index. Set False for a fast symbol-only update (used by background auto-reindex)."
  4. Addedv0.9.2

TDQS

A4.8/5.0
Behavior5/5

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

With no annotations, the description carries the full burden of behavioral disclosure. It explicitly states 'Not read-only' and explains the use of compiler flags from compile_commands.json. It discloses the header re-parsing limitation and the resulting warning, the cost decision (up to 266 units), and the content-addressed analysis regeneration. It also describes the return dict and error handling, leaving no ambiguity about side effects or outcomes.

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?

The description is long but every sentence earns its place. It is front-loaded with the core purpose, then systematically covers limitations, cost, parameter details, and return format. The structure is logical and the language is dense without being verbose, making it easy for an agent to extract the key facts quickly.

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?

Given the complexity (4 parameters, no output schema), the description is exceptionally complete. It explains the header edge case, the performance tradeoff, the meaning of each parameter, the return value format, and error behavior. Nothing an agent needs to decide whether to call this tool and how to use it correctly is missing.

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 schema coverage is 100%, the description adds substantial meaning beyond the schema. It clarifies the difference between source files and headers for file_path, explains the relationship between project and project_root (alternatives, not both), and details the performance tradeoff of with_analysis. These enrichments go well beyond the schema descriptions, helping the agent select the correct parameter values.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Re-parse a single source file with libclang and update its symbols in the index.' It distinguishes itself from a full rebuild and provides specific details about file types. However, it does not explicitly differentiate from the sibling 'reindex_file' tool, leaving the agent to infer the difference from the name.

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 description gives explicit guidance: 'Use after editing a file to keep the index current without a full rebuild.' It also explains when not to use it ('Only a full fw-context index covers every context') and notes the cost tradeoff of using a single translation unit. It further mentions the with_analysis=False fast path used by background auto-reindex, providing clear context for when to choose this tool over alternatives.

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