Which integrations are available for this server?

Integrates with GitHub Copilot in supported IDEs to analyze technical debt across multiple languages and generate actionable insights. Integrates with JetBrains IDEs via the AI Assistant to enable technical debt analysis with SQALE ratings and dependency scanning. Integrates with Xcode via GitHub Copilot for Xcode to analyze technical debt in Swift and Objective-C projects, including SwiftUI-specific checks.

How do I use Tech Debt MCP Server?

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., "@Tech Debt MCP Server analyze the current project for technical debt" 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.

Tech Debt MCP Server

by PierreJanineh

Overview Schema Related Servers Score Discussions

TypeScript

Local

npm version Add to MCP SQALE Rating CodeQL Documentation

16 Tools · 2 Resources · 14 Languages · 10 Dependency Ecosystems

A Model Context Protocol (MCP) server for analyzing technical debt across multiple programming languages. Designed to integrate with GitHub Copilot, Claude, Cursor, and other MCP-compatible tools.

Features

Multi-language support: JavaScript, TypeScript, Python, Java, Swift, Kotlin, Objective-C, C++, C, C#, Go, Rust, Ruby, PHP
Comprehensive analysis: Detects various types of tech debt including code quality issues, security vulnerabilities, and maintainability problems
SQALE Metrics: Calculate technical debt with SQALE rating system (A-E scale)
SwiftUI Analysis: Specialized checks for SwiftUI patterns, state management, memory leaks, view nesting, and concurrency issues
Custom Rules: Define your own pattern-based checks with regex support
Dependency Analysis: Parse package manifests across 10 ecosystems (npm, pip, Maven/Gradle, Cargo, Go Modules, Composer, Bundler, NuGet, C/C++, Swift)
Inline Suppression: Suppress false positives with // techdebt-ignore-next-line or block comments
Config Validation: Validate .techdebtrc.json configuration files for schema correctness
Actionable recommendations: Provides prioritized suggestions for addressing technical debt
Flexible filtering: Filter results by severity, category, or language
Security hardened (v2.0.2): Path traversal prevention on all tool and resource path inputs, ReDoS-safe custom-rule regex validation, regex-injection escaping in SwiftUI checks, absolute-path sanitization in all error messages, and CodeQL SAST scanning on every push/PR

Related MCP server: code-graph-mcp

Supported Languages

Language	Extensions	Key Checks
JavaScript	.js, .mjs, .cjs, .jsx	console.log, debugger, eslint-disable, usage of dynamic code execution, var usage
TypeScript	.ts, .tsx, .mts, .cts	any type, @ts-ignore, non-null assertions, type assertions
Python	.py, .pyw, .pyi	bare except, print statements, global usage, dynamic code execution
Java	.java	System.out, printStackTrace, empty catch, @SuppressWarnings
Swift	.swift	force unwrap (!), force cast (as!), force try, retain cycles, SwiftUI patterns
Kotlin	.kt, .kts	!!, lateinit abuse, @Suppress, unchecked casts
Objective-C	.m, .mm, .h	NSLog, retain cycles, deprecated methods, massive view controllers
C++	.cpp, .cc, .hpp, .h	raw pointers, C-style casts, goto, using namespace std
C	.c, .h	malloc without free, goto, unsafe functions, null checks
C#	.cs	Console.WriteLine, async void, empty catch, dispose pattern
Go	.go	ignored errors, blank imports, fmt.Print, panic, global variables
Rust	.rs	unwrap, expect, unsafe, allow attributes, panic, println
Ruby	.rb	puts, binding.pry, rubocop disable, dynamic code execution, global variables
PHP	.php	var_dump, print_r, die/exit, dynamic code execution, error suppression

Installation

One-Click Install

VS Code (via Terminal):

code --add-mcp '{"name":"tech-debt-mcp","command":"npx","args":["-y","tech-debt-mcp@latest"]}'

One-Click Install

Cursor (via Terminal):

cursor --add-mcp '{"name":"tech-debt-mcp","command":"npx -y tech-debt-mcp@latest"}'

Claude Code (via Terminal):

claude mcp add tech-debt-mcp -- npx -y tech-debt-mcp@latest

Claude Desktop — add to your claude_desktop_config.json:

{
  "mcpServers": {
    "tech-debt-mcp": {
      "command": "npx",
      "args": ["-y", "tech-debt-mcp@latest"]
    }
  }
}

Claude Code plugin — add this repo's marketplace, then install the plugin:

/plugin marketplace add PierreJanineh/TechDebtMCP
/plugin install tech-debt-mcp@techdebtmcp

The plugin runs npx -y tech-debt-mcp@latest under the hood — no source bundling, always tracks the published npm release. See plugin/README.md for plugin-user-facing docs (install flow, example transcripts, security posture).

Claude Desktop MCPB bundle — single-click install with bundled node_modules (no npx, no internet required at runtime).

Download tech-debt-mcp-<version>.mcpb from the latest GitHub Release and open it with Claude for macOS or Windows.

To build the bundle locally:

npm install --include=dev --ignore-scripts
npm run mcpb:pack
# -> mcpb/tech-debt-mcp-<version>.mcpb

Add to your Windsurf MCP configuration (~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "tech-debt-mcp": {
      "command": "npx",
      "args": ["-y", "tech-debt-mcp@latest"]
    }
  }
}

Via AI Assistant — open Settings > Tools > AI Assistant > Model Context Protocol (MCP), click +, select As JSON, and paste:

{
  "mcpServers": {
    "tech-debt-mcp": {
      "command": "npx",
      "args": ["-y", "tech-debt-mcp@latest"]
    }
  }
}

