What can you do with this server?

fittok is an MCP server that parses codebases into knowledge graphs and retrieves the most relevant source code for LLM queries, minimizing token usage. Core Context Optimization * Retrieve the most relevant source code for a natural language query within a token budget (optimize_context_tool), with variants for streaming, batch, and structured output Codebase Parsing & Graph Management * Parse codebases (Python, JS/TS, Java, Go, Rust) into knowledge graphs (parse_codebase_tool, with streaming support) * Query existing graphs, get stats, force re-parse, or compare two graphs structurally (query_graph_tool, get_graph_stats_tool, reset_graph_tool, diff_graph_tool) * Watch codebases for file changes and incremental graph updates Context Compression * Compress arbitrary text using LLMLingua to hit a target token count (compress_context_tool) PII Scrubbing * Scrub secrets, emails, and API keys from text or files; list or add custom detection patterns Cache Management * Clear caches by scope (all, graph, query, compression) and monitor hit/miss statistics Visualization * Launch a web-based UI to interactively explore the code knowledge graph and highlighted relevant nodes

Which integrations are available for this server?

Provides a fallback LLM option (gpt-4o-mini) for answering codebase questions when the Anthropic key is not set.

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@fittok optimize context from /path/to/code for 'how does auth work?' using 500 tokens" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

fittok

by likhithreddy

Overview Schema Related Servers Score Discussions

Python

Local

fittok

Retrieve only the relevant source code for a question — instead of the model reading whole files — so an LLM answers codebase questions on a small, focused slice of context. Less input = fewer tokens, lower cost, faster answers.

Works three ways from one install: an MCP server, a CLI, and a Python library — plus a Claude Code plugin that injects context automatically.

📖 Full command reference → docs/HANDBOOK.md

mcp-name: io.github.likhithreddy/fittok

How it works

codebase ──▶ graphify ──▶ slurp ──▶ readable slice ──▶ LLM answers
             (parse)      (select)   (trim to budget)

