This MCP server provides privacy-preserving, read-only-by-default access to private local files and GitHub issues, exposing redacted content through opaque @p_ references.
Navigate private directories: redctx_tree and redctx_list return redacted file trees and listings with opaque ids.
Read file contents: redctx_read supports paths or @p_<id> references, line ranges, and character limits.
Search redacted text: redctx_search runs literal or regex queries with context lines, case control, and result caps.
Retrieve relevant passages: redctx_retrieve ranks passages by query-term coverage and BM25 relevance, returning opaque references and line ranges.
Inspect metadata: redctx_stat shows redacted file metadata.
Bundle context: redctx_bundle concatenates multiple redacted files with size and file-count limits.
Admin checks: redctx_doctor reports redaction setup counts without printing sensitive terms; redctx_audit runs local containment and redaction checks.
Refresh path index: redctx_refresh_index reloads the in-memory opaque path index.
GitHub integration: redctx_github_repos, redctx_github_list_issues, redctx_github_read_issue, and redctx_github_search_issues expose redacted GitHub issues through neutral repo aliases.
MCP resources: redacted files are available as redctx://p_<id> resource URIs.
Controlled writes (optional): with --enable-writes, redctx_submit_doc lets agents write redacted documents into a configured write subdirectory, rehydrating placeholders locally.
Live config reload: redaction rules and term files are checked before each call, so updated policies take effect without restarting the server.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Redacted Context MCP search for architecture notes about deployment"
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.
Give coding agents useful local project context without exposing raw client names, people, email addresses, URLs, phone numbers, secrets, or meaningful filenames.
redacted-context-mcp is a read-only-by-default MCP server and CLI. It lets an
agent search, navigate, and read useful content from a private local folder
while replacing sensitive text and returning opaque file references.
Before redaction:
Client Example Lantern Labs uses production-db.internal.example
Contact avery@example.com about PROJECT-LANTERN-042.Agent-visible result:
Client [ORG_a81f29d4a9c1e672540f68afc10d22c7] uses [DOMAIN_d12c88e1f730065c97d3f82f06d1188c].
Contact [EMAIL_711ae704108cd6e952dcb27f0d6e999a] about [SENSITIVE_45f80ab22bc94e105a93aa830c7d3b9c].The placeholder values above are illustrative. Real values are deterministic for one local vault salt and will differ.
Python 3.11 or newer is required. Install the commands with pipx, then use a
local Ollama model to draft the project-specific redaction terms:
pipx install redacted-context-mcp
ollama pull gemma4:e4b
redctx --root ~/private-context discover \
--model gemma4:e4b \
--output .agent-context-redactor.tomlReview the generated .agent-context-redactor.toml because it intentionally
contains the raw names and terms that should be hidden. Then audit the setup
and start the stdio MCP server:
redctx --root ~/private-context audit
redctx-mcp --root ~/private-contextDiscovery is explicit: audit does not call a model or generate this config.
Without an explicit config, the built-in detectors still cover common emails,
URLs, phone numbers, domains, secrets, and some names, but project-specific
client names and codenames may be missed. To avoid Ollama, create the config
manually using the Local Redaction Config example.
The server waits for an MCP client on standard input; press Ctrl-C if you start it directly in a terminal. For a no-credentials walkthrough using fictional data, see the self-contained quick-start demo.
Claude Code is one of the clients already supported by this repository. Put
the following in the agent workspace's .mcp.json, replacing the root with an
absolute path to the private context folder:
{
"mcpServers": {
"redacted_context": {
"type": "stdio",
"command": "redctx-mcp",
"args": [
"--root",
"/absolute/path/to/private-context"
]
}
}
}The same installed redctx-mcp command can be used with the Codex and generic
stdio configurations documented below.
Related MCP server: Context MCP
This project provides practical privacy guardrails, not guaranteed anonymization, sandboxing, cryptographic isolation, complete DLP, or perfect prevention of metadata leakage. File sizes, line counts, and timing remain possible metadata side channels.
The protection can be bypassed if the coding agent can also read the unredacted source directory through shell commands or other filesystem tools. For hard enforcement, run the agent as a separate OS user or in a container that cannot access that directory directly, and expose only the MCP server or a separate redaction service.
Read SECURITY.md for the threat model and SECURITY_INVARIANTS.md for the behavior the test suite is intended to preserve.
The core workflow is:
agent workspace
-> redacted MCP tools
-> private source folder
-> redacted output with opaque @p_<id> file referencesDual-era MCP stdio server supporting stateless 2026-07-28 clients and
legacy initialization-based clients through 2025-11-25.
Redacted MCP resources using redctx://p_<id> URIs.
Optional MCP redctx_submit_doc tool for controlled writes of generated
redacted documents back into a configured private-root subdirectory.
CLI fallback with the same redaction behavior.
Local-salted opaque stable path ids such as @p_1a2b3c4d5e6f.
Deterministic 128-bit HMAC placeholders such as
[PERSON_1a2b3c4d5e6f7890a1b2c3d4e5f60718].
Bounded operation budgets for traversals, reads, bundles, searches, audits, benchmarks, discovery samples, MCP resource listing/reads, and controlled write rehydration scans.
Redacted tree, list, read, search, stat, bundle, audit, and
benchmark operations.
CLI-only rehydrate command for restoring redacted exports locally from the
private source root.
Local ignored redaction config for exact client, person, organization, and project terms.
Optional local-LLM discovery command to draft that config from private files without sending content to Claude or a hosted model.
No runtime Python dependencies.
Optional local DOCX, PPTX, PDF, XLSX, and XLS extraction using Microsoft MarkItDown.
Ranked multi-word passage retrieval with opaque references and line citations.
Works well with a neutral agent workspace that does not contain raw context files.
Use this when you want an agent to reason over a private local folder without handing the model the raw names and identifiers in that folder.
Good fits:
consulting or client delivery knowledgebases;
internal project notes, stakeholder notes, and transcripts;
architecture or governance documentation with private names mixed in;
private GitHub issues that should be summarized through neutral aliases.
Do not treat this as a formal anonymization or data-loss-prevention system.
The recommended installation method is pipx:
pipx install redacted-context-mcpRegular pip installation is also supported:
python -m pip install redacted-context-mcpInstall from a source checkout only for development or to test an unreleased version:
python -m pip install -e .This installs two console commands:
redctx # CLI
redctx-mcp # MCP stdio serverFor redctx discover, install Ollama separately and
pull a local model such as gemma4:e4b. The core redacted CLI and MCP server do
not require Ollama.
Model tags must match Ollama exactly. Check installed tags with ollama list
and pass the full value shown in the NAME column to --model.
Use two sibling folders under a neutral parent:
/work/
agent-workdir/ # Claude Code starts here; no raw context files
source-private/ # private project/context repositoryThe agent starts in agent-workdir/. The MCP server reads
source-private/, redacts output, and returns only redacted text.
Keep the private folder outside the active agent workspace when possible. If the agent can still run shell commands against the raw private folder, the MCP redaction layer is only an instruction-level guardrail, not a hard boundary.
If redctx-mcp is installed, put this in agent-workdir/.mcp.json:
{
"mcpServers": {
"redacted_context": {
"type": "stdio",
"command": "redctx-mcp",
"args": [
"--root",
"../source-private"
]
}
}
}If running directly from a source checkout without installing:
{
"mcpServers": {
"redacted_context": {
"type": "stdio",
"command": "python3",
"args": [
"../redacted-context-mcp/src/redacted_context_mcp/server.py",
"--root",
"../source-private"
]
}
}
}Then start Claude Code from the agent workspace:
cd /work/agent-workdir
claudeIf Claude Code was already running, restart it or reconnect MCP servers with
/mcp.
For persistent Claude Code guidance, copy examples/agent-CLAUDE.md into
agent-workdir/CLAUDE.md.
Codex supports local stdio MCP servers through config.toml. Put this in
~/.codex/config.toml, or in agent-workdir/.codex/config.toml for a trusted
project-scoped setup:
[mcp_servers.redacted_context]
command = "redctx-mcp"
args = ["--root", "../source-private"]
enabled = true
required = trueIf running directly from a source checkout without installing:
[mcp_servers.redacted_context]
command = "python3"
args = [
"../redacted-context-mcp/src/redacted_context_mcp/server.py",
"--root",
"../source-private",
]
enabled = true
required = trueFor persistent Codex guidance, copy examples/agent-AGENTS.md into
agent-workdir/AGENTS.md. Codex reads AGENTS.md when a session starts, so
restart Codex after adding or changing it.
Any MCP client that can launch a stdio server can run:
redctx-mcp --root /absolute/path/to/source-privateUse the client-specific configuration format to pass that command and args.
The server advertises instructions and exposes only redacted redctx_* tools.
Modern clients can use the stateless MCP 2026-07-28 flow with per-request
metadata and server/discover; legacy clients continue to negotiate through
initialize.
The server exposes:
redctx_tree — show a redacted file tree with opaque ids
redctx_list — list redacted directory entries
redctx_read — read redacted file contents by path or @p_<id>
redctx_search — search redacted text
redctx_retrieve — retrieve relevant passages ranked by keyword coverage and relevance
redctx_stat — inspect redacted metadata
redctx_bundle — concatenate redacted context files
redctx_doctor — show config counts without sensitive terms
redctx_audit — run local containment and redaction checks
redctx_refresh_index — refresh the in-memory opaque path index
Agents should carry @p_<id> references between calls rather than using raw
filenames.
The MCP server also exposes redacted text files as resources:
resources/list returns redctx://p_<id> resource URIs with redacted titles.
resources/read returns redacted file text for those opaque resource URIs.
By default, the MCP server exposes only read-only tools. To let an agent submit new redacted documents back into the private source root, start the server with an explicit write subdirectory:
redctx-mcp --root ../source-private --enable-writes --write-subdir incomingThis adds redctx_submit_doc. The tool accepts a relative target_path,
redacted text, and optional overwrite. The server rehydrates known
placeholders locally, rejects unresolved redaction tokens, and writes only under
the configured write subdirectory. Tool responses use redacted paths and opaque
ids; they do not return the raw restored path.
The CLI is useful for smoke tests or clients without MCP:
redctx --root ../source-private doctor
redctx --root ../source-private tree context --max-depth 2
redctx --root ../source-private search "governance" context --ignore-case --context 2
redctx --root ../source-private read @p_1a2b3c4d5e6f --start-line 1 --end-line 80
redctx --root ../source-private bundle context --glob "*.md" --max-files 10
redctx --root ../source-private audit --format json
redctx --root ../source-private benchmark --format jsonUse retrieve when you want relevant passages for several keywords, even when
the words appear in a different order or on different lines:
redctx --root ../source-private retrieve "database backup recovery" \
--max-results 8 --max-chars 12000The MCP equivalent is redctx_retrieve with query, optional paths and
glob, max_results, and max_chars. Each result includes an opaque file
reference and a line range that can be passed to redctx_read for more context.
Passages covering more query terms rank first, then BM25 keyword relevance;
matching is case-insensitive and ignores a small set of common English words.
Existing literal and regex search behavior is unchanged.
Only redacted text is tokenized and scored. Complete placeholders can be used
as search terms. Retrieval keeps no persistent index, makes no model calls,
and has no additional dependencies. Results contain complete passages within
the character budget; if none fits, increase max_chars. A limit notice marks
omitted matches. Scan limits fail the request instead of presenting a partial
scan as a complete ranking. Narrow paths or glob for large knowledgebases.
Install the optional Microsoft MarkItDown integration and enable it explicitly for the CLI or MCP server:
python -m pip install 'redacted-context-mcp[documents]'
redctx --root ../source-private --documents retrieve "database backup recovery"
redctx --root ../source-private --documents read @p_1a2b3c4d5e6f
redctx-mcp --root ../source-private --documentsFor pipx, install with pipx install 'redacted-context-mcp[documents]', or add
the dependencies to an existing installation with
pipx inject redacted-context-mcp 'markitdown[docx,pptx,pdf,xlsx,xls]>=0.1.7,<0.2'.
For an MCP client configuration, add --documents to the server's args.
Supported formats are DOCX, PPTX, PDF, XLSX, and XLS. They become available through read/head/tail, search, retrieve, bundle, local discovery, rehydration source scans, and MCP resources. Conversion produces local Markdown, then the same redactor processes it. Line citations refer to extracted Markdown lines, not PDF pages or slide numbers. The extractor does not reproduce document layout or evaluate spreadsheet formulas.
The plain installation stays dependency-free. Installing the extra alone does
not change which files are exposed; --documents removes only the built-in
exclusions for supported formats. Configured exclusions and never-serve paths
still apply. Each document is read through the existing containment checks and
converted in a short-lived local worker with a 15-second deadline, 5 MB input
cap, 1 million extracted-character cap, and OOXML expansion limits (50 MB and
2,000 ZIP members). Existing operation budgets also apply. No raw converted
Markdown is persisted; the MCP resource cache holds redacted text only.
Only the selected format converter is invoked on local bytes. URL fetching,
plugins, cloud conversion, audio transcription, and LLM/OCR clients are not
enabled. Legacy .doc and .ppt files must be exported to a supported format.
Scanned PDFs need OCR outside this MCP; an empty extraction produces a clear
error. Encrypted, malformed, or oversized documents fail with non-sensitive
errors. Conversion is an additional parser surface, not a hard sandbox; use
the isolation described in Security Boundary for untrusted
source files.
The rehydrate command restores redacted text by scanning the private source
root with the same salt and config, rebuilding the placeholder map, and applying
it to a redacted file or folder. This emits raw private text, so it is CLI-only
and requires an explicit acknowledgement flag.
redctx --root ../source-private rehydrate ./redacted-output.md --allow-raw-output > raw-output.md
redctx --root ../source-private rehydrate ./redacted-folder \
--output ./raw-folder \
--allow-raw-outputRehydration is not cryptographic reversal. A redacted file alone is not enough; the command needs access to the original private root or equivalent local source material to rebuild the mapping.
Create .agent-context-redactor.toml in the private source root. This file is
ignored by the example .gitignore because it may contain exact sensitive
terms.
[redaction]
salt = "local-random-string-kept-private"
clients = ["Client Legal Name", "Client Acronym"]
organizations = ["Supplier Name", "Partner Company"]
people = ["Person One", "Person Two"]
terms = ["project codename", "internal programme name"]
allow = ["Azure", "PostgreSQL", "Kubernetes"]
term_files = ["private-redaction-terms.txt"]
[github.repos.context]
owner = "private-org-or-user"
repo = "private-context-repo"
token_env = "GITHUB_TOKEN"The tool also derives likely aliases from the private source folder name and
accepts additional comma- or newline-separated terms through
REDACTED_CONTEXT_TERMS.
The optional salt controls opaque path ids and deterministic placeholders.
If omitted, redctx creates or reuses a random 256-bit vault salt in user-local
state. Empty, malformed, or root-contained salt state fails closed instead of
silently rotating aliases. You can also set REDACTED_CONTEXT_SALT in the
environment that starts redctx or redctx-mcp. redctx doctor reports
whether the active salt came from local state, config, or environment.
GitHub repo entries are optional. Use neutral aliases such as context; agents
use the alias, while the real owner/repo stays in this local config. Private
repos require the named token environment variable in the shell that starts
redctx or redctx-mcp.
The MCP server automatically checks the local config and its referenced
term_files before each tool call or resource list/read. Save your reviewed
rules and retry the request: new terms, exclusions, allow-list changes, and
detector profiles take effect without reconnecting. This also picks up config
updates written by discover-update.
For example, adding a project codename to terms causes the next read of an
already cached document to redact that codename. Successful policy changes
clear the redacted resource cache, path index, and old rehydration mappings.
Opaque path references and placeholders for unchanged terms remain stable as
long as the salt and applicable redaction category stay the same.
If the config is invalid or unreadable, or a previously loaded config or
still-referenced term file disappears, context requests fail closed with a
non-sensitive error. Repair the file and retry; the server recovers without a
restart. Referenced term files remain optional until first loaded and are
watched for creation.
To deliberately stop using a term file, remove its term_files entry.
Salt changes require a server restart and fresh opaque references; requests are blocked until restart or restoration of the original salt. Changes to the launch environment, server flags, or external vault-salt state also require a restart. Reload checks use file metadata at request boundaries; they do not retract previously returned content or provide protection against adversarial concurrent filesystem changes.
Configured GitHub issues can be read through the same redaction layer:
export GITHUB_TOKEN="<github-token>"
redctx --root ../source-private github repos
redctx --root ../source-private github issues context --state open --limit 20
redctx --root ../source-private github issue context 123 --comments
redctx --root ../source-private github search context "policy controls"The MCP server exposes the same flow with:
redctx_github_repos
redctx_github_list_issues
redctx_github_read_issue
redctx_github_search_issues
Outputs redact titles, bodies, labels, and comments, and mark GitHub text as untrusted external content. Raw author logins and raw GitHub URLs are not printed; authors are shown as stable per-vault, per-repo opaque ids.
redctx discover can draft .agent-context-redactor.toml using a local
Ollama model. This is a human setup command, not an MCP tool, because its output
intentionally contains the raw names you want to redact.
Example with a small local model:
ollama pull gemma4:e4b
redctx --root ../source-private discover context progress archive \
--model gemma4:e4b \
--glob "*.md" \
--output .agent-context-redactor.tomlIf you switch models, use the exact tag from ollama list.
Review the generated file before use. To avoid overwriting an existing config,
the command refuses to write over --output unless --force is passed.
Discovery output is post-processed with generic cleanup rules. The cleanup does not include project-specific names; it only:
omits public/default-allowed terms that the redactor already allows;
moves other likely tool/package names to allow;
drops obvious filenames, meeting/ticket IDs, country-only values, job titles, and generic workflow/process labels;
strips role notes from full names such as Alice Example (CIO);
ignores single first names by default because they over-redact.
Use --raw-discovery if you want the local model's categories with only basic
dedupe.
Useful options:
redctx --root ../source-private discover --help
redctx --root ../source-private discover context --format json
redctx --root ../source-private discover context --raw-discovery
redctx --root ../source-private discover context --max-files 20 --max-chars-per-file 8000
redctx --root ../source-private discover context --endpoint http://localhost:11434The command uses Ollama's local /api/generate endpoint with streaming disabled
and JSON output requested. No hosted LLM is called by this feature. Non-loopback
plain-http endpoints are refused unless you pass --allow-remote-endpoint,
because discovery payloads contain raw private text.
Repository hooks can classify exact staged Git blobs without duplicating the MCP's discovery and merge policy. Supply one JSON object per line:
{"path":"private/meeting.md","text":"raw staged document text","sha256":"optional-source-digest"}Then call the hook-facing CLI:
redctx --root ../source-private discover-update \
--input-jsonl /tmp/staged-documents.jsonl \
--seed-config config/redaction-seed.toml \
--output-config .agent-context-redactor.toml \
--model gemma4:e4bdiscover-update sends each complete document to the configured local Ollama
endpoint in a separate request. It rejects model values that are not exact
substrings of that document, monotonically adds sensitive terms, keeps reviewed
seed policy settings authoritative, preserves unrelated TOML tables and
comments, and writes atomically. By default, model output cannot expand the
allow-list.
Documents are never silently truncated. A document over
--max-chars-per-document, or an input set over --max-total-chars, fails
before the model is called. Set those limits to fit the selected model's actual
context window. --merge-only applies a reviewed seed change without reading
documents or calling Ollama.
The equivalent Python composition API is:
from redacted_context_mcp import (
DiscoveryDocument,
build_discovery_update,
discover_documents,
write_discovery_update,
)
from redacted_context_mcp.discovery import OllamaDiscoveryClient
documents = [DiscoveryDocument(path="private/meeting.md", text=raw_text)]
client = OllamaDiscoveryClient(
endpoint="http://127.0.0.1:11434",
model="gemma4:e4b",
timeout=120,
)
discovery = discover_documents(documents, client=client)
update = build_discovery_update(existing_toml, discovery, seed_text=seed_toml)
write_discovery_update(config_path, update)Both interfaces intentionally handle raw private text and raw discovered names. Keep them local and outside an agent's accessible workspace. This feature reduces what a separate coding model receives; it is not encryption, DLP, or a proof that the local model found every sensitive entity.
MCP routing is the main workflow. Claude Code permissions can add guardrails by denying direct reads/searches into the private source folder and allowing only the redacted MCP tools. See examples/claude-settings.example.json.
This project is a practical privacy guardrail, not a formal de-identification system.
It helps because:
the agent starts in a neutral folder with no raw context files;
the useful operations are exposed as redacted MCP tools;
filenames can be navigated through opaque ids;
raw names, emails, URLs, phones, and configured terms are redacted.
The rehydrate command intentionally reverses redacted exports for the local
operator. redctx_submit_doc can also rehydrate generated redacted text, but
only when MCP writes are explicitly enabled and only into the configured write
subdirectory. Submitted content is verified to redact consistently on
read-back, and the write subdirectory itself is never used as a rehydration
source. Do not run rehydration workflows from an agent workspace where the
model can read raw output.
Additional guardrails:
The redaction config (default or explicit --config), configured term
files, .env*, *.key, *.pem, and *.crt files are never served through
redacted tools, even with --include-private, with case-folded matching so
.ENV and server.PEM variants are refused too.
Bare long hex strings (the vault-salt shape), salt-keyed assignments, and
underscore-qualified secrets such as DB_PASSWORD=... are redacted by
default.
MCP searches enforce an operation deadline, and user-supplied regexes are matched in an isolated, killable child process after a fast-fail screen for catastrophic-backtracking patterns, so a crafted regex cannot hang the server.
redctx discover refuses non-loopback plain-http Ollama endpoints unless
--allow-remote-endpoint acknowledges the exposure.
Placeholders are deterministic HMACs over the vault salt. Keep the salt in
the local config or user-local state; REDACTED_CONTEXT_SALT can be visible
in process environments, and anyone holding the salt can verify dictionary
guesses against placeholders.
It is not a hard security boundary if the agent process runs as the same OS user that can read the private source folder. For hard enforcement, run the agent as a separate OS user or container without filesystem access to the private source folder, and expose only the MCP server or a separate redaction service.
See ARCHITECTURE.md for the design boundaries and CONTRIBUTING.md for local
development and release checks.
PYTHONPATH=src python3 -m unittest discover -s tests -p 'test_*.py'
python3 -m py_compile src/redacted_context_mcp/core.py src/redacted_context_mcp/server.pyMIT.
Run safe local redaction and containment checks without printing sensitive terms.
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | text |
| Name | Required | Description |
|---|---|---|
| text | Yes | |
| receipt | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate safety (readOnlyHint, destructiveHint), but the description adds value by specifying that the tool does not print sensitive terms and performs local checks, which are not captured in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that conveys the core purpose without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only one optional parameter and an output schema (not shown), the description is sufficiently complete for this simple tool, though including parameter details would improve it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description should compensate by explaining the 'format' parameter, but it does not mention it at all. The schema provides enum and default, but the description adds no semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('run'), the resource ('local redaction and containment checks'), and a key constraint ('without printing sensitive terms'), effectively distinguishing it from sibling tools like redctx_list or redctx_read.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for safe checks without exposing sensitive terms, but lacks explicit guidance on when to use this tool versus alternatives like redctx_search or redctx_read.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Concatenate redacted text files for compact agent context.
| Name | Required | Description | Default |
|---|---|---|---|
| glob | No | ||
| paths | No | ||
| max_files | No | ||
| max_total_chars | No | ||
| max_chars_per_file | No |
| Name | Required | Description |
|---|---|---|
| text | Yes | |
| receipt | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds that it concatenates files for compact context, which is useful, but does not disclose important behaviors such as how files are selected (glob vs paths), truncation limits, or what happens if limits are exceeded. Given annotation coverage, a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no fluff. It efficiently communicates the core purpose. However, it could be slightly expanded to include parameter or usage details without losing conciseness, but as is, it earns a high score for structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, an output schema, and a specific use case (bundling files for context), the description is incomplete. It does not explain the output format, the selection logic (glob vs paths), or default behaviors. The agent lacks sufficient information to use the tool effectively without external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 does not explain any parameters. The parameters 'glob', 'paths', 'max_files', 'max_total_chars', and 'max_chars_per_file' are not described in the description or via context signals, leaving the agent to guess their semantics. The description must compensate for low schema coverage but fails to do so.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'concatenate' and resource 'redacted text files', and adds the purpose 'for compact agent context'. It distinguishes this tool from siblings like 'redctx_read' (individual file reading) and 'redctx_search' (searching), making it easy for an agent to understand when to use it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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, nor any prerequisites or conditions. It simply states what the tool does, leaving the agent without context on trade-offs or when to prefer this over other tools like redctx_read or redctx_search.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show redaction setup counts without printing sensitive terms.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| text | Yes | |
| receipt | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, but the description adds value by stating it does not print sensitive terms, a behavioral trait beyond annotations. This clarifies what the output excludes, aiding agent decision-making.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the core purpose and a key behavioral note without any wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has zero parameters and an output schema exists, the description is sufficiently complete. It explains the main function and a safety aspect, requiring no additional context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so the description does not need to add parameter details. Baseline score of 4 applies, and the description does not attempt to explain nonexistent parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Show' and clearly identifies the resource as 'redaction setup counts'. It implicitly distinguishes from sibling tools like redctx_list (which likely lists redactions) and redctx_read (which reads details), focusing on counts without sensitive terms.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'without printing sensitive terms', implying safe usage for obtaining counts. However, it does not explicitly state when to use this tool versus alternatives like redctx_audit or redctx_search, nor does it provide exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List redacted GitHub issues from a configured repo alias.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| state | No | open | |
| labels | No | ||
| repo_alias | No | Configured neutral repo alias, not owner/repo. | context |
| Name | Required | Description |
|---|---|---|
| text | Yes | |
| receipt | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is clear. The description adds only the term 'redacted,' which is vague and not elaborated. No additional behavioral traits or limitations are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (one sentence), but it sacrifices completeness. It is not verbose, but it also fails to provide necessary context. Adequate for a simple tool, but barely.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 4 parameters, an output schema, and siblings, the description is too sparse. It does not explain the 'redacted' nature, filtering options, or return format. The agent lacks enough context to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 25% (only repo_alias described). The description hints at repo_alias but provides no meaning for limit, state, or labels. The schema defaults and enums exist, but the description does not compensate for the low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists redacted GitHub issues from a configured repo alias, which distinguishes it from sibling tools like read (single issue) and search (query-based). However, it does not explicitly differentiate, so it's not perfect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. The description does not mention scope, prerequisites, or exclusions, leaving the agent to infer from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one redacted GitHub issue by configured repo alias and issue number.
| Name | Required | Description | Default |
|---|---|---|---|
| number | Yes | ||
| comments | No | ||
| repo_alias | No | Configured neutral repo alias, not owner/repo. | context |
| max_comments | No | ||
| max_body_chars | No |
| Name | Required | Description |
|---|---|---|
| text | Yes | |
| receipt | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds 'redacted', hinting at data security, but does not elaborate on auth, rate limits, or side effects. Value beyond annotations is moderate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single 9-word sentence with no filler. Efficient but could include parameter hints without becoming verbose. Still, it is appropriately front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters and low schema coverage, the description omits essential configuration details (e.g., comments, limits). Output schema exists but return values are not described. The tool is simple but parameter guidance is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20% (only repo_alias described). The tool description mentions only 'repo alias' and 'issue number', leaving comments, max_comments, max_body_chars unexplained. Description fails to compensate for low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Read', the resource 'one redacted GitHub issue', and the distinguishing qualifier 'by configured repo alias and issue number'. It effectively differentiates from sibling tools like redctx_github_list_issues and redctx_github_search_issues.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (specific issue by alias and number) but does not explicitly contrast with alternatives like list or search tools. No when-not-to-use or prerequisite context is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List configured GitHub repo aliases. Aliases should be neutral names such as context.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| text | Yes | |
| receipt | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and destructiveHint, so the safety profile is clear. The description adds that it lists configured aliases and suggests neutral names, which is helpful but not extensive. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action, no redundant words. Efficient and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only tool with an output schema, the description is complete. The naming guideline adds context that the schema cannot capture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With no parameters and 100% schema coverage, the baseline is 3. The description adds no parameter-specific information beyond what the schema implies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists configured GitHub repo aliases, with a specific verb and resource. It distinguishes itself from sibling tools like redctx_github_list_issues by focusing on aliases. The naming guideline adds clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing aliases and provides a naming convention, but it does not explicitly state when to use this tool versus alternatives or when not to use it. Context from sibling names partially compensates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search GitHub issues in a configured repo alias and return redacted summaries.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| state | No | open | |
| repo_alias | No | Configured neutral repo alias, not owner/repo. | context |
| Name | Required | Description |
|---|---|---|
| text | Yes | |
| receipt | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds the behavioral detail of returning 'redacted summaries,' which is not captured by annotations. However, it does not disclose auth requirements, rate limits, or what redaction entails.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is front-loaded with the action and resource. It efficiently conveys the core purpose, though additional guidance could be added without significant bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return values need not be explained. However, the description lacks context on how to effectively use the search (e.g., query syntax, what 'redacted summaries' contain). Given the tool's moderate complexity (4 parameters), the description is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (25%), only the 'repo_alias' parameter has a description. The main description mentions 'configured repo alias' but provides no details on 'query', 'limit', or 'state' parameters. The description fails to compensate for the lack of schema explanations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Search' on the resource 'GitHub issues' with additional context about using a configured repo alias and returning redacted summaries. This distinguishes it from sibling tools like 'redctx_github_list_issues' (listing without search) and 'redctx_github_read_issue' (reading a single issue).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for query-based searching but does not explicitly state when to use this tool vs alternatives like 'redctx_github_list_issues' or 'redctx_github_read_issue'. No exclusions or when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List redacted files/directories with opaque @p_ path references.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Path or @p_<id> reference. | . |
| max_depth | No | ||
| recursive | No |
| Name | Required | Description |
|---|---|---|
| text | Yes | |
| receipt | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds the important behavioral detail that paths are presented as opaque @p_<id> references. This provides beyond-annotation context without contradicting it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that front-loads the core purpose. No fluff, every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple list operation and presence of an output schema and annotations, the description covers the main point. However, it omits behavior of max_depth and recursive, which are not explained anywhere, leaving the agent with incomplete understanding of how to use these parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33% (path has description). The description mentions @p_<id> references which relates to the path parameter but adds nothing for max_depth or recursive. With low coverage, the description should compensate but does not, leaving two parameters undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists redacted files/directories and introduces the key behavior of opaque @p_<id> path references. This is a specific verb+resource combination that distinguishes it from siblings like redctx_read or redctx_tree.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternatives are given. The mention of opaque path references hints at a use case, but there is no guidance on when to prefer this over siblings like redctx_tree or redctx_stat.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a redacted text file by path or opaque @p_ reference.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Path or @p_<id> reference. | |
| end_line | No | ||
| max_chars | No | ||
| start_line | No | ||
| line_numbers | No |
| Name | Required | Description |
|---|---|---|
| text | Yes | |
| receipt | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds context beyond annotations: it reads 'redacted' text files and accepts two reference types. Annotations already declare readOnly, idempotent, non-destructive, so no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no fluff, essential information front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, so return values are covered. But with 5 parameters and low description coverage, the description is incomplete – missing parameter semantics for most parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 20%. Description only explains path parameter, ignoring end_line, max_chars, start_line, line_numbers. Does not compensate for low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Read', resource 'redacted text file', and specifies two referencing methods (path or @p_<id>). Distinguishes from siblings like redctx_list, redctx_search, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use vs alternatives. Implied by purpose but no when-not or alternative tool mentions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Refresh the in-memory opaque path index for the configured local root.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| text | Yes | |
| receipt | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description claims 'Refresh' which implies mutation of the in-memory index, yet annotations set readOnlyHint=true, creating a clear contradiction. No additional behavioral context is provided beyond what annotations already declare. The tool's side effects are not disclosed, and the refresh operation's impact on other tools is unknown.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no filler words. Every word is necessary and front-loaded with the action. Efficient and direct.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no parameters, the description is incomplete. It does not explain what 'refresh' means operationally (e.g., reload from disk vs. reindex), whether it affects other tools, or what the output schema provides. The annotation contradiction further undermines completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has zero parameters, so schema description coverage is 100%. The description adds no parameter-specific meaning, but none is needed. Baseline score of 4 applies for a parameterless tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool refreshes an in-memory index for the configured local root. It uses a specific verb ('Refresh') and resource ('in-memory opaque path index'). However, it does not explicitly distinguish from sibling tools like redctx_read or redctx_search, though the maintenance nature is implied.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. The description does not mention prerequisites, conditions, or exclusions. Sibling tools like redctx_list or redctx_doctor serve different purposes, but the description offers no comparative context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rank redacted passages by multi-word keyword relevance. Returns opaque references and line citations (extracted Markdown lines for documents). No embeddings or persistent index.
| Name | Required | Description | Default |
|---|---|---|---|
| glob | No | ||
| paths | No | ||
| query | Yes | ||
| max_chars | No | ||
| max_results | No |
| Name | Required | Description |
|---|---|---|
| text | Yes | |
| receipt | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already show readOnlyHint, idempotentHint, and destructiveHint, but the description adds meaningful behavior: results are ranked, references are 'opaque,' line citations are returned for documents, and the tool has no embeddings or persistent index. This goes well beyond the structured hints and gives an agent a realistic picture of the operation'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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences tightly pack the core operation, the output shape, and a key non-behavior ('No embeddings or persistent index'). The most important information is front-loaded, and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, idempotent tool with an output schema and only one required parameter, the description is enough to make a basic call. However, it lacks explicit alternative routing and leaves glob/paths semantics unexplained, so an agent may not fully understand scoping options or when to prefer this over sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the burden of explaining parameters. It only clarifies the query concept ('multi-word keyword relevance') and says nothing about glob, paths, max_chars, or max_results. Some parameters have self-descriptive names, but the description does not compensate for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Rank redacted passages by multi-word keyword relevance.' It also clarifies output ('opaque references and line citations') and contrasts itself with embedding/index-based approaches. It stops short of explicitly distinguishing itself from sibling redctx_search, so it gets a 4 rather than a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'by multi-word keyword relevance' and 'No embeddings or persistent index' imply this is the tool for keyword-style retrieval rather than semantic/vector search. However, it never names an alternative or gives explicit when-to-use / when-not-to-use guidance. The usage context is implied but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search redacted text. The query is evaluated against redacted output.
| Name | Required | Description | Default |
|---|---|---|---|
| glob | No | ||
| paths | No | Paths or @p_<id> references to search. Empty searches the root. | |
| query | Yes | ||
| regex | No | ||
| context | No | ||
| ignore_case | No | ||
| max_results | No |
| Name | Required | Description |
|---|---|---|
| text | Yes | |
| receipt | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which cover safety and idempotency. The description adds that the query is evaluated against redacted output, which is a behavioral nuance. However, it does not disclose other traits like rate limits or return format, but given annotations, this 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences and front-loaded purpose. However, it omits essential parameter and usage information, making it efficient but incomplete. Every sentence earns its place, but more value could be added.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 7 parameters, an output schema exists, and annotations are present, the description is incomplete. It fails to explain parameters, return values, or provide context for complex searches. The output schema may help, but the description itself lacks completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 14% (only 'paths' has a description). The description does not explain any parameters, failing to compensate for the low coverage. With 7 parameters, the agent lacks guidance on parameter usage, reducing effectiveness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches redacted text and specifies that the query is evaluated against redacted output. This provides a specific verb and resource, distinguishing it from unrelated tools. However, it does not differentiate from sibling tools like redctx_list or redctx_tree, which may have similar purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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. There is no mention of prerequisites, when-not to use, or comparisons with sibling tools like redctx_list or redctx_audit. The description lacks context for appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show redacted metadata for a path or opaque @p_ reference.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
| Name | Required | Description |
|---|---|---|
| text | Yes | |
| receipt | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, non-destructive. The description adds behavioral context by noting that metadata is 'redacted', implying some content may be hidden. This goes beyond what annotations provide, but does not detail other behaviors like rate limits or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no redundant words. It front-loads the purpose and uses technical terms appropriately. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a simple interface (1 parameter) and an output schema (not shown). The description suffices for normal usage, but could mention what metadata fields are returned or the output format. However, given the output schema likely covers return values, the description is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains that the 'path' parameter can accept either a file path or an opaque @p_<id> reference. This adds meaning beyond the bare string type in the schema, which has 0% coverage. The description compensates for the schema's lack of parameter description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool shows redacted metadata for a path or opaque reference. The verb 'show' and resource 'metadata' are specific, and the mention of both path and opaque reference distinguishes it from siblings like redctx_read (content) and redctx_list (listing).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. It does not mention prerequisites, when not to use it, or refer to other tools. The description only states what it does without context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show a redacted file tree with opaque @p_ path references.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Path or @p_<id> reference. | . |
| max_depth | No |
| Name | Required | Description |
|---|---|---|
| text | Yes | |
| receipt | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint false. The description adds that the tree is 'redacted' with 'opaque @p_<id> path references', which provides useful behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the core action. It is concise but could benefit from slight expansion on the tree depth or reference format.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema is present, so return values need not be explained. The description covers purpose and key behavioral aspects, but missing usage guidelines and parameter details reduce completeness for decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (path has description, max_depth does not). The tool description does not explain parameter usage or add meaning beyond the schema, leaving max_depth ambiguous in its effect.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool shows a redacted file tree with opaque @p_<id> references, which distinguishes it from sibling tools like redctx_list and redctx_read that list files or read contents. The verb 'Show' and resource 'redacted file tree' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 alternatives such as redctx_list or redctx_stat. It lacks context about when not to use it or what distinguishes it further.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.8.0redctx_retrievev0.4.0redctx_auditredctx_bundleredctx_doctorredctx_github_list_issuesredctx_github_read_issueredctx_github_reposredctx_github_search_issuesredctx_listredctx_readredctx_refresh_indexredctx_searchredctx_statredctx_treeScored across 14 tools
redctx_search and redctx_retrieve both perform redacted text lookup with only subtle differences in ranking behavior, while redctx_list and redctx_tree both enumerate redacted paths and could be easily confused. Descriptions help somewhat, but several tool boundaries are not crisp.
All tools share the redctx_ prefix and mostly use snake_case verbs like search, refresh, retrieve, list, read, and stat. However, a few names are bare nouns (tree, bundle, doctor, audit) and the github_* sub-namespace mixes styles, creating minor inconsistency.
With 14 tools, the server is well-scoped for its stated purpose of redacted file and issue exploration. Each tool covers a distinct aspect of the workflow without drowning the agent in redundant endpoints.
The surface provides thorough read-oriented coverage: search, retrieve, tree, list, read, stat, bundle, plus safety checks and GitHub issue reads. The only real gaps are write/update operations and deeper GitHub interactions, but those are arguably out of scope for a redaction/context tool.
Securely search and manage workspace context files for AI agents and teams.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Codebase intelligence for agents: 152 structured artifacts across 21 programs, one call.
Project memory, semantic code search, and grounded agent context.