Via GitHub Copilot for Xcode — open Settings > MCP tab > Edit Config (mcp.json):

{
  "servers": {
    "tech-debt-mcp": {
      "command": "npx",
      "args": ["-y", "tech-debt-mcp@latest"]
    }
  }
}

Manual Setup

Add to your MCP client config:

{
  "mcpServers": {
    "tech-debt-mcp": {
      "command": "npx",
      "args": ["-y", "tech-debt-mcp@latest"]
    }
  }
}

For development: npm run dev

Tools

Every tool declares a tool annotation — Read tools are side-effect-free (readOnlyHint: true); Write tools mutate server session state (destructiveHint: true).

Category	Tool	Type	Description
Analysis	`analyze_project`	Read	Analyze entire project — filter by language, category, severity, maxFiles
	`analyze_file`	Read	Analyze a single file
	`get_debt_summary`	Read	Quick summary with health score and issue counts
	`get_sqale_metrics`	Read	SQALE rating, remediation time, debt ratio, breakdowns
Filtering	`get_recommendations`	Read	Prioritized fix suggestions (configurable limit)
	`get_issues_by_severity`	Read	Issues filtered by severity level
	`get_issues_by_category`	Read	Issues filtered by debt category
	`list_supported_languages`	Read	All languages with their checks
Custom Rules	`add_custom_rule`	Write	Add regex-based tech debt rule
	`remove_custom_rule`	Write	Remove a custom rule by ID
	`list_session_custom_rules`	Read	List rules added via `add_custom_rule` this session (does not include `.techdebtrc.json` `customPatterns`)
	`execute_custom_rules`	Read	Run custom rules against code or file
	`validate_custom_pattern`	Read	Test a pattern before adding it
Dependencies	`check_dependencies`	Read	Scan package manifests across 10 ecosystems
	`get_vulnerability_report`	Read	Offline dependency inventory for CVE review
	`validate_config`	Read	Validate `.techdebtrc.json` schema

Debt categories used throughout: dependency · code-quality · architecture · documentation · testing · security · performance · maintainability

Tool	Parameter	Type	Required	Constraints / default	Description
`analyze_project`	`path`	string	✓	absolute filesystem path	Project root directory
	`languages`	string[]			Filter to specific languages
	`categories`	string[]		see categories above	Filter by debt categories
	`severity`	enum		`low` / `medium` / `high` / `critical`	Minimum severity level
	`maxFiles`	integer		min: 1	Cap on files analyzed
`analyze_file`	`path`	string	✓	absolute filesystem path	File to analyze
`get_debt_summary`	`path`	string	✓	absolute filesystem path	Project root directory
`get_sqale_metrics`	`path`	string	✓	absolute filesystem path	Project root directory
	`developmentTime`	number		hours	Estimated dev time for debt-ratio calc

get_sqale_metrics returns a SQALE rating (A-E) with star visualization, total remediation time, debt ratio, and breakdowns by severity and category.

Tool	Parameter	Type	Required	Constraints / default	Description
`get_recommendations`	`path`	string	✓	absolute filesystem path	Project root directory
	`limit`	integer		default: 5, min: 1	Max recommendations to return
`get_issues_by_severity`	`path`	string	✓	absolute filesystem path	Project root directory
	`severity`	enum	✓	`low` / `medium` / `high` / `critical`	Severity to filter by
`get_issues_by_category`	`path`	string	✓	absolute filesystem path	Project root directory
	`category`	enum	✓	see categories above	Debt category to filter by
`list_supported_languages`	—	—	—	—	No parameters

Tool	Parameter	Type	Required	Constraints / default	Description
`add_custom_rule`	`id`	string	✓		Unique rule identifier
	`pattern`	string	✓	max 1,000 chars	Regex pattern to match
	`message`	string	✓		Issue title/message
	`severity`	enum	✓	`low` / `medium` / `high` / `critical`	Severity level
	`category`	enum	✓	see categories above	Debt category
	`suggestion`	string			How to fix the issue
	`languages`	string[]			Restrict to specific languages
	`flags`	string		allowed: `d g i m s u v y`; `u` / `v` mutually exclusive	Regex flags
`remove_custom_rule`	`id`	string	✓		Rule ID to remove
`list_session_custom_rules`	—	—	—	—	No parameters. Renamed from `list_custom_rules` (TEC-51) to clarify scope: only session-registered rules.
`execute_custom_rules`	`path`	string	◐	absolute path, max 500,000 bytes	File to analyze
	`code`	string	◐	1-500,000 chars	Source code to analyze directly
	`language`	string		must be a supported language ID (same set as `list_supported_languages`)	Filter rules by language
`validate_custom_pattern`	`id`	string	✓		Unique rule identifier
	`pattern`	string	✓	max 1,000 chars	Regex to validate
	`message`	string	✓		Issue title/message
	`severity`	enum	✓	`low` / `medium` / `high` / `critical`	Severity level
	`category`	enum	✓	see categories above	Debt category

◐ execute_custom_rules requires either path or code, not both required. An empty string "" for path is treated the same as omitting the field.

Tool	Parameter	Type	Required	Constraints / default	Description
`check_dependencies`	`path`	string	✓	absolute filesystem path	Project root directory
	`includeDev`	boolean		default: `true`	Include dev/test dependencies
`get_vulnerability_report`	`path`	string	✓	absolute filesystem path	Project root directory
	`includeDev`	boolean		default: `false`	Include dev dependencies
`validate_config`	`path`	string	✓	absolute filesystem path	Project root directory or direct path to `.techdebtrc.json`