graphify — parses the repo with tree-sitter into a knowledge graph of functions / classes / methods (Python, JS, JSX, TS, TSX, Java, Go, Rust). Supports multi-language call/import/reference edges.
slurp — scores every node against the question using a 4-signal hybrid:
- Semantic embeddings (all-MiniLM-L6-v2) — meaning-based matching
- Content-BM25 (with camelCase/snake_case splitting) — keyword matching
- Summary-BM25 (node name + file + callers + callees) — structural matching
- PageRank — graph centrality / hub detection
Signals are fused via Reciprocal Rank Fusion (RRF) — rank-based, no score calibration issues. Nodes are selected via round-robin directory interleaving (guarantees facet coverage on multi-aspect queries — one node from each code area before any gets a second) with a per-node token cap (25% of budget, so large components don't crowd out smaller functions). A relevance cliff (semantic OR BM25 OR summary-BM25 threshold) excludes noise.
readable output — returns the actual source code of selected nodes, plus a codebase map (table of contents with docstrings, inspired by Karpathy's LLM Wiki / Google's OKF) so the model can route follow-up calls precisely. The model answers directly from it — no file reads needed.

As you edit, a file watcher (auto-started on first query) updates the graph incrementally — only changed files are re-parsed and merged, and only changed functions re-embed. Graphs and embeddings are cached on disk (~/.cache/fittok). Set FITTOK_AUTOWATCH=false to disable the watcher, in which case an edit triggers a full re-parse on the next query.

Related MCP server: cctx-mcp

Getting the best results (and known limitations)

Ask focused questions

fittok ranks code against your question using a 4-signal hybrid (semantic + BM25 + structural + PageRank, fused via RRF) with round-robin directory diversity — so multi-facet questions surface code from multiple areas (UI, server, database) instead of clustering in one dominant area. It's most accurate with focused, specific questions — ideally one concern each, and naming the function/component/route when you can. Multi-facet questions are supported via decomposition (the tool description tells the model to call once per aspect) and the codebase map (a table of contents prepended to every response).

✅ "How does runSandboxQuery execute and isolate a SQL query?" → surfaces the exact function + its isolation code.
✅ "How does the querydle client submit a query and render results?" → surfaces the UI component.
✅ "Trace the full lifecycle: UI submission, sandbox execution, data isolation" → decomposition + round-robin diversity covers multiple facets; the codebase map routes the model to any missed files.

Rule of thumb: one concern per question (or 2–3 facets max). For "explain the whole feature," split it into a few focused questions instead of one mega-query.

Known limitations

GitHub Copilot Chat truncates large MCP outputs (the big one). Copilot caches MCP tool results above ~7 KB to a content.json file, where the entire markdown collapses to ONE physical JSON line (newlines escaped) — and its Read tool truncates any line at ~2,000 characters. So an output over ~7 KB is effectively chopped to ~2,000 chars regardless of total size; the model can't see most of the code and falls back to reading source files directly. This is Copilot's delivery layer, not fittok — every MCP server hits this wall. By default (0.10.0+) fittok returns all relevant code uncapped, which is correct for clients that deliver inline but will be truncated by Copilot. Two workarounds:
- Cap the output for Copilot so it's delivered inline (under the ~7 KB threshold). Set FITTOK_MAX_BUDGET=1200 in your MCP server's env:
  { "servers": { "fittok": { "command": "uvx", "args": ["fittok"], "env": { "FITTOK_MAX_BUDGET": "1200" } } } }
- Use Claude Code or the CLI for multi-file questions. They deliver MCP output inline with no truncation — which is where fittok's complete (uncapped) results and anti-re-read design actually pay off.
Vocabulary gap on abstract queries. When the query uses words that don't appear in the code (e.g. "isolation" → REVOKE/DENY), neither semantic nor BM25 can bridge it. The codebase map (file names + docstrings) and round-robin diversity help; naming the function/file routes the model to it.
Incremental edge-loss: editing a file can drop call/import edges into it from unchanged files until a full re-parse. fittok auto-recovers on restart or reset_graph.
Token counts are approximate: counts use cl100k_base, so real usage drifts ~10–20% vs Claude's tokenizer (only matters when you opt into a FITTOK_MAX_BUDGET cap).
Very large repos: PageRank is not yet vectorized — fine through low-thousands of nodes, slower beyond that.

Installation

fittok ships as an MCP server, a CLI, and a Python library. It uses torch for embeddings, so a Python runtime must be present. Pick one runtime below, then follow the section for your client.

Every config below launches fittok as uvx fittok. If you chose Python or pipx, swap that for python -m fittok or pipx run fittok respectively.

Prerequisites — choose a runtime (one of)

A. uv — recommended (no Python needed on the machine)

curl -LsSf https://astral.sh/uv/install.sh | sh   # Linux / macOS
winget install astral-sh.uv                        # Windows
brew install uv                                    # macOS (Homebrew)

Launch command: uvx fittok — uv provisions its own Python + all deps in isolation. One static binary, so it's deployable org-wide via MDM/Intune/winget.

B. Python 3.10+ (already on the machine)

python -m pip install fittok      # Linux / macOS
py    -m pip install fittok       # Windows

Launch command: python -m fittok (Windows: py -m fittok).

Managed Linux may reject pip install with PEP 668 ("externally-managed-environment") — use option A to avoid it.

C. pipx — isolated, no global install

brew install pipx                               # macOS
pip install --user pipx && pipx ensurepath      # Linux / Windows

Launch command: pipx run fittok.

MCP server — Claude Code

claude mcp add fittok -s user -- uvx fittok

Restart Claude Code → /mcp → confirm fittok is connected, then ask codebase questions normally.

MCP server — VS Code / GitHub Copilot Chat

code --add-mcp '{"name":"fittok","command":"uvx","args":["fittok"]}'

Or paste into .vscode/mcp.json (workspace) or your user mcp.json:

{ "servers": { "fittok": { "type": "stdio", "command": "uvx", "args": ["fittok"] } } }

Then in Copilot Chat: Agent mode → enable fittok's tools (Configure Tools).

MCP server — GitHub Copilot CLI

copilot mcp add fittok -- uvx fittok
copilot mcp get fittok          # verify status + tools

MCP server — Cursor / Windsurf / any MCP client

{ "mcpServers": { "fittok": { "command": "uvx", "args": ["fittok"] } } }

Auto-trigger (optional, every MCP client)

To make fittok fire on every codebase question — without naming it — and stop your client from re-reading files fittok already returned (which would discard the savings), add this one line to your client's instructions file:

"For any codebase question, call fittok first and answer from its output — don't re-read files it already returned code from."

The first half triggers fittok; the second keeps the client from opening the same files afterward. They reinforce each other — one shapes strategy (use fittok), the other stops the double-read. For a stronger, more explicit block:

For any codebase question ("how does X work", "where is Y"):
Call the fittok MCP tool first, once.
Answer directly from its optimized_context — it is the real, authoritative source for that question.
Do NOT read or grep the files fittok already returned code from. That discards the token savings fittok exists to provide.

For the strongest effect, put it in your user-global instructions so it applies to every repo, not just one:

Client	Instructions file
Claude Code	`CLAUDE.md` (repo) or `~/.claude/CLAUDE.md` (user-global)
GitHub Copilot	`.github/copilot-instructions.md` or Copilot user instructions
Cursor	`.cursor/rules/*.mdc` (or `.cursorrules`)
Windsurf	`.windsurfrules`

fittok also bakes this rule into every response (an "answer from this, don't re-read" line above the code), so it works even without the snippet above — the snippet just makes it the client's default across all questions.

CLI

cd /path/to/your/repo

uvx fittok index                                      # optional pre-warm (~15s, cached)
uvx fittok query "how does auth work"                 # LLM answers from relevant code
uvx fittok query "how does auth work" --budget 1500   # cap the slice at 1500 tokens
uvx fittok query "how does auth work" --code          # raw relevant code, no LLM
uvx fittok graph                                      # interactive browser graph
uvx fittok graph --query "auth"                       # graph with relevant nodes highlighted

query sends the relevant code slice to an LLM and streams the answer. Set one key in your shell and it just works:

export ANTHROPIC_API_KEY="sk-ant-..."   # → claude-haiku-4-5  (recommended)
export OPENAI_API_KEY="sk-..."          # → gpt-4o-mini  (fallback)

Users of Claude Code already have ANTHROPIC_API_KEY set — no extra step needed. If neither key is set, fittok falls back to --code and prints a setup hint.

graph requires pyvis: uv pip install "fittok[ui]".

Python library

uv add fittok            # in a uv project   (or:  uv pip install fittok  in a venv)

from fittok import optimize

result = optimize("/path/to/repo", "how does authentication work", token_budget=1500)
print(result["optimized_context"])   # the relevant code slice
print(result["savings"])             # token reduction stats

Upgrading

uvx caches the environment, so a new fittok release isn't picked up automatically — server restarts reuse the cached version. Upgrade with one command (no need to re-register the MCP server):

uvx --refresh fittok        # re-resolve from PyPI → latest version

Then restart the MCP server (reload the window in VS Code, or restart the Copilot CLI) so it boots the new version. For other runtimes:

pip: python -m pip install --upgrade fittok
pipx: pipx upgrade fittok

Why tree-sitter, not LSP?

fittok uses tree-sitter (fast, syntactic AST parsing) instead of LSP (Language Server Protocol — semantic analysis with types, cross-file references, go-to-definition). This is a deliberate tradeoff:

	tree-sitter (fittok)	LSP (e.g. Serena MCP)
What it returns	Actual source code — the model answers directly	Symbol metadata (names, refs, types) — the model must still Read files
Setup	Zero config, works on any directory	Needs language servers installed + project config (tsconfig, pyproject, etc.)
Languages	8 out of the box (Python, JS/TS/TSX, Java, Go, Rust)	Only as many as LSP servers you've installed
Startup	~15s (parse + embed)	Minutes (full project indexing per language)
Memory	~100 MB (graph + embeddings)	500 MB+ per language server
Model calls per question	1–5 (one-shot retrieval)	5–20+ (iterative symbol navigation)
Token cost	~2,500 tokens (code delivered directly)	~15,000+ tokens (metadata + file reads)

fittok's USP is token savings. It returns the actual code in one call so the model doesn't need to read files. LSP-based tools return metadata (symbol names, reference lists) — precise, but the model still has to open the files to see the implementation. More round-trips, more tokens.

The tradeoff: tree-sitter can't resolve cross-file references as accurately as LSP (a fetch("/api/run") call in a .tsx file won't perfectly link to the route handler). fittok compensates with 4-signal retrieval (semantic + content-BM25 + structural summary-BM25 + PageRank, fused via RRF) and round-robin directory diversity — which cover the gap in practice.

