codex-workspace-codegraph-mcp

by lllli223

Overview Schema Related Servers Score Discussions

JavaScript

Local

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.2.0
Disambiguation3/5
Several tool clusters overlap—file writing (write_file/edit_file/apply_patch), file reading (read_file/read_many_files/codegraph_node/codegraph_explore), and codegraph queries (search/node/callers/callees/impact)—creating potential misselection. However, detailed descriptions and explicit 'use codegraph_explore instead' guidance help an agent choose correctly.
Naming Consistency4/5
All names are snake_case, and mutating actions generally use verb_noun (write_file, edit_file, move_path, create_directory, update_plan), while read judgements use noun_phrases (git_status, workspace_info, codegraph_files). Minor deviations like interactive_feedback and codegraph_node are noticeable but not confusing.
Tool Count2/5
With 34 tools, this is a very heavy surface for one MCP server. The wide scope—file ops, git, planning, and codegraph—explains the quantity, but the number still exceeds the range where a tool set is easy to navigate, and many tools could be consolidated.
Completeness4/5
The file workspace lifecycle is well covered (create, read, update, delete, move, list, search), and the codegraph side offers init, sync, search, impact, callers, callees, node, and explore. Missing git write operations (add, commit, push) and a dedicated file copy tool are workaroundable via exec_command.
Average 3.7/5 across 34 of 34 tools scored. Lowest: 2.7/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 1 commit in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under Apache 2.0.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint=false annotation already signals mutation, and the description adds the command and outcome. However, it does not disclose side effects such as whether an existing index is overwritten, whether hidden files are created, or whether re-running is safe. For a state-changing tool, this is too thin.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the action and then states the intended result. There is no padding, and the structure is appropriate for a tool with one optional parameter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The simple signature and lack of output schema reduce the burden, but the description still omits usage boundaries, side-effect expectations, and any indication of what success or failure looks like. An agent could guess the purpose, but not confidently decide between this and related codegraph project tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must explain the `path` parameter, but it only implies the workspace-or-subdirectory context. It never explicitly ties the path parameter to the command or describes path constraints, relative versus absolute paths, or how the default '.' interacts with the parameter.
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 names the exact command (`codegraph init .`), the scope (workspace or subdirectory), and the result (local code knowledge graph index). This is a clear verb+resource statement, though it does not explicitly differentiate itself from sibling tools like codegraph_project_sync.
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?
There is no guidance about when to use this tool versus alternatives. Sibling tools such as codegraph_project_sync and codegraph_project_status are not mentioned, so the agent gets no explicit help choosing between initialization and updating or checking status.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds that this tool executes `codegraph status` and returns MCP subprocess status, which is useful behavioral context. The annotations already declare `readOnlyHint: true`, so the read-only nature is covered. The description does not explain output format or failure behavior, but it adds some value beyond 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: one sentence with no filler. It could be restructured to include usage and parameter guidance, but as pure conciseness it is clean and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, a subtle `path` parameter, and a closely named sibling `codegraph_status`, this description is too sparse. It omits when to use the tool, what “MCP subprocess status” means, and whether `path` changes the project context. The read-only annotation helps, but does not fill the completeness gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema shows a `path` string with default `"."`, but no description of what that path controls. The description never mentions `path` or how it affects the command. With schema description coverage at 0%, the description should compensate, and it does not.
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 names a concrete action — run `codegraph status` — and a concrete result: the MCP subprocess status. This is clear enough to identify the tool's basic purpose. However, it does not distinguish this tool from the sibling `codegraph_status`, which is likely to overlap.
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?
There is no guidance on when to use this tool instead of `codegraph_status`, `codegraph_project_sync`, `integration_status`, or any other sibling. No alternatives, exclusions, or preconditions are mentioned, so the agent must infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already covers the safety profile, lowering the bar, and the description adds the semantic that it returns recent commit logs. However, it does not disclose filtering by path, how limit applies, or the shape/content of the returned logs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The single sentence is concise and front-loaded, but it is under-specified for a tool with three parameters and a family of closely related sibling tools. Brevity here is more a sign of missing content than of efficient structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has three parameters, no output schema, and close sibling git tools, yet the description only states what it returns. Key details such as path filtering, commit count limit, working-directory semantics, and how the output is formatted are absent, so it is not complete enough for reliable tool selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description is the only place to explain cwd, path, and limit, but it does not mention any parameter. 'Recent' only weakly hints at the limit parameter; path and cwd remain entirely unexplained.
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 states a specific action ('return') and resource ('recent commit logs'), which clearly identifies the tool's purpose. The phrase 'commit logs' also distinguishes it from sibling git tools like git_status, git_diff, and git_show.
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?
There is no guidance on when to choose git_log over alternatives such as git_status or git_show. The description does not state conditions, exclusions, or context, so an agent must infer when this tool applies.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint already signals no mutation, and the description adds that it covers work tree/staged areas and supports path restriction. However, it does not disclose behavior around default staged=false, whether stat output is returned, or the format of the diff, beyond what the annotation 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler or repetition. It efficiently conveys the core purpose and the main optional capability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Important context is missing: no output schema exists, no parameter descriptions exist, and the description does not explain return format, stat behavior, cwd semantics, or default behavior. For a tool with four parameters and zero schema descriptions, this is too sparse to fully guide correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains path ('可限制路径') and partially staged ('工作树或暂存区'), but leaves cwd and stat completely undocumented, and does not clarify the meaning or interaction of staged with the default work-tree diff.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns work-tree or staged-area differences and can restrict by path, which is specific and actionable. It does not explicitly name sibling tools, but the distinction from git_status/git_log/git_show is reasonably inferable from '差异'.
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 given on when to use this tool versus git_status, git_log, git_show, or exec_command. The description implies it is for diff viewing, but it does not state alternatives, exclusions, or the conditions that would make another tool more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation is present and the description's "view" wording is consistent with it. The description adds the path-restriction behavior, but does not disclose default revision behavior (HEAD) or the nature of the returned output. This is acceptable given the read-only 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 focused sentence with no filler. It front-loads the core action and the optional path restriction, making it concise 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?
For a simple read-only inspection tool with three optional parameters, the description gives the essential idea. However, it omits cwd semantics and revision format details, and there is no output schema to clarify return values. Still, an agent could likely invoke it correctly using defaults and git conventions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It maps "specified commit or object" to revision and "limit file path" to path, but it does not explain cwd, revision formats (branch, SHA, ref), or defaults. This is only partial parameter guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (view) and resource (a specified commit or object), and mentions the optional path restriction. It is distinguishable from git_status (repo state) and file-editing tools, though it does not explicitly contrast with git_log or git_diff.
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 gives no guidance about when to prefer this tool over alternatives like git_log or git_diff, and no exclusions or prerequisites. The path restriction is implied as a usage option, but no when-to-use or when-not-to-use context is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already covers the safety profile, and the description adds a useful workspace scope plus the observable behavior of returning line numbers. However, it does not disclose behavior for missing paths, binary files, encoding, or the effect of max_bytes, so behavioral detail remains limited.
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, front-loaded with the core read action and resource, followed by the key optional behaviors. No filler or redundant restatement of the annotated readOnlyHint.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters, no output schema, and only readOnlyHint annotation, the description is too thin. It fails to explain max_bytes, does not address error or edge-case behavior, and does not clarify how it differs from the nearby read_many_files tool, leaving an agent to guess at important invocation details.
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?
With 0% schema description coverage, the description compensates partially by explaining line-range control ('可指定行范围') and the line_numbers option ('返回行号'), and path is implied by '读取...文件'. However, max_bytes is completely undocumented in both schema and description, leaving a meaningful parameter unexplained.
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 names a specific verb ('读取'/read) and resource ('工作区内文本文件'/text files in the workspace), and notes the ability to specify a line range and return line numbers. It clearly separates reading from sibling write/edit/delete tools, but does not distinguish itself from the close sibling read_many_files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for reading workspace text files but offers no explicit guidance on when to prefer this tool over read_many_files, search_text, list_directory, or file_metadata. There are no when-to-use/ when-not-to-use criteria or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and requiresSourceAccess=true, so safety is covered. The description adds a useful behavioral detail: ripgrep is preferred and a Node fallback is used when ripgrep is missing, which can affect performance and regex support. This goes beyond the structured annotations and does not contradict them.
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 two short sentences with no filler: purpose first, implementation second. It is easy to scan and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, and the description does not explain return format, whether it searches file contents, matching behavior, or the effect of path/glob/limit. Given the number of parameters and the many search-like sibling tools, this is not enough for confident invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds almost no parameter meaning beyond implying that query is the text to search. There are six parameters and the schema has no property descriptions, so glob, path, limit, regex, and case_sensitive semantics are left entirely to inference.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action and resource: searching text in the workspace. However, it does not explicitly differentiate from sibling tools such as find_files (likely filename search) or codegraph_search, so the top differentiation criterion is not met.
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 gives no when-to-use guidance, exclusions, or alternatives. The ripgrep/Node fallback note is an implementation detail, not guidance about when to choose search_text over find_files, codegraph_search, or exec_command.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations only indicate readOnlyHint=false, which signals mutation. The description essentially restates the tool name ('sync') without adding meaningful behavioral context: it does not disclose whether the sync modifies local files, whether it is safe to rerun, how long it might take, or what happens if the index is missing or corrupt.
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 short sentence that names the command, the target, and the scope. It is front-loaded and contains no filler or redundant restatement beyond the core semantic info.
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 command-execution tool, the description provides the essential information: the command and the directory. However, it lacks context about required preconditions (except implied existing index), expected output, failure modes, and whether the operation has side effects beyond the local index. Given the minimal annotations and no output schema, the description is adequate but not thorough.
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?
With 0% schema description coverage, the description must carry the parameter meaning. It does clarify that `path` refers to the directory where the sync command executes. However, it does not explain path formatting, whether relative and absolute paths are both acceptable, or how the default '.' behaves in context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific operation: run `codegraph sync` in a specified directory to synchronize the existing index. The phrase '已有索引' distinguishes it from initialization-related siblings like codegraph_project_init, giving the agent a clear sense of what this tool does and when it applies.
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 explicit guidance is given about when to use this tool versus alternatives such as codegraph_project_init or codegraph_status. The only implied usage is through the word '已有', but the description does not state prerequisites, exclusions, or which sibling tools to prefer in other situations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already communicates that this is a safe read operation. The description adds the non-recursive 'direct children' behavior, which is useful, but does not disclose ordering, hidden-file handling, or path resolution semantics beyond the schema defaults.
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, short sentence with no filler. It states the core operation immediately and every word contributes to meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and no parameter descriptions, this description is too sparse. An agent cannot determine how to specify a subdirectory, whether hidden files are included by default, or what form the returned listing takes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not mention either the 'path' or 'include_hidden' parameters. The tool description provides no added meaning to help an agent understand what values to pass or how the defaults behave.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('列出') and a specific resource ('工作区目录的直接子项'), clearly indicating that it lists immediate children of a workspace directory. The word '直接' distinguishes it from recursive search tools like find_files.
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 flat directory listing but does not explicitly state when to prefer this tool over siblings such as find_files or read_many_files. There is no exclusion guidance, though the 'direct children' phrasing provides some implicit context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already establishes that this operation does not mutate state. The description adds that the tool returns type/size/mtime/permissions, which is useful context but does not disclose behavior for missing paths, symlinks, or error cases. With annotations covering the safety profile, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence that front-loads the verb and lists the returned metadata fields without redundant words. Every part contributes directly to the tool's purpose.
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 one-parameter, read-only metadata tool with no output schema, the description covers the essential return fields and accepts both files and directories. Missing edge-case behavior (nonexistent path, permission errors) is minor given the low complexity and readOnlyHint annotation.
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 provides only a required string 'path' with zero description coverage. The description partially compensates by indicating the path may refer to a file or directory, but it does not specify path format, relative/absolute requirements, or examples. Baseline 3 is justified because the single parameter is self-explanatory and the description adds some meaning.
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 uses a specific verb ('返回') and names the resource (文件或目录) plus the exact fields returned (类型、大小、修改时间和权限), making the purpose clear. It does not explicitly differentiate itself from sibling tools like read_file or list_directory, so it falls short of a 5.
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?
There is no guidance about when to choose file_metadata over siblings such as find_files, list_directory, or read_file. The description implies a metadata use case but provides no exclusions or alternative routing, leaving the decision to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already covers safety, and the description adds the scope of what is returned. However, it does not explain the shape of the status result, whether it aggregates live checks, or what "集成状态" includes. No contradiction exists.
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 one concise, front-loaded sentence that states the action and the involved subjects without any filler.
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 no-parameter, read-only status tool, the description is minimally adequate. Yet it lacks any clarification of the return structure and does not explain how this differs from sibling status tools, leaving some ambiguity for an agent choosing among them.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema is fully described, so there is no parameter meaning for the description to add. This baseline is appropriate.
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 uses a specific verb ("返回" / returns) and names the concrete resources: local workspace, feedback Web UI, and CodeGraph integration status. It is not a tautology, but it does not distinguish itself from sibling status tools such as workspace_info or codegraph_status.
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?
There is no guidance about when to use this tool versus the many closely related sibling status tools. No exclusions, alternatives, or selection criteria are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. But the description adds no behavioral detail beyond its core purpose: it does not disclose that results are direct callees only, how overloads or dynamic dispatch are handled, or what happens when multiple same-named symbols exist. The 'full flow' sentence is routing guidance, not a behavioral trait.
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 short sentences with no filler. The main action is front-loaded, and the alternative tool note is appended efficiently. Every word earns its place.
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 schema covers parameters well, but there is no output schema and the description does not describe the result shape, whether the list is sorted, or whether it includes only direct calls. Given the complexity of code-graph analysis, an agent would benefit from knowing what the returned list contains and how to disambiguate symbols, so the description is adequate but incomplete.
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 description coverage is 100%, so all four parameters are already documented in the input schema. The description introduces no additional parameter-level meaning beyond what the schema provides, which meets the high-coverage baseline but adds no extra value.
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 uses a specific verb-resource pair ('List functions that <symbol> calls') that unambiguously defines callees. It names one sibling (codegraph_explore) as an alternative, but does not explicitly contrast with codegraph_callers or clarify whether only direct calls are returned, so it stops short of full sibling differentiation.
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 gives a clear routing instruction: 'For the full flow, use codegraph_explore,' which tells the agent when not to use this tool. However, it does not explain when to choose callees over other codegraph siblings like callers or impact, leaving some usage context implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=true already establishes the operation is safe. The description adds transparency by explicitly revealing the exact command and its flags (--short --branch), so an agent knows precisely what output format to expect. No contradiction with annotations exists.
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?
A single sentence fully captures the tool's behavior with no filler. The most important information, the exact command executed, is front-loaded and sufficient.
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 read-only command with one optional parameter, the description is mostly adequate. However, it omits any mention of cwd semantics and provides no usage context, which leaves minor but real gaps for an agent deciding whether this tool fits the task.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter cwd has no schema description and 0% schema description coverage. The description never mentions cwd or how it affects execution. The name 'cwd' is conventional, but the description does not compensate for the missing semantic detail.
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 states exactly what the tool does: '返回 git status --short --branch' (returns git status --short --branch). This names a specific verb, resource, and flags, making it clearly distinct from sibling tools like git_diff, git_log, and git_show.
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 gives no guidance about when to use this tool versus alternatives. It does not mention that this is appropriate for inspecting working tree state, nor does it exclude cases where git_diff or git_log would be more suitable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description is consistent with a read operation. It adds useful context about workspace text files and the 20-file limit, but does not disclose failure behavior for missing files, non-text files, or oversized files. The added behavioral context is moderate 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short sentence with no filler. It front-loads the core purpose and includes the key constraint, making it efficient and easy to parse. Every word earns its place.
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 batch-read tool with only two parameters and no output schema, the description is minimally viable but incomplete. It does not explain what happens when a file is too large, when a path is invalid, or what the output shape is. These gaps are meaningful because no output schema exists to fill them.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for parameter documentation. It clarifies that multiple paths are supported and that the limit is 20, but it says nothing about the meaning or semantics of max_bytes_per_file. The second parameter is effectively undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb and resource: reading multiple workspace text files in one operation, with an explicit cap of 20 files. This distinguishes it from the single-file sibling read_file and makes the batch nature immediately obvious.
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 it should be used when reading multiple text files at once, but it does not explicitly state when to prefer this over alternatives like read_file, nor does it mention exclusions like binary files or non-workspace paths. Usage guidance is present only by implication.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only. The description adds useful behavioral context beyond annotations: recursion and automatic skipping of common build directories. However, it does not disclose the result format, matching semantics, or treatment of hidden files, so it only partially carries the burden in the absence of an output schema.
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?
A single front-loaded sentence that states the core behavior and the key caveat (build directories are skipped). Every word earns its place; there is no filler.
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 4-parameter read-only tool with no output schema, the description is adequate but not complete: it leaves usage guidance, result shape, and pattern matching semantics to be inferred. The presence of sibling tools like search_text makes the missing comparison more noticeable.
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 description coverage is 0%, so the description must carry parameter meaning. It usefully maps 'path fragment' to pattern and 'extension' to extensions, but it does not explain pattern matching syntax, whether extensions need leading dots, or any semantics for path/limit beyond what the schema defaults already convey.
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 states a specific action ('recursively find files') with clear criteria ('by path fragment and extension') and a distinguishing behavioral detail (skips common build directories). This clearly separates it from content-search tools like search_text and non-recursive listing tools like list_directory.
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 intended use is implied: use this tool when you need to locate files by path segment or extension rather than by file contents. However, the description does not explicitly say when to prefer it over alternatives such as search_text, list_directory, or read_many_files, and it gives no exclusion conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnly, idempotent, and non-destructive behavior, so the description only adds 'Indexed' and the performance comparison. That adds some context beyond the annotations but does not disclose details such as index freshness or behavior when no .codegraph index exists near the supplied projectPath.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the key value proposition and includes a performance/selection cue. Every word earns its place; there is no filler, restatement, or redundancy.
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 read-only file-tree operation, the description plus a fully described schema is adequate. The schema covers projectPath quirks, defaults, and filter semantics, while the description states what is returned. A small gap is the absence of any note about output shape when metadata is disabled, but this is minor.
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 description coverage is 100%, with each parameter including meaningful descriptions, defaults, and examples. The tool description itself adds no parameter-level semantics, so the baseline of 3 applies.
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 identifies the resource as an 'Indexed file tree with language + symbol counts' and distinguishes it from Glob/project-layout tools. It lacks an explicit verb like 'list' or 'get', but the noun phrase and title leave little ambiguity about what the tool returns.
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?
'Faster than Glob for project layout' gives a clear use context and positions the tool as the better choice for layout queries. It does not name specific sibling alternatives or state exclusions, but the guidance is enough for an agent to select this tool for exploring project structure.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint=false annotation already signals mutation, and the description adds meaningful behavior beyond that: recursive creation and workspace scoping. It does not disclose failure behavior or what happens if the directory already exists, but the core side effect is clearly stated.
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 short sentence with no redundant wording. The essential behavior (recursive creation) is front-loaded and every word earns its place.
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, the description covers the main purpose and the recursive behavior. However, there is no output schema, no parameter detail, and no mention of failure semantics or whether the directory must be inside the workspace. It is minimally viable but leaves some practical gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only implies that 'path' refers to a workspace directory, without explaining path format, relative vs absolute, or whether it must be a new path. This is minimal added meaning beyond the schema's type and property name.
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 ('创建' / create) and the resource ('工作区目录' / workspace directory), and adds the key recursive behavior. This distinguishes it from sibling file operations like write_file, delete_path, and move_path.
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 usage context is implied: use this tool when you need to create a workspace directory, including parent directories. However, it does not explicitly state when not to use it, mention alternatives, or address edge cases like existing directories.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as destructive (readOnlyHint=false, destructiveHint=true), and the description adds a valuable safety behavior beyond them: replacement is guarded by occurrence-count matching to avoid accidental edits. It does not describe what happens on mismatch, but the guardrail itself is meaningful behavioral context.
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?
A single sentence contains the operation, the condition, and the rationale with no filler. It is front-loaded with the key safety condition and reads clearly in one pass.
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 moderately simple edit tool with destructive annotations, the description covers the essential behavior and the main safety mechanism. The main omission is the failure or no-op behavior when the occurrence count does not match, but this is partially implied and not critical for basic invocation.
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 description coverage is 0%, so the description must compensate. It clarifies the role of old_text and expected_occurrences by linking them to the exact-count safety condition. However, it adds no explicit meaning for path or new_text, which are left to their self-explanatory parameter names.
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 identifies a replacement operation conditioned on exact occurrence count, and the title specifies file content as the resource. It is not a tautology and conveys the core function, though it does not explicitly differentiate itself from sibling editing tools like write_file or patch.
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 gives a clear precondition: replacement only happens when old_text's occurrence count matches expected_occurrences. This implies the tool should be used when that count is known, but it provides no guidance on when to prefer this tool over siblings such as write_file, patch, or apply_patch.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already establishes that this is a safe read operation. The description adds detail about what information is returned but does not disclose any behavioral nuances such as authentication requirements, failure modes, or performance characteristics. It does not contradict 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, compact sentence that lists exactly what the tool returns. There is no redundant wording, and the most informative content is delivered immediately.
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 information tool, this description covers the essential substance: the four categories of workspace information returned. A minor gap is the lack of response structure detail, but the description is otherwise sufficient for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is empty with zero parameters, so there is nothing for the description to clarify about parameter meaning. The baseline for zero-parameter tools is 4, and the description appropriately focuses on the returned content instead of inventing parameter details.
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 states a specific verb ('返回') and resource ('工作区') and enumerates the exact information returned: root directory, sandbox mode, approval policy, and service status. This makes the tool's purpose unambiguous and clearly distinguishes it 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?
The description gives no guidance on when to use this tool versus alternatives like integration_status, workspace_instructions, or get_plan. It only implies a generic use case without mentioning conditions, exclusions, or preferred alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey the destructive profile (destructiveHint=true, readOnlyHint=false), and the description adds genuinely useful behavior beyond that: all operations are validated before applying, rollback is attempted on failure, and paths are restricted to workspace-relative. This materially helps an agent anticipate failure semantics and safety boundaries.
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 compact sentences with zero filler: the first front-loads purpose and format, the second packs the critical constraints (path scoping, validation, rollback). Every clause earns its place.
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 is simple on the surface (one required string parameter, no output schema, no nested objects), and the description covers the envelope, operations, path scope, and failure behavior. However, it omits the precise patch-entry grammar and what the tool returns on success, both of which an agent would need to invoke it reliably; the complexity of the patch format makes these omissions notable.
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 description coverage is 0%, so the description must carry the semantic burden, and it largely does: it defines the expected patch envelope, the four operation types, and the relative-path constraint. It stops short of specifying the exact per-entry syntax (e.g., how file paths and content blocks are delimited inside the patch), which an agent would still need to construct a valid patch.
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 names a specific verb (apply), a specific resource (Codex-style file patches), and pins the exact format wrappers ('*** Begin Patch / *** End Patch') plus the supported operations (Add, Delete, Update, Move). This clearly distinguishes it from single-operation siblings like write_file, edit_file, delete_path, and move_path.
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 given on when to choose apply_patch over its many file-operation siblings (write_file, edit_file, delete_path, move_path). The description states what the tool does but never says when it should be preferred, e.g., for batched multi-operation changes, nor what conditions would make an alternative more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds meaningful behavioral context beyond the annotations by requiring interactive_feedback approval and forbidding root deletion. It does not discuss irreversibility or non-empty directory handling, but the destructive annotation covers the core safety concern.
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 two short sentences with no filler. The core action and scope are front-loaded, and each sentence carries a meaningful constraint or instruction. It is as concise as possible while conveying the essential safety rules.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with no output schema and 0% schema description coverage, the description omits important invocation details: the semantics of the `recursive` parameter, whether deletion is permanent, and what counts as success or failure. It covers approval and root prohibition, but an agent still lacks enough information to confidently use the recursive option.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for explaining `path` and `recursive`, but it does not. It only implies that path refers to a workspace-relative file or directory. The meaning of `recursive` and the behavior when a directory is non-empty and recursive=false are entirely unexplained.
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 states a specific verb ('删除' / delete) and a precise resource ('工作区内文件或目录' / files or directories in the workspace). It also adds a clear scope restriction by prohibiting deletion of the workspace root. No sibling tool performs deletion, so the purpose is unmistakable.
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 gives explicit operational guidance: always request approval through interactive_feedback, and never delete the workspace root. It does not mention alternatives such as move_path for non-destructive relocation, but the destructive nature and the explicit constraints are clear enough for an agent to know when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond destructiveHint=true/readOnlyHint=false, it discloses that execution is foreground/blocking and that string commands are interpreted by a shell. The high-risk approval path through interactive_feedback adds actionable behavioral context without contradicting 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?
Three terse sentences with no filler. The core purpose is front-loaded, followed by invocation preference and risk handling—each sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description fails to mention what the tool returns (stdout/stderr/exit code) or how failures surface. Several parameters are undocumented, so an agent still needs to infer key behavior for a tool with destructive potential.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it only clarifies the command parameter (array vs string) and shell behavior. cwd, env, stdin, and timeout_ms receive no explanation, leaving significant semantic gaps.
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?
States a specific action and resource: 'execute foreground command in the workspace'. It also distinguishes invocation styles (argv array vs shell string) and names the approval sibling, so an agent can tell what this tool does at a glance.
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?
Gives concrete usage guidance: prefer argv arrays, string commands go through the system shell, and high-risk commands require interactive_feedback approval. It lacks an explicit when-not-to-use clause, but no sibling command-execution tool exists to contrast with.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as destructive (destructiveHint: true), and the description adds a crucial behavioral trait beyond that: overwrite requires user approval in interactive_feedback. This informs the agent about an interactive approval step that annotations alone would not convey. It does not go into details like irreversibility or failure modes, but with the annotation context, this is a strong, non-redundant disclosure.
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 exactly two sentences: the first states the core operation, the second states the overwrite approval condition. Every word contributes value, there is no redundant phrasing, and the primary purpose is front-loaded.
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 description is adequate for a basic move/rename tool: it names the operation, the workspace scope, and the key overwrite approval behavior. However, with no output schema and no mention of the default behavior when overwrite is false, path constraints, or error handling, there are clear gaps for an agent fully invoking the tool in edge cases. The overwrite default value in the schema helps, but the description does not tie it to success/failure semantics.
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 description coverage is 0%, so the description must compensate. It directly clarifies the overwrite parameter's approval requirement and implies the meaning of from and to through 'move or rename'. However, it does not fully document path format expectations or what happens when overwrite is false and the target exists, so it only partially compensates for the missing schema descriptions.
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 states a specific action ('move or rename') and a clear resource type ('files/directories in the workspace'), which distinguishes it from sibling tools like delete_path, write_file, and edit_file. The title reiterates the same intent, but the description adds the workspace scope and file/directory target, making the purpose unambiguous.
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 tells what the tool does and adds one conditional: overwriting requires user approval via interactive_feedback. However, it gives no explicit guidance on when to choose this tool over alternatives like delete_path + write_file or create_directory, and it does not state prerequisites such as source existence or destination parent directory requirements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false) and idempotentHint=true. The description adds meaningful behavioral context by specifying the required plan state invariant: exactly one in_progress unless all steps are completed. This goes beyond the annotations and helps the agent construct valid updates.
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 tool's purpose and follows with the critical invariant. There is no redundant or filler content; every clause contributes meaningful information.
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 two-parameter tool with a clear schema, the description plus annotations cover the essential behavior well. The main gap is the lack of explicit usage guidance and explanation of the optional 'explanation' parameter, but the plan invariant and schema structure make the tool usable without much missing context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it never explains the 'steps' or 'explanation' parameters directly. It does add value by clarifying the valid status distribution (one in_progress, all completed), which gives meaning to the status enum, but this is only partial coverage of the parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('维护' / maintain) on a specific resource ('Codex 风格任务计划'), and the invariant distinguishes it from read-only siblings like get_plan. It also conveys the exact state model the tool enforces, leaving no ambiguity about its role.
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 purpose implies this tool is for updating the task plan, and the invariant gives internal rules, but there is no explicit guidance about when to use this tool versus alternatives like get_plan. The context is clear a basic level, but no direct exclusions or sibling comparisons are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (read-only, idempotent, non-destructive, closed-world), so the description only adds the 'full flow' routing hint. It does not disclose whether callers are direct/one-level vs transitive, what the return list shape is, or any index prerequisites. No contradiction with annotations, but minimal extra behavioral context.
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 short sentences deliver the core purpose and point to the appropriate sibling tool. There is no filler or repetition; the description is front-loaded with the actionable verb-resource statement.
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?
With 100% schema coverage and strong annotations, the definition is largely complete for a simple read-only listing tool. The main gaps are the lack of explicit 'direct callers only' clarification and any return shape detail, but the description plus schema gives an agent enough to invoke it correctly in most situations.
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 description coverage is 100%, so all four parameters are already documented with meaningful details (file disambiguation, limit, symbol, projectPath semantics). The tool description itself adds no parameter-specific guidance, so it earns the baseline 3 rather than higher.
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 states a specific verb ('List') and resource ('functions that call <symbol>'), making the tool's purpose immediately clear. It also distinguishes itself from the sibling by pointing to codegraph_explore for the broader flow, and the name 'codegraph_callers' aligns cleanly with this purpose.
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 gives a clear routing hint: 'For the full flow, use codegraph_explore.' This tells an agent when a broader alternative is appropriate. It does not explicitly mention codegraph_callees for downstream callers or state exclusions, but the caller-vs-full-flow distinction provides useful, non-misleading context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the semantic context that this is an analysis of hypothetical changes rather than a mutation, which aligns with the annotations. It does not contradict them, but it also does not disclose much behavioral detail beyond what the annotations and schema already convey.
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 with no filler. The core action and resource are front-loaded, and the usage guidance is immediate. Every word earns its place, making this a model of concise tool documentation.
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 read-only analysis tool with rich annotations and full schema coverage, the description is mostly sufficient: it states what it lists, what triggers its use, and its temporal context. The remaining gap is not explicitly distinguishing it from directly related sibling tools like codegraph_callers or codegraph_explore, though 'affected by changing' largely does this implicitly.
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 description coverage is 100%, so the input schema already documents all four parameters thoroughly. The description only mentions <symbol> and does not add parameter-level meaning beyond the schema. A baseline of 3 is appropriate since the schema carries the parameter-documentation burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'List symbols affected by changing <symbol>.' This clearly identifies the tool as impact analysis, distinguishing it from sibling tools like codegraph_callers or codegraph_callees that answer different relationship questions. The phrase 'before a refactor' further anchors its purpose.
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 gives a clear usage context: 'Use before a refactor.' It tells the agent when this tool is appropriate, though it does not explicitly name alternatives or state when not to use it. This is clear context without exclusions, so a 4 is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already disclose read-only, idempotent, and non-destructive behavior. The description adds value by clarifying the tool reports on index health metrics (files, nodes, edges) and frames it as a debugging aid, going slightly beyond annotation data without contradicting it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two short phrases, with the core purpose front-loaded and no redundant content. Every word contributes to the agent's understanding.
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 debug-only status tool, the description is mostly complete given the rich schema and safety annotations. The only minor gap is that without an output schema, the exact return shape of the health check is not spelled out, though 'files / nodes / edges' gives a strong hint.
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 tool description itself says nothing about the projectPath parameter, but the input schema provides a detailed, 100%-coverage description including path resolution behavior and default-project semantics. With the schema carrying the full explanatory burden, a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is an 'Index health check' and specifies the relevant dimensions: files, nodes, edges. This is more specific than simply restating the tool name and helps distinguish it from codegraph_project_status, though it does not explicitly name that sibling.
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?
'Skip unless debugging' is explicit usage guidance that tells the agent this tool is for diagnostic use only. It does not name alternatives or state when to prefer them, but it provides clear context for when this tool should not be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the disclosure burden, and it covers the important behaviors: it blocks for user feedback, the timeout is fixed at 172800 seconds, and it must be invoked at the end of every answer. It could additionally state the precise consequence of a timeout or what feedback is returned, but the core blocking/communication behavior is transparent.
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 short and front-loads the core purpose. There is some redundancy between '唯一沟通渠道' and '这是你与用户之间的唯一沟通渠道', but the additional '每次回答结束前都要调用' clause adds an important mandatory-frequency fact, so overall it is 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 tool with no annotations and no output schema, the description gives the operational context an agent needs: when to call it, what it does, and its fixed timeout. Optional parameter semantics are already in the schema; return-value behavior is implied by '等待反馈' and is not a critical gap for invocation.
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 80%, so the schema already documents most parameters. The description adds no meaning beyond noting the fixed timeout, which the schema also encodes via const/default. This meets the baseline but does not elevate it.
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 names the action ('展示工作摘要并等待反馈') on the resource (user feedback), and marks it as the only communication channel before a final answer. Among the sibling tools—file, git, exec, codegraph, plan—none shares this interactive user-feedback role, so it is unambiguously distinguishable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly instructs the agent to call the tool before every final answer and states that it is the only channel for communicating with the user. This is a strong, unconditional usage signal that leaves no ambiguity about when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already signals a safe read operation, and the description adds useful context: the plan is the 'current' one held 'in memory', indicating a volatile, point-in-time snapshot rather than a persisted artifact. This adds value beyond the annotation without contradicting it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence that states exactly what the tool does with no filler. The key qualifiers 'current' and 'in-memory' are front-loaded, making the definition highly scannable.
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, parameterless, read-only tool, the description is nearly complete: it names the resource, its source, and its temporal scope. It does not describe the return shape or behavior when no execution plan exists, but the low complexity and readOnlyHint annotation make this a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema is empty, so there is no parameter ambiguity to resolve. The baseline for a zero-parameter tool is 4, and the description correctly avoids inventing parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('返回'/returns) and a clear resource ('当前内存中的执行计划'/current in-memory execution plan), making the tool's purpose immediately apparent. It is clearly distinct from sibling tools like update_plan, which modify the plan rather than read it.
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 provides clear context by specifying that this tool retrieves the current in-memory execution plan, implying it should be used for read-only inspection. It does not explicitly mention alternatives or exclusions, but the read/write distinction from sibling tools is evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true, and the description adds behavior beyond that: it describes the layer-by-layer loading from workspace root to target directory and lists both file names searched. There is no contradiction with the read-only 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 two short sentences with no filler. The main action and method are front-loaded, and the usage timing is appended in a clear second sentence.
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-only tool with one optional parameter and no output schema, the description covers what it does, how it traverses directories, which files it loads, and when to call it. Return-value details are not essential given the tool's obvious purpose, though behavior when no AGENTS.md exists is not described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one optional cwd parameter with 0% description coverage. The description compensates by referring to '目标目录' (target directory), which maps to the cwd parameter's intended role. It does not explicitly name the parameter or specify path format, but the meaning is inferable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('加载'/load) and identifies the exact resource ('AGENTS.override.md 或 AGENTS.md') plus the traversal behavior (from root to target directory layer by layer). It clearly distinguishes this tool from generic file readers like read_file by focusing on project instruction files.
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 explicitly states when to call the tool: '修改代码前应先调用' (should be called before modifying code). It provides a clear trigger condition but does not mention alternatives or when-not-to-use scenarios, so it falls short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true. The description adds useful behavioral context beyond that: atomic replacement semantics, default overwrite of existing files, and the fact that it performs full writes rather than targeted edits.
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 short sentences carry the essential information: operation type, atomics, overwrite default, and routing to alternatives. There is no wasted text and the most important behavioral detail is front-loaded.
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 destructive write tool with four simple parameters, the description is mostly complete: it states what it writes, how it writes atomically, the overwrite default, and when to prefer alternatives. Slight gap: no explicit guidance on create_only or what happens when the file already exists under that mode, though the schema default hints at it.
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 description coverage is 0%, so the description must compensate. It does clarify the overwrite default, but it does not explain the create_only parameter or explicitly map path/content semantics. The parameter names and defaults are reasonably self-explanatory, but the description does not fully cover all four 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 states a specific verb ('create or completely write') and resource ('text file') and clarifies the atomic replacement behavior. It also explicitly distinguishes itself from siblings by naming edit_file and apply_patch as alternatives for precise modifications.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: use this tool for full-file creation/writing, while precise edits should use edit_file or apply_patch. This provides both when-to-use and when-not-to-use guidance with named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish this as read-only, idempotent, and non-destructive. The description adds important behavioral context beyond those hints: results contain only locations, not code, and the operation is quick. This is meaningful disclosure of what the agent can expect from the response.
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 compact sentences with zero filler. The core behavior is front-loaded ('Quick symbol search by name'), followed immediately by the output type and the routing to the sibling tool. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich schema, the safety-carrying annotations, and the explicit statement of what results contain, the description covers everything an agent needs to invoke the tool correctly. It tells what the tool does, what it returns, and when to use a different tool, with no output schema needed.
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 description coverage is 100%, so the input schema already documents all four parameters with examples and the enum. The description does not need to add parameter-level detail, and the baseline of 3 applies because it adds no extra semantics 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?
States a specific action ('quick symbol search by name') and resource (codegraph index), and explicitly contrasts itself with codegraph_explore by noting this tool returns locations only, not code. This clearly distinguishes it from the most similar sibling without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description directly tells the agent when to choose an alternative: if the goal is to get actual source code or understand an area, use codegraph_explore instead. This explicit when-not/alternative guidance is exactly what an agent needs to route correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (read-only, idempotent, non-destructive), the description discloses that the call is capped, returns verbatim source grouped by file, includes a call path, and is semantically equivalent to Read so files should not be re-read. This significantly shapes how an agent should consume the result.
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 front-loaded with the most important usage directive, followed by concrete output details and query flexibility. Every sentence earns its place, and there is minimal redundancy despite the amount of guidance packed in.
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?
Despite having no output schema, the description clearly explains what will be returned, how to query it, and what follow-up action is unnecessary. The schema fills in parameter defaults and project-path nuances, so the combined definition gives an agent everything needed to invoke the tool correctly.
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 covers all parameters with rich descriptions and examples, so the baseline of 3 applies. The tool-level description mostly restates the query flexibility and capped-call behavior rather than adding new parameter-specific semantics beyond the schema.
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 immediately states that this is the primary codegraph exploration tool and specifies exactly what it returns: verbatim source of relevant symbols grouped by file, plus the call path among them. It is clearly distinguishable from siblings like codegraph_search or read_file because it brands itself as a Read-equivalent source-returning entry point.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a strong, actionable rule: 'call FIRST for almost any question OR before an edit', and explains that it is usually the only call needed compared to a search/Read/Grep loop. It also tells the agent not to re-open files whose source has already been returned, which is a clear behavioral instruction for follow-up actions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds rich behavioral detail beyond the readOnly/idempotent annotations: same bytes as Read but faster, capped at 2000 lines, blast radius/dependents note, ambiguous names return every matching definition, and mode-specific defaults (includeCode ignored in file mode, symbolsOnly). 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-organized around 'Two modes.' Every sentence provides distinct information—mode semantics, defaults, limits, alternatives. It is front-loaded and scannable despite the density. Slightly verbose but every part earns its place.
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?
With 8 parameters and no output schema, the description covers return shapes for both modes (source with line numbers, symbol location/signature/source/caller/callee trail), ambiguous name handling, file limits, defaults, and alternative tools. Nothing critical for invoking correctly is missing.
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?
Though schema coverage is 100%, the description adds cross-parameter mode logic that the schema describes only per-parameter: how 'file alone' vs 'file+symbol' selects modes, how offset/limit mirror Read, and which flags are ignored in which mode. This meaningfully supplements the schema.
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 has two distinct modes with specific verbs: 'READ A FILE' and 'ONE SYMBOL you can name'. It identifies the resource (file or symbol) and explicitly differentiates from the Read tool and codegraph_explore, so an agent understands exactly what this tool does versus siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit usage directives: 'use INTEAD of the Read tool', 'Use it whenever you would Read a source file', and 'Use codegraph_explore for several related symbols or the full flow.' This provides clear when-to-use and when-not-to-use guidance with alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

codex-workspace-codegraph-mcp MCP server

Copy to your README.md:

[![codex-workspace-codegraph-mcp MCP server](https://glama.ai/mcp/servers/lllli223/codex-workspace-codegraph-mcp/badges/card.svg)](https://glama.ai/mcp/servers/lllli223/codex-workspace-codegraph-mcp)

Score Badge

Copy to your README.md:

[![codex-workspace-codegraph-mcp MCP server](https://glama.ai/mcp/servers/lllli223/codex-workspace-codegraph-mcp/badges/score.svg)](https://glama.ai/mcp/servers/lllli223/codex-workspace-codegraph-mcp)

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/lllli223/codex-workspace-codegraph-mcp'

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