This server provides deep structural analysis of TypeScript/JavaScript code using the TypeScript Compiler API, supporting JSX/TSX and treating arrow functions as first-class. It offers syntactic and semantic tier analysis.
Structural Queries
analyze_file – File-level summary of symbols (classes, interfaces, types, enums, functions)
list_functions – All functions/methods with signatures and line ranges
get_function_body – Extract a function's implementation (supports Class.method)
list_methods – Methods for a class or interface
get_type_definition – Full definition of any type
list_declarations – Module-level const/let/var declarations with types
list_exports – Exported symbols and their kind
list_imports – Import statements with bindings and module paths
find_usages – All occurrences of an identifier (file or directory)
Call Analysis
call_graph – Mermaid call graph diagrams (forward/reverse, file/package scope, focus on function, include external calls)
get_callers – Reverse call graph (file or directory)
Code Quality & Dead Code
code_complexity – Cyclomatic complexity per function
code_smells – Long functions, deep nesting, god classes, as any, non-null assertions
find_errors – Floating promises, empty catches, double type assertions
dead_code – Unreferenced unexported symbols
find_implementations – Classes implementing an interface (explicit, inherited, structural via type checker)
Documentation & IDE Integration
get_doc – JSDoc/TSDoc extraction (supports Class.method)
find_node_at_position – AST node at cursor position
Multi-file Analysis
analyze_package – Directory summary of TS/JS files
diff_ast – Structural diff between two file versions (added/removed/modified symbols)
Click on "Install 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., "@TypeScript AST MCP Server generate a call graph for processUser in src/auth.ts"
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.
A Model Context Protocol (MCP) server for deep structural analysis of TypeScript and JavaScript source code. Unlike text-based search, this server parses your code with the TypeScript Compiler API and walks the real AST - types, functions, call relationships, interface satisfaction, and more.
Most tools run on the syntactic tier (ts.createSourceFile, no type resolution) because it is fast and needs no build. find_implementations runs on the semantic tier - a full ts.Program and its type checker - because deciding whether a class satisfies an interface cannot be done from syntax alone. Each tool's tier is stated in the table below.
Companion to py-ast-mcp, the same idea applied to Python; a Go AST MCP server by another author served as prior art for this one.
20 analysis tools covering file-level, directory-level, and cross-file structural queries
Fast syntactic parsing - ts.createSourceFile() per file, under 5ms; cross-file tools re-parse in scope, so results always reflect the latest edit
Arrow function awareness - const foo = () => {} treated as first-class functions throughout
Signature extraction - parameters, class-qualified names, and return types as written. These come from the annotation, so an unannotated return reads as blank rather than as the inferred type
Call graph generation with Mermaid diagrams, forward and reverse traversal, file or package scope
Cyclomatic complexity computation per function
Interface implementation discovery - explicit implements plus structural matches decided by the type checker's own assignability rules, so member types and call signatures count, not just member names
Structural diffing between file versions (added/removed/modified symbols)
Cursor-position awareness for IDE integrations
JSX/TSX parsing - .tsx/.jsx files parse under the right ScriptKind, so every tool works on React source. There is no React-specific analysis: a component is a function like any other
TypeScript-specific quality checks - any casts, non-null assertions, floating promises, empty catches, double assertions
Dead code detection - unexported symbols never referenced within their own file. Unexported means file-local, so that is the whole search space. A same-named binding in another scope of the same file still reads as a use, which makes this under-report rather than over-report
JSDoc/TSDoc extraction for any symbol
Related MCP server: TypeScript Extractor MCP Server
Tool | Description | Parameters |
| High-level summary of the file's own symbols: classes, interfaces, types, enums, namespaces, functions. Class members are left to |
|
| List all functions/methods with full signatures and line ranges, including accessors ( |
|
| Extract a function/method body (supports |
|
| List all methods for a class or interface |
|
| Extract any type definition (interface, type alias, class, enum) |
|
| List module-level const/let/var with types |
|
| List all exported symbols with kind (function, class, type, namespace, re-export). An overloaded function is one symbol |
|
| List all import statements with bindings and module paths |
|
| Find all occurrences of an identifier with source context, in one file or across a directory |
|
Tool | Description | Parameters |
| Generate a Mermaid call graph diagram |
|
| Reverse call graph - find all callers of a function |
|
* Optional call_graph parameters:
function - Focus on calls reachable from this function only
direction - TD (top-down, default) or LR (left-right)
include_external - Include calls to functions not defined in the file (default: false)
scope - file (default) or package (cross-file analysis)
* Optional get_callers parameter:
scope - file (default) or package (search all files in the directory)
* Optional find_usages parameter:
scope - file (default) or package (search all files in the directory). Passing a
directory as path implies package.
Tool | Description | Parameters |
| Cyclomatic complexity per function |
|
| Long functions, deep nesting, god classes, |
|
| Floating promises, empty catches, double type assertions, optional chain + non-null |
|
A floating promise here means a discarded call to a function the same file declares async (or to fetch). Without type resolution that is the limit of what can be claimed soundly - an imported async function is not detected. It under-reports on purpose: the alternative is guessing from the callee's name, which reports map.get(k).
| dead_code | Find module-local symbols never referenced inside their own file: unexported declarations, plus private and #name class members | path (directory), include_tests* |
| find_implementations | Find classes satisfying an interface, labelled explicit / inherited / structural and marked abstract where it applies (semantic tier) | path, interface |
* Optional - omit to report all functions / exclude test files.
Tool | Description | Parameters |
| Extract JSDoc/TSDoc comments for any symbol (supports |
|
Tool | Description | Parameters |
| Directory-level summary of all TS/JS files |
|
| Structural diff between two file versions (added/removed/modified) |
|
* Optional - include test files (default: false).
Tool | Description | Parameters |
| Identify the AST node at a cursor position |
|
Add a .mcp.json file to the repository root:
{
"mcpServers": {
"ts-ast": {
"command": "npx",
"args": ["-y", "github:gclluch/ts-ast-mcp"]
}
}
}Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):
{
"mcpServers": {
"ts-ast": {
"command": "npx",
"args": ["-y", "github:gclluch/ts-ast-mcp"]
}
}
}Create .vscode/mcp.json in the project root:
{
"mcpServers": {
"ts-ast": {
"command": "npx",
"args": ["-y", "github:gclluch/ts-ast-mcp"]
}
}
}Add to the extension's MCP settings:
{
"mcpServers": {
"ts-ast": {
"command": "npx",
"args": ["-y", "github:gclluch/ts-ast-mcp"],
"env": {}
}
}
}For working on ts-ast-mcp itself, clone and build locally:
git clone https://github.com/gclluch/ts-ast-mcp.git
cd ts-ast-mcp
npm install # prepare script builds automaticallyThen point your .mcp.json at the local build:
{
"mcpServers": {
"ts-ast": {
"command": "node",
"args": ["/path/to/ts-ast-mcp/dist/index.js"]
}
}
}Most tools use the syntactic tier - ts.createSourceFile() parses a single file in under 5ms. No tsconfig or type checker needed.
Tools that operate across files (dead_code, analyze_package) and tools with scope: "package" (call_graph, get_callers) do this by re-parsing every file in scope on each call via the syntactic parser - always correct on the latest edit, at the cost of re-parsing repeatedly.
The semantic tier backs find_implementations, the one question that syntax cannot answer: whether a class satisfies an interface depends on member types and call signatures, not member names. loadProgram() (in src/parse.ts) builds a cached ts.Program and hands the tool the real type checker, which then answers via isTypeAssignableTo - the same rule the compiler applies to an implements clause.
Compiler options come from the nearest tsconfig.json; the file list never does. findConfigFile walks up, so the directory you asked about is routinely outside that config's include, and building from the config's own file list would produce a program that doesn't contain the files under analysis. The cache invalidates when the tsconfig's mtime changes or any file feeding the program changes, so an edit is always reflected on the next call while an unchanged tree reuses the Program.
Cost of the semantic tier is real: the first find_implementations call on a directory pays a full parse-bind-check pass. Subsequent calls on an unchanged tree are cache hits.
list_functions, code_complexity and call_graph share a single traversal
(src/scopes.ts). They used to carry one each, and each knew a different subset
of the language, so the three tools disagreed about the same file. Everything
that owns executable code is covered in one place:
Construct | Reported as |
|
|
function nested in another |
|
method, constructor |
|
|
|
class arrow property |
|
| marked |
namespace member |
|
object-literal method or arrow |
|
A consequence worth stating: a call written inside a nested function is attributed to that function, not to the one it is written in. A call inside an anonymous callback is attributed to the enclosing named function, because that callback is not a scope anyone can name.
All output is plain text, not JSON.
npm install
npm test # builds, then runs the vitest suiteThe suite covers the pure helpers (listTsFiles, bindingNames) plus an
integration layer that spawns the real stdio server and drives it over JSON-RPC,
so tool wiring is exercised the way a client actually uses it.
Once registered, you can ask your AI assistant to:
"List all functions in Dashboard.tsx with their signatures."
"Extract the full definition of the UserConfig interface."
"Show me who calls the useApiQuery hook."
"Generate a call graph for utils/ErrorUtils.ts."
"What's the cyclomatic complexity of functions in DataTable.tsx?"
"Which classes implement the DataProvider interface?"
"Compare the old and new versions of api.ts structurally."
"What AST node is at line 42, column 10?"
"Give me a directory-level summary of src/hooks/."
"Find error patterns in AuthService.ts."
"Run a code smell check on BigComponent.tsx."
"Find dead code in src/utils/."
"What's the JSDoc for the useApiQuery function?"
"List all exports from src/types/index.ts."
Provides a high-level summary of all symbols (classes, interfaces, types, enums, functions) in a TypeScript/JavaScript file
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path to the TS/JS file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the core action (providing a summary) without disclosing side effects, read-only nature, performance implications, or error behavior. This is minimal disclosure for a tool that could potentially be used in a larger analysis workflow.
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, focused sentence that front-loads the main purpose and lists the symbol types. It is concise and contains no fluff or repetition.
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 is simple with one parameter and no output schema, and the description explains what it returns (a high-level summary of symbols). However, it lacks additional context such as expected output format, handling of large files, or relationship to sibling tools, leaving some gaps for an agent trying to fully understand its place in the toolset.
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 schema provides 100% coverage for the single parameter 'path' with a clear description. The tool description adds no additional parameter semantics, but since the schema already fully documents the parameter, the baseline 3 is appropriate.
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's function: providing a high-level summary of all symbols in a TS/JS file, listing specific symbol types (classes, interfaces, types, enums, functions). It distinguishes itself from siblings like list_declarations or list_functions by focusing on a summary rather than raw declarations.
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 when a high-level overview of a file's symbols is needed, but it does not explicitly state when to use this tool over alternatives or mention any exclusions (e.g., 'use list_declarations for detailed declarations'). There is clear context but no explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyzes all TypeScript/JavaScript files in a directory, providing a package-level summary
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path to the directory | |
| include_tests | No | Include test files (default: false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility. It discloses that all TS/JS files are analyzed, but does not clarify recursion, read-only nature, handling of non-TS files, or any limitations. This is insufficient given the absence of 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 entire description is a single sentence with no redundancy. It front-loads the verb and scope, making it easy to scan. Every word contributes.
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?
Without an output schema, the description should explain what the package-level summary contains or any directory traversal behavior. It only vaguely states 'package-level summary' and omits recursion semantics, error behavior, and potential performance implications. For a directory-wide analysis tool, this 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 100%, with both path and include_tests documented in the schema. The description adds no additional parameter meaning, so the baseline score of 3 applies.
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 'Analyzes' and identifies the resource ('all TypeScript/JavaScript files in a directory') and the output ('package-level summary'). This clearly distinguishes it from sibling analyze_file, which targets a single file.
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 use for whole-package analysis but does not explicitly state when to choose this over analyze_file or other siblings. No exclusion criteria or alternatives are mentioned, relying on the reader to infer scope.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generates a Mermaid flowchart showing the call graph of functions in a TypeScript/JavaScript file or directory
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path to the TS/JS file | |
| scope | No | Analysis scope: 'file' or 'package' | file |
| function | No | Focus on calls reachable from this function only | |
| direction | No | Graph direction: TD (top-down) or LR (left-right) | TD |
| include_external | No | Include calls to external functions |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for behavioral disclosure. It merely says it generates a flowchart, with no mention of read-only nature, performance implications, output format details, or how external calls are handled beyond the include_external parameter.
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 directly states the tool's purpose. No filler or redundancy; 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?
Despite having 5 parameters and two enums, the description offers no detail about the output format, return behavior, or limitations. It lacks information on how the Mermaid flowchart is returned (string? file?) and does not differentiate from similar sibling tools, making it incomplete for reliable 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?
Schema coverage is 100%, so the schema already documents parameters well. However, the description introduces ambiguity by saying 'file or directory' while the path parameter schema says 'file', potentially misleading an agent about accepted inputs. No additional parameter semantics are clarified.
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 states a specific verb ('Generates') and resource ('Mermaid flowchart showing the call graph of functions'), clearly distinguishing it from sibling analysis tools. The scope ('TypeScript/JavaScript file or directory') adds useful context.
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 like get_callers or find_usages. The description only states what it does, not when it's the preferred choice or when to avoid it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Computes cyclomatic complexity for functions in a TypeScript/JavaScript file
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path to the TS/JS file | |
| function | No | Compute only for this function (omit for all) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states the read-only computation nature, the supported file types, and the function scope. There are no side effects, auth requirements, or rate limits disclosed because none are relevant, making this adequate for a simple analysis tool.
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, direct sentence that immediately states the action and target. It contains no filler or redundant information, making it highly concise and well-structured.
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 is simple with two parameters and no output schema. The description clarifies purpose but does not mention the return format (e.g., a map of function names to complexity values) or error behavior. Given the tool's simplicity, leaving out return details is a minor gap, so a mid-range score is justified.
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 descriptions for both 'path' and 'function' already fully explain their meanings (absolute path and optional function filter). The tool description adds no additional parameter-level detail, so with 100% schema coverage, the baseline score of 3 is appropriate.
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 the specific verb 'Computes' with the resource 'cyclomatic complexity for functions in a TypeScript/JavaScript file', clearly distinguishing it from sibling analysis tools like code_smells or find_errors. It precisely scopes the input (functions in a file) and leaves no ambiguity about what the tool does.
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 measuring cyclomatic complexity but does not explicitly state when to choose this tool over siblings such as code_smells or analyze_file. There are no exclusions or preferred contexts, so the guidance is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Detects code smells: long functions, too many parameters, deep nesting, god classes, 'any' casts, non-null assertions
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path to the TS/JS file | |
| function | No | Scope analysis to a specific function |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the burden of behavioral disclosure. It lists the types of smells detected, giving some transparency, but does not mention whether the tool is read-only, what output format to expect, or any limitations (e.g., static analysis only).
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 with a list of concrete examples. It is front-loaded with the main verb and resource, and every word contributes. No redundant or misleading content.
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 no output schema, so the description should explain what the tool returns or how results are presented. It does not, leaving a significant gap. It also lacks context about the tool's role within the sibling set, making it incomplete for an agent to fully understand the tool's behavior.
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 100% for both parameters (path and function), so the baseline is 3. The description adds no extra meaning beyond what the schema already provides; for example, the 'function' parameter's scoping behavior is already described in the schema.
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's purpose: detecting code smells. It enumerates specific smells (long functions, too many parameters, deep nesting, god classes, 'any' casts, non-null assertions), which provides concrete examples and distinguishes it from sibling tools like code_complexity or dead_code.
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 the tool (when you want to detect code smells) but does not explicitly mention alternatives or exclusions. It lacks guidance on when not to use it or how it compares to similar tools like code_complexity or dead_code.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Finds unreferenced unexported symbols (functions, types, variables) within a directory
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path to the directory | |
| include_tests | No | Include test files (default: false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that it finds only unexported unreferenced symbols within a directory, adding some behavioral context. However, it does not explain how 'unreferenced' is determined, whether cross-package references are considered, or what the return format looks like.
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 clearly states the action and scope without extraneous information. 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?
For a simple read-only analysis tool with two fully documented parameters, the description covers the core function and scope adequately. Although there is no output schema or return format explained, the nature of the tool makes the result (a list of dead symbols) reasonably implicit. Slightly more detail on the definition of 'unreferenced' would make it fully 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?
Schema coverage is 100%, with both 'path' and 'include_tests' fully described. The tool description adds no additional parameter semantics beyond what the schema provides, so baseline 3 is appropriate.
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 'Finds unreferenced unexported symbols (functions, types, variables) within a directory' uses a specific verb and resource, clearly stating the tool's scope. It distinguishes itself from siblings like list_declarations or find_usages by focusing on unreferenced, unexported symbols.
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 dead code detection within a directory but does not provide explicit when-to-use/when-not-to-use guidance or name alternative tools. There is no exclusionary context, so the usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compares two TypeScript/JavaScript files structurally, reporting added/removed/modified symbols
| Name | Required | Description | Default |
|---|---|---|---|
| new_path | Yes | Absolute path to the new version of the file | |
| old_path | Yes | Absolute path to the old version of the file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations available, the description carries the full burden of behavioral disclosure. It mentions that the comparison is 'structural' and reports 'added/removed/modified symbols', which gives some insight into behavior. However, it does not describe whether the tool is read-only, how it handles syntax errors, or the exact output format, leaving some ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that starts with the action verb and immediately conveys the core purpose and output. There is no redundant or filler content, and every word contributes meaning.
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's simplicity (two parameters, no output schema), the description is mostly complete. It clearly states what it does (structural comparison) and what it reports (added/removed/modified symbols). It could be enhanced by explicitly noting that the paths must be files on disk or by specifying the output structure, but these gaps are minor for a tool of this complexity.
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 provides full coverage of the two parameters, both with clear descriptions ('Absolute path to the old/new version of the file'). The description adds no additional meaning beyond what the schema already states, so the baseline score of 3 is appropriate.
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's purpose with a specific verb ('Compares') and resource ('two TypeScript/JavaScript files structurally'). It distinguishes itself from sibling tools like analyze_file and list_declarations by focusing on differential analysis between two files rather than inspecting a single file.
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 a use case: comparing old and new versions of a file to see structural changes. However, it provides no explicit guidance on when to choose this tool over alternatives, nor does it mention exclusions or prerequisites. The contrast with sibling tools is implicit through the phrase 'two files', but it's not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyzes TypeScript-specific error patterns: floating promises, empty catches, unsafe type assertions, double assertions
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path to the TS/JS file | |
| function | No | Scope analysis to a specific function |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only lists the patterns analyzed but does not disclose what the tool returns, whether it modifies anything, or any prerequisites. With no annotations available, this leaves important behavioral aspects unstated.
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, focused sentence front-loads the key purpose and lists concrete error patterns; no 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?
Without an output schema, the description should explain the return value or result format, but it only mentions the analysis scope. The lack of behavioral context (e.g., read-only, output shape) makes it incomplete for an agent to fully anticipate the tool's response.
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 schema already fully describes both parameters (path and function) with 100% coverage, so the description adds no additional parameter meaning. Baseline score of 3 is appropriate.
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 'Analyzes' and a specific resource 'TypeScript-specific error patterns' with concrete examples (floating promises, empty catches, etc.), clearly distinguishing it from sibling tools like code_smells or dead_code.
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?
It gives clear context by specifying TypeScript-specific patterns, implying it's for TS files, but it does not explicitly compare with alternatives or explain when to prefer it over tools like code_smells.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Finds classes that implement a specified interface - explicit 'implements' plus structural matches, checked by the TypeScript type checker (member types and call signatures, not just names)
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path to the file or directory to search | |
| interface | Yes | Name of the interface to check against |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the disclosure burden. It discloses the TypeScript type checker usage and that it checks member types and call signatures, not just names, which is a valuable behavioral trait. However, it does not explicitly mention side effects, error conditions, or read-only nature, though 'finds' implies a non-mutating operation.
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 front-loads the core action and then adds relevant details about structural matching and type checking. Each clause contributes necessary information, and it avoids redundancy or excessive length.
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 description thoroughly explains the tool's approach and purpose, but it does not describe the return format (e.g., list of classes, file locations) or any prerequisites such as a valid TypeScript project. Since there is no output schema, these omissions leave gaps in what an agent can expect from the tool.
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 already describes both parameters with 100% coverage. The description adds minimal per-parameter meaning beyond implying that the interface is used for type checking, which is already evident from the tool's purpose. Thus, the baseline of 3 is appropriate.
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 finds classes implementing a specified interface, with specific details on explicit 'implements' and structural matches. This makes it distinct from sibling tools like find_usages or get_type_definition, which serve different 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?
The description implies its usage when the agent needs to discover classes that implement an interface, but it does not explicitly compare with alternatives or state when not to use it. There is no guidance on selection among sibling tools, so it only provides implied context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Identifies the AST node at a given cursor position (line and column) in a TypeScript/JavaScript file
| Name | Required | Description | Default |
|---|---|---|---|
| line | Yes | Line number (1-based) | |
| path | Yes | Absolute path to the TS/JS file | |
| column | Yes | Column number (1-based) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for behavioral disclosure. The description states the tool 'identifies' a node, implying a read-only operation, but it does not disclose return format, error behavior (e.g., invalid position), or side effects, leaving significant behavioral ambiguity for an agent.
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 front-loads the core purpose. Every word is necessary, and there is no redundancy or 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?
While the tool has only three self-explanatory parameters, the absence of an output schema and annotations leaves the return value and error behavior completely unspecified. The description does not compensate for these gaps, so an agent would not know what to do with the result or how to handle failure cases.
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 100%: the input schema already provides clear descriptions for path, line, and column, including 1-based indexing. The description itself adds no extra parameter detail, so it remains at the baseline for full 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 uses a specific verb ('Identifies') and a precise resource ('AST node at a given cursor position'), clearly distinguishing it from sibling tools that focus on declarations, functions, usages, etc. It also scopes to TypeScript/JavaScript files, leaving no ambiguity about what the tool does.
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 when an agent has a positional query (line/column) in a TS/JS file, but it does not explicitly contrast with alternatives or state when not to use it. No exclusionary or alternative-tool guidance is provided, so the usage context is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Finds all occurrences of a specific identifier (variable, function, type) within a file
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path to the TS/JS file | |
| identifier | Yes | The name of the identifier to search for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the transparency burden, but it only states the search behavior without disclosing whether the operation is read-only, how results are returned, or any limitations. It also does not clarify if it searches comments, strings, or only code, which is a significant ambiguity.
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 directly states the tool's purpose without any extraneous information. It is appropriately sized and 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?
The description lacks information about the return format or output structure, which is critical since there is no output schema. It also does not provide context about the tool's behavior beyond the basic search, making it incomplete for an agent to know what to expect.
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 fully describes both parameters (path and identifier) with clear descriptions, and parameter coverage is 100%. The description adds no additional parameter semantics, which is acceptable under the baseline for high 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 states the tool finds all occurrences of a specific identifier within a file, specifying the verb, resource, and scope. It distinguishes itself from sibling tools like list_declarations by focusing on usages rather than declarations.
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 like list_declarations or find_implementations. There is no mention of prerequisites, exclusions, or typical scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Finds all functions in a file or package that call the specified function (reverse call graph)
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path to the TS/JS file | |
| scope | No | Analysis scope: 'file' or 'package' | file |
| function | Yes | Name of the target function (e.g., 'setup' or 'MyClass.method') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must disclose behavioral context on its own. It mentions scope (file/package) and the reverse call graph concept, but omits details like whether callers are direct or transitive, the format of the result, and handling of unresolved symbols. This leaves significant ambiguity.
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 action, target, and scope with no redundant words. It is ideally concise.
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 no output schema and no annotations, the description is too terse for a complex analysis tool. It fails to describe the return format, whether the search is direct or transitive, or how external function references are handled, leaving the tool under-specified for an agent.
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 fully covers all three parameters (100% coverage) with descriptions for path, scope, and function. The description adds no substantive parameter details beyond restating the 'file or package' scope already in the schema, so the baseline 3 applies.
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's purpose with a specific verb ('Finds'), resource ('functions in a file or package that call the specified function'), and explicitly notes 'reverse call graph', distinguishing it from the sibling call_graph tool.
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 reverse call analysis but does not explicitly reference alternatives or exclusion conditions. The term 'reverse call graph' hints at when to use it, but no direct comparison to siblings like call_graph or find_usages is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extracts JSDoc/TSDoc comments for a symbol (function, type, class, variable). Supports Class.method syntax.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Symbol name (e.g., 'Config', 'MyClass.method', 'DEFAULT_VALUE') | |
| path | Yes | Absolute path to the TS/JS file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full burden of behavioral disclosure. It states the core behavior (extracts comments) and the supported syntax, but does not explain what happens if no doc comment exists, whether it returns the raw comment, or any error behavior. This leaves moderate ambiguity for a simple read-only tool.
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, consisting of two short sentences that front-load the primary action. Every word adds value, with no fluff or redundancy.
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 is simple with two parameters and no output schema, but the description does not detail the return format or behavior in edge cases (e.g., missing comments, invalid symbol). Given the lack of output schema, this gap in completeness makes the description minimally adequate but not fully comprehensive.
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 schema already provides 100% coverage with descriptive examples for both parameters. The description adds the list of symbol types (function, type, class, variable), but this overlaps with the schema's example values, providing minimal additional meaning beyond the schema.
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 extracts JSDoc/TSDoc comments for a symbol, listing the symbol types (function, type, class, variable) and noting support for Class.method syntax. This specific verb+resource combination clearly distinguishes it from sibling tools like get_type_definition or get_function_body.
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 the tool is used when documentation comments are needed, but it does not explicitly state when to use it over alternatives or when not to use it. There are no references to other tools or context-based guidance, so usage is implied rather than clearly directed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extracts the full body of a specific function or method. Supports Class.method syntax.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Function name (e.g., 'setup' or 'MyClass.method') | |
| path | Yes | Absolute path to the TS/JS file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. 'Extracts' implies a read operation, and it mentions the name syntax, but it doesn't state side effects, permissions, or error behavior. It adds some context but lacks detail beyond the core action.
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 concise sentences. The first is front-loaded with the action, and the second adds necessary syntax detail. Every word earns its place with no redundancy.
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 simple two-parameter tool with no output schema, the description states the primary behavior but doesn't detail the return value format or clarify overlap with sibling tools like get_doc. It is adequate but not 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?
Schema description coverage is 100%: the 'name' parameter already includes the example ('MyClass.method'), and 'path' is described. The description's mention of 'Class.method' syntax adds no new information beyond what the schema already provides, so it's baseline.
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 states a specific verb 'Extracts' and the resource ('full body of a specific function or method'). It also clarifies 'Class.method' syntax support, which differentiates it from sibling tools like list_functions or get_type_definition.
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 use when needing a function's full body, but it doesn't explicitly state when to use this tool over alternatives or provide exclusions. No sibling tools are mentioned in the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extracts the full definition of any type (interface, type alias, class, enum) by name
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name of the type to extract | |
| path | Yes | Absolute path to the TS/JS file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only says 'extracts,' which does not disclose whether the operation is read-only, what happens if the type does not exist, or the exact return format. It lacks behavioral context beyond what the tool name already implies.
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 of 12 words, front-loaded with the verb and target, with no redundant information. 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 is simple, the schema fully documents both parameters, and the description communicates the main use case and supported type kinds. It omits details like return format and error behavior, but these are not critical for this activity, making the description sufficiently 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?
Schema coverage is 100%, giving baseline 3. The description adds valuable meaning by specifying the supported type kinds (interface, type alias, class, enum), clarifying what the 'name' parameter can refer to beyond the schema's generic 'Name of the type to extract.'
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 action (extracts), the target (full definition), and names specific type categories (interface, type alias, class, enum). This distinguishes it from sibling tools like list_declarations or analyze_file, which either enumerate or analyze rather than extract a specific type definition.
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 name' provides clear context for when to use this tool: when the agent knows the type name and needs its full definition. It does not explicitly mention alternatives or exclusions, but the purpose is so focused that the usage context is obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists package-level constant and variable declarations in a TypeScript/JavaScript file
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path to the TS/JS file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool is a read-only 'list' operation and clarifies the scope as 'package-level', but it does not describe the return format (e.g., array of names, objects with type) or any potential limitations (e.g., excluding declarations inside functions).
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 one concise sentence (13 words) that is front-loaded with the key verb 'Lists' and immediately specifies the resource and scope. No 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?
For a simple tool with one parameter and no output schema or annotations, the description covers the tool's purpose and scope but omits what the returned data looks like (e.g., list of names, declaration objects). This is a notable gap for an agent needing to interpret the result, though the tool's simplicity mitigates 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?
The schema defines the single parameter 'path' as 'Absolute path to the TS/JS file' with 100% coverage. The description adds no additional parameter information, so it relies entirely on the schema, which is adequate, thus scoring the baseline 3.
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 package-level constant and variable declarations in a TypeScript/JavaScript file. It specifies the action (lists), resource (constant and variable declarations), and scope (package-level), distinguishing it from siblings like list_functions and list_methods.
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 makes the tool's purpose clear enough for an agent to infer when to use it (when needing top-level const/let/var declarations). However, it does not explicitly mention alternatives or exclusions, such as 'use list_functions for functions'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists all exported symbols with their kind (function, class, interface, type, variable, re-export)
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path to the TS/JS file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only states listing behavior and does not explicitly confirm read-only semantics, mention permissions, error behavior, or any limitations. The verb 'lists' suggests non-mutating, but this is not explicitly stated.
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 front-loads the action and result. Every word earns its place, and it does not restate the tool name or repeat schema information.
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 simple tool with one parameter and no output schema, the description provides enough context: it explains what is listed and the kinds of symbols. It does not detail the return format, but this is largely inferable and the description mentions the key output aspects. Slightly more detail could improve it, but it is sufficiently 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?
Schema description coverage is 100%, so the schema already documents the 'path' parameter. The tool description does not add extra meaning beyond the schema's 'Absolute path to the TS/JS file'. Baseline 3 is appropriate as the schema handles parameter semantics.
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 ('Lists') and resource ('all exported symbols') and enumerates the kinds (function, class, interface, type, variable, re-export), which clearly distinguishes it from sibling tools like list_declarations and list_functions. The scope is unequivocal.
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 by stating what the tool does, but it does not explicitly say when to use it over alternatives such as list_declarations or list_functions. There is no exclusion guidance, leaving the agent to infer context from the name and sibling set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists all functions and methods in a TypeScript/JavaScript file with their signatures and line ranges
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path to the TS/JS file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description must carry the behavioral disclosure burden. It states that the output includes signatures and line ranges, giving some insight into the result, but it does not detail the exact return structure, error behavior on invalid paths, or whether it includes nested vs top-level functions. The read-only nature is implied by the verb 'Lists' but not explicitly stated.
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 of 17 words that immediately states the action, scope, and output. No filler or redundancy.
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's simplicity (one required parameter, no output schema), the description is fairly complete. It specifies the file type, the entities listed (functions and methods), and the output format at a high level (signatures and line ranges). The main missing piece is the exact JSON structure, but for a list tool this is reasonably inferred.
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 covers 100% of the single parameter with a clear description ('Absolute path to the TS/JS file'). The tool description adds no additional parameter semantics beyond what the schema already provides, so a baseline of 3 is appropriate.
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 the specific verb 'Lists' and identifies the resource as 'all functions and methods in a TypeScript/JavaScript file' with output details (signatures and line ranges). This clearly distinguishes it from sibling tools like list_methods (which likely only covers methods) and list_declarations (which covers broader declarations).
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 does not provide any explicit guidance on when to use this tool versus alternatives such as list_methods or list_declarations. No exclusions, prerequisites, or alternative tool names are mentioned; the usage is only implied by the action statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists all import statements in a TypeScript/JavaScript file with their bindings and module paths
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path to the TS/JS file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states a read-only action ('Lists') and describes the output contents, but does not disclose potential limitations, error behavior, or return structure beyond the bindings and module paths. For a simple list operation, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It directly communicates the tool's function and scope.
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 tool with one parameter and no output schema, the description adequately explains what the tool returns (bindings and module paths). It might be improved by specifying whether imports are sorted or filtered, but the core information is present and sufficiently complete for the tool's simplicity.
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 100%, with the only parameter 'path' described as 'Absolute path to the TS/JS file'. The description adds little beyond this, mainly reaffirming the file type. With full schema coverage, baseline 3 is appropriate.
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 ('Lists') and clearly identifies the resource ('all import statements in a TypeScript/JavaScript file') plus the detail 'with their bindings and module paths'. This distinguishes it from siblings like list_exports and list_functions.
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 the tool (when you need to inspect imports) but does not explicitly mention alternatives or when not to use it. Given the large set of sibling tools, explicit guidance would help, but the purpose is clear enough for basic inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists all methods for a specific class in a TypeScript/JavaScript file
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path to the TS/JS file | |
| type | Yes | The class name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must bear the full burden. It only states 'lists all methods' without clarifying whether inherited, private, or static methods are included, or what the return format is (e.g., names only or signatures). Lacks behavioral caveats such as error handling or output shape.
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, well-structured sentence that front-loads the core action ('Lists all methods') and immediately specifies the context. No filler or redundant information.
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's relative simplicity (2 params, no output schema, no annotations), the description is adequate but not fully complete. It does not mention the return value shape (e.g., array of strings) or behavior when the class is not found. It's a moderate gap, not completely inadequate.
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?
Input schema has descriptions for both required parameters (path and type) with 100% coverage, so the baseline is 3. The description adds no additional parameter semantics beyond what the schema already provides, which is acceptable but not enhanced.
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 all methods for a specific class in a TS/JS file. The verb 'lists' is specific, the resource 'methods' is precise, and the scope 'for a specific class' distinguishes it from sibling tools like list_functions and list_declarations.
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: when you need methods of a particular class in a file, provide the path and class name. However, it does not explicitly mention when to use this over list_functions or list_declarations, nor does it note any exclusions. There's a clear context but no alternative guidance.
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.1.0analyze_fileanalyze_packagecall_graphcode_complexitycode_smellsdead_codediff_astfind_errorsfind_implementationsfind_node_at_positionfind_usagesget_callersget_docget_function_bodyget_type_definitionlist_declarationslist_exportslist_functionslist_importslist_methodsScored across 20 tools
Each tool targets a distinct aspect of TypeScript AST analysis, such as listing symbols, extracting definitions, analyzing dependencies, or detecting issues. Even related tools like call_graph and get_callers have clearly differentiated scopes, preventing misselection.
The majority of tools follow a consistent verb_noun snake_case pattern (list_functions, get_type_definition, find_usages). Minor deviations exist, such as noun-only names like call_graph, code_complexity, code_smells, and dead_code, but these remain readable and do not disrupt overall coherence.
With 20 tools, the server is slightly above the typical ideal range, but each tool addresses a distinct need within the TypeScript AST analysis domain. The count feels justified given the breadth of operations covered, from symbol enumeration to code quality checks.
The tool set provides comprehensive coverage for static AST analysis, including symbol discovery, detail extraction, relationship mapping, complexity measurement, error detection, and dead code identification. No obvious gaps exist for the server's stated purpose.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
AI-powered codebase analysis — call graphs, security, dead code, complexity. 150+ tools.
Ship production-ready TypeScript code in half the time, at half the cost.
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