Complementary, not competitive: LSP-based tools like Serena excel at symbol-level navigation ("find all callers of runSandboxQuery"). fittok excels at semantic retrieval ("how does SQL execution work?"). Install both — the model picks the right tool per task.

Token savings — honest numbers

On a real Next.js/TS repo (~5k functions), fittok returns a ~1.5–3.5k-token slice instead of the model reading 15–20k+ tokens of files — an ~80–90% reduction on input, deterministic and reported in the savings footer.

On Opus 4.8, a broad question cost ~84k total tokens without fittok vs ~27k with it — because fittok replaced a 58k-token Explore subagent with one tool call.

How to measure it honestly:

Use the 🪙 saved X% footer or your API bill (total tokens).
Do not judge by Claude Code's /context Messages number — it excludes subagent tokens and is dominated by model reasoning, which fittok doesn't touch.

Configuration

Variable	Default	Description
`ANTHROPIC_API_KEY`	—	Enables LLM answers via `claude-haiku-4-5`
`OPENAI_API_KEY`	—	Fallback LLM via `gpt-4o-mini`
`FITTOK_SHOW_SAVINGS`	`true`	`🪙 saved X%` footer on MCP answers; set `false` to disable
`FITTOK_MAX_BUDGET`	`0` (unlimited)	Code-token cap. `0` = return ALL relevant code in full (default — complete results in Claude Code / CLI). Set `1200` for GitHub Copilot, which truncates MCP outputs >~7 KB (see Known limitations).
`FITTOK_AUTOWATCH`	`true`	Auto-start the file watcher so graph updates are incremental (only changed files re-parse); set `false` to fall back to full re-parse on edits
`FITTOK_EMBED_MODEL`	`all-MiniLM-L6-v2`	Embedding model
`FITTOK_DEVICE`	`auto`	`auto` / `cuda` / `mps` / `cpu`
`FITTOK_CACHE_DIR`	`~/.cache/fittok`	Cache location

Full reference: docs/HANDBOOK.md

Requirements

Python ≥ 3.10. First run downloads a ~90 MB embedding model. Graph visualization (fittok graph) is included by default. Optional extras:

uv pip install "fittok[ui]" — Gradio web dashboard (launch_ui tool)
uv pip install "fittok[gpu]" — torch/CUDA for GPU-accelerated embeddings

License

MIT

Available Tools

20 tools

add_pii_pattern_toolC

Add or override a PII detection pattern.

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes
`regex`	Yes

TDQS

C2.4/5.0

Behavior2/5

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

The description indicates an action that mutates state, but provides no details on persistence, reversibility, or side effects. Since no annotations are present, the description carries the full burden but fails to disclose important behavioral traits.

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

Conciseness3/5

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

The description is extremely short (one sentence) and front-loaded, but arguably too concise for a tool with two parameters and no annotations. It could be more efficient by adding necessary details without becoming verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of annotations and output schema, the description is incomplete. It does not explain the effect of adding/overriding a pattern, expected format for regex, or what happens on conflict. More context is needed for an agent to use it correctly.

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

Parameters1/5

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

The input schema has 0% description coverage, and the tool description adds no meaning beyond the parameter names 'name' and 'regex'. It does not explain expected formats, constraints, or behavior (e.g., whether name must be unique).

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 action (add or override) and the resource (PII detection pattern). It distinguishes from siblings like list_pii_patterns_tool and scrub_text_tool, but does not clarify the distinction between 'add' and 'override'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives, such as when a pattern already exists or when listing is needed first. The usage context is implied but not explicit.

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

cache_stats_toolB

Return cache hit/miss statistics and size.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

B3/5.0

Behavior2/5

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

No annotations exist, so the description must fully disclose behavior. It states it returns stats, implying a read operation, but does not confirm safety (no destructive effects) or mention any side effects. The lack of detail leaves uncertainty.

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?