check_dependencies detects manifests for npm, pip, Maven/Gradle, Cargo, Go Modules, Composer, Bundler, NuGet, C/C++ (CMakeLists.txt, conanfile.txt/py, vcpkg.json), and Swift Package Manager. get_vulnerability_report produces an offline dependency inventory — see ROADMAP.md for planned online CVE lookup.

Resources

Two MCP resources expose read-only tech debt data as JSON. Both use RFC 6570 URI templates: the {+projectPath} syntax is reserved expansion, which allows the variable to contain the / characters of an absolute filesystem path without percent-encoding.

URI template	Description
`debt://summary/{+projectPath}`	Health score, debt score, issue counts, and SQALE metrics
`debt://issues/{+projectPath}`	Filterable list of all tech debt issues; supports `severity`, `category`, and `limit` query params

Concrete examples — substitute {+projectPath} with an absolute path. Note the double slash: the template's trailing / plus the path's leading / produce //, which is valid URI syntax.

debt://summary//Users/you/projects/myapp
debt://issues//Users/you/projects/myapp
debt://issues//Users/you/projects/myapp?severity=high&limit=50
debt://issues//Users/you/projects/myapp?category=security

Testing interactively — the easiest way to exercise tools and resources is the MCP Inspector:

npm run build
npx @modelcontextprotocol/inspector node dist/index.js

Open the URL it prints, switch to the Resources tab, and read a template URI with your absolute project path.

Configuration

Create a .techdebtrc.json file in your project root:

{
  "include": ["src/**", "lib/**"],
  "ignore": ["vendor/**", "generated/**"],
  "rules": {
    "maxFileLines": 500,
    "maxFunctionLines": 50,
    "maxComplexity": 10,
    "maxNestingDepth": 4
  },
  "severity": {
    "todo-comment": "low",
    "console-log": "medium"
  },
  "ruleExclusions": {
    "debugger": ["**/src/analyzers/**"],
    "ts-ignore": ["**/src/analyzers/**"]
  },
  "customPatterns": [
    {
      "id": "no-console-log",
      "pattern": "console\\.log",
      "severity": "low",
      "category": "code-quality",
      "message": "Remove console.log() statements",
      "suggestion": "Use proper logging library instead",
      "languages": ["javascript", "typescript"]
    }
  ]
}

Language Overrides

Override rules, severity, or file extensions on a per-language basis using languageOverrides. Keys must be valid supported language identifiers.

{
  "languageOverrides": {
    "typescript": {
      "rules": {
        "maxFileLines": 800,
        "maxFunctionLines": 80
      },
      "severity": {
        "todo-comment": "high"
      }
    },
    "python": {
      "extensions": [".pyx"],
      "rules": {
        "maxComplexity": 15
      }
    }
  }
}

rules — per-language thresholds (override the top-level rules for matching files).
severity — per-language rule severity overrides.
extensions — additional file extensions (beyond the defaults) to attribute to this language.

Rule Exclusions

