Integrates with Git repositories to provide project-aware memory management, tracking coding decisions and changes within version-controlled codebases.
Provides comprehensive metadata management and safety controls for JavaScript projects, including method-level permissions and automated changelog generation.
Referenced in decision-making examples for database technology choices, with the server capable of tracking and remembering architectural decisions including PostgreSQL adoption reasoning.
Built with TypeScript support and provides metadata management capabilities for TypeScript projects through AI-metadata headers and file tracking.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP Memory Server generate folder maps for my project so I can see what's available"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A comprehensive MCP (Model Context Protocol) server that provides AI coding assistants with memory management, file approval tracking, changelog functionality, and automatic folder mapping.
Automatically generates _map.md files for each folder in your project, providing quick overviews of:
Classes, interfaces, functions, and types
Method signatures and parameters
File purposes and relationships
Dependencies and test locations
Risk assessments
This solves the problem of code discoverability - helping both AI agents and developers quickly understand what's available without diving into every file.
Related MCP server: ContextStream MCP Server
npm installnode test-memory.jsnpm run buildnpm startstart_session(task) - Start a new coding session
add_session_step(step, filesModified, description?) - Record completed work
add_decision(key, value, reasoning) - Record important decisions
get_project_memory() - Get current project state
set_file_approval(filePath, approvalType, approvedBy) - Set approval status
get_file_approval_status(filePath) - Check approval status
check_before_modification(filePath) - Validate before changes
get_modification_actions(filePath) - Get post-change actions
generate_folder_map(folderPath) - Generate _map.md for specific folder
generate_all_folder_maps() - Generate maps for all project folders
update_folder_map_if_needed(filePath) - Update map if files changed
find_all_map_files() - List all existing map files
validate_all_maps() - Check if maps are up-to-date
parse_file_metadata(filePath) - Extract AI metadata from files
update_file_metadata(filePath, updates) - Update file metadata
add_changelog_entry(...) - Add changelog entry
get_recent_changes(days?) - Get recent project changes
When you run generate_folder_map("src/services"), it creates src/services/_map.md:
# ⚙️ services Module Map
> **Purpose**: Business logic and external service integrations
## 📊 Quick Stats
- **Files**: 4
- **Classes**: 3
- **Interfaces**: 2
- **Functions**: 8
## 🗂️ Files Overview
### `user-service.ts`
**Purpose**: User management and authentication | **Risk**: medium
**CLASS**: `UserService`
- `authenticateUser(credentials)` - Validates user credentials
- `getUserProfile(userId)` - Retrieves user profile data
- `updateUserSettings(userId, settings)` - Updates user preferences
### `api-client.ts`
**Purpose**: HTTP client for external APIs | **Risk**: high
**CLASS**: `ApiClient`
- `get(url, options?)` - HTTP GET request
- `post(url, data, options?)` - HTTP POST request
- `handleError(error)` - Centralized error handling
## 🔗 Dependencies
- `../types/user-types.ts`
- `../utils/http-utils.ts`
## 🧪 Tests
- `tests/services/user-service.test.ts`
- `tests/services/api-client.test.ts`Navigate to your test project:
cd D:\Development\Projects\Products\zendesk-clickup-automationCopy the MCP server files or install as dependency
Generate folder maps:
# Using MCP client, call:
generate_all_folder_maps()Your folder structure will get maps:
src/
├── agents/
│ └── _map.md ← Overview of all agent classes
├── services/
│ └── _map.md ← Service integrations overview
├── types/
│ └── _map.md ← All TypeScript definitions
└── utils/
└── _map.md ← Utility functions overviewThe memory recording issues have been fixed by:
Ensuring directory creation before all file operations
Better error handling with detailed logging
Automatic retry logic for file system operations
Proper async/await patterns throughout
AI has to read every file to understand what's available
Often creates duplicate functionality
Slow to understand project structure
Poor code reuse suggestions
Instant project comprehension from _map.md files
Prevents duplicate code - AI sees what already exists
Better suggestions - AI knows available methods and classes
Faster development - Quick navigation and understanding
# 1. Start a session
start_session("Add user authentication feature")
# 2. Generate/update maps to understand codebase
generate_all_folder_maps()
# 3. AI reads maps to understand existing code
# 4. AI writes new code using existing patterns
# 5. Record progress
add_session_step("Created UserAuth class", ["src/auth/user-auth.ts"], "Implemented JWT-based authentication")
# 6. Update relevant maps
update_folder_map_if_needed("src/auth/user-auth.ts")Always read relevant _map.md files before suggesting new code
Use update_folder_map_if_needed() after creating/modifying files
Check existing functionality to avoid duplication
Review generated maps for accuracy
Update maps when adding major new features
Use maps for onboarding new team members
Maps can be kept current by:
File watchers - Update when source files change
Build integration - Generate maps during build process
Git hooks - Update maps on commits
CI/CD integration - Validate maps in pipelines
# Run the test script
node test-memory.js
# Check for errors in .ai-memory folder creation
# Ensure proper permissions on project directory# Check TypeScript parsing dependencies
npm install @typescript-eslint/typescript-estree
# Verify src directory exists
# Check file permissions# Rebuild the project
npm run build
# Check MCP client configuration
# Verify server is running on correct portTest the system with your Zendesk-ClickUp project
Generate initial maps to see the folder mapping in action
Integrate with your AI workflow using the MCP tools
Customize map templates if needed for your specific patterns
The folder mapping feature transforms how AI agents understand and work with your codebase, making them far more effective at code reuse and avoiding duplication.
Add an entry to the project changelog
| Name | Required | Description | Default |
|---|---|---|---|
| description | Yes | Description of the change | |
| filesChanged | Yes | Files that were changed | |
| type | Yes | ||
| breakingChange | No | Whether this is a breaking change | |
| impact | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states this is an 'Add' operation, implying mutation, but doesn't disclose behavioral traits like whether it requires specific permissions, if entries are permanent or reversible, or any rate limits. The description is minimal and lacks critical context for a write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste. It's front-loaded and appropriately sized for the tool's complexity, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (a write operation with 5 parameters, 3 required), no annotations, and no output schema, the description is incomplete. It doesn't explain what happens after adding an entry, such as return values or success indicators, leaving significant gaps for an AI agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no parameter semantics beyond what the input schema provides. With 60% schema description coverage (3 of 5 parameters have descriptions), the baseline is 3. The description doesn't compensate for the undocumented parameters or provide additional context like format examples or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add an entry') and the resource ('project changelog'), which is specific and unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'get_file_changelog' or 'get_recent_changes', which are read operations versus this write operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, such as needing an active project or session, or when to choose this over similar tools like 'update_file_metadata' for logging changes. Usage is implied but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record an important technical decision
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Decision key/name | |
| value | Yes | Decision value | |
| reasoning | Yes | Reasoning behind the decision |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. 'Record' implies a write operation, but it doesn't specify whether this creates a new decision, updates an existing one, requires authentication, has side effects (e.g., notifications), or what the response looks like. It lacks details on persistence, error handling, or any behavioral traits beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste. It's appropriately sized and front-loaded, directly stating the tool's purpose without unnecessary elaboration, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a write operation with no annotations and no output schema, the description is incomplete. It doesn't explain what 'recording' entails (e.g., storage location, format), potential outcomes, or error conditions. For a tool that likely modifies state, more context is needed to guide safe and effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema fully documents the parameters (key, value, reasoning). The description adds no additional meaning beyond what the schema provides, such as examples or constraints on parameter values. Baseline 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Record an important technical decision' states a clear verb ('Record') and resource ('technical decision'), but it's somewhat vague about what constitutes 'recording' versus other actions like logging or documenting. It doesn't distinguish from siblings like 'add_changelog_entry' or 'add_session_step', which might involve similar recording actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, context (e.g., during project planning or code reviews), or exclusions, leaving the agent to infer usage from the tool name alone among many siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record completion of a step in the current session
| Name | Required | Description | Default |
|---|---|---|---|
| step | Yes | Description of the completed step | |
| filesModified | Yes | List of files that were modified | |
| description | No | Optional detailed description |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states it 'records' completion without disclosing behavioral traits like whether this is a write operation, if it's idempotent, what happens if no session exists, or how it interacts with session state. This is inadequate for a mutation tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero wasted words, clearly front-loading the core purpose. Every word earns its place, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is incomplete. It lacks critical context like what 'recording' entails (e.g., creates a log entry, updates session state), expected outcomes, or error conditions, leaving significant gaps for agent understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all three parameters. The description adds no additional parameter semantics beyond what's in the schema (e.g., no examples or constraints), meeting the baseline for high coverage but not providing extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Record completion') and resource ('a step in the current session'), making the purpose understandable. However, it doesn't explicitly differentiate from siblings like 'add_changelog_entry' or 'add_decision' which might also record progress-related information, preventing a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides minimal guidance by implying usage during a session ('current session'), but offers no explicit when-to-use rules, prerequisites (e.g., requires an active session), or alternatives (e.g., vs. 'add_changelog_entry'). This leaves the agent with insufficient context for optimal tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check if a file can be modified according to AI metadata rules
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | Path to the file to check |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool checks modification permissions based on 'AI metadata rules,' but doesn't explain what these rules entail, whether the check is read-only, if it requires specific permissions, or what the output might be (e.g., a boolean, detailed status). This leaves significant gaps in understanding the tool's behavior and implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It is front-loaded with the core action ('Check') and resource ('file'), making it easy to parse. Every part of the sentence contributes to understanding, earning its place with no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of checking modification permissions based on 'AI metadata rules,' the description is incomplete. With no annotations and no output schema, it fails to explain behavioral aspects like what the check entails, potential outcomes, or error conditions. The description alone is insufficient for an agent to fully understand how to use this tool effectively in context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with 'filePath' clearly documented as 'Path to the file to check.' The description adds no additional parameter semantics beyond this, as it doesn't elaborate on format constraints or examples. Given the high schema coverage, a baseline score of 3 is appropriate, as the description doesn't compensate but also doesn't detract from the schema's information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Check if a file can be modified according to AI metadata rules.' It specifies the verb ('check') and resource ('file'), and while it doesn't explicitly differentiate from all siblings, it implies a distinct function related to modification permissions based on metadata rules, which is more specific than generic file operations like 'get_file_approval_status' or 'update_file_metadata'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. It mentions 'AI metadata rules' but doesn't clarify prerequisites, context, or exclusions. For example, it doesn't specify if this should be used before attempting modifications or how it differs from sibling tools like 'get_file_approval_status', leaving the agent to infer usage scenarios without clear direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find all files that contain AI metadata
| Name | Required | Description | Default |
|---|---|---|---|
| pattern | No | File pattern to search (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool finds files with AI metadata but doesn't describe what 'AI metadata' entails, how results are returned (e.g., list format, pagination), or any constraints like rate limits or permissions required. For a search tool with zero annotation coverage, this is a significant gap, warranting a score of 2.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence: 'Find all files that contain AI metadata.' It is front-loaded with the core purpose, has no unnecessary words, and every part earns its place by specifying the action and target. This is appropriately sized for a simple tool, scoring a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (a search operation with no annotations and no output schema), the description is incomplete. It doesn't explain what 'AI metadata' means, how results are structured, or any behavioral aspects like search scope or limitations. Without annotations or output schema to fill these gaps, the description should provide more context, but it falls short, resulting in a score of 2.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with one optional parameter 'pattern' documented as 'File pattern to search (optional).' The description doesn't add any meaning beyond this, such as examples of patterns or how they interact with AI metadata. Given the high schema coverage, the baseline is 3, as the schema handles parameter documentation adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Find all files that contain AI metadata.' It specifies the verb ('Find') and resource ('files'), and distinguishes it from siblings like 'parse_file_metadata' or 'get_file_changelog' by focusing on searching rather than parsing or retrieving logs. However, it doesn't explicitly differentiate from 'get_recent_changes' or other search-related tools, keeping it at a 4 instead 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, such as whether files need to be indexed or accessible, or compare it to siblings like 'get_recent_changes' for time-based searches. Without any usage context or exclusions, it scores a 2.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate _map.md files for all folders in the project
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While 'Generate' implies a write operation, it doesn't specify whether this is destructive (overwrites existing files), requires specific permissions, has side effects, or provides any output format. The description lacks crucial behavioral context for a tool that presumably creates or modifies files.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that states exactly what the tool does with no wasted words. It's front-loaded with the core action and target, making it immediately comprehensible while remaining appropriately brief for a parameterless tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool that presumably creates or modifies files across an entire project, the description is insufficient given the absence of annotations and output schema. It doesn't explain what the generated files contain, how they're structured, where they're placed, or what happens if files already exist. The description leaves too many behavioral questions unanswered for effective agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters with 100% schema description coverage, so the schema already fully documents the parameter situation. The description appropriately doesn't mention parameters since none exist, earning a baseline score of 4 for not introducing confusion or redundancy.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Generate') and target resource ('_map.md files for all folders in the project'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from the sibling tool 'generate_folder_map', which appears to be a single-folder version, leaving some ambiguity about when to choose one over the other.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'generate_folder_map' (which likely handles individual folders). There's no mention of prerequisites, timing considerations, or typical use cases, leaving the agent to infer usage context 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.
Generate or update a _map.md file for a specific folder
| Name | Required | Description | Default |
|---|---|---|---|
| folderPath | Yes | Path to the folder to generate map for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions 'Generate or update' but does not clarify what 'update' entails (e.g., overwriting, merging), potential side effects, permissions required, or error handling. This leaves significant gaps in understanding the tool's behavior beyond the basic action stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It is front-loaded and clear, making it easy to grasp quickly, which aligns well with best practices for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is incomplete for a tool that performs file generation or updates. It does not explain what the '_map.md' file contains, how it is structured, or what the tool returns upon success or failure. This leaves the agent with insufficient context to use the tool effectively in complex scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage, with 'folderPath' fully described in the schema. The description does not add any additional meaning or context about the parameter beyond what the schema provides, such as format examples or constraints. With high schema coverage, a baseline score of 3 is appropriate as the description does not compensate but also does not detract.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Generate or update') and the resource ('a _map.md file for a specific folder'), making the purpose understandable. However, it does not explicitly differentiate this tool from its sibling 'generate_all_folder_maps', which might handle multiple folders, leaving some ambiguity in sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'generate_all_folder_maps' or other file-related tools. It lacks context on prerequisites, such as whether the folder must exist or have specific content, and does not mention any exclusions or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get approval status for a file
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | Path to the file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states what the tool does without detailing traits like whether it's read-only, requires authentication, has rate limits, or what the output format might be. This is inadequate for a tool with no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words. It is front-loaded and directly states the tool's purpose, making it highly concise and well-structured for quick understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is incomplete. It does not explain what the approval status entails, potential return values, or error conditions. For a tool with no structured support, more context is needed to be fully helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the parameter 'filePath' fully documented in the schema. The description does not add any meaning beyond the schema, such as examples or constraints on the file path. Baseline 3 is appropriate since the schema handles parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'approval status for a file', making the purpose specific and understandable. However, it does not distinguish this tool from sibling tools like 'get_file_changelog' or 'get_file_last_editor', which also retrieve file-related information, so it lacks explicit differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, context, or exclusions, such as whether it applies to specific file types or requires certain permissions. This leaves the agent without usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get changelog entries for a specific file
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | Path to the file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While 'Get' implies a read operation, it doesn't specify whether this requires authentication, what format the changelog entries return in, whether there are rate limits, or if there are any side effects. The description is minimal and leaves critical behavioral questions unanswered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that gets straight to the point with zero wasted words. It's appropriately sized for a simple retrieval tool and front-loads the essential information without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, the description is insufficiently complete. It doesn't explain what 'changelog entries' consist of, their format, whether this includes all history or recent changes only, or how the information might differ from what sibling tools provide. The minimal description leaves too many contextual gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the single parameter 'filePath' clearly documented in the schema. The description doesn't add any additional parameter semantics beyond what the schema already provides, such as path format requirements or examples. The baseline of 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get changelog entries') and target resource ('for a specific file'), making the purpose immediately understandable. However, it doesn't distinguish this tool from potential sibling tools like 'get_recent_changes' or 'parse_file_metadata', which might have overlapping functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With sibling tools like 'get_recent_changes' and 'parse_file_metadata' that might retrieve similar information, there's no indication of when this specific changelog retrieval is appropriate versus other change-tracking methods.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the last editor of a file from Git history
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | Path to the file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states it retrieves information from Git history but doesn't specify what happens if the file doesn't exist, if Git history is unavailable, what format the output takes, or whether this operation has side effects. The description is minimal and leaves critical behavioral aspects undefined.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's appropriately sized for a simple retrieval tool and front-loads the core functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, the description is insufficient. It doesn't explain what 'last editor' means (most recent commit author? last person to modify?), what the return format is, or potential error conditions. Given the complexity of Git operations and the lack of structured metadata, more context is needed for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% description coverage for its single parameter 'filePath', which is documented as 'Path to the file'. The description doesn't add any additional parameter context beyond what's in the schema, such as path format requirements or examples. With high schema coverage, the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get') and resource ('last editor of a file'), specifying it retrieves this information 'from Git history'. However, it doesn't differentiate from sibling tools like 'get_file_changelog' or 'update_last_editor', which might have overlapping functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'get_file_changelog' (which might provide more comprehensive history) or 'update_last_editor' (which modifies rather than retrieves). There's no mention of prerequisites, error conditions, or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get actions that should be taken after modifying a file
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | Path to the file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool 'Get actions that should be taken', which implies a read-only operation, but doesn't clarify what types of actions are returned (e.g., cleanup steps, notifications), whether it requires specific permissions, or how it handles errors. This leaves key behavioral traits unspecified for a tool that likely interacts with file systems.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that directly states the tool's purpose without unnecessary words. It's front-loaded and efficiently conveys the core functionality, making it easy to understand at a glance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is incomplete for a tool that likely returns actionable steps. It doesn't explain what 'actions' entail (e.g., list of tasks, warnings), how results are structured, or any side effects. For a tool with potential complexity in post-modification workflows, this leaves too much unspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with 'filePath' documented as 'Path to the file'. The description doesn't add any semantic details beyond this, such as format examples or constraints. Since the schema already provides adequate parameter documentation, the baseline score of 3 is appropriate, as the description doesn't compensate but also doesn't detract.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Get') and resource ('actions'), and specifies the context ('after modifying a file'). However, it doesn't explicitly differentiate from siblings like 'check_before_modification' or 'get_recent_changes', which might have overlapping contexts, so it falls short of a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides minimal guidance by implying usage 'after modifying a file', but it doesn't specify when to use this tool versus alternatives (e.g., 'check_before_modification' for pre-modification checks or 'get_recent_changes' for broader change tracking). No exclusions or prerequisites are mentioned, leaving significant gaps in usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get current project memory and session state
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states what the tool does but lacks details on traits like whether it's read-only, requires permissions, returns structured data, or has side effects. This is inadequate for a tool with no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words. It is front-loaded and directly states the tool's purpose, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description is incomplete. It doesn't explain what 'project memory' or 'session state' entail, the return format, or any behavioral context, leaving significant gaps for an AI agent to understand and use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description doesn't add parameter details, which is appropriate, but it could slightly clarify the scope (e.g., what 'current' means), keeping it from a perfect score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resources 'current project memory and session state', making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'get_recent_changes' or 'get_file_changelog', which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With many sibling tools that might retrieve related information (e.g., 'get_recent_changes', 'get_file_changelog'), there is no indication of context, prerequisites, or exclusions for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get recent changelog entries
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Number of days to look back (default: 7) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but offers minimal behavioral insight. It doesn't disclose whether this is a read-only operation, how results are returned (e.g., pagination, format), rate limits, or authentication needs. 'Get' implies a read, but lacks confirmation of safety or other traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste. It's front-loaded with the core purpose and appropriately sized for a simple tool, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description is incomplete for a tool that likely returns data. It doesn't explain what 'changelog entries' contain, how they're structured, or any limitations. For a data retrieval tool, more context on output behavior is needed beyond the minimal input parameter info.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the 'days' parameter fully documented in the schema. The description adds no additional parameter semantics beyond implying 'recent' relates to time, which aligns with the schema's 'days' parameter. Baseline 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get recent changelog entries' clearly states the action (get) and resource (changelog entries), but it's vague about scope and doesn't distinguish from sibling tools like 'get_file_changelog' or 'add_changelog_entry'. It specifies 'recent' but doesn't clarify what that means compared to other changelog tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'get_file_changelog' or 'add_changelog_entry'. The description implies it's for recent entries, but doesn't specify use cases, prerequisites, or exclusions, leaving the agent to guess based on tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Parse AI metadata from a file
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | Path to the file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool parses metadata, implying a read-only operation, but doesn't clarify aspects like whether it requires specific file permissions, what happens if the file doesn't exist or lacks metadata, or if there are rate limits. For a tool with no annotation coverage, this leaves significant gaps in understanding its behavior and constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence: 'Parse AI metadata from a file'. It's front-loaded with the core action and target, with zero wasted words. This makes it easy to scan and understand quickly, earning a high score for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (parsing metadata from files), lack of annotations, and no output schema, the description is incomplete. It doesn't explain what 'AI metadata' includes, the return format, error handling, or how it differs from sibling tools. For a tool that likely involves file I/O and data extraction, more context is needed to guide effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 1 parameter with 100% description coverage ('filePath' is documented as 'Path to the file'), so the schema does the heavy lifting. The description adds no additional meaning about parameters, such as file format expectations or metadata parsing details. With high schema coverage, the baseline is 3, as the description doesn't compensate but also doesn't detract.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Parse AI metadata from a file' clearly states the action (parse) and target (AI metadata from a file), which is better than a tautology. However, it's somewhat vague about what 'AI metadata' entails and doesn't differentiate from siblings like 'find_files_with_metadata' or 'update_file_metadata', leaving ambiguity about its specific scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With siblings like 'find_files_with_metadata' (which likely searches for files based on metadata) and 'update_file_metadata' (which modifies metadata), there's no indication of this tool's role—e.g., whether it's for reading metadata, when it's preferred over other tools, or any prerequisites. This lack of context makes it hard for an agent to choose appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set approval status for a file
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | Path to the file | |
| approvalType | Yes | ||
| approvedBy | Yes | Who approved it |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the tool sets approval status, implying a write/mutation operation, but doesn't disclose behavioral traits such as permissions required, whether changes are reversible, side effects, or error handling. This is inadequate for a mutation tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste. It's appropriately sized and front-loaded, directly stating the tool's purpose without unnecessary elaboration. Every word earns its place, making it highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (a mutation operation with 3 required parameters), lack of annotations, and no output schema, the description is incomplete. It doesn't cover return values, error conditions, or behavioral context, leaving significant gaps for an AI agent to understand how to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% (2 out of 3 parameters have descriptions). The description adds no parameter semantics beyond what the schema provides—it doesn't explain the meaning of 'approvalType' enum values or provide examples. With moderate schema coverage, the baseline is 3 as the description doesn't compensate for gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Set approval status for a file' clearly states the action (set) and resource (file approval status), but it's vague about what 'approval status' entails and doesn't distinguish from sibling tools like 'get_file_approval_status'. It's not tautological but lacks specificity about the approval mechanism or context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It doesn't mention prerequisites, when-not scenarios, or how it relates to sibling tools like 'get_file_approval_status' or 'update_file_metadata'. The description implies usage for setting approvals but offers no contextual boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a new AI coding session with a specific task
| Name | Required | Description | Default |
|---|---|---|---|
| task | Yes | Description of the task to work on |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool starts a session but doesn't explain what that entails—e.g., whether it creates persistent state, requires authentication, has side effects like resource allocation, or what the expected outcome is. This leaves critical behavioral traits unspecified for a tool that likely initiates a process.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that directly states the tool's purpose without any fluff or redundancy. It is front-loaded with the essential information, making it highly efficient and easy to parse. Every word earns its place, contributing to understanding without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of starting a session (which likely involves state creation or initialization), the lack of annotations and output schema means the description is insufficient. It doesn't cover what the tool returns, potential errors, or behavioral details like session persistence. For a tool with no structured data to supplement it, this leaves significant gaps in understanding its full context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, with the single parameter 'task' fully documented in the schema as 'Description of the task to work on'. The description adds no additional meaning beyond this, such as examples or constraints. Given the high schema coverage, the baseline score of 3 is appropriate, as the schema handles the parameter documentation adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Start') and resource ('new AI coding session') with a specific purpose ('with a specific task'). It distinguishes itself from siblings like 'add_session_step' by indicating it initiates a session rather than adding to an existing one. However, it doesn't explicitly contrast with all sibling tools, keeping it from a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, such as whether a session must be started before using tools like 'add_session_step', or when to choose this over other session-related tools. This lack of contextual direction leaves the agent without explicit usage cues.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update @last-editor fields in all files with Git author information
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool performs updates (implying mutation) but doesn't describe what 'update' entails—whether it overwrites existing data, requires specific permissions, has side effects, or provides any response format. This is inadequate for a mutation tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action ('Update @last-editor fields') and target. There is no wasted verbiage, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't explain what 'Git author information' entails, how the update is performed, what happens on failure, or what (if anything) is returned. Given the complexity of updating all files, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and schema description coverage is 100%, so there are no parameters to document. The description adds value by explaining the tool's purpose without needing to compensate for missing param info, earning a baseline score above the minimum.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update @last-editor fields') and the target ('in all files with Git author information'), providing a specific verb+resource combination. However, it doesn't explicitly differentiate from its sibling 'update_last_editor' (which likely updates a single file), leaving some ambiguity about scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'update_last_editor' or 'update_file_metadata'. It lacks context about prerequisites, timing, or exclusions, leaving the agent to infer usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update AI metadata in a file
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | Path to the file | |
| updates | Yes | Metadata updates to apply |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but offers minimal behavioral insight. It implies a mutation operation ('update') but doesn't disclose permissions needed, whether changes are reversible, potential side effects, or error conditions. This is inadequate for a tool that modifies data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero wasted words. It's front-loaded with the core action and target, making it easy to parse quickly. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is insufficient. It doesn't explain what 'AI metadata' includes, how updates are applied, what the response looks like, or error handling. Given the complexity implied by nested parameters, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are documented in the schema. The description adds no additional meaning beyond implying 'updates' relate to 'AI metadata', which is already inferred from the tool name. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update AI metadata in a file' clearly states the action (update) and target (AI metadata in a file), distinguishing it from siblings like 'parse_file_metadata' (read) or 'set_file_approval' (different metadata type). However, it lacks specificity about what 'AI metadata' entails, preventing a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., file existence), exclusions, or comparisons to siblings like 'update_last_editor' or 'set_file_approval', leaving the agent to infer usage from context alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update @last-editor field in a file with Git author information
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | Path to the file to update |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the tool updates a field, implying a mutation, but doesn't disclose behavioral traits such as required permissions, whether changes are reversible, potential side effects (e.g., file modification), or error handling. For a mutation tool with zero annotation coverage, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action and resource. It wastes no words and is appropriately sized for a simple tool with one parameter. Every part of the sentence earns its place by conveying essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's mutation nature, lack of annotations, and no output schema, the description is incomplete. It doesn't explain what the update entails (e.g., overwriting vs. appending), what Git author information is used, or what the response might be. For a tool that modifies files, more context is needed to ensure safe and correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents the 'filePath' parameter. The description adds no additional meaning beyond what the schema provides (e.g., it doesn't specify file format constraints or Git context requirements). With high schema coverage, the baseline score of 3 is appropriate, as the description doesn't compensate but doesn't need to.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update'), the target resource ('@last-editor field in a file'), and the source of information ('with Git author information'). It distinguishes itself from siblings like 'get_file_last_editor' (which reads) and 'update_file_metadata' (which updates broader metadata), though it doesn't explicitly name these alternatives. The purpose is specific but could be slightly more differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., Git repository context), when not to use it, or compare it to siblings like 'update_all_last_editors' (for bulk updates) or 'update_file_metadata' (for other metadata changes). Usage is implied by the action but lacks explicit context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0get_file_last_editorupdate_all_last_editorsupdate_last_editoradd_changelog_entryadd_decisionadd_session_stepcheck_before_modificationfind_files_with_metadatagenerate_all_folder_mapsgenerate_folder_mapget_file_approval_statusget_file_changelogget_modification_actionsget_project_memoryget_recent_changesparse_file_metadataset_file_approvalstart_sessionupdate_file_metadataScored across 19 tools
Most tools have distinct purposes, but there is some overlap between 'update_file_metadata' and 'parse_file_metadata' that could cause confusion, as both involve metadata handling. Additionally, 'get_file_last_editor' and 'update_last_editor' are closely related but serve different functions, which is acceptable. Overall, the tools are well-differentiated with only minor ambiguities.
The tool names follow a consistent verb_noun pattern throughout, such as 'add_changelog_entry', 'find_files_with_metadata', and 'update_file_metadata'. All tools use snake_case without deviation, making the naming highly predictable and readable. This consistency aids in easy identification and usage by agents.
With 19 tools, the count is slightly high but reasonable for a memory server that manages project metadata, changelogs, and sessions. The tools cover various aspects like file operations, session management, and metadata handling, so each seems to earn its place. However, it borders on being heavy, which could overwhelm agents if not well-organized.
The tool set provides comprehensive coverage for project memory management, including CRUD operations for metadata, changelogs, and approvals, as well as session lifecycle management. Tools like 'start_session', 'add_session_step', and 'get_project_memory' ensure full session handling, while others cover file-specific actions and metadata updates, leaving no obvious gaps for the domain.
One searchable history across every AI coding tool, with secret scanning and a shared task board.
Shared project memory that keeps teammates and AI agents aligned across sessions.
Gives your AI assistant persistent memory and intelligence about your work patterns.
Shared memory for coding agents. Stop re-explaining your codebase every session.