The description is a single, clear sentence with no waste. It could add a bit more detail (e.g., 'Returns a JSON object with hit/miss counts and total size') without losing conciseness, but current form is still efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and no annotations, the description should hint at the return format. It only says 'cache hit/miss statistics and size' without specifying structure, units, or whether the size is in bytes/entries. This is insufficient for an agent to interpret results without further context.

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?

No parameters exist, so schema coverage is trivially 100%. Per the baseline rule for zero parameters, the description adds no param info but does not need to. Score reflects the baseline.

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 it returns cache statistics and size, with a verb+resource structure. It distinguishes from siblings like clear_cache_tool. However, it could be more specific about what 'size' refers to (e.g., total entries, bytes).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like clear_cache_tool or compress_context_tool. The agent is given no context on prerequisites or scenarios.

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

clear_cache_toolB

Clear the cache. Scope: 'all' | 'graph' | 'query' | 'compression'.

ParametersJSON Schema

Name	Required	Description	Default
`scope`	No		all

TDQS

B3.2/5.0

Behavior2/5

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

The description mentions scope options but lacks details about the destructive nature of clearing caches, permissions needed, or potential side effects. With no annotations, the description carries full burden and falls short.

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?

Extremely concise: two sentences with the verb first. Every word adds value, and the structure is clean.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one parameter and no output schema, the description is adequate but could be more complete by explaining consequences of clearing different scopes and whether the operation is reversible.

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 0%, but the description lists valid scope values ('all', 'graph', 'query', 'compression'), adding meaning beyond the schema's generic string type. However, it doesn't explain what each scope clears.

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 action (Clear the cache) and lists specific scopes ('all', 'graph', 'query', 'compression'), making the purpose distinct from siblings like cache_stats_tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. It only states the action without context for decision making.

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

compress_context_toolD

Compress text context using LLMLingua with a local model.

ParametersJSON Schema

Name	Required	Description	Default
`context`	Yes
`question`	Yes
`target_tokens`	No
`rate`	No

TDQS

D1.8/5.0

Behavior2/5

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

With no annotations, description must disclose behavioral traits. It only mentions 'compress' and the method, but omits side effects, idempotency, or output expectations. Minimal transparency.

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

Conciseness2/5

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

Single sentence is concise but not effective; it lacks essential details and fails to earn its place as a complete description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 4 parameters, no output schema, and 0% schema coverage, the description fails to explain parameter purposes or use case, making it incomplete for agent invocation.

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

Parameters1/5

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

Schema coverage is 0% and description adds no meaning to parameters. 'question' and 'rate' remain unexplained beyond their names.

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

Purpose3/5

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

Description states verb 'compress' and resource 'text context' with method 'using LLMLingua with a local model'. It is clear but overly generic; does not distinguish from sibling optimization tools that also manage context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like optimize_context_tool. Missing usage context entirely.

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

diff_graph_toolC

Compare two knowledge graphs and return structural differences.

ParametersJSON Schema

Name	Required	Description	Default
`graph_path_a`	Yes
`graph_path_b`	Yes

TDQS

C2.8/5.0

Behavior2/5

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

No annotations exist, so the description must carry the full burden. It only states the basic action (compare, return differences) without disclosing side effects, authentication needs, error behavior, or output structure.

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?

The description is a single sentence with no wasted words, achieving conciseness. However, it lacks structural elements like bullet points or examples that would improve scannability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of output schema and annotations, the description is too sparse. It fails to explain what 'structural differences' means, what the output looks like, or how to handle invalid inputs.

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

Parameters1/5

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

Schema description coverage is 0% and the description adds no information about the parameters beyond their names. The paths are not explained (e.g., file paths, URLs, or graph identifiers).

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 states the tool compares two knowledge graphs and returns structural differences. This clearly identifies the verb ('compare') and resource ('knowledge graphs'), but does not differentiate from siblings like get_graph_stats_tool or query_graph_tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when comparing two graphs, but provides no explicit guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions.

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

get_graph_stats_toolC

Return metadata and stats for a graph.

ParametersJSON Schema

Name	Required	Description	Default
`graph_path`	Yes

TDQS

C2.6/5.0

Behavior2/5

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

With no annotations, the description should disclose behavioral traits such as read-only nature, potential errors, or performance implications. It only states the function without any additional transparency.

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?

The description is a single concise sentence, which is efficient. However, it could be expanded to include necessary details while remaining well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of output schema and parameter description, the description is incomplete. It fails to inform the user about the returned data or how to use the tool effectively.

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

Parameters1/5

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

The sole parameter 'graph_path' has no description in the schema, and the tool description does not explain what it represents (e.g., file path, identifier). This provides zero value beyond the schema.

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?

Description clearly states the verb 'Return' and resource 'metadata and stats for a graph', distinguishing it from querying or diff tools. However, it lacks specificity about what metadata/stats are included, which could be improved.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus siblings like query_graph_tool or diff_graph_tool. The description provides no context for appropriate usage scenarios.

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

launch_ui_toolC

Launch the web visualization UI for graph exploration.

ParametersJSON Schema

Name	Required	Description	Default
`port`	No
`open_browser`	No

TDQS

C2.9/5.0

Behavior2/5

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

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It only says 'Launch the web visualization UI' without mentioning side effects like port binding, browser opening, or any state changes. The parameters imply behavior but are not discussed.

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

Conciseness3/5

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

The description is a single sentence, which is front-loaded but overly sparse. It is too minimal to be considered well-structured; it prioritizes brevity over completeness. A 3 reflects adequacy but with clear gaps.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with two parameters, no output schema, and no annotations, the description is incomplete. It fails to convey return behavior, parameter usage, or any operational context. The minimal description leaves the agent underinformed.

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

