Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Agent Communication MCP Server create a frontend engineer agent to build a login form with validation"
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.
Make AI agents work together seamlessly. This Model Context Protocol (MCP) server enables Claude Code to coordinate multiple specialized agents, track their progress in real-time, and understand exactly how they approach and solve complex tasks.
Author: Jeremy Fowler
Latest Release: See releases for version history and changes.
Related MCP server: Claude Swarm MCP Server
Think of this as a mission control for AI agents. Instead of trying to do everything yourself, you can delegate specific tasks to specialized agents (like a frontend engineer, backend engineer, or QA tester) and monitor their complete thought process from start to finish.
🎯 Delegation Made Simple: Create tasks for specific agents without worrying about file management or coordination complexity
🔍 Complete Transparency: See exactly how each agent understood your request, planned their approach, and executed the work
📊 Real-Time Monitoring: Track progress without interrupting agents or blocking your workflow
🛡️ Zero Complexity: Agents get clean task context automatically—no file paths, no setup headaches
🔄 Smart Completion: Flexible task completion that handles real-world variations from the original plan
⚡ Non-Blocking: All agents can work simultaneously while you stay productive
🎯 Universal Orchestration Guidance (Issue #64): Get consistent, parallel-first instructions every time you delegate tasks. No more guessing how to coordinate multiple agents—the system tells you exactly how to run them together efficiently.
⚙️ Configurable Protocol Management (Issue #63): New protocol_config tool lets you customize how tasks are created and plans are structured. Want different templates for different types of work? Now you can set that up easily.
⚡ 90% Performance Boost (Issue #60): Plan validation is now lightning fast thanks to smart caching with the new stepCount parameter. What used to take 100ms now takes less than 10ms. Your agents get feedback faster, work flows smoother.
How to Use: Add stepCount to your submit_plan calls:
// Old way: ~100ms validation time
mcp__agent_comm__submit_plan(agent="engineer", content="plan with checkboxes")
// New way: <10ms validation time
mcp__agent_comm__submit_plan(agent="engineer", stepCount=5, content="plan with 5 checkboxes")Benefits: Creates PLAN.metadata.json for caching, dramatically speeds up report_progress and track_task_progress operations.
🔍 Smart Agent Discovery (Issue #59): The system automatically finds and validates agents, making setup more reliable. Less trial-and-error, more "it just works."
📊 Enhanced Visibility (Issue #51): Better reporting and context sharing means you always know what your agents are thinking and doing. No more black boxes—complete transparency into their work process.
Choose the method that works best for your setup:
# Option 1: Global installation (recommended for MCP)
npm install -g @jerfowler/agent-comm-mcp-server
# Option 2: Use directly without installation
npx @jerfowler/agent-comm-mcp-server
# Option 3: From source
git clone https://github.com/jerfowler/agent-comm-mcp-server.git
cd agent-comm-mcp-server
npm install && npm run buildQuick Setup:
# Install and setup in one step
npm install -g @jerfowler/agent-comm-mcp-server
npm run setup # Creates .mcp.json with all configured serversManual Setup:
Add this to your Claude configuration file (.mcp.json or claude_desktop_config.json):
{
"mcpServers": {
"agent-comm": {
"command": "npx",
"args": ["@jerfowler/agent-comm-mcp-server"],
"env": {
"AGENT_COMM_DIR": "./comm"
}
}
}
}🔒 Security Note: Never commit API keys to git. The .mcp.json file is gitignored to protect sensitive credentials. Use .mcp.json.example as a template and npm run setup for easy configuration.
Want your Claude Code todos to automatically sync with agent task checkboxes? This optional hook makes it seamless.
What it does: When you update todos with TodoWrite, the hook reminds you to sync those changes to your active agent task's PLAN.md checkboxes. No more manual checkbox updates!
Quick Setup (3 steps):
Copy the hook file to your Claude Code hooks directory:
# The hook is already in your agent-comm-mcp-server installation
cp node_modules/@jerfowler/agent-comm-mcp-server/.claude/hooks/sync-todos-to-checkboxes.py ~/.claude/hooks/Make it executable:
chmod +x ~/.claude/hooks/sync-todos-to-checkboxes.pyTest it works:
echo '{"tool":{"name":"TodoWrite"},"result":{"todos":[{"content":"Test todo","status":"completed","activeForm":"Testing"}]}}' | python3 ~/.claude/hooks/sync-todos-to-checkboxes.py
# Should output: "TodoWrite updated 1 todo: 1 completed, 0 in-progress, 0 pending"
# Remember to sync to your task checkboxes using the agent-comm MCP if you have an active taskNeed help? Run our verification script to check everything:
# Download and run the verification script
curl -s https://raw.githubusercontent.com/jerfowler/agent-comm-mcp-server/main/scripts/verify-hook-installation.sh | bash
# Or if you have the project locally
./scripts/verify-hook-installation.shThat's it! Now when you use TodoWrite, you'll get helpful reminders to sync your todo changes to agent task checkboxes using the sync_todo_checkboxes tool.
Skip this if: You don't use TodoWrite or prefer manual checkbox management. The agent communication works perfectly without this hook.
Here are some conversational prompts you can use with Claude right away:
Delegate a task:
Using the agent-comm tools, create a task for senior-frontend-engineer to implement a responsive dashboard with dark mode support and real-time updates. Include proper TypeScript interfaces.Check on progress:
Can you use the agent-comm server to check how the dashboard task is going for the frontend engineer?Get the full story:
Use agent-comm tools to show me the complete lifecycle of that dashboard task - what did the agent understand, how did they plan it, and what was the final result?Clean up when done:
Please use the agent-comm server to archive all completed tasks.Every task goes through a clear, trackable lifecycle:
1. INIT: What you asked for → 2. PLAN: How they'll do it → 3. PROGRESS: Work updates → 4. DONE/ERROR: Final resultThis gives you complete visibility into:
What the agent understood from your request
How they planned to approach the work
What they actually did step by step
What the final outcome was (success or failure)
Context-Based (Recommended - Simple): Agents get clean task descriptions automatically. You never deal with file paths or technical details. Just create tasks and monitor progress.
Traditional (Advanced - Full Control): Direct access to all task files and management. Perfect if you need granular control over the process.
The Smart Response System learns from your agent interactions to provide progressively better guidance over time. It automatically detects common patterns and helps agents complete tasks more effectively.
What it does for you:
Detects Incomplete Delegations: When you create a task for another agent, the system notices if you forget to follow up and provides the exact command to check on it.
Progressive Guidance: As agents work together more, the system learns their patterns and provides increasingly specific help:
New agents get friendly reminders about the workflow
Experienced agents get concise, targeted guidance
Struggling agents receive more detailed assistance
Automatic Compliance Tracking: The system quietly tracks how well agents follow the task workflow and adjusts its guidance accordingly—no manual intervention needed.
Parallel Execution Optimization: Automatically detects opportunities to run multiple agents in parallel and generates the specific Task() commands for you. The parallel execution feature analyzes task dependencies and suggests concurrent execution patterns to maximize throughput.
Escalating Urgency Levels: Provides gentle reminders for compliant agents, firm warnings for those falling behind, and critical alerts when immediate action is required.
Example: Before and After
Before Smart Response System:
{
"success": true,
"taskId": "2025-01-10T10-30-00-implement-feature",
"message": "Task created successfully"
}After Smart Response System:
{
"success": true,
"taskId": "2025-01-10T10-30-00-implement-feature",
"message": "Task created successfully",
"guidance": {
"next_steps": "You've delegated to frontend-engineer. Check their progress with:",
"actionable_command": "mcp__agent_comm__track_task_progress(agent=\"frontend-engineer\", taskId=\"2025-01-10T10-30-00-implement-feature\")",
"contextual_reminder": "Remember to review their plan before they start implementation",
"compliance_level": 85
}
}Parallel Execution Example:
When the system detects multiple independent tasks, it automatically suggests parallel execution patterns. This parallel execution capability dramatically reduces overall completion time by utilizing all available agents concurrently.
{
"tasks": [
{ "id": "task-1", "targetAgent": "senior-frontend-engineer" },
{ "id": "task-2", "targetAgent": "senior-backend-engineer" },
{ "id": "task-3", "targetAgent": "senior-dba-advisor" }
],
"guidance": {
"contextual_reminder": "🚀 PARALLEL EXECUTION OPPORTUNITY: Multiple independent tasks detected!",
"actionable_command": "# Execute these agents in parallel:\nTask(subagent_type=\"senior-frontend-engineer\", prompt=\"Handle task: task-1\")\nTask(subagent_type=\"senior-backend-engineer\", prompt=\"Handle task: task-2\")\nTask(subagent_type=\"senior-dba-advisor\", prompt=\"Handle task: task-3\")"
}
}The parallel execution optimizer considers task dependencies, agent availability, and workload distribution to generate optimal execution strategies.
The system is completely automatic—it's enabled by default and works silently in the background. You'll only notice it when it helps you avoid mistakes or complete tasks more efficiently.
The complete PROTOCOL.md documentation covers everything in detail. Here's what you'll find:
Task Lifecycle: Complete breakdown of how tasks flow from creation to completion
Agent Communication Patterns: Context-based vs traditional workflows
Task Organization: How files and data are structured behind the scenes
Traditional Task Management (7 tools):
Create and manage tasks with full control
Read and write task files directly
List agents and their current workload
Archive and restore completed work
Context-Based Tools (5 tools):
Get clean task context without file paths
Submit implementation plans with automatic validation
Report progress updates in real-time
Complete tasks with intelligent reconciliation
Batch cleanup operations
NEW: Optional taskId parameter support for targeting specific tasks
Diagnostic Tools (2 tools):
Get complete lifecycle visibility for any task
Track real-time progress with detailed percentages
Utility Tools (4 tools):
Server health checks and status
Comprehensive server information and capabilities
TodoWrite integration for checkbox synchronization
Protocol configuration management for custom templates
Context-Based Workflow: The recommended simple approach
Diagnostic Monitoring: How to track multiple agents non-blocking
Traditional Workflow: Full control for advanced users
TodoWrite Integration:
Seamless synchronization between Claude Code's TodoWrite system and agent PLAN.md checkboxes. The integration includes a PostToolUse hook that automatically detects todo changes and reminds you to sync with the MCP server. See docs/TODOWRITE-INTEGRATION.md for complete setup and usage guide.
Intelligent Reconciliation: Handle real-world scenarios where agents optimize their approach or encounter blockers. Four reconciliation modes help you complete tasks even when the original plan changes.
Archive and Restore: Keep your workspace clean with smart archiving that lets you restore previous work when needed.
Environment Variables: Complete list with defaults and examples
MCP Client Setup: Configuration for Claude Desktop, VSCode, and other clients
Agent Instructions: Ready-to-use templates for your agent descriptions
Common Error Patterns: What goes wrong and how to fix it
Best Practices: Proven approaches for reliable agent coordination
Performance Tips: Keep everything running smoothly
Current version information
MCP compatibility details
Node.js requirements and testing info
Create these tasks in parallel using agent-comm tools:
1. senior-backend-engineer: "Design REST API for user authentication"
2. senior-frontend-engineer: "Build login/signup UI components"
3. qa-test-automation-engineer: "Create test suite for auth system"
4. devops-deployment-engineer: "Set up staging environment"Use agent-comm to delegate this complex e-commerce cart implementation to senior-frontend-engineer: "Build shopping cart with real-time inventory updates, discount code support, saved cart persistence, and mobile-responsive checkout flow."
Then monitor progress and get diagnostic insights on their approach.After the frontend work is complete, use agent-comm to assign qa-test-automation-engineer: "Review the shopping cart implementation and create comprehensive automated tests covering all user flows and edge cases."Non-Blocking by Design: You can launch multiple agents and they'll work simultaneously while you stay productive. No waiting around for sequential completion.
Complete Transparency: Instead of wondering "what is that agent doing?", you get full insight into their thinking process, planning, and execution.
File System Abstraction: Agents never see file paths or directory structures. They get clean task context and produce clean results. No more path-related bugs or setup complexity.
Real-World Flexibility: The reconciliation system handles when agents find better approaches or encounter unexpected issues. Tasks can still complete successfully even when the original plan changes.
Production Ready: Full TypeScript implementation with comprehensive testing, error handling, and logging. Built for reliability in real development workflows.
The server is configurable via environment variables:
Variable | What It Does | Default |
| Where to store task communications |
|
| Where to store completed tasks |
|
| Where to store operation logs |
|
| Turn off archiving completely |
|
For most users, the defaults work perfectly. The system creates directories automatically as needed.
The server implements a robust dual-layer filesystem architecture designed for reliable file operations with comprehensive error handling and cross-platform compatibility.
High-Level Operations (file-system.ts)
↓ Validation & Error Handling
Low-Level Operations (fs-extra-safe.ts)
↓ Fallback Mechanisms
Node.js Built-in Modules (fs, path)
↓ Cross-Platform Support
Operating System Filesystem🎯 High-Level Layer (src/utils/file-system.ts)
Task-focused operations with domain validation
Automatic directory creation for write operations
Meaningful error messages with context (FileNotFoundError, InvalidTaskError)
Task metadata parsing and validation utilities
Agent Communication Server specific functionality
⚙️ Low-Level Layer (src/utils/fs-extra-safe.ts)
Direct filesystem operations with Node.js built-in fallbacks
Handles fs-extra import issues and module resolution conflicts
Diagnostic capabilities and performance monitoring
Cross-platform reliability with multiple import strategies
Basic operations: pathExists, readdir, writeFile, readFile, stat, remove, ensureDir
Use High-Level Layer when:
Creating or managing agent tasks
Need validation (task names, agent names)
Want automatic directory creation
Need domain-specific error handling
Use Low-Level Layer when:
Need direct filesystem control
Bulk operations like directory scanning
Require specific fs-extra features
Building custom filesystem utilities
🛡️ Reliability: Multi-strategy imports with Node.js fallbacks ensure operations work regardless of fs-extra installation status
🔒 Validation: Comprehensive input validation prevents path traversal attacks and invalid task creation
🚀 Performance: Optimized imports and caching reduce overhead while maintaining flexibility
🔧 Maintainability: Clear separation of concerns makes the codebase easier to understand and extend
🌐 Cross-Platform: Consistent behavior across Windows, macOS, and Linux environments
This architecture ensures reliable filesystem operations while providing the flexibility needed for both simple task management and complex agent coordination workflows.
npm run build # Build everything
npm run dev # Development mode with auto-reload
npm test # Run all tests
npm run test:coverage # Test with coverage report
npm run lint # Check code style
npm run type-check # TypeScript validationThe project uses build-time version injection - version info is automatically pulled from package.json and compiled into the server, so there's no runtime file access needed.
Install: npm install -g @jerfowler/agent-comm-mcp-server
Configure: Add the MCP server to your Claude configuration
Try it: Ask Claude to "create a task for senior-frontend-engineer using agent-comm tools"
Explore: Check out the complete PROTOCOL.md documentation for everything else
This project uses a Git Feature Branch Workflow with branch protection on main:
# Create feature branch
git checkout -b feature/your-feature-name
# Make changes and test
npm run ci # Run all quality checks
# Push and create PR
git push -u origin feature/your-feature-name
gh pr-create # Uses our custom alias
# Check status
gh pr-checks✅ No direct commits to main - all changes via PRs
✅ Required reviews - at least 1 approval needed
✅ All tests must pass - comprehensive CI pipeline
✅ Up-to-date branches - must be current with main
See CONTRIBUTING.md and BRANCHING.md for complete workflow details.
Pre-configured aliases for streamlined workflow:
gh pr-create - Create PR with auto-fill and self-assignment
gh pr-checks - Check PR status and CI results
gh pr-merge - Squash merge with branch cleanup
gh feature - Create branch from GitHub issue
Questions? Check the issues tab or create a new issue with:
What you were trying to do
What happened instead
Your configuration and environment details
Agent Communication MCP Server - Making AI agent coordination simple, transparent, and powerful.
Archive all completed tasks - batch cleanup operation
| Name | Required | Description | Default |
|---|---|---|---|
| agent | No | Optional: Archive tasks for specific agent only |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only states 'batch cleanup operation' without disclosing destructive behavior, permissions, or side effects. Insufficient for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no fluff, but too short to convey necessary information. Could be expanded while remaining 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?
No output schema, and description does not explain return values, effects, or limitations. Incomplete for a batch operation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The parameter schema already describes the 'agent' parameter fully. The tool description adds 'all completed tasks' but provides no additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description includes specific verb 'archive', resource 'completed tasks', and indicates batch cleanup. It clearly distinguishes from sibling 'archive_tasks' by specifying scope, though sibling differentiation is not explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'archive_tasks'. No when-not-to-use context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Archive tasks to clean up communication directory (clear comms)
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Archive mode: completed tasks only, all tasks, by specific agent, or by date | |
| agent | No | Agent name (required for by-agent mode) | |
| olderThan | No | Archive tasks older than N days (required for by-date mode) | |
| dryRun | No | Preview changes without actually archiving |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should fully disclose behavior. It mentions 'clear comms' but does not explain whether tasks are deleted, hidden, or recoverable. The dryRun parameter is not described in the text. Missing critical details about side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundancy. It is appropriately concise, though it could benefit from slight expansion without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 4 parameters with modal behavior, but the description does not explain when to use each mode, how the agent parameter works, or what the output is. No output schema is provided, so the description should indicate return values. Incomplete for a multi-modal tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already defines parameters clearly. The description adds no additional meaning beyond the schema; it is a generic statement that does not enhance parameter understanding.
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 'Archive' and resource 'tasks', and includes the purpose 'clean up communication directory'. It implicitly distinguishes from the sibling 'archive_completed_tasks' by supporting multiple modes beyond just completed tasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like 'archive_completed_tasks'. The mode enum implies different use cases, but the description lacks direct instructions or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check for tasks assigned to an agent
| Name | Required | Description | Default |
|---|---|---|---|
| agent | Yes | Agent name (e.g., senior-frontend-engineer) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must disclose behavior. It does not state if this is read-only, what happens when no tasks exist, or any side effects. The mutation safety is unclear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at one sentence, but it omits important information. While not verbose, it sacrifices completeness for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does not explain what the tool returns (e.g., list of task IDs, count, detailed objects). This leaves ambiguity for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (one parameter with description and example). The tool description adds no additional semantic value beyond the schema, meeting the baseline expectation.
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 verb 'check' is vague; it is not clear whether it returns a list, count, or status of tasks. It does distinguish itself from 'read_task' by referencing tasks assigned to an agent, but lacks specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'read_task' or 'track_task_progress'. The description does not mention prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Unified task creation tool with duplicate prevention - replaces delegate_task and init_task
| Name | Required | Description | Default |
|---|---|---|---|
| agent | Yes | Target agent name | |
| taskName | Yes | Clean task name (NO timestamps) - will be auto-timestamped internally | |
| content | No | Task content in markdown format (optional for self tasks) | |
| parentTask | No | Parent task ID for subtasks (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It notes duplicate prevention and auto-timestamping, but does not disclose behavior on duplicate (error vs. return existing), return values, or authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that is front-loaded with the core purpose and key differentiator (duplicate prevention, replacement status). No redundant or unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite simple tool, description lacks mention of return value (e.g., task ID) and error handling. Output schema is absent, so description should cover these. The key behavioral aspects (duplicate prevention, timestamping) are noted but insufficient for complete 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?
Input schema has 100% coverage with descriptions. The description adds value by noting that taskName will be auto-timestamped internally, which is beyond schema info. No additional param context provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it's a unified task creation tool with duplicate prevention, and it explicitly replaces delegate_task and init_task, making the purpose distinct from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates this is the unified replacement for delegate_task and init_task, implying preferred use. However, it does not explicitly state when not to use it or provide alternatives for other operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get complete lifecycle visibility for a task - diagnostic tool for comprehensive task journey
| Name | Required | Description | Default |
|---|---|---|---|
| agent | Yes | Agent name | |
| taskId | Yes | Task ID to get lifecycle for | |
| include_progress | No | Optional: Include progress markers analysis (default: true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, and description does not disclose side effects, permissions, data volume, or whether it is safe to call repeatedly. 'Complete lifecycle visibility' is vague.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single clear sentence. Could add structured detail but no waste. Minimal but effective.
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?
No output schema and no annotations; description is brief. For a diagnostic tool, more detail on what lifecycle data includes (events, states, timings) would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all parameter descriptions (100%), so description adds minimal extra meaning beyond 'diagnostic tool' context. Baseline score 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?
Description clearly states verb (Get), resource (lifecycle for a task), and context (diagnostic tool). Differentiated from siblings like get_task_context by emphasizing comprehensive journey.
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 term 'diagnostic tool' implies use for troubleshooting or deep inspection, but no explicit when-to-use or when-not-to-use guidance or alternative tool referrals.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get comprehensive server information including version, capabilities, and runtime status
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It mentions the tool is a 'get' operation, implying read-only behavior, but does not disclose any potential side effects, authentication needs, or error conditions. The description is adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no extraneous information. It is clear and efficient, earning its place 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 simplicity of the tool (no parameters, no output schema), the description reasonably covers what is returned: version, capabilities, and runtime status. It might benefit from mentioning the format or indicating if it's JSON, but it is largely complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, and the input schema covers exhaustively. The description does not need to explain parameter semantics, so a baseline of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to get comprehensive server information including version, capabilities, and runtime status. It uses a specific verb-resource combination and distinguishes itself from sibling tools like 'ping' by indicating it returns more detailed information.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives is provided. However, the context implies it is used when server info is needed, and there is no sibling tool with similar purpose, so the lack of explicit exclusions is not critical.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get pure task context without file paths - for current or specified task
| Name | Required | Description | Default |
|---|---|---|---|
| taskId | No | Optional task ID. If omitted, returns context for current active task | |
| agent | No | Agent name (defaults to default-agent if not provided) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states the purpose without disclosing behavioral traits like read-only nature, rate limits, or potential side effects. More detail is needed for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is concise and front-loaded with the primary purpose. Every word is necessary.
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 output schema and no annotations, the description lacks details about return format and safety. It covers the core purpose but is incomplete for a comprehensive 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%, with both 'taskId' and 'agent' parameters described in the schema. The description does not add additional meaning beyond the schema, earning a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool does: 'Get pure task context without file paths - for current or specified task'. It uses a specific verb ('Get') and resource ('task context'), and distinguishes itself from siblings like 'read_task' by emphasizing 'without file paths'.
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 indicates when to use the tool: 'for current or specified task'. It implies a scenario but does not explicitly mention alternatives or when not to use it. However, the context is clear enough for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all agents with task counts and statistics
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, and the description does not disclose behavioral traits such as pagination, rate limits, or the exact meaning of 'statistics'. It only indicates a read 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, front-loaded sentence with no wasted words. It efficiently conveys the core function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no parameters and no output schema, the description is adequate but could be improved by clarifying what 'statistics' entails and whether the list is exhaustive.
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 and 100% schema coverage, so the baseline is 4. The description adds value by specifying that the output includes task counts and statistics, which is not in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'all agents', and specifies that it includes 'task counts and statistics', differentiating it from sibling tools that focus on tasks.
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_server_info or get_task_context. The description only states what it does without context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark task as complete or error with intelligent reconciliation for unchecked plan items
| Name | Required | Description | Default |
|---|---|---|---|
| status | Yes | Completion status | |
| summary | Yes | Completion summary with results or error details | |
| agent | Yes | Agent name completing the task | |
| reconciliation_mode | No | How to handle unchecked plan items: strict (default, requires all checked), auto_complete (marks all complete), reconcile (explain variances), force (override with documentation) | |
| reconciliation_explanations | No | For reconcile mode: mapping of unchecked item titles to explanations of why they are complete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavioral traits. It mentions 'intelligent reconciliation' but does not explain what the tool actually does to the task (e.g., whether it updates a status field, triggers side effects, or requires specific permissions). The agent lacks critical 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no fluff. It is front-loaded with the core action and key differentiator, wasting no words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, nested objects, and no output schema, the description is too brief. It omits information about what happens to the task, return format, or success/failure behavior, making it insufficient for an agent to fully understand the tool's operation.
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, so the schema already documents parameters. The description's phrase 'intelligent reconciliation' loosely hints at the reconciliation_mode parameter but does not add new semantic meaning beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Mark task as complete or error with intelligent reconciliation for unchecked plan items.' It specifies the verb ('mark'), resource ('task'), and includes a distinctive feature ('intelligent reconciliation') that helps differentiate it from sibling tools like check_tasks or archive_tasks.
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 check_tasks or track_task_progress. It does not mention prerequisites, exclusions, or preferred contexts, leaving the agent to infer usage without clear direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Health check tool that returns server status and timestamp
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It describes output but does not explicitly state it is read-only or safe.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, front-loaded sentence with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description fully specifies purpose and output for this simple tool with no parameters and no output schema.
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?
No parameters, so baseline 4. Description adds no parameter info, which is acceptable.
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?
Clearly states it is a health check tool returning server status and timestamp, with a specific verb and resource, and clearly distinct from sibling task 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?
Usage is implied as a connectivity test, but no explicit guidance on when to use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage protocol injection configuration for task and plan templates
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Action to perform: get current config, set new config, or reset to defaults | |
| config | No | Protocol configuration object (required for set action) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only states the tool's general purpose but does not disclose behavioral traits such as destructiveness (reset could be destructive), authorization requirements, or side effects. With no annotations, the description carries the full burden, and it fails to provide key 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that efficiently communicates the core purpose. It is front-loaded and contains no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is brief and leaves much context to the schema. Given the tool's complexity (nested config, three actions, no output schema), the description alone does not fully explain behavior or return values, though the schema mitigates this somewhat. Adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers all parameters with descriptions (100% coverage). The description adds no additional meaning beyond the schema. Baseline of 3 is appropriate as the schema already documents parameters 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 'Manage protocol injection configuration for task and plan templates' clearly states the verb (Manage) and the resource (protocol injection configuration for templates). It is specific and distinct from sibling tools, which focus on task and plan operations.
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 usage guidance is provided. The description does not mention when to use this tool versus alternatives, nor does it specify prerequisites or context for using get, set, or reset actions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a task file by type (init, plan, done, error)
| Name | Required | Description | Default |
|---|---|---|---|
| agent | Yes | Agent name | |
| task | Yes | Task folder name | |
| file | Yes | File type to read (init, plan, done, error) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the burden. It indicates a non-destructive read operation, but lacks details on potential side effects, authentication requirements, or error behaviors. For a simple read, this is adequate but minimal.
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 conveys the essential information with no unnecessary words. It is front-loaded and direct.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (three required params with full schema coverage), the description is adequate but not thorough. It does not explain return values, error cases, or prerequisites, which would be helpful for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage, so baseline is 3. The description adds 'by type' which groups the file parameter, but the enum values are already documented in the schema. No significant added meaning beyond what schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Read', the resource 'task file', and specifies the types (init, plan, done, error). This distinguishes it from sibling tools like write_task or archive_completed_tasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. Does not mention any context or exclusions, such as situations where other tools like get_task_context might be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report progress updates on plan steps - no file operations exposed
| Name | Required | Description | Default |
|---|---|---|---|
| updates | Yes | Array of step updates | |
| agent | Yes | Agent name reporting progress | |
| contextStatus | No | Optional: Current context usage status | |
| capabilityChanges | No | Optional: Capability changes discovered during execution |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden but only notes 'no file operations exposed'. It does not disclose other behavioral traits such as side effects, persistence, or required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence. It is appropriately sized but could be more front-loaded with key 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 complexity of the input schema with nested objects and no annotations or output schema, the description is too brief. It lacks information on return values, error handling, and overall behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The tool description adds no additional semantic value beyond what the schema provides, achieving the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly indicates the tool reports progress updates on plan steps. It is specific about what it does, but does not distinguish it from sibling tools like track_task_progress.
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. The description does not mention when it is appropriate to use or any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Restore tasks from archive
| Name | Required | Description | Default |
|---|---|---|---|
| timestamp | Yes | Archive timestamp (YYYY-MM-DDTHH-mm-ss format) | |
| agent | No | Restore tasks for specific agent only (optional) | |
| taskName | No | Restore tasks matching this name pattern (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must fully disclose behavioral traits. It only states the action without clarifying side effects (e.g., whether it overwrites current tasks, whether it requires permissions, or if it supports selective restoration). The lack of detail forces the agent to guess.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at one sentence with no filler. However, it is minimal to the point of being uninformative for a tool with three parameters and no annotations. While concise, it sacrifices completeness.
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 absence of annotations and output schema, the description should provide comprehensive context. It fails to explain restoration semantics, error conditions, return values, or relevant constraints. The tool has 3 parameters but the description gives no context on how they affect behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with individual parameter descriptions, but the tool description adds no additional meaning beyond what the schema already provides (e.g., timestamp format, optional filters). It does not explain how parameters interact or provide usage tips, adding zero 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 'Restore tasks from archive' clearly states the action (restore) and the resource (tasks from archive). It distinguishes from sibling tools like archive_tasks and archive_completed_tasks, which perform the opposite operation. However, it could be more specific about what restoration entails (e.g., moving to active state).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, such as requiring an existing archive timestamp, or when not to use it (e.g., if tasks are already active). With siblings like archive_tasks, explicit differentiation is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Submit implementation plan content - handles file creation internally
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | Plan content in markdown format with progress markers | |
| agent | Yes | Agent name submitting the plan | |
| agentContext | No | Optional: Agent context data including identity, capabilities, and working context | |
| contextEstimate | No | Optional: Context estimate for the plan |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description reveals only that file creation occurs internally, but lacks details on side effects, authorization, or state changes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words, though it sacrifices detail for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having 4 parameters, nested objects, and no output schema, the description provides minimal context, lacking return value, side effects, or usage 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?
Schema coverage is 100% and already describes parameters well; the description adds no additional semantic value beyond what is in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool submits implementation plan content and mentions internal file creation, 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.
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, and sibling tools like write_task are not distinguished.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sync TodoWrite updates to PLAN.md checkboxes - TodoWrite integration for automatic checkbox updates
| Name | Required | Description | Default |
|---|---|---|---|
| agent | Yes | Agent name for which to sync todo updates | |
| todoUpdates | Yes | Array of todo update objects with title and status | |
| taskId | No | Optional specific task ID to target. If not provided, uses the most recent task for the agent. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as side effects, required permissions, rate limits, or what happens to existing checkboxes. With no annotation support, the description carries the full burden but adds minimal 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 concise sentence, but the repetition of 'TodoWrite integration for automatic checkbox updates' adds little value. It is front-loaded and efficient but could be tightened.
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 moderate complexity (array of objects, required fields) and no output schema, the description does not explain return values, error handling, or sync behavior. This leaves significant gaps for an agent to use the tool 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?
Input schema has 100% description coverage for all three parameters. The description does not add extra meaning beyond what the schema already provides, meeting the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool syncs TodoWrite updates to PLAN.md checkboxes, using specific verbs and resources. It distinguishes from siblings like mark_complete or check_tasks which are more general task operations.
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?
Description implies usage for automatic checkbox updates but does not explicitly state when to use this tool versus alternatives. No when-not-to or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Track real-time task progress - diagnostic tool for progress monitoring
| Name | Required | Description | Default |
|---|---|---|---|
| agent | Yes | Agent name | |
| taskId | Yes | Task ID to track progress for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description gives minimal behavioral info. 'Real-time' hints at monitoring but lacks details on side effects, auth needs, or output nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is concise but under-informative. It could be more structured to include purpose, usage context, and behavior.
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 output schema and a simple input schema, the description fails to explain what 'progress' means, how to interpret results, or whether it's read-only. Incomplete for a diagnostic tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter descriptions. The description adds no extra value beyond the schema, which is adequate but not improved.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it tracks real-time task progress and positions it as a diagnostic tool. However, it does not distinguish from siblings like check_tasks or get_task_context, which could overlap.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. Does not mention prerequisites, context, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write a task progress file
| Name | Required | Description | Default |
|---|---|---|---|
| agent | Yes | Agent name | |
| task | Yes | Task folder name | |
| file | Yes | File type to write (plan, done, error) | |
| content | Yes | File content to write |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and description only states the basic action. Does not disclose whether files are overwritten, appended, or created, nor any side effects like directory creation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words. Front-loaded with the essential purpose.
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?
Description is too brief for a tool with 4 required parameters and no output schema. Missing details about file behavior, expected content format, and error conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds no extra meaning beyond the schema; the schema already describes each parameter with names and enum.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'write' and resource 'task progress file', distinguishing it from siblings like read_task. However, it does not specify the file types (PLAN, DONE, ERROR) that are in the input schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like report_progress or create_task. No exclusions or prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tools have generally distinct purposes (e.g., create_task vs. read_task), but some overlap exists (archive_completed_tasks vs. archive_tasks). Descriptions help disambiguate most cases.
Nearly all tools follow a consistent verb_noun pattern (e.g., create_task, list_agents, report_progress). The few exceptions like protocol_config still fit the pattern.
18 tools cover a broad range of task lifecycle and communication features. The count is slightly high but justified by the domain scope.
Covers task creation, reading, progress updates, completion, archiving, restoration, and diagnostics. Minor gap: no explicit task deletion, but archiving handles cleanup.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
AI work orchestration for plans, tasks, teams, and coding-agent dispatch.
Connect, monitor, and control AI agents — tasks, approvals, schedules, and governance.
Task management for teams building with AI agents. Agents claim tasks and report progress.
Agent personas for Claude. 16 tools, 13 personas, 3 workflows. Zero extra API cost. Free.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/jerfowler/agent-comm-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