Use ruleExclusions to suppress specific rules for files matching glob patterns. Patterns use forward slashes (/) on all platforms. Use **/ prefixed patterns (e.g., **/src/analyzers/**) for reliable matching regardless of path format.

Inline Suppression

Suppress specific issues directly in source code. Both // and # comment prefixes are supported across all languages.

Single-line — suppresses the next line:

// techdebt-ignore-next-line debugger
debugger; // only the 'debugger' rule is suppressed

# techdebt-ignore-next-line print-statement
print("debug output")  # will not be reported

Block — suppresses all lines between start and end:

// techdebt-ignore-start ts-ignore
issues.push(...this.checkPattern(filePath, content, /@ts-ignore/g, { ... }));
// techdebt-ignore-end ts-ignore

Without a rule name, all rules are suppressed. Blocks can be nested. Suppression comments must appear on their own line.

Example Custom Rules

Scope note: customPatterns defined in .techdebtrc.json are applied only by analyze_project, which loads the project config before scanning. analyze_file invokes the language analyzer directly without loading .techdebtrc.json, so config-defined patterns are not applied on that path. Use add_custom_rule at runtime (or call execute_custom_rules directly) to run custom patterns against a single file.

Define patterns in .techdebtrc.json under customPatterns, or register them at runtime via the add_custom_rule MCP tool:

{
  "customPatterns": [
    {
      "id": "no-magic-numbers",
      "pattern": "=\\s*\\d{3,}",
      "severity": "medium",
      "category": "maintainability",
      "message": "Magic number detected",
      "suggestion": "Extract to named constant"
    },
    {
      "id": "forbidden-library",
      "pattern": "import.*moment.*from",
      "severity": "medium",
      "category": "dependency",
      "message": "moment.js is deprecated",
      "suggestion": "Use native Date or date-fns instead",
      "languages": ["javascript", "typescript"]
    }
  ]
}

SQALE Metrics

Tech Debt MCP uses SQALE methodology to quantify technical debt:

Rating	Debt Ratio	Quality
A	≤5%	Excellent
B	6-10%	Good
C	11-20%	Fair
D	21-50%	Poor
E	>50%	Critical

Effort-to-time mapping: trivial (≤5m) · small (5-30m) · medium (30m-2h) · large (2-4h) · xlarge (4h+)

SwiftUI Analysis

14 specialized checks for SwiftUI apps covering state management (excessive @State, @ObservedObject misuse, environment value safety), memory & lifecycle (Combine retain cycles, timer cleanup, task cancellation, closure retain cycles), performance (missing .id() modifiers, expensive body calculations, deep nesting, GeometryReader misuse), and best practices (AnyView type erasure, deprecated NavigationLink, main thread safety).

State Management Issues

Excessive @State Variables - Detects views with >5 @State variables that should use a ViewModel
@ObservedObject Misuse - Flags @ObservedObject with initialization (should use @StateObject)
Environment Value Safety - Detects force unwrapping of @Environment values

Memory & Lifecycle

Combine Circular References - Finds missing [weak self] in Combine sinks
Missing Timer Cleanup - Detects Timers without cleanup in onDisappear
Missing Task Cancellation - Flags async Tasks without cancellation handling
Retain Cycles in Closures - Detects self captures in onChange/onReceive without [weak self]

Performance & View Hierarchy

Missing .id() Modifiers - Detects ForEach without stable identifiers
Expensive View Body Calculations - Flags reduce/sort/filter in view bodies
Deep View Nesting - Warns when nesting depth exceeds 6 levels
GeometryReader Misuse - Detects GeometryReader at view root

SwiftUI Best Practices

AnyView Type Erasure - Suggests using generics or @ViewBuilder instead
Deprecated NavigationLink - Flags old-style NavigationLink patterns
Main Thread Safety - Ensures UI updates happen on main thread

Example Issues Detected

// Excessive @State - should use ViewModel
struct UserView: View {
  @State private var firstName = ""
  @State private var lastName = ""
  @State private var email = ""
  @State private var phone = ""
  @State private var address = ""
  @State private var city = ""  // 6+ @State variables!
}

// @ObservedObject with initialization
struct ContentView: View {
  @ObservedObject var viewModel = UserViewModel()  // Should be @StateObject!
}

// Missing Timer cleanup
struct TimerView: View {
  var body: some View {
    Text("Hello")
      .onAppear {
        Timer.scheduledTimer(...)  // Missing .onDisappear cleanup!
      }
  }
}

// Retain cycle in Combine
publisher
  .sink { value in
    self.updateUI(value)  // Missing [weak self]!
  }

Example Output

# Tech Debt Analysis Report

## Health Score: 72/100

### Issues by Severity
| Severity | Count |
|----------|-------|
| Critical | 2 |
| High | 15 |
| Medium | 45 |
| Low | 120 |

## Top Recommendations

1. **Address Critical Issues Immediately**
   Fix 2 critical security issues.

2. **Clean Up TODO/FIXME Comments**
   Found 45 TODO comments - consider creating tracked issues.

Code Quality

Tech Debt MCP practices what it preaches — built with AI-assisted vibe coding, it maintains an A rating by regularly scanning itself. Internal refactors (e.g., nesting reduction in customRulesEngine.validatePattern via extracted helper — #146) are driven by self-scan findings.

Self-Scan Results (v2.0.2, April 2026)

SQALE Rating: A (Excellent)
Debt Score: 5/100 (Target: ≤5/100)
Total Issues: 13 (0 critical, 0 high, 6 medium, 7 low)
Remediation Time: 14 hours
Health Score: 95/100

Down from 118 issues / 42.4 health in the v2.0.1 baseline after the v2.0.2 security hardening, ruleExclusions config, nesting refactors (#113, #118, #131, #146), and custom-rules handler extraction (#145). Remaining debt: 5 nesting hotspots (4 in server / core modules + 1 in eslint.config.mjs), 7 type-assertion usages at system boundaries, and 1 non-null assertion. See TECH_DEBT_SCAN.md for per-issue detail.

Development

npm install --include=dev --ignore-scripts  # Install dependencies (incl. devDependencies)
npm run typecheck  # Type-check without emitting output
npm run lint       # Lint source files
npm run build      # Compile TypeScript
npm run dev        # Run with ts-node
npm run watch      # Watch mode
npm test           # Run tests

Documentation

ARCHITECTURE.md - System architecture and design patterns
ROADMAP.md - Development phases and future enhancements
CONTRIBUTING.md - Contribution guidelines
CHANGELOG.md - Version history and changes
RELEASE.md - Release process and versioning guide
TECH_DEBT_SCAN.md - Self-scan results with before/after comparison
CODE_OF_CONDUCT.md - Community standards
PRIVACY.md - Privacy policy (also hosted at https://pierrejanineh.github.io/TechDebtMCP/privacy)
plugin/README.md - Plugin-user-facing docs (install, example transcripts, security posture)

Privacy

Tech Debt MCP runs entirely on your machine. Once installed, it reads files you pass it, returns issues to your MCP client over the local stdio transport, and does nothing else — the server itself makes no outbound network calls, has no telemetry, no analytics, and uses no third-party services. Installation via npm/npx does contact the npm registry as standard package-manager behavior; the MCPB bundle ships pre-installed and needs no further network access. See PRIVACY.md or the hosted policy at https://pierrejanineh.github.io/TechDebtMCP/privacy for details.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines and CODE_OF_CONDUCT.md for our community standards.

Releases

Latest:
Releases: GitHub Releases
Roadmap: See ROADMAP.md for planned features
Security: escapeRegExp() (src/utils/regexUtils.ts) must be used when interpolating captured strings into new RegExp() — see issue #128; handler output uses basename() / getRelativePath() to prevent absolute filesystem path leakage in intentional messages, and raw err.message strings from filesystem operations are sanitized before being returned to clients — see issue #129

License

MIT

Available Tools

16 tools

add_custom_ruleA

Destructive

Add a custom pattern-based tech debt rule.

ParametersJSON Schema

Name	Required	Description
`id`	Yes	Unique identifier for the rule
`pattern`	Yes	Regex pattern to match
`message`	Yes	Issue title/message
`severity`	Yes	Issue severity level
`category`	Yes	Debt category
`suggestion`	No	Optional: how to fix the issue
`languages`	No	Optional: apply only to specific languages
`flags`	No	Optional: regex flags (g, i, m, s, etc.)

TDQS

A3.5/5.0

Behavior3/5

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

Annotations already declare destructiveHint=true, and the description implies a create operation. No additional behavioral details are given (e.g., overwrites, validation side effects). The description adds minimal value beyond the annotation.

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 concise sentence with no redundant words, efficiently conveying the core purpose.

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?

Given 8 parameters (5 required) and no output schema, the description is minimal. It does not explain the relationship with siblings like execute_custom_rules or error scenarios, but it suffices for a straightforward creation tool.

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

Parameters3/5

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

Input schema has 100% description coverage; each parameter is documented. The tool description does not add any extra meaning or context beyond what the schema provides.

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 ('Add') and the resource ('custom pattern-based tech debt rule'), effectively distinguishing it from sibling tools like remove_custom_rule or list_session_custom_rules.

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, nor does it specify preconditions or context. It simply states what it does without usage criteria.

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

analyze_fileA

Read-only

Analyze a single file for technical debt issues.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes	Absolute path to the file to analyze

TDQS

A3.7/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true, indicating a safe read operation. The description adds context about analyzing for technical debt, but does not disclose any additional behavioral traits beyond what annotations provide. 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.

Conciseness5/5

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

The description is a single, front-loaded sentence that conveys the essential purpose without any unnecessary words. It is extremely efficient and easy to parse.

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?

Given the tool's simplicity (one parameter, no output schema), the description is marginally adequate but lacks details about return values or integration with other tools. More context could be provided to clarify how results are used.

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

Parameters3/5

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

Schema coverage is 100% with the 'path' parameter already described. The tool description adds context about analyzing for technical debt, but does not provide meaningful new information beyond the schema description for 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 verb (analyze), the resource (a single file), and the purpose (for technical debt issues). It effectively distinguishes from the sibling 'analyze_project' which analyzes an entire project, leaving no ambiguity about the tool's scope.

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 individual files, but does not explicitly state when to use this tool versus alternatives like 'analyze_project' or 'get_issues_by_category'. It lacks explicit 'when not to use' or comparison with other tools.

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

analyze_projectA

Read-only

Analyze an entire project for technical debt. Scans all supported files and returns a comprehensive report with issues, metrics, and recommendations.

ParametersJSON Schema

Name	Required	Description
`path`	Yes	Absolute path to the project root directory
`languages`	No	Optional: specific languages to analyze
`categories`	No	Optional: filter by debt categories
`severity`	No	Optional: minimum severity level
`maxFiles`	No	Optional: maximum number of files to analyze (minimum: 1)

TDQS

A4.2/5.0

Behavior5/5

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

Annotations declare readOnlyHint=true, and the description confirms a read-only scan of files. It adds context about returning a comprehensive report, consistent with annotations. 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.

Conciseness5/5

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

Two sentences, front-loaded with purpose, no redundant information. Every word contributes to understanding the tool's function.

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 no output schema, the description does not detail the report structure, but it mentions key components (issues, metrics, recommendations). Sibling tools cover specific aspects, so the description is mostly complete for an overview.

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

Parameters3/5

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

Schema coverage is 100%, so description adds marginal value beyond the schema. Parameters are adequately described in the schema, and the description does not introduce additional semantics or usage tips.

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 the tool analyzes an entire project for technical debt, distinguishing it from siblings like 'analyze_file' (single file) and 'get_debt_summary' (summary only).

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 full-project analysis but lacks explicit guidance on when to use this tool versus alternatives (e.g., analyze_file for single files, get_debt_summary for summaries). No exclusions are stated.

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

check_dependenciesB

Read-only

Analyze project dependencies across multiple package managers.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes	Absolute path to the project root directory
`includeDev`	No	Optional: include development dependencies (default: true)

TDQS

B3.3/5.0

Behavior3/5

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

The annotations declare 'readOnlyHint: true', indicating the tool is safe and non-destructive. The description adds limited behavioral context: it 'analyzes' dependencies, implying no side effects, but does not elaborate on scope (e.g., recursive scanning, supported package managers) or output format. This is adequate given the annotations.

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, front-loaded sentence that efficiently communicates the core purpose without redundancy. Every word serves a clear function.

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?

Given the simple schema (2 parameters) and readOnlyHint annotation, the description is minimally sufficient. However, it lacks information about return values (no output schema), supported package managers, or how it differs from sibling tools. More context would improve completeness.

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

Parameters3/5

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

The input schema covers both parameters with clear descriptions (100% coverage). The description does not add parameter-specific insights, relying on the schema. The phrase 'multiple package managers' hints at the tool's behavior but does not enhance parameter understanding.

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

Purpose4/5

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

The description clearly states the tool's purpose: 'Analyze project dependencies across multiple package managers.' It specifies the action ('analyze') and the resource ('project dependencies') with added scope ('multiple package managers'), distinguishing it from generic analysis tools. However, it does not differentiate from siblings like 'analyze_project' or 'analyze_file'.

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 such as 'analyze_project' or 'get_debt_summary'. It does not mention prerequisites, limitations, or context-specific use cases. The agent receives no hints about appropriate scenarios.

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

execute_custom_rulesA

Read-only

Execute all custom rules against code or a file.

ParametersJSON Schema

Name	Required	Description
`path`	No	Absolute filesystem path to the file to analyze (maximum 500000 bytes). An empty string is treated the same as omitting the field.
`code`	No	Source code content to analyze directly (maximum 500000 characters; alternative to path). Either path or code must be provided.
`language`	No	Optional: programming language for filtering rules

TDQS

A3.7/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true, so the description mainly confirms execution without mutation. It adds that it runs 'all' custom rules, which is useful context. However, no additional behavioral details (e.g., performance impact, error handling) are disclosed beyond what annotations provide.

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, concise sentence that front-loads the purpose. Every word is necessary—no fluff or redundancy.

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?

The tool has 3 parameters with full schema descriptions and no output schema. The description covers the function but omits details about return values or output format. Given the simple nature of the tool, this is adequate but leaves room for improvement.

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

Parameters3/5

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

Schema coverage is 100%, so the parameters are fully documented in the schema. The description does not add significant meaning beyond restating that it analyzes 'code or a file,' which aligns with the 'path' and 'code' parameters. No extra details on format or constraints are provided.

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: 'Execute all custom rules against code or a file.' It identifies the verb (execute), resource (custom rules), and scope (code or a file), distinguishing it from siblings like 'add_custom_rule' or 'list_session_custom_rules'.

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 running custom rules but provides no explicit guidance on when to use this tool versus alternatives like 'analyze_file' or 'get_issues_by_category'. No exclusions or prerequisites are mentioned.

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

get_debt_summaryA

Read-only

Get a quick summary of technical debt in a project.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes	Absolute path to the project root directory

TDQS

A3.6/5.0

Behavior3/5

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

The description aligns with the readOnlyHint annotation, confirming it is a read operation. However, it adds little beyond the annotation—'quick summary' is vague and lacks specifics on aggregation, scope, or limitations.

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, well-structured sentence that is front-loaded with the verb. No extraneous words—every word earns its place.

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 simple input schema (one required param) and no output schema, the description provides adequate context. However, it could briefly note what the summary includes (e.g., count of issues, severity breakdown) to set expectations.

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

Parameters3/5

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

The input schema already fully covers the single parameter 'path' with a description ('Absolute path to the project root directory'). The tool description adds no further parameter context, so baseline score applies.

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 ('Get') and the resource ('quick summary of technical debt'), making the tool's purpose immediately understandable. It distinguishes itself from siblings like 'analyze_project' or 'get_issues_by_category' by emphasizing 'quick' and 'summary'.

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. The description does not mention exclusions, prerequisites, or suggest sibling tools for more detailed analysis.

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

get_issues_by_categoryB

Read-only

Get all issues of a specific category.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes	Absolute path to the project root directory
`category`	Yes	Category to filter by

TDQS

B3.4/5.0

Behavior3/5

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

Annotations already provide readOnlyHint: true, indicating a safe read operation. The description adds no further behavioral context (e.g., return format, pagination). With annotations covering safety, the description's minimal addition is acceptable but does not exceed expectations.

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, clear sentence with no wasted words. It is front-loaded with the action and resource, perfectly sized for the tool's simplicity.

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?

For a simple read tool with complete schema and annotations, the description adequately conveys the purpose. However, it could mention that results are returned as a list or that the path must be a valid project root, but these are implicit in the schema.

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

Parameters3/5

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

Schema coverage is 100% with clear descriptions for both parameters. The description adds no additional meaning beyond the schema, so it meets the baseline but does not enhance parameter understanding.

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

Purpose4/5

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

The description clearly states the tool retrieves issues filtered by category, which is a specific verb and resource. However, it does not distinguish from sibling tools like 'get_issues_by_severity' which also retrieves issues with a different filter.

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 such as 'get_issues_by_severity' or other filtering tools. There is no mention of context, 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_issues_by_severityB

Read-only

Get all issues of a specific severity level.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes	Absolute path to the project root directory
`severity`	Yes	Severity level to filter by

TDQS

B3.4/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true, and the description's 'Get' is consistent. No additional behavioral context is added, such as rate limits or data freshness. With annotations, the bar is lowered, so a neutral score.

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, efficient sentence. It is concise with no unnecessary words, though it could be slightly more informative without losing conciseness.

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?

Given the simplicity of the tool (2 params, no output schema), the description provides the core functionality. However, it lacks details about the scope (e.g., entire project) and output format, and with sibling tools, more context would help.

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

Parameters3/5

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

Schema coverage is 100% with both parameters described. The description does not add extra meaning beyond what the schema already provides, so baseline score applies.

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 verb 'Get' and the resource 'issues' with a specific filter 'severity level'. It distinguishes from sibling tools like 'get_issues_by_category' which filter by a different attribute.

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 such as 'get_issues_by_category' or 'get_vulnerability_report'. Missing when-not-to-use or prerequisite information.

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

get_recommendationsA

Read-only

Get prioritized recommendations for addressing technical debt.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes	Absolute path to the project root directory
`limit`	No	Optional: maximum number of recommendations to return (default: 5, minimum: 1)

TDQS

A3.6/5.0

Behavior3/5

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

The readOnlyHint annotation already declares the tool is safe; the description adds that recommendations are 'prioritized', but lacks details on ordering criteria, pagination, or other behavioral constraints.

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, front-loaded sentence that efficiently conveys the tool's purpose with no extraneous words.

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?

For a simple tool with two parameters and no output schema, the description adequately states the core function. However, omitting prerequisites (e.g., project analysis) and output format limits completeness.

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

Parameters3/5

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

Schema coverage is 100%, with both parameters described in the schema. The description does not add further meaning beyond the schema, so baseline score applies.

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 'Get prioritized recommendations for addressing technical debt' clearly states the tool's function. It distinguishes from siblings like get_debt_summary and get_issues_by_category by focusing on prioritized actionable items.

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 such as get_debt_summary or get_issues_by_category, leaving the agent without 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.

get_sqale_metricsB

Read-only

Get SQALE technical debt metrics including remediation time, debt ratio, and rating.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes	Absolute path to the project root directory
`developmentTime`	No	Optional: estimated development time in hours for debt ratio calculation

TDQS

B3.4/5.0

Behavior3/5

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

Annotations declare readOnlyHint=true, confirming no destructive behavior. The description adds that output includes remediation time, debt ratio, and rating, but does not disclose other behavioral traits like caching or performance implications.

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?

Single sentence, front-loaded with purpose and key outputs. No extraneous words or structure issues.

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?

Adequate for a simple read-only tool with well-documented parameters and no output schema. However, lacks explicit mention that the tool operates on a project path (though schema covers it) and could better tie description to the path parameter.

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 100%, but the description adds value by explaining the optional developmentTime parameter's role in debt ratio calculation, linking the parameter to its purpose beyond schema types.

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 'get' and the resource 'SQALE technical debt metrics', specifying included fields. However, it does not differentiate from siblings like get_debt_summary, which may also provide debt metrics but not SQALE-specific.

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 such as get_debt_summary or get_issues_by_category. The description implies use for SQALE metrics but lacks context on 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_vulnerability_reportA

Read-only

Generate an offline dependency report listing all project dependencies for vulnerability review. Note: actual CVE lookups require Phase 2b online integration.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes	Absolute path to the project root directory
`includeDev`	No	Optional: include development dependencies (default: false)

TDQS

A4.1/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true, indicating a safe read operation. The description adds value by explaining that the report is offline and that CVE lookups are not included, which prevents false expectations. There is no contradiction with annotations.

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 consists of two short, focused sentences. The first sentence states the core purpose, and the second adds a critical limitation. No wasted words.

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?

Without an output schema, the description does not explain the report's format, structure, or how the output is delivered (e.g., file path or response object). The note about CVE integration adds context, but the description leaves room for ambiguity about the output's nature.

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

Parameters3/5

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

Schema coverage is 100%, so the schema already describes both parameters (path and includeDev). The description adds only that the report lists 'all project dependencies for vulnerability review,' but does not enhance parameter understanding beyond what the schema provides. Baseline 3 is appropriate.

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: generating an offline dependency report for vulnerability review. It uses a specific verb ('generate') and resource ('dependency report'), and the phrase 'offline' distinguishes it from sibling tools like check_dependencies that may perform online checks.

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?

The description notes that actual CVE lookups require Phase 2b online integration, providing clear context that this tool is for offline report generation only. This implies when not to use it (for full vulnerability analysis), but it does not explicitly name sibling alternatives or provide exclusions.

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

list_session_custom_rulesA

Read-only

List custom rules registered in this server session via add_custom_rule. Does NOT include customPatterns declared in .techdebtrc.json (those run inside analyze_project via AnalysisEngine but are not surfaced here). Renamed from list_custom_rules (TEC-51) for clarity; the old name is no longer registered.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already provide readOnlyHint=true. The description adds behavioral context by clarifying that the tool only lists session rules, not file-based patterns, and mentions the old name removal. 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.

Conciseness5/5

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

Two sentences, each purposeful. The first states the core function, the second clarifies exclusions and renaming. No fluff, highly efficient.

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?

For a zero-parameter, read-only list tool, the description covers what is listed and excluded. Without an output schema, it could mention the return structure, but the function is straightforward and the sibling tool add_custom_rule hints at the rule format. Slightly incomplete but acceptable.

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 has no parameters (100% coverage), so baseline is 4. The description does not need to add parameter semantics; it correctly omits them.

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 lists custom rules registered via add_custom_rule in the server session. It explicitly distinguishes from customPatterns in .techdebtrc.json and notes a renaming for clarity, making it specific and differentiating from siblings.

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?

It explains what the tool does and excludes (file-based custom patterns), providing clear context. However, it does not explicitly say when to use it versus alternatives like analyze_project, though the exclusion implies it.

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

list_supported_languagesA

Read-only

List all programming languages supported by the analyzer.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.3/5.0

Behavior3/5

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

The description aligns with the readOnlyHint annotation. It adds no additional behavioral context beyond the purpose, but for a simple listing tool this is acceptable.

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 concise sentence with no wasted words, front-loaded with the action and object.

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

Completeness5/5

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

For a parameterless tool with no output schema, the description is complete. It fully explains what the tool does without requiring additional 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?

There are no parameters, and the schema coverage is 100% (vacuously). The description does not need to add parameter details. Baseline 4 for zero parameters.

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 verb 'list' and the resource 'programming languages supported by the analyzer', distinguishing it from sibling tools which focus on analysis, rules, and reporting.

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?

The tool's purpose is straightforward and no explicit alternatives are needed. Context is clear: to view all supported languages. No exclusions are required.

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

remove_custom_ruleA

Destructive

Remove a custom rule by ID.

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes	ID of the rule to remove

TDQS

A3.5/5.0

Behavior2/5

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

Annotations already declare destructiveHint=true; the description adds 'Remove', which aligns but provides no additional behavioral details beyond what the annotation states.

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, concise sentence with front-loaded verb and no unnecessary words.

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 one-parameter tool with destructive annotation, the description is minimally adequate but lacks details on return values or behavior for non-existent IDs.

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

Parameters3/5

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

Schema coverage is 100% and the parameter 'id' is well-documented. The description adds no new meaning beyond the schema's description.

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 removes a custom rule by ID, with a specific verb and resource. It distinguishes from siblings like add_custom_rule and list_session_custom_rules.

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 removing a rule, but lacks explicit guidance on when to use or not use, such as prerequisites or alternatives.

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

validate_configA

Read-only

Validate a .techdebtrc.json configuration file for syntax and schema correctness.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes	Absolute path to the project root directory or directly to a .techdebtrc.json file

TDQS

A3.5/5.0

Behavior3/5

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

Annotations indicate readOnlyHint=true; description aligns with read-only validation. However, no additional behavioral details (e.g., file required to exist, error reporting) beyond what annotations provide.

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?

Single sentence with no wasted words, directly conveying the tool's purpose.

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?

No output schema, and description does not explain what the validation returns (e.g., boolean, error messages). Lacks completeness for an agent to anticipate the result.

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

Parameters3/5

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

Schema coverage is 100% for the single 'path' parameter. Description does not add meaning beyond the schema's description of 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?

Description clearly states the tool validates a .techdebtrc.json file for syntax and schema correctness, using specific verb and resource. It is distinct from sibling tools.

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 vs alternatives like validate_custom_pattern, nor any prerequisites or exclusions provided.

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

validate_custom_patternA

Read-only

Validate a custom pattern before adding it as a rule.

ParametersJSON Schema

Name	Required	Description
`id`	Yes	Unique identifier for the rule
`pattern`	Yes	Regex pattern to validate
`message`	Yes	Issue title/message
`severity`	Yes	Issue severity level
`category`	Yes	Debt category

TDQS

A3.7/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true, confirming read-only behavior. Description adds the 'before adding' workflow context but does not disclose additional behavioral traits beyond the annotation.

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?

Single, front-loaded sentence with no extraneous words. Efficiently conveys the tool's purpose.

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?

With 5 required parameters and no output schema, the description adequately hints at usage but does not specify return value or validation result format, leaving some uncertainty for the agent.

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

Parameters3/5

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

Schema coverage is 100% with each parameter described. Description reinforces that parameters compose a pattern but adds no new semantics beyond what the schema provides.

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 'Validate a custom pattern before adding it as a rule', specifying the action and resource, and distinguishes from sibling 'add_custom_rule'. However, it lacks detail on what validation entails (e.g., syntax, semantics).

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?

The phrase 'before adding it as a rule' provides clear usage context, implying it should be used prior to 'add_custom_rule'. No explicit when-not-to-use or alternatives, but the context is sufficient.

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.

16 tool updatesv2.1.0Jun 3, 2026
- First observedadd_custom_rule
- First observedanalyze_file
- First observedanalyze_project
- First observedcheck_dependencies
- First observedexecute_custom_rules
- First observedget_debt_summary
- First observedget_issues_by_category
- First observedget_issues_by_severity
- First observedget_recommendations
- First observedget_sqale_metrics
- First observedget_vulnerability_report
- First observedlist_session_custom_rules
- First observedlist_supported_languages
- First observedremove_custom_rule
- First observedvalidate_config
- First observedvalidate_custom_pattern

Install Server

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

TDQS

A3.8/5.0

Disambiguation5/5

Each tool has a distinct purpose. analyze_file vs analyze_project differ by scope. get_issues_by_category and get_issues_by_severity filter differently. Custom rule tools (add, remove, list, execute) are clearly separate actions. No overlapping functionality.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case. Verbs like add, analyze, check, execute, get, list, remove, validate are used predictably. No mixing of conventions.

Tool Count4/5

16 tools is slightly above the typical 3-15 range, but each tool serves a clear purpose for tech debt analysis. The count is reasonable for the domain and does not feel excessive.

Completeness4/5

The tool surface covers analysis, custom rules, metrics, filtering, recommendations, and config validation. Minor gaps: get_vulnerability_report is offline only (no actual CVE lookup), and there is no tool for tracking debt over time. Otherwise complete for its purpose.

Maintenance

ActivitySlowing

ResponsivenessSyncing

Resources

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

Android Security Analyzer A
io.github.ako2345
MCP server for static security analysis of Android source code
Security Code Analysis Testing & QA Tools
422
neverinfamous-memory-journal-mcp
ai.smithery
A MCP server built for developers enabling Git based project management with project and personal…
Version Control Developer Tools Project Management
320
Compuute MCP Security Scanner A
io.github.Compuute
Scan any public GitHub MCP-server repo for security issues. 37 MCP-specific L1 rules, 8 languages.
Security Code Analysis Version Control
12
mcpcheck B
io.github.joeyough
Scan any MCP server for tool-poisoning, security, auth & license. Trust score before install.
Penetration Testing Security
21

Related MCP Servers

GitHub PR Review MCP Server
Version Control Code Analysis Security
Vibe-Code-Agent
A
license
Not graded
quality
F
maintenance
Comprehensive MCP server for analyzing GitHub pull requests, detecting security vulnerabilities, assessing code quality, and providing risk ratings across multiple languages.
Updated 9 months ago (2025-12-08 02:28 UTC)
9
MIT
code-graph-mcp
Developer Tools Code Analysis Software Architecture
eas4ai
A
license
A
quality
D
maintenance
MCP server for comprehensive code analysis, navigation, and quality assessment across 25+ programming languages.
Updated a year ago (2025-07-26 13:27 UTC)
9
88
MIT
Code-Oracle
Code Analysis Security Developer Tools
Sri-Lohith-Mulugu
F
license
Not graded
quality
D
maintenance
MCP server for automated architectural mapping, security vulnerability detection, ML asset tracking, and code metrics in local repositories.
Updated 5 months ago (2026-04-21 10:35 UTC)
-
code-review-mcp-server
Code Analysis Developer Tools Testing & QA Tools
troshenkov
A
license
Not graded
quality
F
maintenance
An MCP server that provides senior-level code review, quality checks, security analysis, and refactoring suggestions directly in your editor.
Updated 4 months ago (2026-05-15 04:49 UTC)
1
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/PierreJanineh/TechDebtMCP'

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