Parameters2/5

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

Schema description coverage is 0%, and the description adds no meaning beyond the schema's parameter names and defaults. It does not explain what 'port' or 'open_browser' control, leaving the agent to infer from their titles and defaults alone.

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 clearly states it launches a web visualization UI for graph exploration. The verb 'launch' is specific, and the resource 'web visualization UI' is distinct from sibling tools that deal with PII patterns, caching, or graph analysis.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. The description lacks any context on prerequisites, scenarios, or exclusions. Given the lack of context signals (e.g., no annotations), the agent receives no help in deciding when to invoke this tool.

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

list_pii_patterns_toolA

List all registered PII detection patterns.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4/5.0

Behavior3/5

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

No annotations are provided, so the description must fully disclose behavior. It correctly indicates a read operation, but it fails to describe the output format (e.g., pattern names, IDs), potential size of results, or any side effects. The minimal description leaves some ambiguity.

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 a single sentence that efficiently conveys the tool's purpose with no unnecessary words. It is front-loaded and directly to the point.

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?

Given the tool's simplicity (zero parameters, no nested objects) and the absence of an output schema, the description is sufficient for an agent to understand the tool's basic function. However, it could be improved by mentioning the nature of the returned list (e.g., pattern names and IDs) to provide full context.

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?

The tool has zero parameters, and the schema coverage is 100%. Per guidelines, the baseline is 4 for zero-parameter tools. The description does not need to add parameter meaning, but it is clear that no arguments are required.

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 uses a specific verb ('List') and a clear resource ('all registered PII detection patterns'). It distinguishes this tool from sibling tools like 'add_pii_pattern_tool' and 'scrub_text_tool' by explicitly stating it lists patterns.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for viewing patterns, but it does not provide explicit guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or exclusions. The context is clear but incomplete.

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

optimize_context_batchC

One parse, many queries. Builds graph once, runs slurp+compress per query.

ParametersJSON Schema

Name	Required	Description	Default
`codebase_path`	Yes
`queries`	Yes
`token_budget`	No

TDQS

C2.4/5.0

Behavior2/5

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It mentions building a graph once and performing 'slurp+compress' per query, but does not clarify side effects (e.g., caching, data persistence), resource consumption, error handling, or whether the operation is read-only or destructive. The term 'slurp+compress' is undefined.

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

Conciseness3/5

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

The description is very concise (one short sentence), which is good for brevity. However, it uses jargon ('slurp+compress') without explanation, which may confuse an agent. The structure is front-loaded but lacks detail on parameters and use cases.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (3 parameters, 0% schema coverage, no output schema, 19 siblings), the description is insufficient. It does not explain return values, error behavior, or how to use the 'token_budget' parameter. An agent would likely need to guess or experiment to use the tool correctly.

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

Parameters1/5

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

The description adds no meaning to any of the three parameters. Schema description coverage is 0%, and the description does not mention 'codebase_path', 'queries', or 'token_budget'. It fails to explain how these parameters influence the tool's behavior, leaving the agent without guidance.

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 core functionality: 'One parse, many queries' and 'Builds graph once, runs slurp+compress per query'. It effectively conveys that this tool performs batch processing across multiple queries on a single parsed codebase. The mention of 'slurp+compress' is jargon but understandable in context. It distinguishes itself from siblings like 'optimize_context_tool' by implying batch processing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no explicit guidance on when to use this tool versus its siblings or other tools. It does not mention scenarios, prerequisites, or exclusions. The batch nature is implied but not directly compared to single-query variants. An agent would need to infer usage context from the tool name and siblings.

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

optimize_context_streamC

Streaming pipeline: yields stage-by-stage progress events.

Returns a list of event dicts in order: [{"stage": "parsing", "status": "started"}, ...]

ParametersJSON Schema

Name	Required	Description	Default
`codebase_path`	Yes
`query`	Yes
`token_budget`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

C2.7/5.0

Behavior3/5

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

The description discloses the behavior of yielding progress events and returning a list of event dicts. Without annotations, it provides basic transparency but lacks details on side effects, state changes, authorization needs, or rate limits. It does not contradict any annotations since none exist.

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

Conciseness3/5

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

The description is concise with two sentences, but it omits critical information such as parameter semantics and usage context. While efficient, it sacrifices completeness for brevity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of a streaming pipeline tool with three parameters and no annotation support, the description is incomplete. It fails to explain the parameters, and the output example is partial, lacking full schema details. The agent would have insufficient context to use the tool correctly.

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

Parameters1/5

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

With 0% schema description coverage, the description must compensate, but it does not mention any of the three parameters (codebase_path, query, token_budget). No explanation of their meaning or role is provided, leaving the agent without guidance.

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 identifies the tool as a streaming pipeline that yields stage-by-stage progress events and returns a list of event dicts, which is specific. However, it does not explicitly state the overall optimization purpose hinted by the name, nor does it distinguish from siblings like optimize_context_batch or optimize_context_structured.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives such as optimize_context_batch or optimize_context_structured. There is no mention of prerequisites, conditions, or when not to use it.

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

optimize_context_structuredD

Full pipeline with structured JSON output mode.

Args: output_format: "markdown" (default) or "json" for structured output.

ParametersJSON Schema

Name	Required	Default
`codebase_path`	Yes
`query`	Yes
`token_budget`	No
`output_format`	No	markdown

TDQS

D1.3/5.0

Behavior1/5

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

No annotations are provided, and the description does not disclose any behavioral traits (e.g., whether it modifies state, permissions needed, side effects). It only mentions output format, which is already in the schema.

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

Conciseness2/5

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

The description is very short, but this results from under-specification rather than efficient communication. Every sentence should add value; here, the second sentence merely restates a parameter default.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/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, multiple siblings), the description is completely inadequate. It does not explain the tool's purpose, behavior, or when to use it, leaving the agent without essential information.

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

Parameters1/5

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

Schema description coverage is 0%. The description only mentions the output_format parameter, but adds no further meaning to any of the four parameters. This is a significant gap; the description fails to compensate for the lack of schema documentation.

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

Purpose2/5

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

The description states 'Full pipeline with structured JSON output mode' but does not specify what the pipeline does. It lacks a clear verb and resource, making it vague. Compared to calibration, this is above a tautology but still minimal.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus its siblings (optimize_context_batch, optimize_context_stream, optimize_context_tool). The description provides no context for tool selection.

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

optimize_context_toolA

Return the most relevant REAL source code for a question, within a token budget.

Use this FIRST for any "how does X work / where is Y" question about the codebase, and prefer it over reading files or grepping. Call it ONCE per question: the returned optimized_context contains the relevant code — answer directly from it and do NOT separately read the files it came from (that defeats the whole point of the token savings).

ParametersJSON Schema

Name	Required	Description	Default
`codebase_path`	Yes
`query`	Yes
`token_budget`	No

TDQS

A3.9/5.0

Behavior4/5

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

With no annotations, the description does a good job disclosing behavior: it returns relevant code within a token budget, warns against separate file reading, and implies a read-only operation. It does not mention authorization needs or rate limits, but for a read-only tool, the transparency is adequate.

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?

The description is concise (about 60 words) and front-loaded with the main purpose. Each sentence adds value: purpose, usage guidance, and a prohibition. No unnecessary words, though it could be structured slightly better.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers the main functionality and usage well, but lacks parameter descriptions, return format details beyond mentioning optimized_context, and differentiation from several very similar sibling tools (optimize_context_batch, stream, structured). Given no output schema, some return info would help.

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

Parameters2/5

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

Schema description coverage is 0%, meaning no parameter descriptions exist. The description mentions 'token budget' but does not explain the parameters (codebase_path, query, token_budget) beyond their names. It adds minimal value beyond the schema parameter names.

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?

Description clearly states it returns the most relevant source code within a token budget, uses a specific verb ('Return'), and distinguishes from alternatives like reading files or grepping. It also provides context about when to use it (for 'how does X work / where is Y' questions).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly instructs to use this tool first for codebase questions, prefer it over file reading/grepping, and call it once per question. It also tells the assistant not to separately read the files. However, it does not compare with similar sibling tools like optimize_context_batch or optimize_context_structured.

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

parse_codebase_stream_toolC

Stream parse progress. Parses in batches, returns progress events.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`batch_size`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

C2.9/5.0

Behavior3/5

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

Without annotations, the description carries the burden of behavioral disclosure. It mentions streaming, batching, and progress events, which give basic behavioral context. However, it lacks details on side effects, rate limits, or the nature of progress events.

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?

The description is very short (two sentences) and front-loaded, which is efficient. However, it sacrifices informativeness for brevity; a slightly longer description could add value without losing conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the existence of an output schema (not shown) and moderate complexity (2 parameters), the description is insufficient. It does not cover input semantics, output format, or how progress events are structured, leaving gaps for confident tool use.

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

Parameters2/5

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

Schema coverage is 0% (no parameter descriptions). The description does not explain the 'path' parameter or clarify the meaning of 'batch_size' beyond its default value. This leaves parameters semantically under-defined.

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 it streams parse progress and returns progress events, distinguishing it from a non-stream sibling (parse_codebase_tool). However, it does not specify what is being parsed, though 'codebase' is implied by the tool name.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like parse_codebase_tool, or any prerequisites or context for its use.

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

parse_codebase_toolC

Parse all code files in a directory into a knowledge graph.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes

TDQS

C2.6/5.0

Behavior2/5

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

With no annotations provided, the description carries full burden but only states a high-level action. It does not disclose whether parsing is recursive, permissions needed, effects on existing graph (overwrite vs merge), or error handling. This lack of behavioral detail limits agent understanding.

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

Conciseness2/5

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

The description is a single sentence, which is concise but at the cost of missing critical details about parameters, usage, and behavior. It is under-specified, not efficiently conveying necessary information for an agent.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (parsing a codebase into a graph) and lack of annotations, output schema, or param description, the description is far from complete. It omits language support, recursion, state interactions, and error behavior, making it insufficient for reliable agent use.

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

Parameters1/5

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

The description does not explain the single parameter 'path' beyond implying it is a directory. With 0% schema description coverage, the description adds no value over the schema. It fails to specify format (absolute/relative), valid values, or constraints, leaving the agent without essential guidance.

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 clearly states a specific verb ('Parse'), resource ('code files in a directory'), and outcome ('into a knowledge graph'), distinguishing it from siblings like 'query_graph_tool' or 'reset_graph_tool'. However, it does not differentiate from 'parse_codebase_stream_tool' (streaming vs batch) but the core purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description fails to provide any guidance on when to use this tool versus alternatives, such as 'parse_codebase_stream_tool'. No context about prerequisites, when not to use, or preferred scenarios is given, leaving the agent to infer usage.

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

query_graph_toolC

Query a knowledge graph for the most relevant subgraph within a token budget.

ParametersJSON Schema

Name	Required	Description	Default
`graph_path`	Yes
`query`	Yes
`token_budget`	No

TDQS

C2.7/5.0

Behavior3/5

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

With no annotations, the description carries full burden. It indicates the tool retrieves a subgraph without modifying the graph, but does not explain how 'most relevant' is determined, the effect of 'token_budget', or any authentication needs. It is adequate but not detailed.

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

Conciseness3/5

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

The description is a single sentence, which is concise but lacks structure. It does not separate purpose from parameter details or usage notes, making it less scannable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has three parameters, no output schema, and no annotations, the description is insufficient. It fails to clarify the required 'graph_path', the query format, what constitutes 'relevant', or the output structure. A more complete description is needed for correct invocation.

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

Parameters1/5

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

Schema description coverage is 0%, and the description adds no parameter information. The parameters 'graph_path', 'query', and 'token_budget' are not described. The description only vaguely references the token budget without clarifying its format or usage.

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 action (Query), the resource (knowledge graph), and the specific outcome (most relevant subgraph within a token budget). This distinguishes it from sibling tools like 'get_graph_stats_tool' or 'diff_graph_tool', though no explicit differentiation is made.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance provided on when to use this tool versus alternatives like 'optimize_context_tool' or 'compress_context_tool'. The description does not mention prerequisites, scenarios, or when to avoid using it.

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

reset_graph_toolC

Force a full re-parse of the codebase, ignoring cache.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes

TDQS

C2.7/5.0

Behavior3/5

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

Given no annotations, the description carries the full burden. It transparently states the tool forces a full re-parse and ignores cache, which implies it may be slower and destructive to cached state. However, it does not disclose what happens to existing graph state, required permissions, or potential risks. It is adequate but not rich.

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?

The description is a single, brief sentence that front-loads the core action. Every word serves a purpose. It could be slightly expanded to include parameter details without becoming verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With one undocumented parameter, no output schema, and no annotations, the description is incomplete. It fails to explain how to use the tool (e.g., what value to provide for 'path') or what the outcome looks like. It only covers the high-level operation.

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

Parameters1/5

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

Schema coverage is 0%, so the description must explain parameters. It provides no explanation of the required 'path' parameter—what it represents (e.g., directory path, file path) or constraints. This is a significant gap for a single-parameter tool.

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 it forces a full re-parse of the codebase while ignoring cache. The verb 'force' and resource 're-parse of the codebase' are specific. It implicitly distinguishes from siblings like parse_codebase_tool (which may not ignore cache) and clear_cache_tool (which clears but doesn't re-parse). However, explicit differentiation is missing, so it loses a point.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like clear_cache_tool or parse_codebase_tool. There is no mention of prerequisites, side effects, or typical use cases. The agent is left to infer usage context.

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

scrub_file_toolC

Scrub PII from a file.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`output_path`	No

TDQS

C2.4/5.0

Behavior1/5

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

No annotations are provided, and the description fails to disclose behavioral traits such as whether the file is modified in-place, what PII patterns are applied, error handling, or if the operation is reversible. The description is insufficient for understanding the tool's behavior.

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

Conciseness2/5

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

The description is extremely brief (5 words), which is concise but comes at the cost of completeness. It is underspecified and fails to convey essential information. Every sentence should earn its place; here, a single phrase is insufficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the absence of annotations, output schema, and parameter explanations, the description is severely incomplete. It does not cover return values, side effects, supported file formats, or performance implications. A tool with two parameters and no additional context needs a richer description.

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

Parameters2/5

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

With 0% schema description coverage, the description must explain the parameters, but it does not. The 'path' parameter likely specifies the file location, and 'output_path' likely defines an alternative output location, but this is not stated. The description adds no value beyond the schema itself.

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 'Scrub PII from a file' clearly specifies the action (scrub PII) and the resource (a file). It is concise and distinguishes this tool from sibling 'scrub_text_tool' which operates on text strings, not files.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool over alternatives like 'scrub_text_tool'. It lacks context about suitable file types, prerequisites, or conditions that favor this tool.

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

scrub_text_toolC

Scrub PII (secrets, emails, API keys, etc.) from text.

ParametersJSON Schema

Name	Required	Description	Default
`text`	Yes
`custom_patterns`	No

TDQS

C2.6/5.0

Behavior2/5

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

No annotations are present, and the description does not disclose behavioral traits such as side effects, safety, or whether the tool returns modified text. It only states the high-level action without details on how it behaves.

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

Conciseness2/5

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

The description is extremely short (one sentence) but lacks necessary information. While concise, it sacrifices completeness, missing details on parameters and usage context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has two parameters and no output schema, the description is incomplete. It does not describe the return value, behavior of custom patterns, or any additional context needed for effective use.

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

Parameters1/5

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

Schema description coverage is 0%, and the description does not explain the 'custom_patterns' parameter at all. It adds no meaning beyond what the schema provides (name and type), leaving the agent without guidance on how to use the parameter.

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 clearly states the tool's purpose: scrubbing PII (secrets, emails, API keys) from text. The verb 'scrub' and the resource 'text' are specific, and it distinguishes itself from the sibling 'scrub_file_tool' which targets files.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like 'scrub_file_tool' or when not to use it. There is no mention of prerequisites, context, or exclusions.

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

watch_start_toolC

Start watching a codebase for incremental graph updates.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes

TDQS

C2.7/5.0

Behavior2/5

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

With no annotations, the description must convey behavioral traits but fails to do so. It does not explain what 'watching' entails (e.g., monitoring interval, resource usage, side effects) or whether it is safe to call multiple times.

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

Conciseness3/5

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

The description is appropriately short (one sentence) and front-loaded, but it omits essential information. Conciseness should not come at the cost of clarity and completeness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (no output schema, one parameter), the description is incomplete. It lacks details on return value (e.g., watch identifier), termination conditions, and interaction with watch_stop_tool.

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

Parameters1/5

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

The only parameter 'path' is not described beyond its name. Schema coverage is 0%, and the description does not clarify what path format is expected (absolute, relative, directory or file) or its role in the watch operation.

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 clearly states the action ('Start watching a codebase') and the purpose ('for incremental graph updates'). It distinguishes the tool from siblings like parse_codebase_tool (parsing) and watch_stop_tool (stopping).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives, such as parse_codebase_tool or query_graph_tool. There are no prerequisites, postconditions, or context about the watch lifecycle mentioned.

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

watch_stop_toolC

Stop watching a codebase.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes

TDQS

C2.4/5.0

Behavior2/5

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

With no annotations, the description should reveal behavioral traits, but it only states the action. It does not mention potential side effects, reversibility, or state changes beyond stopping.

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

Conciseness3/5

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

The description is extremely concise at 3 words, but lacks necessary detail. While succinct, it is under-specified for effective tool usage.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one parameter and no output schema, the description still falls short. It doesn't explain the concept of 'watching' or how to use the path, leaving the agent with insufficient context.

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

Parameters1/5

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

The description adds no meaning to the 'path' parameter from the input schema. With 0% schema description coverage, the description should compensate but fails to explain what path refers to or its format.

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 verb 'stop' and the resource 'watching a codebase', which is specific. However, it does not distinguish from the sibling tool 'watch_start_tool', missing an opportunity to clarify the relationship.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives, no prerequisites or context provided. The agent has no information about preconditions or limitations.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

20 tool updatesv0.3.0Jun 13, 2026
- First observedadd_pii_pattern_tool
- First observedcache_stats_tool
- First observedclear_cache_tool
- First observedcompress_context_tool
- First observeddiff_graph_tool
- First observedget_graph_stats_tool
- First observedlaunch_ui_tool
- First observedlist_pii_patterns_tool
- First observedoptimize_context_batch
- First observedoptimize_context_stream
- First observedoptimize_context_structured
- First observedoptimize_context_tool
- First observedparse_codebase_stream_tool
- First observedparse_codebase_tool
- First observedquery_graph_tool
- First observedreset_graph_tool
- First observedscrub_file_tool
- First observedscrub_text_tool
- First observedwatch_start_tool
- First observedwatch_stop_tool

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

C2.5/5.0

Disambiguation4/5

Most tools have distinct purposes, with PII, cache, graph, and context optimization groups clearly separated. However, the optimize_context_* series (batch, stream, structured, tool) may cause confusion as they all relate to context optimization with different modes, but detailed descriptions help differentiate.

Naming Consistency3/5

Most tools use snake_case with '_tool' suffix (e.g., add_pii_pattern_tool, clear_cache_tool), but several like optimize_context_batch, optimize_context_stream, and optimize_context_structured lack the suffix, creating inconsistency.

Tool Count4/5

20 tools cover a complex domain including parsing, caching, PII, context optimization, graph queries, and UI. While on the higher side, each tool serves a specific function and the count is appropriate for the server's scope.

Completeness3/5

The tool set covers major operations like parsing, querying, caching, and PII scrubbing. However, missing operations such as deleting a PII pattern or explicitly deleting a graph (only reset exists) leave minor gaps in lifecycle management.

Maintenance

ActivityMaintained

ResponsivenessSyncing

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

gread A
io.github.NitroRCr
An MCP server that gives your AI access to the source code and docs of all public github repos
Version Control Code Analysis Documentation Access
5361
mcp A
ai.llmse
Public MCP server for the LLM Search Engine
Search RAG Systems Developer Tools
102
anotherai
dev.anotherai
MCP server for building and testing AI agents with multi-model experimentation and insights.
Agent Orchestration Autonomous Agents Testing & QA Tools
2
driflyte-mcp-server
com.driflyte
Driflyte MCP server which lets AI assistants query topic-specific knowledge from web and GitHub.
Search Web Scraping Knowledge & Memory
211

Related MCP Servers

claw-tsaver
AI & Machine Learning Autonomous Agents Developer Tools
Yang1Bai
A
license
A
quality
C
maintenance
An MCP server that helps AI agents reduce token usage by compressing, summarizing, and managing conversation/context data more efficiently.
Updated 4 months ago (2026-05-20 00:30 UTC)
1
1
MIT
cctx-mcp
Developer Tools Code Analysis Version Control
nikondrat
A
license
Not graded
quality
C
maintenance
An MCP server that provides structure-aware code analysis (symbol trees, dependencies, docs) to reduce AI agent token consumption by up to 99%, along with Git commit intelligence.
Updated 2 months ago (2026-06-29 14:16 UTC)
MIT
cerberus-mcp
Code Analysis Developer Tools
Undermybelt
A
license
Not graded
quality
C
maintenance
An MCP server that provides ultra-efficient code exploration through AST analysis, reducing LLM token usage by up to 95% while enabling instant call graph generation and dependency analysis for massive codebases.
Updated 7 months ago (2026-02-11 07:23 UTC)
MIT
contextsliver
Code Analysis Knowledge & Memory Developer Tools
DevMuneeb
A
license
Not graded
quality
A
maintenance
An MCP server that indexes codebases into a local graph and provides on-demand context retrieval for AI coding agents, reducing token usage by tracking session history and delivering only relevant code subgraphs.
Updated a month ago (2026-07-24 18:02 UTC)
14
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/likhithreddy/fittok'

If you have feedback or need assistance with the MCP directory API, please join our Discord server