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-llm-router route 'explain quantum entanglement' to deepseek-r1 and save to memory"
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.
╔════════════════════════════════════════════════════════════╗
║ ║
║ ███╗ ███╗ ██████╗██████╗ ██╗ ██╗ ███╗ ███╗║
║ ████╗ ████║██╔════╝██╔══██╗ ██║ ██║ ████╗ ████║║
║ ██╔████╔██║██║ ██████╔╝ ██║ ██║ ██╔████╔██║║
║ ██║╚██╔╝██║██║ ██╔═══╝ ██║ ██║ ██║╚██╔╝██║║
║ ██║ ╚═╝ ██║╚██████╗██║ ███████╗███████╗██║ ╚═╝ ██║║
║ ╚═╝ ╚═╝ ╚═════╝╚═╝ ╚══════╝╚══════╝╚═╝ ╚═╝║
║ ║
║ L L M R O U T E R ║
║ ║
╚════════════════════════════════════════════════════════════╝A Model Context Protocol (MCP) server for routing LLM requests across multiple providers and connecting to other MCP servers. Designed with an "all-local except the brain" architecture for privacy and control.
One server, two roles: mcp_llm_router.server now ships Judge tools in-process—no separate mcp-as-a-judge server required.
Multi-Provider LLM Routing: Route requests to OpenAI, OpenRouter, DeepInfra, and other OpenAI-compatible APIs.
Configurable "Brain" Model: Choose DeepSeek reasoning or any OpenAI-compatible model as the router brain.
Session Management: Track agent sessions with goals, constraints, and event logging.
Quality Gating (Judge): Plan → code → test → completion validation using the embedded Judge toolset.
MCP-Native Context: Embedded judge resources expose current task state, history, rubric, and workflow state snapshots.
Local-First Memory: Default: Local embeddings via Ollama with optional ChromaDB vector store for efficient semantic search. OpenAI-compatible endpoints supported as fallback.
Local Cross-Encoder Reranking: Optional privacy-focused reranking using Qwen3-Reranker-0.6B for improved search relevance without external API calls.
MCP Server Orchestration: Connect to and orchestrate multiple MCP servers.
Cross-Server Tool Calling: Call tools across different MCP servers.
Universal MCP Compatibility: Works with any MCP-compatible client (not tied to specific IDEs).
Related MCP server: MCP Server Copilot
This project follows an "all-local except the brain" design philosophy:
✅ Embeddings: Run locally via Ollama (default: qwen3-embedding:0.6b)
✅ Vector Storage: SQLite (default) or ChromaDB with HNSW indexing (optional RAG package)
✅ Document Chunking: Token-based chunking with overlap (optional RAG package)
✅ Semantic Search: Local cosine similarity with L2-normalized vectors
✅ Reranking: Optional local cross-encoder reranking with Qwen3-Reranker-0.6B
🌐 LLM "Brain": Configurable external API (DeepSeek, OpenAI, etc.) for reasoning and generation
Why? This architecture keeps your data and semantic search private and fast, while leveraging powerful external LLMs only for high-level reasoning tasks.
This project is tested on Python 3.12 and 3.13.
One-command automated installation:
./install.shThis script will:
✅ Create a Python virtual environment
✅ Install all dependencies from pyproject.toml
✅ Check for Ollama installation
✅ Verify the setup
✅ Display next steps with your specific paths
If you prefer manual installation or need a Conda environment:
# Clone the repository
git clone https://github.com/groxaxo/mcp-llm-router.git
cd mcp-llm-router
# Option 1: Using venv (recommended)
python3 -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install -U pip
pip install -e .
# Option 2: Using Conda
conda create -n mcp-router python=3.13 -y
conda activate mcp-router
pip install -U pip
pip install -e .Install Ollama for local, privacy-focused embeddings:
# Linux/macOS
curl -fsSL https://ollama.ai/install.sh | sh
# Or download from https://ollama.aiPull the embedding model:
ollama pull qwen3-embedding:0.6bVerify Ollama is running:
curl http://localhost:11434/api/versionAlternative Embedding Models:
nomic-embed-text - General-purpose embeddings
mxbai-embed-large - Larger model for better quality
Set via environment variable:
export EMBEDDINGS_MODEL="nomic-embed-text"mcp-llm-router/
├── install.sh # Automated installation script
├── README.md # This file
├── pyproject.toml # Python package configuration
│
├── mcp_llm_router/ # Main package
│ ├── server.py # MCP server entry point
│ ├── brain.py # LLM routing logic
│ ├── memory.py # Memory management (embeddings, search, rerank)
│ ├── codex.py # MCP server orchestration
│ └── judge/ # Embedded judge tools for quality gating
│
├── rag/ # Optional RAG package (ChromaDB, chunking)
│ ├── main.py # CLI for indexing and queries
│ ├── indexer.py # Document indexing
│ ├── retriever.py # Vector search
│ └── reranker.py # Local cross-encoder reranking
│
├── scripts/ # Utility scripts
│ ├── verify_server.py # Installation verification
│ ├── opencode # CLI tool for direct LLM requests
│ ├── mcp_client.py # MCP client for testing
│ └── mcp_manager.py # MCP server management
│
├── examples/ # Example configurations and demos
│ ├── demo_judge_gating.py # End-to-end judge workflow demo
│ ├── local_reranker_example.py # Local reranking example
│ ├── mcp-config.deepseek-ollama.json
│ └── mcp-config.local-reranker.json
│
└── tests/ # Test suite
├── test_server.py
├── test_mcp.py
└── test_local_reranker.pymcp-config.json){
"mcpServers": {
"llm-router": {
"command": "python",
"args": ["-m", "mcp_llm_router.server"],
"env": {
"DEEPSEEK_API_KEY": "your-deepseek-key",
"ROUTER_BRAIN_PROVIDER": "deepseek",
"ROUTER_BRAIN_MODEL": "deepseek-reasoner",
"ROUTER_BRAIN_API_KEY_ENV": "DEEPSEEK_API_KEY",
"EMBEDDINGS_PROVIDER": "ollama",
"EMBEDDINGS_BASE_URL": "http://localhost:11434",
"EMBEDDINGS_MODEL": "qwen3-embedding:0.6b"
}
}
}
}{
"mcpServers": {
"llm-router": {
"command": "python",
"args": ["-m", "mcp_llm_router.server"],
"env": {
"OPENROUTER_API_KEY": "sk-or-...",
"ROUTER_BRAIN_PROVIDER": "openrouter",
"ROUTER_BRAIN_MODEL": "anthropic/claude-3.7-sonnet",
"ROUTER_BRAIN_API_KEY_ENV": "OPENROUTER_API_KEY",
"ROUTER_BRAIN_BASE_URL": "https://openrouter.ai/api/v1",
"EMBEDDINGS_PROVIDER": "ollama",
"EMBEDDINGS_BASE_URL": "http://localhost:11434",
"EMBEDDINGS_MODEL": "qwen3-embedding:0.6b"
}
}
}
}examples/mcp-config.deepseek-ollama.json - DeepSeek brain + Ollama embeddings + judge history persistence.
examples/mcp-config.local-reranker.json - DeepSeek brain + Ollama embeddings + local cross-encoder reranking.
examples/demo_judge_gating.py - End-to-end demo that indexes memory and walks a task through judge gating via router_chat.
examples/local_reranker_example.py - Example of using local cross-encoder reranking to improve search relevance.
Run the demo:
python examples/demo_judge_gating.py --config examples/mcp-config.deepseek-ollama.jsonRun the local reranker example:
python examples/local_reranker_example.pyNote: the demo skips request_plan_approval because it requires user elicitation. Ensure DEEPSEEK_API_KEY (or LLM_API_KEY) is set and Ollama is running for embeddings.
The embedded judge now exposes additive MCP resources and prompts alongside the existing tools:
Resources:
judge://current-task
judge://task/{task_id}
judge://task/{task_id}/history
judge://policy/rubric
judge://workflow/states
Prompts:
start_judged_coding_task
submit_implementation_for_review
prepare_testing_evidence
When an MCP client exposes roots, judge review/testing tools validate submitted paths against those roots. When roots are unavailable, the server preserves the existing stdio-first behavior.
Set API keys in your environment or in the config:
export OPENAI_API_KEY="sk-proj-..."
export DEEPINFRA_API_KEY="..."
export OPENROUTER_API_KEY="sk-or-..."
export DEEPSEEK_API_KEY="..."The canonical examples in this README use a DeepSeek brain + local Ollama embeddings baseline. Provider overrides only need to change the ROUTER_BRAIN_* variables and API key.
# Core brain settings
export ROUTER_BRAIN_MODEL="deepseek-reasoner"
export ROUTER_BRAIN_PROVIDER="deepseek"
export ROUTER_BRAIN_API_KEY_ENV="DEEPSEEK_API_KEY"
# Optional overrides
export ROUTER_BRAIN_BASE_URL="https://api.deepseek.com"
export ROUTER_BRAIN_MAX_TOKENS="4000"
export ROUTER_BRAIN_TEMPERATURE="0.2"You can also set the brain per session using the configure_brain tool.
No API keys required! The default configuration uses local Ollama embeddings:
# Storage paths
export MCP_ROUTER_DATA_DIR="./.mcp-llm-router"
export MCP_ROUTER_MEMORY_DB="./.mcp-llm-router/memory.db"
# Local embeddings via Ollama (DEFAULT - no API key needed)
export EMBEDDINGS_PROVIDER="ollama"
export EMBEDDINGS_BASE_URL="http://localhost:11434"
export EMBEDDINGS_MODEL="qwen3-embedding:0.6b"
export EMBEDDINGS_PATH="/api/embed"
# No EMBEDDINGS_API_KEY_ENV needed for local Ollama!If you prefer cloud-based embeddings:
# Embeddings via OpenAI
export EMBEDDINGS_PROVIDER="openai"
export EMBEDDINGS_BASE_URL="https://api.openai.com/v1"
export EMBEDDINGS_MODEL="text-embedding-3-small"
export EMBEDDINGS_API_KEY_ENV="OPENAI_API_KEY"
export EMBEDDINGS_PATH="/embeddings"Reranking is optional and defaults to "none". Three modes are available:
Uses the local Qwen3-Reranker-0.6B model for reranking without external API calls:
# Local cross-encoder reranking (requires transformers and torch)
export RERANK_PROVIDER="local"
export RERANK_MODE="local"
export RERANK_MODEL="tomaarsen/Qwen3-Reranker-0.6B-seq-cls" # Default modelRequirements:
Install PyTorch: pip install torch
Install Transformers: pip install transformers
The model will be automatically downloaded on first use (~1.2GB)
Uses an external LLM API for reranking:
# Rerank using OpenAI-compatible LLM (optional)
export RERANK_PROVIDER="openai"
export RERANK_BASE_URL="https://api.openai.com/v1"
export RERANK_MODEL="gpt-4o-mini"
export RERANK_API_KEY_ENV="OPENAI_API_KEY"
export RERANK_PATH="/chat/completions"
export RERANK_MODE="llm"# Or disable reranking entirely (default)
export RERANK_PROVIDER="none"# Persist judge conversation history + task metadata
export MCP_JUDGE_DATABASE_URL="sqlite:///./.mcp-llm-router/judge_history.db"For enhanced semantic search with vector indexing and intelligent chunking, this repository includes an optional rag package that provides:
Token-based chunking with overlap for consistent semantic granularity
ChromaDB vector store with HNSW indexing for fast similarity search
L2-normalized embeddings for consistent cosine similarity
Batch embedding and efficient upserts
Install additional dependencies (already included in pyproject.toml):
pip install -e . # chromadb, transformers are now includedIndex your codebase:
python -m rag.main --path . --exts .py,.md --interactiveThis will:
Scan the current directory for .py and .md files
Chunk them into 400-token segments with 80-token overlap
Embed using Ollama (qwen3-embedding:0.6b)
Store in ChromaDB at data/chroma/
Enter interactive mode for testing queries
Use in your code:
from rag.retriever import retrieve
from rag.indexer import index_path
# Index documents
stats = index_path("/path/to/docs", exts=[".py", ".md"])
print(f"Indexed {stats['files_indexed']} files")
# Retrieve relevant chunks
results = retrieve("How does authentication work?", top_k=5)
for hit in results:
print(f"Score: {hit['distance']:.4f}")
print(f"File: {hit['meta']['path']}")
print(f"Content: {hit['doc']}\n")RAG Package Components:
rag/embedding_config.py - Configuration constants
rag/chunker.py - Token-based text chunking
rag/ollama_embedder.py - Ollama embedding with normalization
rag/chroma_store.py - ChromaDB initialization and management
rag/indexer.py - Document indexing pipeline
rag/retriever.py - Vector search and retrieval
rag/main.py - CLI for indexing and queries
Note: The RAG package is a self-contained enhancement. The core MCP server works with its built-in SQLite memory store without requiring ChromaDB.
# List configured servers
python scripts/mcp_server_runner.py list
# Run a specific server
python scripts/mcp_server_runner.py run llm-router# Add a new server
python scripts/mcp_manager.py add my-server python -m my_mcp_server
# List servers
python scripts/mcp_manager.py list
# Test server connection
python scripts/mcp_manager.py test llm-router
# Remove a server
python scripts/mcp_manager.py remove my-server# List tools on a server
python scripts/mcp_client.py list-tools llm-router
# Call a tool on a server
python scripts/mcp_client.py call-tool llm-router start_session '{"goal": "Test session"}'# Call a tool across all configured servers
python scripts/mcp_manager.py call start_session '{"goal": "Test all servers"}'start_session(goal, constraints, context, metadata) - Start a new agent session
log_event(session_id, kind, message, details) - Log events to a session
get_session_context(session_id) - Retrieve full session data
agent_llm_request(session_id, prompt, model, base_url, api_key_env, ...) - Route to LLM providers
configure_brain(...) - Set the global or per-session brain model/settings
get_brain_config(session_id) - Read the active brain configuration
router_chat(session_id, message, ...) - Main brain chat (memory + workflow guidance)
configure_memory(...) - Set embedding/rerank configuration globally or per-session
memory_index(namespace, texts, metadatas, doc_ids) - Index texts into memory
memory_search(namespace, query, top_k, rerank) - Retrieve relevant memory hits
memory_delete(namespace, doc_id) - Delete one doc or a whole namespace
memory_list_namespaces() - List namespaces
memory_stats() - Show memory counts
connect_mcp_server(server_name, command, args, env) - Configure connection to another MCP server
list_mcp_servers() - List configured MCP server connections
call_mcp_tool(server_name, tool_name, arguments) - Call tools on other MCP servers
list_mcp_tools(server_name) - List tools available on another MCP server
set_coding_task(...)
get_current_coding_task()
request_plan_approval(...)
judge_coding_plan(...)
judge_code_change(...)
judge_testing_implementation(...)
judge_coding_task_completion(...)
raise_obstacle(...)
raise_missing_requirements(...)
The server works with any client that supports the MCP protocol:
{
"mcpServers": {
"llm-router": {
"command": "python",
"args": ["-m", "mcp_llm_router.server"],
"env": {
"OPENAI_API_KEY": "your-key"
}
}
}
}Add to your Claude Desktop MCP configuration:
{
"mcpServers": {
"llm-router": {
"command": "python",
"args": ["-m", "mcp_llm_router.server"],
"env": {
"OPENAI_API_KEY": "sk-...",
"DEEPINFRA_API_KEY": "..."
}
}
}
}import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
async def main():
server_params = StdioServerParameters(
command="python",
args=["-m", "mcp_llm_router.server"],
env={"OPENAI_API_KEY": "your-key"}
)
async with stdio_client(server_params) as (read, write):
async with ClientSession(read, write) as session:
await session.initialize()
# Start a session
result = await session.call_tool("start_session", {
"goal": "Test the MCP server"
})
print("Session started:", result)
if __name__ == "__main__":
asyncio.run(main()){
"base_url": null, # Uses default
"api_key_env": "OPENAI_API_KEY"
}{
"base_url": "https://openrouter.ai/api/v1",
"api_key_env": "OPENROUTER_API_KEY"
}{
"base_url": "https://api.deepinfra.com/v1/openai",
"api_key_env": "DEEPINFRA_API_KEY"
}The opencode command provides direct CLI access:
# Basic usage
scripts/opencode run "What is Python"
# Use specific provider
scripts/opencode run "Explain Docker" --provider deepinfra --model meta-llama/Meta-Llama-3.1-70B-Instructcd ~/mcp-llm-router
conda activate mcp-router
python -m mcp_llm_router.server# Test server startup
timeout 5 python -m mcp_llm_router.server
# Test CLI
scripts/opencode run "Hello world"
# Test MCP client
python scripts/mcp_client.py list-tools llm-router┌─────────────────┐ ┌──────────────────────────────────────┐
│ MCP Client │◄──►│ LLM Router MCP Server │
│ (Claude, etc.) │ │ ┌────────────────────────────────┐ │
└─────────────────┘ │ │ Session & Memory Management │ │
│ │ • SQLite/ChromaDB (local) │ │
│ │ • Ollama Embeddings (local) │ │
│ │ • L2-normalized vectors │ │
│ └────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────┐ │
│ │ Brain (External LLM API) │ │
│ │ • DeepSeek / OpenAI / etc. │ │
│ │ • Reasoning & Generation │ │
│ └────────────────────────────────┘ │
└──────────────────────────────────────┘
│
▼
┌──────────────────┐
│ Other MCP Servers│
│ • File system │
│ • Database │
│ • APIs │
└──────────────────┘
All-Local Except the Brain:
✅ Embeddings: Ollama (local, no API key)
✅ Vector Store: SQLite or ChromaDB (local)
✅ Semantic Search: Local cosine similarity
🌐 LLM Brain: External API (configurable)MIT License - see LICENSE file for details.
# Basic usage with OpenAI (default)
scripts/opencode run "Explain quantum computing"
# Use a specific provider
scripts/opencode run "Write a Python function" --provider openrouter --model anthropic/claude-3-opus
# Use DeepInfra
scripts/opencode run "Summarize this text" --provider deepinfra --model meta-llama/Llama-3.1-70B-InstructAvailable providers:
openai (default) - Uses OPENAI_API_KEY
openrouter - Uses OPENROUTER_API_KEY
deepinfra - Uses DEEPINFRA_API_KEY
When used as an MCP server in Antigravity, the following tools are available:
Start a new agent session with a goal and constraints.
{
"goal": "Implement user authentication",
"constraints": "Use JWT tokens, no external dependencies",
"context": "FastAPI application"
}Log events during an agent session (info, error, warning, success).
{
"session_id": "uuid-here",
"kind": "error",
"message": "Build failed",
"details": {"exit_code": 1}
}Make a request to an LLM provider within a session.
{
"session_id": "uuid-here",
"prompt": "How do I fix this error?",
"model": "gpt-4",
"base_url": "https://openrouter.ai/api/v1", # optional
"api_key_env": "OPENROUTER_API_KEY"
}Retrieve full session history and events.
{
"session_id": "uuid-here"
}Start session:
Call start_session with goal="Build a REST API for task management"Work on task:
Create files, run commands, etc.Log progress:
Call log_event with kind="info", message="Created database schema"When stuck:
Call agent_llm_request with prompt="How do I handle authentication?"Review context:
Call get_session_context to see full historyRun the MCP server directly:
cd ~/mcp-llm-router
conda activate mcp-router
python -m mcp_llm_router.serverOr use the packaged CLI entrypoint after installation:
mcp-llm-routerInspector-style capability smoke check:
python scripts/inspector_smoke.pyArchitecture and contributor guides:
docs/architecture.md
docs/how-to-add-a-judge-tool.md
Set these in your ~/.bashrc or Antigravity config:
export OPENAI_API_KEY="sk-..."
export OPENROUTER_API_KEY="sk-or-..."
export DEEPINFRA_API_KEY="..."Make a request to an OpenAI-compatible LLM provider.
| Name | Required | Description | Default |
|---|---|---|---|
| model | Yes | ||
| prompt | Yes | ||
| base_url | No | ||
| provider | No | ||
| max_tokens | No | ||
| session_id | Yes | ||
| api_key_env | No | OPENAI_API_KEY | |
| temperature | No | ||
| system_prompt | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It does not mention that the tool likely uses an API key, consumes tokens, stores conversation history via session_id, or potentially calls external services. The one-sentence description reveals nothing about side effects or requirements beyond the obvious.
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 fluff. It earns its place by stating the fundamental action clearly. However, it is so brief that it borders on under-specification, but conciseness itself is strong.
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 9 parameters and no annotations, making it a complex tool. The description only states the basic function and omits explanations of optional parameters (base_url, provider, temperature, etc.) or how session_id affects behavior. While an output schema exists, it does not compensate for the missing context needed 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?
Schema description coverage is 0% and the description adds no parameter explanations. The 9 parameters (model, prompt, base_url, provider, max_tokens, session_id, api_key_env, temperature, system_prompt) are not described in the text. Even though property names hint at meaning, the description provides zero added value for understanding parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action: 'Make a request to an OpenAI-compatible LLM provider.' It identifies the verb (make a request) and the resource (OpenAI-compatible LLM provider), which is distinct enough from sibling tools like router_chat or judge_code_change. It could be more specific about session handling, but the core purpose is evident.
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 gives no guidance on when to use this tool versus alternatives. Sibling tools include router_chat, start_session, and various judge_* tools, but no comparative context is provided. An agent is left to infer when a direct LLM request is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Call a tool on a connected MCP server.
| Name | Required | Description | Default |
|---|---|---|---|
| arguments | No | ||
| tool_name | Yes | ||
| server_name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only implies that the server must be connected, but does not explain side effects, error cases, return format, or any security implications. This is a significant gap for a generic invocation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no waste. For a simple tool, this is appropriately concise, though it lacks necessary details, which affects other dimensions rather than this one.
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 an output schema and only three parameters, the description over-relies on the schema. It does not explain how arguments should be structured, what 'connected' means operationally, or what the output represents. This is incomplete for a generic MCP invoker.
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?
There is 0% schema description coverage and the description does not mention any of the three parameters (server_name, tool_name, arguments). The tool name provides little semantic value for a generic forwarder, so the description fails to help the agent understand how to populate these fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Call') and identifies a clear resource ('a tool on a connected MCP server'), which distinguishes it from siblings like list_mcp_tools and connect_mcp_server. However, it does not elaborate on what kinds of tools or the nature of the call, which keeps it from 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?
No guidance is provided about when to use this tool versus alternatives. There is no mention of prerequisites like server connection status, or how this compares to list_mcp_tools or other related operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Configure the default or session-specific brain model.
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | ||
| base_url | No | ||
| provider | No | ||
| timeout_s | No | ||
| extra_body | No | ||
| max_tokens | No | ||
| session_id | No | ||
| api_key_env | No | ||
| temperature | No | ||
| extra_headers | No | ||
| system_prompt | No | ||
| reasoning_effort | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 says nothing about side effects, persistence, what 'default' vs 'session-specific' means, whether changes are reversible, or any required authentication or context. This is a significant gap for a configuration tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence, but it is under-specified for a tool with 12 optional parameters. Conciseness is not merely brevity; here it omits essential information, making it more of an under-specification than an efficient summary.
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 (12 parameters, no annotations, no output schema provided) the description is wholly inadequate. It does not explain how to select default vs session-specific scope, what parameters do, or what the response will look like. The presence of an output schema partially covers return values, but all other context is missing.
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 0%, so the description must compensate by explaining parameters. It does not mention any of the 12 parameters (e.g., model, base_url, session_id), leaving their meanings entirely undisclosed beyond the schema's variable names and defaults.
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 'Configure' and the resource 'brain model', with a distinction between 'default' and 'session-specific'. This is specific enough to identify the tool's core function, though it does not explicitly differentiate from sibling tools like get_brain_config.
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?
There is no guidance on when to use this tool versus alternatives, nor any mention of prerequisites or context. The description simply states what the tool does without indicating the appropriate scenarios, making it insufficient for an agent to choose between this and related tools like start_session or configure_memory.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Configure memory embedding/rerank settings (global or per-session).
| Name | Required | Description | Default |
|---|---|---|---|
| rerank | No | ||
| embedding | No | ||
| session_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. 'Configure' implies a mutation, but there is no disclosure of persistence behavior, whether settings are merged or overridden, how global vs per-session scopes interact, or any validation or error behavior. This lack of context is a significant gap for a configuration tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with a clear verb, noun, and scope parenthetical. Every word earns its place; no redundancy or fluff.
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?
An output schema exists, so return value details are not necessary, but the description is too thin overall. It does not explain the tool's effect on memory configuration, how it relates to configure_brain, or what happens when the embedding/rerank objects are omitted. For a tool with two open-object parameters and zero annotations, 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 0% and the parameters are open objects. The description adds minimal value by linking 'embedding' and 'rerank' to the corresponding settings and 'per-session' to session_id, but it does not clarify the expected fields inside the embedding/rerank objects or how session_id controls scope.
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 'Configure' and the resource 'memory embedding/rerank settings', with a scope indication of 'global or per-session'. It identifies the tool's function distinctly from memory retrieval tools, though it does not explicitly differentiate from sibling 'configure_brain'.
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 parenthetical '(global or per-session)' gives a hint about scope options, implying session_id usage, but the description provides no guidance on when to use this tool over configure_brain or other configuration tools. No when-not-to-use or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Connect to another MCP server.
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | ||
| args | No | ||
| command | Yes | ||
| server_name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for disclosing side effects and behavior. It simply restates the action without explaining what connecting entails (e.g., spawning a process, network requirements, persistence, or side effects), leaving the agent with no 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, clear sentence with no wasted words, but it is under-specified for a tool with this complexity. It is concise but not effectively structured to convey necessary 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 complexity, four parameters, and the lack of annotations or parameter descriptions, this minimal description is grossly insufficient. The presence of an output schema does not compensate for the absence of any usage context or behavioral guidance.
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 four parameters with 0% schema description coverage, and the description mentions none of them. It does not clarify the meaning of env, args, command, or server_name, failing to compensate for the schema's lack of detail.
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 identifies the action (connect) and resource (another MCP server), making the tool's purpose understandable. However, it does not explicitly distinguish from sibling tools like list_mcp_servers or call_mcp_tool, 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 no guidance on when to use this tool versus alternatives. It does not mention prerequisites, configuration steps, or scenarios where connecting is appropriate, and sibling tools such as list_mcp_servers are not referenced.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve the most recently active coding task UUID (task_id) and metadata from conversation history. Use when the task_id is missing from context.
Skipping this tool causes severe token inefficiency and wasted iterations.
Always invoke this tool at the appropriate stage to avoid extreme token loss and redundant processing.
Do not rely on assistant memory for identifiers. Always pass the exact task_id and recover it via get_current_coding_task if missing.
Need the task_id for follow-up tool calls
Want to resume the last active coding task
None
found: boolean — whether a recent task was found
task_id: string — task UUID (present when found)
last_activity: integer — last-activity timestamp for the session
current_task_metadata: object — TaskMetadata (when available)
workflow_guidance: object — WorkflowGuidance with next_tool, preparation, and guidance
After recovery, always use the exact task_id UUID in all subsequent tool calls. Do not invent or transform the value.
| 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 discloses behavioral traits such as the token inefficiency warning, the fact that it retrieves from conversation history, and the explicit instruction not to invent or transform the task_id. It adds meaningful context beyond a simple '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 well-structured with clear sections (Description, Warning, When to use, Args, Returns, Notes). However, the 'Critical Tool Warning' is repetitive and somewhat verbose, using dramatic language like 'severe token inefficiency' and 'extreme token loss', which could be trimmed without losing value.
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 complete for a tool with no parameters and no output schema. It covers purpose, usage, return values, and important notes about task_id handling. There is no missing information needed for the 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?
The tool has zero parameters, and the description explicitly states 'Args: None', which is clear and sufficient. The baseline for zero-param tools is 4, and the description does not need to add more.
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: 'Retrieve the most recently active coding task UUID (task_id) and metadata from conversation history.' It uses a specific verb and resource, and distinguishes itself from siblings like set_coding_task.
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 explicitly says 'Use when the task_id is missing from context' and provides a 'When to use' section. It gives clear context for when to invoke the tool, though it does not explicitly mention alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve the full context of a session.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits. It merely says 'Retrieve' without stating safety (read-only), required permissions, potential errors, or the nature of the returned context. It lacks any depth 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, front-loaded sentence with no filler words. It wastes no tokens and is appropriately sized for the tool's simplicity.
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?
Although the tool has an output schema, the description fails to provide context on what 'full context' includes, any preconditions (e.g., session must exist), or how to retrieve session_id. For a simple one-parameter read tool, this minimal description is inadequate for reliable 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 schema has 0% description coverage, so the description should compensate for the sole parameter 'session_id'. However, the description adds no information about the parameter's format, how to obtain it, or its role in the retrieval. The agent is left with only the parameter name.
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 'Retrieve the full context of a session' uses a specific verb and resource, clearly indicating the tool's function. It is implicitly distinguished from sibling tools like 'start_session', but it doesn't explicitly differentiate itself or elaborate on what 'full context' includes, 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?
There is no guidance on when to use this tool, prerequisites, or alternatives. The description does not mention how it relates to session creation or other retrieval tools, leaving the agent without contextual information for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Review implementation code changes (not tests) strictly based on a unified Git diff patch. Tests are validated separately by judge_testing_implementation. Called when workflow_guidance.next_tool == "judge_code_change".
Skipping this tool causes severe token inefficiency and wasted iterations.
Always invoke this tool at the appropriate stage to avoid extreme token loss and redundant processing.
Do not rely on assistant memory for identifiers. Always pass the exact task_id and recover it via get_current_coding_task if missing.
After creating or modifying implementation code and a review is needed. Provide a unified Git diff of the changes. Tests may be written before or after review; they are validated via judge_testing_implementation.
If foundational choices are unclear or need confirmation (e.g., framework/library, UI vs CLI, web vs desktop, API style, auth, hosting), first call raise_missing_requirements to elicit the user’s intent
If the implementation proposes changing a previously described/understood fundamental choice, call raise_obstacle to involve the user in selecting the new direction
These HITL tools do not return next_tool; follow workflow guidance for the next step after elicitation
task_id: string — Task UUID (required)
code_change: string — Unified Git diff patch representing the changes (REQUIRED)
file_path: string — Path to the primary created/modified file (optional; use when diff covers a single file)
change_description: string — What the change accomplishes
Response JSON schema (JudgeResponse):
{
"$defs": {
"FileReview": {
"properties": {
"path": {
"description": "File path reviewed",
"title": "Path",
"type": "string"
},
"feedback": {
"description": "Per-file feedback summary",
"title": "Feedback",
"type": "string"
},
"approved": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional per-file approval or risk flag",
"title": "Approved"
}
},
"required": [
"path",
"feedback"
],
"title": "FileReview",
"type": "object"
},
"LibraryPlanItem": {
"properties": {
"purpose": {
"description": "Non-domain concern or integration point this library addresses",
"title": "Purpose",
"type": "string"
},
"selection": {
"description": "Chosen library or internal utility (name and optional version)",
"title": "Selection",
"type": "string"
},
"source": {
"description": "Source of solution: 'internal' for repo utility, 'external' for well-known library, 'custom' for in-house code",
"title": "Source",
"type": "string"
},
"justification": {
"default": "",
"description": "One-line rationale for the selection and any trade-offs",
"title": "Justification",
"type": "string"
}
},
"required": [
"purpose",
"selection",
"source"
],
"title": "LibraryPlanItem",
"type": "object"
},
"PlanRequiredField": {
"description": "Specification for a required field in judge_coding_plan.",
"properties": {
"name": {
"description": "Field name in the judge_coding_plan tool",
"title": "Name",
"type": "string"
},
"type": {
"description": "Expected data type (string, list[str], list[dict], etc.)",
"title": "Type",
"type": "string"
},
"description": {
"description": "What this field should contain",
"title": "Description",
"type": "string"
},
"required": {
"description": "Whether this field is required",
"title": "Required",
"type": "boolean"
},
"conditional_on": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Task metadata field this requirement depends on (e.g., 'design_patterns_enforcement')",
"title": "Conditional On"
},
"example_value": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Example of what this field should contain",
"title": "Example Value"
}
},
"required": [
"name",
"type",
"description",
"required"
],
"title": "PlanRequiredField",
"type": "object"
},
"RequirementsVersion": {
"description": "A version of user requirements with timestamp and source.",
"properties": {
"content": {
"title": "Content",
"type": "string"
},
"source": {
"title": "Source",
"type": "string"
},
"timestamp": {
"title": "Timestamp",
"type": "integer"
}
},
"required": [
"content",
"source"
],
"title": "RequirementsVersion",
"type": "object"
},
"ResearchScope": {
"description": "Research scope enum for workflow-driven research validation.\n\nDetermines the depth and requirements for research validation:\n- NONE: No research required for this task complexity\n- LIGHT: Light research required (1+ authoritative domain source)\n- DEEP: Deep research required (2+ authoritative domain sources)",
"enum": [
"none",
"light",
"deep"
],
"title": "ResearchScope",
"type": "string"
},
"ReuseComponent": {
"properties": {
"path": {
"description": "Repository path to the reusable component",
"title": "Path",
"type": "string"
},
"purpose": {
"default": "",
"description": "What part of the task this component will support",
"title": "Purpose",
"type": "string"
},
"notes": {
"default": "",
"description": "Any integration notes or caveats",
"title": "Notes",
"type": "string"
}
},
"required": [
"path"
],
"title": "ReuseComponent",
"type": "object"
},
"TaskMetadata": {
"description": "Lightweight metadata for coding tasks that flows with memory layer.\n\nThis model serves as the foundation for the enhanced workflow v3 system,\nreplacing session-based tracking with task-centric approach.",
"properties": {
"task_id": {
"description": "IMMUTABLE: Auto-generated UUID, primary key for memory storage",
"title": "Task Id",
"type": "string"
},
"created_at": {
"description": "IMMUTABLE: Task creation timestamp (epoch seconds)",
"title": "Created At",
"type": "integer"
},
"title": {
"description": "Display title for coding task (updatable)",
"title": "Title",
"type": "string"
},
"description": {
"description": "Detailed coding task description (updatable)",
"title": "Description",
"type": "string"
},
"user_requirements": {
"default": "",
"description": "Current coding requirements (updatable)",
"title": "User Requirements",
"type": "string"
},
"state": {
"$ref": "#/$defs/TaskState",
"default": "created",
"description": "Current task state (updatable, follows TaskState transitions)"
},
"task_size": {
"$ref": "#/$defs/TaskSize",
"description": "Task size classification for workflow optimization (XS=simple fixes, S=minor features, M=standard, L=complex, XL=major changes)"
},
"user_requirements_history": {
"description": "History of requirements changes",
"items": {
"$ref": "#/$defs/RequirementsVersion"
},
"title": "User Requirements History",
"type": "array"
},
"accumulated_diff": {
"additionalProperties": true,
"description": "Code changes accumulated over time",
"title": "Accumulated Diff",
"type": "object"
},
"modified_files": {
"description": "List of file paths that were created or modified during task implementation",
"items": {
"type": "string"
},
"title": "Modified Files",
"type": "array"
},
"test_files": {
"description": "List of test file paths that were created during testing phase",
"items": {
"type": "string"
},
"title": "Test Files",
"type": "array"
},
"test_status": {
"additionalProperties": {
"type": "string"
},
"description": "Status of different test types (unit, integration, e2e, etc.)",
"title": "Test Status",
"type": "object"
},
"updated_at": {
"description": "Last update timestamp (epoch seconds)",
"title": "Updated At",
"type": "integer"
},
"tags": {
"description": "Coding-related tags",
"items": {
"type": "string"
},
"title": "Tags",
"type": "array"
},
"problem_domain": {
"default": "",
"description": "Concise statement of the problem domain and scope for this task",
"title": "Problem Domain",
"type": "string"
},
"problem_non_goals": {
"description": "Explicit non-goals/boundaries to prevent scope creep and re-solving commodity concerns",
"items": {
"type": "string"
},
"title": "Problem Non Goals",
"type": "array"
},
"library_plan": {
"description": "Planned libraries/utilities per purpose; prefer internal reuse and well-known libraries; custom code only with justification",
"items": {
"$ref": "#/$defs/LibraryPlanItem"
},
"title": "Library Plan",
"type": "array"
},
"internal_reuse_components": {
"description": "Existing repository components/utilities to reuse with paths and purposes",
"items": {
"$ref": "#/$defs/ReuseComponent"
},
"title": "Internal Reuse Components",
"type": "array"
},
"research_required": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether research is required by workflow guidance (None=undetermined, True=required, False=optional)",
"title": "Research Required"
},
"research_scope": {
"$ref": "#/$defs/ResearchScope",
"default": "none",
"description": "Research scope determined by workflow: none|light|deep"
},
"research_completed": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Epoch seconds when research validation passed",
"title": "Research Completed"
},
"research_rationale": {
"default": "",
"description": "Explanation of why research was required and how the scope was determined",
"title": "Research Rationale",
"type": "string"
},
"expected_url_count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "LLM-determined expected number of research URLs based on task complexity",
"title": "Expected Url Count"
},
"minimum_url_count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "LLM-determined minimum acceptable URL count for adequate research",
"title": "Minimum Url Count"
},
"url_requirement_reasoning": {
"default": "",
"description": "LLM-generated explanation of why specific URL count is needed for this task",
"title": "Url Requirement Reasoning",
"type": "string"
},
"research_complexity_analysis": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Detailed complexity analysis factors from LLM (domain, tech maturity, integration scope, etc.)",
"title": "Research Complexity Analysis"
},
"internal_research_required": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether internal codebase research is needed (None=undetermined, True=required, False=not needed)",
"title": "Internal Research Required"
},
"related_code_snippets": {
"description": "Related code snippets from the codebase that are relevant to this task",
"items": {
"type": "string"
},
"title": "Related Code Snippets",
"type": "array"
},
"risk_assessment_required": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether risk assessment is needed (None=undetermined, True=required, False=not needed)",
"title": "Risk Assessment Required"
},
"identified_risks": {
"description": "Areas that could be harmed by the proposed changes",
"items": {
"type": "string"
},
"title": "Identified Risks",
"type": "array"
},
"risk_mitigation_strategies": {
"description": "Strategies to mitigate identified risks",
"items": {
"type": "string"
},
"title": "Risk Mitigation Strategies",
"type": "array"
},
"design_patterns_enforcement": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether design patterns are required for this task (None=undetermined, True=required, False=not needed)",
"title": "Design Patterns Enforcement"
},
"plan_approved_at": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Timestamp when plan was approved by judge_coding_plan (None=not approved)",
"title": "Plan Approved At"
},
"plan_rejection_count": {
"default": 0,
"description": "Number of times the plan has been rejected (max 1 allowed)",
"title": "Plan Rejection Count",
"type": "integer"
},
"code_approved_files": {
"additionalProperties": {
"type": "integer"
},
"description": "Dictionary mapping file paths to approval timestamps from judge_code_change",
"title": "Code Approved Files",
"type": "object"
},
"testing_approved_at": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Timestamp when testing was approved by judge_testing_implementation (None=not approved)",
"title": "Testing Approved At"
},
"all_approvals_validated": {
"default": false,
"description": "Whether all required approvals (plan, code, testing) have been validated",
"title": "All Approvals Validated",
"type": "boolean"
}
},
"required": [
"title",
"description",
"task_size"
],
"title": "TaskMetadata",
"type": "object"
},
"TaskSize": {
"description": "Task size classification for workflow optimization.\n\nSizes are based on estimated complexity and time requirements:\n- XS: Extra Small - Simple fixes, typos, minor config changes (< 30 minutes)\n- S: Small - Minor features, simple refactoring (30 minutes - 2 hours)\n- M: Medium - Standard features, moderate complexity (2-8 hours) - DEFAULT\n- L: Large - Complex features, multiple components (1-3 days)\n- XL: Extra Large - Major system changes, architectural updates (3+ days)\n\nThis classification determines planning complexity and validation depth:\n- XS/S: Basic planning requirements, streamlined validation\n- M: Standard planning and validation\n- L/XL: Comprehensive planning with enhanced validation (library plans, risk assessment, design patterns)\n\nAll tasks follow the unified workflow: CREATED \u2192 PLANNING \u2192 PLAN_APPROVED \u2192 IMPLEMENTING \u2192 REVIEW_READY \u2192 TESTING \u2192 COMPLETED",
"enum": [
"xs",
"s",
"m",
"l",
"xl"
],
"title": "TaskSize",
"type": "string"
},
"TaskState": {
"description": "Coding task state enum with well-documented transitions.\n\nState Transitions:\n- CREATED \u2192 PLANNING: Task created, ready for planning phase (XS/S may skip to IMPLEMENTING)\n- PLANNING \u2192 PLAN_PENDING_APPROVAL: Plan created, awaiting user approval\n- PLAN_PENDING_APPROVAL \u2192 PLANNING: User requests plan changes\n- PLAN_PENDING_APPROVAL \u2192 PLAN_APPROVED: User approves plan\n- PLAN_APPROVED \u2192 IMPLEMENTING: Implementation phase started\n- IMPLEMENTING \u2192 IMPLEMENTING: Multiple code changes during implementation\n- IMPLEMENTING \u2192 REVIEW_READY: Implementation complete, ready for code review\n- REVIEW_READY \u2192 TESTING: Code review approved, ready for testing validation\n- TESTING \u2192 TESTING: Multiple test iterations\n- TESTING \u2192 COMPLETED: All tests validated; task completed successfully\n- Any state \u2192 BLOCKED: Task blocked by external dependencies\n- Any state \u2192 CANCELLED: Task cancelled\n- BLOCKED \u2192 Previous state: Unblocked, return to previous state\n\nUsage:\n- CREATED: Default state for new tasks, all tasks proceed to planning (unified workflow)\n- PLANNING: Planning phase in progress (set when planning starts)\n- PLAN_PENDING_APPROVAL: Plan created, awaiting user approval and potential iteration\n- PLAN_APPROVED: Plan validated and approved (set by judge_coding_plan)\n- IMPLEMENTING: Implementation phase in progress (set when coding starts)\n- REVIEW_READY: Implementation complete and ready for code review\n- TESTING: Testing/validation phase after code review approval\n- COMPLETED: Task completed successfully (set by judge_coding_task_completion)\n- BLOCKED: Task blocked by external dependencies (manual override)\n- CANCELLED: Task cancelled (manual override)",
"enum": [
"created",
"planning",
"plan_pending_approval",
"plan_approved",
"implementing",
"testing",
"review_ready",
"completed",
"blocked",
"cancelled"
],
"title": "TaskState",
"type": "string"
},
"WorkflowGuidance": {
"description": "Canonical workflow guidance model used across the system.\n\nReturned by tools to provide consistent next steps and instructions for\nthe coding assistant. This is the single source of truth for the\nWorkflowGuidance schema.",
"properties": {
"next_tool": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Next tool to call, or None if workflow complete",
"title": "Next Tool"
},
"reasoning": {
"default": "",
"description": "Clear explanation of why this tool should be used next",
"title": "Reasoning",
"type": "string"
},
"preparation_needed": {
"description": "List of things that need to be prepared before calling the recommended tool",
"items": {
"type": "string"
},
"title": "Preparation Needed",
"type": "array"
},
"guidance": {
"default": "",
"description": "Detailed step-by-step guidance for the AI assistant",
"title": "Guidance",
"type": "string"
},
"research_required": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether research is required for this task (only determined for new CREATED tasks)",
"title": "Research Required"
},
"research_scope": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Research scope: 'none', 'light', or 'deep' (only determined for new CREATED tasks)",
"title": "Research Scope"
},
"research_rationale": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Explanation of research requirements (only determined for new CREATED tasks)",
"title": "Research Rationale"
},
"internal_research_required": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether internal codebase analysis is needed (only determined for new CREATED tasks)",
"title": "Internal Research Required"
},
"risk_assessment_required": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether risk assessment is needed (only determined for new CREATED tasks)",
"title": "Risk Assessment Required"
},
"design_patterns_enforcement": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether design patterns are required (only determined for new CREATED tasks)",
"title": "Design Patterns Enforcement"
},
"plan_required_fields": {
"description": "Structured specification of required fields for judge_coding_plan tool",
"items": {
"$ref": "#/$defs/PlanRequiredField"
},
"title": "Plan Required Fields",
"type": "array"
}
},
"title": "WorkflowGuidance",
"type": "object"
}
},
"properties": {
"approved": {
"description": "Whether the validation passed",
"title": "Approved",
"type": "boolean"
},
"required_improvements": {
"description": "List of required improvements if not approved",
"items": {
"type": "string"
},
"title": "Required Improvements",
"type": "array"
},
"feedback": {
"description": "Detailed feedback about the validation",
"title": "Feedback",
"type": "string"
},
"suggested_diff": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Unified Git diff patch with suggested changes (optional). Provide when rejecting with concrete fixes or when proposing minor refinements.",
"title": "Suggested Diff"
},
"reviewed_files": {
"description": "Per-file reviews. Must include an entry for every file changed in the diff.",
"items": {
"$ref": "#/$defs/FileReview"
},
"title": "Reviewed Files",
"type": "array"
},
"current_task_metadata": {
"$ref": "#/$defs/TaskMetadata",
"description": "ALWAYS current state of task metadata after operation"
},
"workflow_guidance": {
"anyOf": [
{
"$ref": "#/$defs/WorkflowGuidance"
},
{
"type": "null"
}
],
"default": null,
"description": "LLM-generated next steps and instructions from shared method"
}
},
"required": [
"approved",
"feedback"
],
"title": "JudgeResponse",
"type": "object"
}Review only implementation code here; tests are validated via judge_testing_implementation.
The code_change MUST be a unified Git diff (e.g., contains diff --git, ---, +++, @@). If a diff is not provided, this tool will return approved: false and request a proper diff.
Always use the exact task_id; recover it via get_current_coding_task if missing.
If HITL was performed, update the task description/requirements via set_coding_task if text needs to be clarified for future steps
Implementations that re-solve commodity concerns will be rejected unless a strong justification is provided. Prefer existing repo utilities or well-known libraries over custom code.
Provide per-file coverage: include a reviewed_files array with one entry per changed file path in the diff, each with a brief per-file summary and any specific issues.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | No | ||
| file_path | No | File path not specified | |
| code_change | Yes | ||
| user_requirements | No | ||
| change_description | No | Change description not provided |
| Name | Required | Description |
|---|---|---|
| approved | Yes | Whether the validation passed |
| feedback | Yes | Detailed feedback about the validation |
| reviewed_files | No | Per-file reviews. Must include an entry for every file changed in the diff. |
| suggested_diff | No | Unified Git diff patch with suggested changes (optional). Provide when rejecting with concrete fixes or when proposing minor refinements. |
| workflow_guidance | No | LLM-generated next steps and instructions from shared method |
| current_task_metadata | No | ALWAYS current state of task metadata after operation |
| required_improvements | No | List of required improvements if not approved |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full transparency burden and meets it extensively. It discloses that a missing/invalid diff will cause approved:false, that commodity re-solutions are rejected without justification, per-file coverage is required in reviewed_files, and exact task_id must be supplied. It also warns about token inefficiency and HITL handling.
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 well-structured with headings but is repetitive: the need for exact task_id appears at least three times, and the 'not tests' exclusion appears twice. The embedded JSON schema adds significant length, but the prose itself could be leaner without losing 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?
For a complex workflow tool with no annotations and a rich output schema, the description is highly complete. It covers workflow triggering, HITL escalation, diff format enforcement, per-file review requirements, and task_id recovery. However, the omission of the user_requirements parameter and some redundancy prevent it from being fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description enriches four of five parameters: task_id must be exact and recoverable, code_change must be a unified Git diff (with specific markers), file_path is optional for single-file diffs, and change_description summarizes the change. However, user_requirements is entirely missing from the Args section, and task_id is labeled required even though the schema defaults it and only code_change is required.
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 explicitly states the tool's purpose: 'Review implementation code changes (not tests) strictly based on a unified Git diff patch.' It clearly differentiates from the sibling tool judge_testing_implementation and references the workflow trigger condition (workflow_guidance.next_tool == "judge_code_change").
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?
A dedicated 'When to use' section explains to use the tool after creating/modifying implementation code, and explicitly says tests are validated via judge_testing_implementation. It also provides alternatives for ambiguous foundational choices (raise_missing_requirements) and fundamental changes (raise_obstacle), plus recovery instructions via get_current_coding_task.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate a proposed plan and design against requirements, research needs, and risks. Called when workflow_guidance.next_tool == "judge_coding_plan".
Skipping this tool causes severe token inefficiency and wasted iterations.
Always invoke this tool at the appropriate stage to avoid extreme token loss and redundant processing.
Do not rely on assistant memory for identifiers. Always pass the exact task_id and recover it via get_current_coding_task if missing.
Thoroughly analyze requirements, propose a concrete plan, and produce a system design
Include a Problem Domain Statement, a Library Selection Map (well-known libraries by purpose, with justifications), and an Internal Reuse Map (existing repo components with paths)
If foundational choices are ambiguous or missing (e.g., framework/library, UI vs CLI, web vs desktop, API style, auth, hosting), first call raise_missing_requirements to elicit user preferences
If the plan proposes changing an already understood fundamental choice, call raise_obstacle to involve the user’s decision
These HITL tools do not return next_tool; rely on workflow guidance to determine the next tool after elicitation
task_id: string — Task UUID (required)
plan: string — Detailed implementation plan (required)
design: string — Architecture, components, data flow, key decisions (required)
research: string — Findings and rationale (provide if available)
research_urls: list[string] — URLs for external research (if required)
context: string — Additional project context
problem_domain: string — Concise problem domain statement (optional but recommended)
problem_non_goals: list[string] — Non-goals/out-of-scope items (optional)
library_plan: list[object] — Library Selection Map entries: {purpose, selection, source: internal|external|custom, justification}
internal_reuse_components: list[object] — Internal Reuse Map entries: {path, purpose, notes}
design_patterns: list[object] — Design patterns to be applied: {name, area} (required when current_task_metadata.design_patterns_enforcement=true)
identified_risks: list[string] — Enumerated risks; required when current_task_metadata.risk_assessment_required=true (the server will auto-seed sensible defaults if omitted)
risk_mitigation_strategies: list[string] — Mitigations aligned one-to-one with identified_risks
Response JSON schema (JudgeResponse):
{
"$defs": {
"FileReview": {
"properties": {
"path": {
"description": "File path reviewed",
"title": "Path",
"type": "string"
},
"feedback": {
"description": "Per-file feedback summary",
"title": "Feedback",
"type": "string"
},
"approved": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional per-file approval or risk flag",
"title": "Approved"
}
},
"required": [
"path",
"feedback"
],
"title": "FileReview",
"type": "object"
},
"LibraryPlanItem": {
"properties": {
"purpose": {
"description": "Non-domain concern or integration point this library addresses",
"title": "Purpose",
"type": "string"
},
"selection": {
"description": "Chosen library or internal utility (name and optional version)",
"title": "Selection",
"type": "string"
},
"source": {
"description": "Source of solution: 'internal' for repo utility, 'external' for well-known library, 'custom' for in-house code",
"title": "Source",
"type": "string"
},
"justification": {
"default": "",
"description": "One-line rationale for the selection and any trade-offs",
"title": "Justification",
"type": "string"
}
},
"required": [
"purpose",
"selection",
"source"
],
"title": "LibraryPlanItem",
"type": "object"
},
"PlanRequiredField": {
"description": "Specification for a required field in judge_coding_plan.",
"properties": {
"name": {
"description": "Field name in the judge_coding_plan tool",
"title": "Name",
"type": "string"
},
"type": {
"description": "Expected data type (string, list[str], list[dict], etc.)",
"title": "Type",
"type": "string"
},
"description": {
"description": "What this field should contain",
"title": "Description",
"type": "string"
},
"required": {
"description": "Whether this field is required",
"title": "Required",
"type": "boolean"
},
"conditional_on": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Task metadata field this requirement depends on (e.g., 'design_patterns_enforcement')",
"title": "Conditional On"
},
"example_value": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Example of what this field should contain",
"title": "Example Value"
}
},
"required": [
"name",
"type",
"description",
"required"
],
"title": "PlanRequiredField",
"type": "object"
},
"RequirementsVersion": {
"description": "A version of user requirements with timestamp and source.",
"properties": {
"content": {
"title": "Content",
"type": "string"
},
"source": {
"title": "Source",
"type": "string"
},
"timestamp": {
"title": "Timestamp",
"type": "integer"
}
},
"required": [
"content",
"source"
],
"title": "RequirementsVersion",
"type": "object"
},
"ResearchScope": {
"description": "Research scope enum for workflow-driven research validation.\n\nDetermines the depth and requirements for research validation:\n- NONE: No research required for this task complexity\n- LIGHT: Light research required (1+ authoritative domain source)\n- DEEP: Deep research required (2+ authoritative domain sources)",
"enum": [
"none",
"light",
"deep"
],
"title": "ResearchScope",
"type": "string"
},
"ReuseComponent": {
"properties": {
"path": {
"description": "Repository path to the reusable component",
"title": "Path",
"type": "string"
},
"purpose": {
"default": "",
"description": "What part of the task this component will support",
"title": "Purpose",
"type": "string"
},
"notes": {
"default": "",
"description": "Any integration notes or caveats",
"title": "Notes",
"type": "string"
}
},
"required": [
"path"
],
"title": "ReuseComponent",
"type": "object"
},
"TaskMetadata": {
"description": "Lightweight metadata for coding tasks that flows with memory layer.\n\nThis model serves as the foundation for the enhanced workflow v3 system,\nreplacing session-based tracking with task-centric approach.",
"properties": {
"task_id": {
"description": "IMMUTABLE: Auto-generated UUID, primary key for memory storage",
"title": "Task Id",
"type": "string"
},
"created_at": {
"description": "IMMUTABLE: Task creation timestamp (epoch seconds)",
"title": "Created At",
"type": "integer"
},
"title": {
"description": "Display title for coding task (updatable)",
"title": "Title",
"type": "string"
},
"description": {
"description": "Detailed coding task description (updatable)",
"title": "Description",
"type": "string"
},
"user_requirements": {
"default": "",
"description": "Current coding requirements (updatable)",
"title": "User Requirements",
"type": "string"
},
"state": {
"$ref": "#/$defs/TaskState",
"default": "created",
"description": "Current task state (updatable, follows TaskState transitions)"
},
"task_size": {
"$ref": "#/$defs/TaskSize",
"description": "Task size classification for workflow optimization (XS=simple fixes, S=minor features, M=standard, L=complex, XL=major changes)"
},
"user_requirements_history": {
"description": "History of requirements changes",
"items": {
"$ref": "#/$defs/RequirementsVersion"
},
"title": "User Requirements History",
"type": "array"
},
"accumulated_diff": {
"additionalProperties": true,
"description": "Code changes accumulated over time",
"title": "Accumulated Diff",
"type": "object"
},
"modified_files": {
"description": "List of file paths that were created or modified during task implementation",
"items": {
"type": "string"
},
"title": "Modified Files",
"type": "array"
},
"test_files": {
"description": "List of test file paths that were created during testing phase",
"items": {
"type": "string"
},
"title": "Test Files",
"type": "array"
},
"test_status": {
"additionalProperties": {
"type": "string"
},
"description": "Status of different test types (unit, integration, e2e, etc.)",
"title": "Test Status",
"type": "object"
},
"updated_at": {
"description": "Last update timestamp (epoch seconds)",
"title": "Updated At",
"type": "integer"
},
"tags": {
"description": "Coding-related tags",
"items": {
"type": "string"
},
"title": "Tags",
"type": "array"
},
"problem_domain": {
"default": "",
"description": "Concise statement of the problem domain and scope for this task",
"title": "Problem Domain",
"type": "string"
},
"problem_non_goals": {
"description": "Explicit non-goals/boundaries to prevent scope creep and re-solving commodity concerns",
"items": {
"type": "string"
},
"title": "Problem Non Goals",
"type": "array"
},
"library_plan": {
"description": "Planned libraries/utilities per purpose; prefer internal reuse and well-known libraries; custom code only with justification",
"items": {
"$ref": "#/$defs/LibraryPlanItem"
},
"title": "Library Plan",
"type": "array"
},
"internal_reuse_components": {
"description": "Existing repository components/utilities to reuse with paths and purposes",
"items": {
"$ref": "#/$defs/ReuseComponent"
},
"title": "Internal Reuse Components",
"type": "array"
},
"research_required": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether research is required by workflow guidance (None=undetermined, True=required, False=optional)",
"title": "Research Required"
},
"research_scope": {
"$ref": "#/$defs/ResearchScope",
"default": "none",
"description": "Research scope determined by workflow: none|light|deep"
},
"research_completed": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Epoch seconds when research validation passed",
"title": "Research Completed"
},
"research_rationale": {
"default": "",
"description": "Explanation of why research was required and how the scope was determined",
"title": "Research Rationale",
"type": "string"
},
"expected_url_count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "LLM-determined expected number of research URLs based on task complexity",
"title": "Expected Url Count"
},
"minimum_url_count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "LLM-determined minimum acceptable URL count for adequate research",
"title": "Minimum Url Count"
},
"url_requirement_reasoning": {
"default": "",
"description": "LLM-generated explanation of why specific URL count is needed for this task",
"title": "Url Requirement Reasoning",
"type": "string"
},
"research_complexity_analysis": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Detailed complexity analysis factors from LLM (domain, tech maturity, integration scope, etc.)",
"title": "Research Complexity Analysis"
},
"internal_research_required": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether internal codebase research is needed (None=undetermined, True=required, False=not needed)",
"title": "Internal Research Required"
},
"related_code_snippets": {
"description": "Related code snippets from the codebase that are relevant to this task",
"items": {
"type": "string"
},
"title": "Related Code Snippets",
"type": "array"
},
"risk_assessment_required": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether risk assessment is needed (None=undetermined, True=required, False=not needed)",
"title": "Risk Assessment Required"
},
"identified_risks": {
"description": "Areas that could be harmed by the proposed changes",
"items": {
"type": "string"
},
"title": "Identified Risks",
"type": "array"
},
"risk_mitigation_strategies": {
"description": "Strategies to mitigate identified risks",
"items": {
"type": "string"
},
"title": "Risk Mitigation Strategies",
"type": "array"
},
"design_patterns_enforcement": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether design patterns are required for this task (None=undetermined, True=required, False=not needed)",
"title": "Design Patterns Enforcement"
},
"plan_approved_at": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Timestamp when plan was approved by judge_coding_plan (None=not approved)",
"title": "Plan Approved At"
},
"plan_rejection_count": {
"default": 0,
"description": "Number of times the plan has been rejected (max 1 allowed)",
"title": "Plan Rejection Count",
"type": "integer"
},
"code_approved_files": {
"additionalProperties": {
"type": "integer"
},
"description": "Dictionary mapping file paths to approval timestamps from judge_code_change",
"title": "Code Approved Files",
"type": "object"
},
"testing_approved_at": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Timestamp when testing was approved by judge_testing_implementation (None=not approved)",
"title": "Testing Approved At"
},
"all_approvals_validated": {
"default": false,
"description": "Whether all required approvals (plan, code, testing) have been validated",
"title": "All Approvals Validated",
"type": "boolean"
}
},
"required": [
"title",
"description",
"task_size"
],
"title": "TaskMetadata",
"type": "object"
},
"TaskSize": {
"description": "Task size classification for workflow optimization.\n\nSizes are based on estimated complexity and time requirements:\n- XS: Extra Small - Simple fixes, typos, minor config changes (< 30 minutes)\n- S: Small - Minor features, simple refactoring (30 minutes - 2 hours)\n- M: Medium - Standard features, moderate complexity (2-8 hours) - DEFAULT\n- L: Large - Complex features, multiple components (1-3 days)\n- XL: Extra Large - Major system changes, architectural updates (3+ days)\n\nThis classification determines planning complexity and validation depth:\n- XS/S: Basic planning requirements, streamlined validation\n- M: Standard planning and validation\n- L/XL: Comprehensive planning with enhanced validation (library plans, risk assessment, design patterns)\n\nAll tasks follow the unified workflow: CREATED \u2192 PLANNING \u2192 PLAN_APPROVED \u2192 IMPLEMENTING \u2192 REVIEW_READY \u2192 TESTING \u2192 COMPLETED",
"enum": [
"xs",
"s",
"m",
"l",
"xl"
],
"title": "TaskSize",
"type": "string"
},
"TaskState": {
"description": "Coding task state enum with well-documented transitions.\n\nState Transitions:\n- CREATED \u2192 PLANNING: Task created, ready for planning phase (XS/S may skip to IMPLEMENTING)\n- PLANNING \u2192 PLAN_PENDING_APPROVAL: Plan created, awaiting user approval\n- PLAN_PENDING_APPROVAL \u2192 PLANNING: User requests plan changes\n- PLAN_PENDING_APPROVAL \u2192 PLAN_APPROVED: User approves plan\n- PLAN_APPROVED \u2192 IMPLEMENTING: Implementation phase started\n- IMPLEMENTING \u2192 IMPLEMENTING: Multiple code changes during implementation\n- IMPLEMENTING \u2192 REVIEW_READY: Implementation complete, ready for code review\n- REVIEW_READY \u2192 TESTING: Code review approved, ready for testing validation\n- TESTING \u2192 TESTING: Multiple test iterations\n- TESTING \u2192 COMPLETED: All tests validated; task completed successfully\n- Any state \u2192 BLOCKED: Task blocked by external dependencies\n- Any state \u2192 CANCELLED: Task cancelled\n- BLOCKED \u2192 Previous state: Unblocked, return to previous state\n\nUsage:\n- CREATED: Default state for new tasks, all tasks proceed to planning (unified workflow)\n- PLANNING: Planning phase in progress (set when planning starts)\n- PLAN_PENDING_APPROVAL: Plan created, awaiting user approval and potential iteration\n- PLAN_APPROVED: Plan validated and approved (set by judge_coding_plan)\n- IMPLEMENTING: Implementation phase in progress (set when coding starts)\n- REVIEW_READY: Implementation complete and ready for code review\n- TESTING: Testing/validation phase after code review approval\n- COMPLETED: Task completed successfully (set by judge_coding_task_completion)\n- BLOCKED: Task blocked by external dependencies (manual override)\n- CANCELLED: Task cancelled (manual override)",
"enum": [
"created",
"planning",
"plan_pending_approval",
"plan_approved",
"implementing",
"testing",
"review_ready",
"completed",
"blocked",
"cancelled"
],
"title": "TaskState",
"type": "string"
},
"WorkflowGuidance": {
"description": "Canonical workflow guidance model used across the system.\n\nReturned by tools to provide consistent next steps and instructions for\nthe coding assistant. This is the single source of truth for the\nWorkflowGuidance schema.",
"properties": {
"next_tool": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Next tool to call, or None if workflow complete",
"title": "Next Tool"
},
"reasoning": {
"default": "",
"description": "Clear explanation of why this tool should be used next",
"title": "Reasoning",
"type": "string"
},
"preparation_needed": {
"description": "List of things that need to be prepared before calling the recommended tool",
"items": {
"type": "string"
},
"title": "Preparation Needed",
"type": "array"
},
"guidance": {
"default": "",
"description": "Detailed step-by-step guidance for the AI assistant",
"title": "Guidance",
"type": "string"
},
"research_required": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether research is required for this task (only determined for new CREATED tasks)",
"title": "Research Required"
},
"research_scope": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Research scope: 'none', 'light', or 'deep' (only determined for new CREATED tasks)",
"title": "Research Scope"
},
"research_rationale": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Explanation of research requirements (only determined for new CREATED tasks)",
"title": "Research Rationale"
},
"internal_research_required": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether internal codebase analysis is needed (only determined for new CREATED tasks)",
"title": "Internal Research Required"
},
"risk_assessment_required": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether risk assessment is needed (only determined for new CREATED tasks)",
"title": "Risk Assessment Required"
},
"design_patterns_enforcement": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether design patterns are required (only determined for new CREATED tasks)",
"title": "Design Patterns Enforcement"
},
"plan_required_fields": {
"description": "Structured specification of required fields for judge_coding_plan tool",
"items": {
"$ref": "#/$defs/PlanRequiredField"
},
"title": "Plan Required Fields",
"type": "array"
}
},
"title": "WorkflowGuidance",
"type": "object"
}
},
"properties": {
"approved": {
"description": "Whether the validation passed",
"title": "Approved",
"type": "boolean"
},
"required_improvements": {
"description": "List of required improvements if not approved",
"items": {
"type": "string"
},
"title": "Required Improvements",
"type": "array"
},
"feedback": {
"description": "Detailed feedback about the validation",
"title": "Feedback",
"type": "string"
},
"suggested_diff": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Unified Git diff patch with suggested changes (optional). Provide when rejecting with concrete fixes or when proposing minor refinements.",
"title": "Suggested Diff"
},
"reviewed_files": {
"description": "Per-file reviews. Must include an entry for every file changed in the diff.",
"items": {
"$ref": "#/$defs/FileReview"
},
"title": "Reviewed Files",
"type": "array"
},
"current_task_metadata": {
"$ref": "#/$defs/TaskMetadata",
"description": "ALWAYS current state of task metadata after operation"
},
"workflow_guidance": {
"anyOf": [
{
"$ref": "#/$defs/WorkflowGuidance"
},
{
"type": "null"
}
],
"default": null,
"description": "LLM-generated next steps and instructions from shared method"
}
},
"required": [
"approved",
"feedback"
],
"title": "JudgeResponse",
"type": "object"
}Follow workflow_guidance.next_tool for the next step. Use the exact task_id from set_coding_task; recover via get_current_coding_task if missing.
Plans missing a library selection map and internal reuse map will be rejected.
| Name | Required | Description | Default |
|---|---|---|---|
| plan | Yes | ||
| design | Yes | ||
| context | No | ||
| task_id | No | ||
| research | Yes | ||
| library_plan | No | ||
| research_urls | Yes | ||
| problem_domain | No | ||
| design_patterns | No | ||
| identified_risks | No | ||
| problem_non_goals | No | ||
| user_requirements | No | ||
| internal_reuse_components | No | ||
| risk_mitigation_strategies | No |
| Name | Required | Description |
|---|---|---|
| approved | Yes | Whether the validation passed |
| feedback | Yes | Detailed feedback about the validation |
| reviewed_files | No | Per-file reviews. Must include an entry for every file changed in the diff. |
| suggested_diff | No | Unified Git diff patch with suggested changes (optional). Provide when rejecting with concrete fixes or when proposing minor refinements. |
| workflow_guidance | No | LLM-generated next steps and instructions from shared method |
| current_task_metadata | No | ALWAYS current state of task metadata after operation |
| required_improvements | No | List of required improvements if not approved |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses important behavioral traits: skipping causes severe token inefficiency, exact identifiers must be recovered via get_current_coding_task, HITL tools should be called for ambiguity, and plans missing library/internal reuse maps will be rejected. It also notes server auto-seeds sensible risk defaults. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured and front-loaded, but it embeds the entire JudgeResponse JSON schema (several hundred lines) plus duplicate notes, adding substantial redundancy beyond the separately provided output schema. It is not appropriately sized for a tool description.
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 14-parameter tool with workflow dependencies, the description covers prerequisites, HITL routing, parameter semantics, return schema, and rejection criteria. It also provides the trigger condition and final warning about required maps, making it complete for agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the Args section explains every parameter's purpose, requiredness/defaults, and complex object shapes such as library_plan and internal_reuse_components. It also adds conditional requirements (e.g., design_patterns_enforcement). Minor inconsistency: description marks research/research_urls optional while schema says required, and task_id required while schema has default empty.
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 opens with 'Validate a proposed plan and design against requirements, research needs, and risks,' a specific verb+resource that clearly distinguishes it from sibling tools like judge_code_change and judge_testing_implementation. The name and description align well.
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?
Explicitly states the trigger condition: 'Called when workflow_guidance.next_tool == "judge_coding_plan".' It also provides exclusions: if foundational choices are ambiguous, call raise_missing_requirements first; if a fundamental choice is being changed, call raise_obstacle. Clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Final validation gate before declaring a task complete. Called when workflow_guidance.next_tool == "judge_coding_task_completion".
Skipping this tool causes severe token inefficiency and wasted iterations.
Always invoke this tool at the appropriate stage to avoid extreme token loss and redundant processing.
Do not rely on assistant memory for identifiers. Always pass the exact task_id and recover it via get_current_coding_task if missing.
Plan approved via judge_coding_plan, code approved via judge_code_change, tests approved via judge_testing_implementation
task_id: string — Task UUID (required)
completion_summary: string — Summary of implemented work (required)
requirements_met: list[string] — Requirements satisfied (required)
implementation_details: string — Key implementation details (required)
remaining_work: list[string] — Open items if any (optional)
quality_notes: string — Quality/standards notes (optional)
testing_status: string — Testing status summary (optional)
Response JSON schema (TaskCompletionResult):
{
"$defs": {
"LibraryPlanItem": {
"properties": {
"purpose": {
"description": "Non-domain concern or integration point this library addresses",
"title": "Purpose",
"type": "string"
},
"selection": {
"description": "Chosen library or internal utility (name and optional version)",
"title": "Selection",
"type": "string"
},
"source": {
"description": "Source of solution: 'internal' for repo utility, 'external' for well-known library, 'custom' for in-house code",
"title": "Source",
"type": "string"
},
"justification": {
"default": "",
"description": "One-line rationale for the selection and any trade-offs",
"title": "Justification",
"type": "string"
}
},
"required": [
"purpose",
"selection",
"source"
],
"title": "LibraryPlanItem",
"type": "object"
},
"PlanRequiredField": {
"description": "Specification for a required field in judge_coding_plan.",
"properties": {
"name": {
"description": "Field name in the judge_coding_plan tool",
"title": "Name",
"type": "string"
},
"type": {
"description": "Expected data type (string, list[str], list[dict], etc.)",
"title": "Type",
"type": "string"
},
"description": {
"description": "What this field should contain",
"title": "Description",
"type": "string"
},
"required": {
"description": "Whether this field is required",
"title": "Required",
"type": "boolean"
},
"conditional_on": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Task metadata field this requirement depends on (e.g., 'design_patterns_enforcement')",
"title": "Conditional On"
},
"example_value": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Example of what this field should contain",
"title": "Example Value"
}
},
"required": [
"name",
"type",
"description",
"required"
],
"title": "PlanRequiredField",
"type": "object"
},
"RequirementsVersion": {
"description": "A version of user requirements with timestamp and source.",
"properties": {
"content": {
"title": "Content",
"type": "string"
},
"source": {
"title": "Source",
"type": "string"
},
"timestamp": {
"title": "Timestamp",
"type": "integer"
}
},
"required": [
"content",
"source"
],
"title": "RequirementsVersion",
"type": "object"
},
"ResearchScope": {
"description": "Research scope enum for workflow-driven research validation.\n\nDetermines the depth and requirements for research validation:\n- NONE: No research required for this task complexity\n- LIGHT: Light research required (1+ authoritative domain source)\n- DEEP: Deep research required (2+ authoritative domain sources)",
"enum": [
"none",
"light",
"deep"
],
"title": "ResearchScope",
"type": "string"
},
"ReuseComponent": {
"properties": {
"path": {
"description": "Repository path to the reusable component",
"title": "Path",
"type": "string"
},
"purpose": {
"default": "",
"description": "What part of the task this component will support",
"title": "Purpose",
"type": "string"
},
"notes": {
"default": "",
"description": "Any integration notes or caveats",
"title": "Notes",
"type": "string"
}
},
"required": [
"path"
],
"title": "ReuseComponent",
"type": "object"
},
"TaskMetadata": {
"description": "Lightweight metadata for coding tasks that flows with memory layer.\n\nThis model serves as the foundation for the enhanced workflow v3 system,\nreplacing session-based tracking with task-centric approach.",
"properties": {
"task_id": {
"description": "IMMUTABLE: Auto-generated UUID, primary key for memory storage",
"title": "Task Id",
"type": "string"
},
"created_at": {
"description": "IMMUTABLE: Task creation timestamp (epoch seconds)",
"title": "Created At",
"type": "integer"
},
"title": {
"description": "Display title for coding task (updatable)",
"title": "Title",
"type": "string"
},
"description": {
"description": "Detailed coding task description (updatable)",
"title": "Description",
"type": "string"
},
"user_requirements": {
"default": "",
"description": "Current coding requirements (updatable)",
"title": "User Requirements",
"type": "string"
},
"state": {
"$ref": "#/$defs/TaskState",
"default": "created",
"description": "Current task state (updatable, follows TaskState transitions)"
},
"task_size": {
"$ref": "#/$defs/TaskSize",
"description": "Task size classification for workflow optimization (XS=simple fixes, S=minor features, M=standard, L=complex, XL=major changes)"
},
"user_requirements_history": {
"description": "History of requirements changes",
"items": {
"$ref": "#/$defs/RequirementsVersion"
},
"title": "User Requirements History",
"type": "array"
},
"accumulated_diff": {
"additionalProperties": true,
"description": "Code changes accumulated over time",
"title": "Accumulated Diff",
"type": "object"
},
"modified_files": {
"description": "List of file paths that were created or modified during task implementation",
"items": {
"type": "string"
},
"title": "Modified Files",
"type": "array"
},
"test_files": {
"description": "List of test file paths that were created during testing phase",
"items": {
"type": "string"
},
"title": "Test Files",
"type": "array"
},
"test_status": {
"additionalProperties": {
"type": "string"
},
"description": "Status of different test types (unit, integration, e2e, etc.)",
"title": "Test Status",
"type": "object"
},
"updated_at": {
"description": "Last update timestamp (epoch seconds)",
"title": "Updated At",
"type": "integer"
},
"tags": {
"description": "Coding-related tags",
"items": {
"type": "string"
},
"title": "Tags",
"type": "array"
},
"problem_domain": {
"default": "",
"description": "Concise statement of the problem domain and scope for this task",
"title": "Problem Domain",
"type": "string"
},
"problem_non_goals": {
"description": "Explicit non-goals/boundaries to prevent scope creep and re-solving commodity concerns",
"items": {
"type": "string"
},
"title": "Problem Non Goals",
"type": "array"
},
"library_plan": {
"description": "Planned libraries/utilities per purpose; prefer internal reuse and well-known libraries; custom code only with justification",
"items": {
"$ref": "#/$defs/LibraryPlanItem"
},
"title": "Library Plan",
"type": "array"
},
"internal_reuse_components": {
"description": "Existing repository components/utilities to reuse with paths and purposes",
"items": {
"$ref": "#/$defs/ReuseComponent"
},
"title": "Internal Reuse Components",
"type": "array"
},
"research_required": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether research is required by workflow guidance (None=undetermined, True=required, False=optional)",
"title": "Research Required"
},
"research_scope": {
"$ref": "#/$defs/ResearchScope",
"default": "none",
"description": "Research scope determined by workflow: none|light|deep"
},
"research_completed": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Epoch seconds when research validation passed",
"title": "Research Completed"
},
"research_rationale": {
"default": "",
"description": "Explanation of why research was required and how the scope was determined",
"title": "Research Rationale",
"type": "string"
},
"expected_url_count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "LLM-determined expected number of research URLs based on task complexity",
"title": "Expected Url Count"
},
"minimum_url_count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "LLM-determined minimum acceptable URL count for adequate research",
"title": "Minimum Url Count"
},
"url_requirement_reasoning": {
"default": "",
"description": "LLM-generated explanation of why specific URL count is needed for this task",
"title": "Url Requirement Reasoning",
"type": "string"
},
"research_complexity_analysis": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Detailed complexity analysis factors from LLM (domain, tech maturity, integration scope, etc.)",
"title": "Research Complexity Analysis"
},
"internal_research_required": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether internal codebase research is needed (None=undetermined, True=required, False=not needed)",
"title": "Internal Research Required"
},
"related_code_snippets": {
"description": "Related code snippets from the codebase that are relevant to this task",
"items": {
"type": "string"
},
"title": "Related Code Snippets",
"type": "array"
},
"risk_assessment_required": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether risk assessment is needed (None=undetermined, True=required, False=not needed)",
"title": "Risk Assessment Required"
},
"identified_risks": {
"description": "Areas that could be harmed by the proposed changes",
"items": {
"type": "string"
},
"title": "Identified Risks",
"type": "array"
},
"risk_mitigation_strategies": {
"description": "Strategies to mitigate identified risks",
"items": {
"type": "string"
},
"title": "Risk Mitigation Strategies",
"type": "array"
},
"design_patterns_enforcement": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether design patterns are required for this task (None=undetermined, True=required, False=not needed)",
"title": "Design Patterns Enforcement"
},
"plan_approved_at": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Timestamp when plan was approved by judge_coding_plan (None=not approved)",
"title": "Plan Approved At"
},
"plan_rejection_count": {
"default": 0,
"description": "Number of times the plan has been rejected (max 1 allowed)",
"title": "Plan Rejection Count",
"type": "integer"
},
"code_approved_files": {
"additionalProperties": {
"type": "integer"
},
"description": "Dictionary mapping file paths to approval timestamps from judge_code_change",
"title": "Code Approved Files",
"type": "object"
},
"testing_approved_at": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Timestamp when testing was approved by judge_testing_implementation (None=not approved)",
"title": "Testing Approved At"
},
"all_approvals_validated": {
"default": false,
"description": "Whether all required approvals (plan, code, testing) have been validated",
"title": "All Approvals Validated",
"type": "boolean"
}
},
"required": [
"title",
"description",
"task_size"
],
"title": "TaskMetadata",
"type": "object"
},
"TaskSize": {
"description": "Task size classification for workflow optimization.\n\nSizes are based on estimated complexity and time requirements:\n- XS: Extra Small - Simple fixes, typos, minor config changes (< 30 minutes)\n- S: Small - Minor features, simple refactoring (30 minutes - 2 hours)\n- M: Medium - Standard features, moderate complexity (2-8 hours) - DEFAULT\n- L: Large - Complex features, multiple components (1-3 days)\n- XL: Extra Large - Major system changes, architectural updates (3+ days)\n\nThis classification determines planning complexity and validation depth:\n- XS/S: Basic planning requirements, streamlined validation\n- M: Standard planning and validation\n- L/XL: Comprehensive planning with enhanced validation (library plans, risk assessment, design patterns)\n\nAll tasks follow the unified workflow: CREATED \u2192 PLANNING \u2192 PLAN_APPROVED \u2192 IMPLEMENTING \u2192 REVIEW_READY \u2192 TESTING \u2192 COMPLETED",
"enum": [
"xs",
"s",
"m",
"l",
"xl"
],
"title": "TaskSize",
"type": "string"
},
"TaskState": {
"description": "Coding task state enum with well-documented transitions.\n\nState Transitions:\n- CREATED \u2192 PLANNING: Task created, ready for planning phase (XS/S may skip to IMPLEMENTING)\n- PLANNING \u2192 PLAN_PENDING_APPROVAL: Plan created, awaiting user approval\n- PLAN_PENDING_APPROVAL \u2192 PLANNING: User requests plan changes\n- PLAN_PENDING_APPROVAL \u2192 PLAN_APPROVED: User approves plan\n- PLAN_APPROVED \u2192 IMPLEMENTING: Implementation phase started\n- IMPLEMENTING \u2192 IMPLEMENTING: Multiple code changes during implementation\n- IMPLEMENTING \u2192 REVIEW_READY: Implementation complete, ready for code review\n- REVIEW_READY \u2192 TESTING: Code review approved, ready for testing validation\n- TESTING \u2192 TESTING: Multiple test iterations\n- TESTING \u2192 COMPLETED: All tests validated; task completed successfully\n- Any state \u2192 BLOCKED: Task blocked by external dependencies\n- Any state \u2192 CANCELLED: Task cancelled\n- BLOCKED \u2192 Previous state: Unblocked, return to previous state\n\nUsage:\n- CREATED: Default state for new tasks, all tasks proceed to planning (unified workflow)\n- PLANNING: Planning phase in progress (set when planning starts)\n- PLAN_PENDING_APPROVAL: Plan created, awaiting user approval and potential iteration\n- PLAN_APPROVED: Plan validated and approved (set by judge_coding_plan)\n- IMPLEMENTING: Implementation phase in progress (set when coding starts)\n- REVIEW_READY: Implementation complete and ready for code review\n- TESTING: Testing/validation phase after code review approval\n- COMPLETED: Task completed successfully (set by judge_coding_task_completion)\n- BLOCKED: Task blocked by external dependencies (manual override)\n- CANCELLED: Task cancelled (manual override)",
"enum": [
"created",
"planning",
"plan_pending_approval",
"plan_approved",
"implementing",
"testing",
"review_ready",
"completed",
"blocked",
"cancelled"
],
"title": "TaskState",
"type": "string"
},
"WorkflowGuidance": {
"description": "Canonical workflow guidance model used across the system.\n\nReturned by tools to provide consistent next steps and instructions for\nthe coding assistant. This is the single source of truth for the\nWorkflowGuidance schema.",
"properties": {
"next_tool": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Next tool to call, or None if workflow complete",
"title": "Next Tool"
},
"reasoning": {
"default": "",
"description": "Clear explanation of why this tool should be used next",
"title": "Reasoning",
"type": "string"
},
"preparation_needed": {
"description": "List of things that need to be prepared before calling the recommended tool",
"items": {
"type": "string"
},
"title": "Preparation Needed",
"type": "array"
},
"guidance": {
"default": "",
"description": "Detailed step-by-step guidance for the AI assistant",
"title": "Guidance",
"type": "string"
},
"research_required": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether research is required for this task (only determined for new CREATED tasks)",
"title": "Research Required"
},
"research_scope": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Research scope: 'none', 'light', or 'deep' (only determined for new CREATED tasks)",
"title": "Research Scope"
},
"research_rationale": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Explanation of research requirements (only determined for new CREATED tasks)",
"title": "Research Rationale"
},
"internal_research_required": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether internal codebase analysis is needed (only determined for new CREATED tasks)",
"title": "Internal Research Required"
},
"risk_assessment_required": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether risk assessment is needed (only determined for new CREATED tasks)",
"title": "Risk Assessment Required"
},
"design_patterns_enforcement": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether design patterns are required (only determined for new CREATED tasks)",
"title": "Design Patterns Enforcement"
},
"plan_required_fields": {
"description": "Structured specification of required fields for judge_coding_plan tool",
"items": {
"$ref": "#/$defs/PlanRequiredField"
},
"title": "Plan Required Fields",
"type": "array"
}
},
"title": "WorkflowGuidance",
"type": "object"
}
},
"properties": {
"approved": {
"description": "Whether the task completion is approved",
"title": "Approved",
"type": "boolean"
},
"feedback": {
"description": "Detailed feedback about the completion validation",
"title": "Feedback",
"type": "string"
},
"required_improvements": {
"description": "List of required improvements if not approved",
"items": {
"type": "string"
},
"title": "Required Improvements",
"type": "array"
},
"current_task_metadata": {
"$ref": "#/$defs/TaskMetadata",
"description": "ALWAYS current state of task metadata after operation"
},
"workflow_guidance": {
"$ref": "#/$defs/WorkflowGuidance",
"description": "LLM-generated next steps and instructions (or workflow complete)"
}
},
"required": [
"approved",
"feedback",
"current_task_metadata",
"workflow_guidance"
],
"title": "TaskCompletionResult",
"type": "object"
}The AI coding assistant MUST NOT present or claim task completion, or provide a final completion summary to the user, without successfully calling this tool and receiving approval.
Always use the exact task_id; if missing due to memory limits, recover it via get_current_coding_task.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | ||
| quality_notes | No | ||
| remaining_work | No | ||
| testing_status | No | ||
| requirements_met | Yes | ||
| completion_summary | Yes | ||
| implementation_details | Yes |
| Name | Required | Description |
|---|---|---|
| approved | Yes | Whether the task completion is approved |
| feedback | Yes | Detailed feedback about the completion validation |
| workflow_guidance | Yes | LLM-generated next steps and instructions (or workflow complete) |
| current_task_metadata | Yes | ALWAYS current state of task metadata after operation |
| required_improvements | No | List of required improvements if not approved |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses that this is a mandatory final gate, warns that skipping causes severe token inefficiency, forbids claiming completion without receiving approval, and instructs recovering task_id via get_current_coding_task if missing. It does not explicitly discuss permissions or side effects, but the embedded output schema indicates current_task_metadata is returned after the 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 well-organized with clear headings and front-loads the purpose, but it is lengthy because it embeds the full TaskCompletionResult JSON schema and repeats the task_id recovery instruction in both the warning section and Notes. The redundancy and schema dump make it less concise than ideal, though the structure remains navigable.
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 complex final-validation tool, the description covers the call condition, prerequisites, argument meanings, and explicit constraints around claiming completion. The rich output schema fills in return-value semantics, so the description is sufficiently complete, though it does not spell out the post-approval workflow or rejection handling in prose.
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% description coverage, but the Args section provides a one-line semantic description for every parameter, e.g., task_id as 'Task UUID', requirements_met as 'Requirements satisfied', and implementation_details as 'Key implementation details'. This fully compensates for the sparse schema, though the descriptions are terse and lack examples or formatting 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 opens with 'Final validation gate before declaring a task complete', which clearly states the tool's verb, resource, and phase. It also distinguishes this tool from sibling judges by specifying it is called when workflow_guidance.next_tool equals the tool name and by listing prior approvals from judge_coding_plan, judge_code_change, and judge_testing_implementation as prerequisites.
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 an explicit call condition (`workflow_guidance.next_tool == "judge_coding_task_completion"`), lists prerequisites from sibling tools, and includes a 'Critical Tool Warning' that this tool must always be invoked at the appropriate stage. It does not explicitly state when not to use it or name an alternative for this final validation step, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate test quality, coverage, and execution results after code review is approved. The input MUST include real test evidence (raw test runner output and list of test files). Called when workflow_guidance.next_tool == "judge_testing_implementation".
Skipping this tool causes severe token inefficiency and wasted iterations.
Always invoke this tool at the appropriate stage to avoid extreme token loss and redundant processing.
Do not rely on assistant memory for identifiers. Always pass the exact task_id and recover it via get_current_coding_task if missing.
task_id: string — Task UUID (required)
test_summary: string — Summary of the implemented tests (required)
test_files: list[string] — Paths to created/modified test files (required)
test_execution_results: string — Raw test runner output (required). For example, pytest/jest/mocha/go test/JUnit logs including pass/fail counts.
test_coverage_report: string — Coverage details (optional)
test_types_implemented: list[string] — e.g., unit, integration, e2e (optional)
testing_framework: string — e.g., pytest, jest (optional)
performance_test_results: string — Performance results (optional)
manual_test_notes: string — Manual testing notes (optional)
Response JSON schema (JudgeResponse):
{
"$defs": {
"FileReview": {
"properties": {
"path": {
"description": "File path reviewed",
"title": "Path",
"type": "string"
},
"feedback": {
"description": "Per-file feedback summary",
"title": "Feedback",
"type": "string"
},
"approved": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional per-file approval or risk flag",
"title": "Approved"
}
},
"required": [
"path",
"feedback"
],
"title": "FileReview",
"type": "object"
},
"LibraryPlanItem": {
"properties": {
"purpose": {
"description": "Non-domain concern or integration point this library addresses",
"title": "Purpose",
"type": "string"
},
"selection": {
"description": "Chosen library or internal utility (name and optional version)",
"title": "Selection",
"type": "string"
},
"source": {
"description": "Source of solution: 'internal' for repo utility, 'external' for well-known library, 'custom' for in-house code",
"title": "Source",
"type": "string"
},
"justification": {
"default": "",
"description": "One-line rationale for the selection and any trade-offs",
"title": "Justification",
"type": "string"
}
},
"required": [
"purpose",
"selection",
"source"
],
"title": "LibraryPlanItem",
"type": "object"
},
"PlanRequiredField": {
"description": "Specification for a required field in judge_coding_plan.",
"properties": {
"name": {
"description": "Field name in the judge_coding_plan tool",
"title": "Name",
"type": "string"
},
"type": {
"description": "Expected data type (string, list[str], list[dict], etc.)",
"title": "Type",
"type": "string"
},
"description": {
"description": "What this field should contain",
"title": "Description",
"type": "string"
},
"required": {
"description": "Whether this field is required",
"title": "Required",
"type": "boolean"
},
"conditional_on": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Task metadata field this requirement depends on (e.g., 'design_patterns_enforcement')",
"title": "Conditional On"
},
"example_value": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Example of what this field should contain",
"title": "Example Value"
}
},
"required": [
"name",
"type",
"description",
"required"
],
"title": "PlanRequiredField",
"type": "object"
},
"RequirementsVersion": {
"description": "A version of user requirements with timestamp and source.",
"properties": {
"content": {
"title": "Content",
"type": "string"
},
"source": {
"title": "Source",
"type": "string"
},
"timestamp": {
"title": "Timestamp",
"type": "integer"
}
},
"required": [
"content",
"source"
],
"title": "RequirementsVersion",
"type": "object"
},
"ResearchScope": {
"description": "Research scope enum for workflow-driven research validation.\n\nDetermines the depth and requirements for research validation:\n- NONE: No research required for this task complexity\n- LIGHT: Light research required (1+ authoritative domain source)\n- DEEP: Deep research required (2+ authoritative domain sources)",
"enum": [
"none",
"light",
"deep"
],
"title": "ResearchScope",
"type": "string"
},
"ReuseComponent": {
"properties": {
"path": {
"description": "Repository path to the reusable component",
"title": "Path",
"type": "string"
},
"purpose": {
"default": "",
"description": "What part of the task this component will support",
"title": "Purpose",
"type": "string"
},
"notes": {
"default": "",
"description": "Any integration notes or caveats",
"title": "Notes",
"type": "string"
}
},
"required": [
"path"
],
"title": "ReuseComponent",
"type": "object"
},
"TaskMetadata": {
"description": "Lightweight metadata for coding tasks that flows with memory layer.\n\nThis model serves as the foundation for the enhanced workflow v3 system,\nreplacing session-based tracking with task-centric approach.",
"properties": {
"task_id": {
"description": "IMMUTABLE: Auto-generated UUID, primary key for memory storage",
"title": "Task Id",
"type": "string"
},
"created_at": {
"description": "IMMUTABLE: Task creation timestamp (epoch seconds)",
"title": "Created At",
"type": "integer"
},
"title": {
"description": "Display title for coding task (updatable)",
"title": "Title",
"type": "string"
},
"description": {
"description": "Detailed coding task description (updatable)",
"title": "Description",
"type": "string"
},
"user_requirements": {
"default": "",
"description": "Current coding requirements (updatable)",
"title": "User Requirements",
"type": "string"
},
"state": {
"$ref": "#/$defs/TaskState",
"default": "created",
"description": "Current task state (updatable, follows TaskState transitions)"
},
"task_size": {
"$ref": "#/$defs/TaskSize",
"description": "Task size classification for workflow optimization (XS=simple fixes, S=minor features, M=standard, L=complex, XL=major changes)"
},
"user_requirements_history": {
"description": "History of requirements changes",
"items": {
"$ref": "#/$defs/RequirementsVersion"
},
"title": "User Requirements History",
"type": "array"
},
"accumulated_diff": {
"additionalProperties": true,
"description": "Code changes accumulated over time",
"title": "Accumulated Diff",
"type": "object"
},
"modified_files": {
"description": "List of file paths that were created or modified during task implementation",
"items": {
"type": "string"
},
"title": "Modified Files",
"type": "array"
},
"test_files": {
"description": "List of test file paths that were created during testing phase",
"items": {
"type": "string"
},
"title": "Test Files",
"type": "array"
},
"test_status": {
"additionalProperties": {
"type": "string"
},
"description": "Status of different test types (unit, integration, e2e, etc.)",
"title": "Test Status",
"type": "object"
},
"updated_at": {
"description": "Last update timestamp (epoch seconds)",
"title": "Updated At",
"type": "integer"
},
"tags": {
"description": "Coding-related tags",
"items": {
"type": "string"
},
"title": "Tags",
"type": "array"
},
"problem_domain": {
"default": "",
"description": "Concise statement of the problem domain and scope for this task",
"title": "Problem Domain",
"type": "string"
},
"problem_non_goals": {
"description": "Explicit non-goals/boundaries to prevent scope creep and re-solving commodity concerns",
"items": {
"type": "string"
},
"title": "Problem Non Goals",
"type": "array"
},
"library_plan": {
"description": "Planned libraries/utilities per purpose; prefer internal reuse and well-known libraries; custom code only with justification",
"items": {
"$ref": "#/$defs/LibraryPlanItem"
},
"title": "Library Plan",
"type": "array"
},
"internal_reuse_components": {
"description": "Existing repository components/utilities to reuse with paths and purposes",
"items": {
"$ref": "#/$defs/ReuseComponent"
},
"title": "Internal Reuse Components",
"type": "array"
},
"research_required": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether research is required by workflow guidance (None=undetermined, True=required, False=optional)",
"title": "Research Required"
},
"research_scope": {
"$ref": "#/$defs/ResearchScope",
"default": "none",
"description": "Research scope determined by workflow: none|light|deep"
},
"research_completed": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Epoch seconds when research validation passed",
"title": "Research Completed"
},
"research_rationale": {
"default": "",
"description": "Explanation of why research was required and how the scope was determined",
"title": "Research Rationale",
"type": "string"
},
"expected_url_count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "LLM-determined expected number of research URLs based on task complexity",
"title": "Expected Url Count"
},
"minimum_url_count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "LLM-determined minimum acceptable URL count for adequate research",
"title": "Minimum Url Count"
},
"url_requirement_reasoning": {
"default": "",
"description": "LLM-generated explanation of why specific URL count is needed for this task",
"title": "Url Requirement Reasoning",
"type": "string"
},
"research_complexity_analysis": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Detailed complexity analysis factors from LLM (domain, tech maturity, integration scope, etc.)",
"title": "Research Complexity Analysis"
},
"internal_research_required": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether internal codebase research is needed (None=undetermined, True=required, False=not needed)",
"title": "Internal Research Required"
},
"related_code_snippets": {
"description": "Related code snippets from the codebase that are relevant to this task",
"items": {
"type": "string"
},
"title": "Related Code Snippets",
"type": "array"
},
"risk_assessment_required": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether risk assessment is needed (None=undetermined, True=required, False=not needed)",
"title": "Risk Assessment Required"
},
"identified_risks": {
"description": "Areas that could be harmed by the proposed changes",
"items": {
"type": "string"
},
"title": "Identified Risks",
"type": "array"
},
"risk_mitigation_strategies": {
"description": "Strategies to mitigate identified risks",
"items": {
"type": "string"
},
"title": "Risk Mitigation Strategies",
"type": "array"
},
"design_patterns_enforcement": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether design patterns are required for this task (None=undetermined, True=required, False=not needed)",
"title": "Design Patterns Enforcement"
},
"plan_approved_at": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Timestamp when plan was approved by judge_coding_plan (None=not approved)",
"title": "Plan Approved At"
},
"plan_rejection_count": {
"default": 0,
"description": "Number of times the plan has been rejected (max 1 allowed)",
"title": "Plan Rejection Count",
"type": "integer"
},
"code_approved_files": {
"additionalProperties": {
"type": "integer"
},
"description": "Dictionary mapping file paths to approval timestamps from judge_code_change",
"title": "Code Approved Files",
"type": "object"
},
"testing_approved_at": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Timestamp when testing was approved by judge_testing_implementation (None=not approved)",
"title": "Testing Approved At"
},
"all_approvals_validated": {
"default": false,
"description": "Whether all required approvals (plan, code, testing) have been validated",
"title": "All Approvals Validated",
"type": "boolean"
}
},
"required": [
"title",
"description",
"task_size"
],
"title": "TaskMetadata",
"type": "object"
},
"TaskSize": {
"description": "Task size classification for workflow optimization.\n\nSizes are based on estimated complexity and time requirements:\n- XS: Extra Small - Simple fixes, typos, minor config changes (< 30 minutes)\n- S: Small - Minor features, simple refactoring (30 minutes - 2 hours)\n- M: Medium - Standard features, moderate complexity (2-8 hours) - DEFAULT\n- L: Large - Complex features, multiple components (1-3 days)\n- XL: Extra Large - Major system changes, architectural updates (3+ days)\n\nThis classification determines planning complexity and validation depth:\n- XS/S: Basic planning requirements, streamlined validation\n- M: Standard planning and validation\n- L/XL: Comprehensive planning with enhanced validation (library plans, risk assessment, design patterns)\n\nAll tasks follow the unified workflow: CREATED \u2192 PLANNING \u2192 PLAN_APPROVED \u2192 IMPLEMENTING \u2192 REVIEW_READY \u2192 TESTING \u2192 COMPLETED",
"enum": [
"xs",
"s",
"m",
"l",
"xl"
],
"title": "TaskSize",
"type": "string"
},
"TaskState": {
"description": "Coding task state enum with well-documented transitions.\n\nState Transitions:\n- CREATED \u2192 PLANNING: Task created, ready for planning phase (XS/S may skip to IMPLEMENTING)\n- PLANNING \u2192 PLAN_PENDING_APPROVAL: Plan created, awaiting user approval\n- PLAN_PENDING_APPROVAL \u2192 PLANNING: User requests plan changes\n- PLAN_PENDING_APPROVAL \u2192 PLAN_APPROVED: User approves plan\n- PLAN_APPROVED \u2192 IMPLEMENTING: Implementation phase started\n- IMPLEMENTING \u2192 IMPLEMENTING: Multiple code changes during implementation\n- IMPLEMENTING \u2192 REVIEW_READY: Implementation complete, ready for code review\n- REVIEW_READY \u2192 TESTING: Code review approved, ready for testing validation\n- TESTING \u2192 TESTING: Multiple test iterations\n- TESTING \u2192 COMPLETED: All tests validated; task completed successfully\n- Any state \u2192 BLOCKED: Task blocked by external dependencies\n- Any state \u2192 CANCELLED: Task cancelled\n- BLOCKED \u2192 Previous state: Unblocked, return to previous state\n\nUsage:\n- CREATED: Default state for new tasks, all tasks proceed to planning (unified workflow)\n- PLANNING: Planning phase in progress (set when planning starts)\n- PLAN_PENDING_APPROVAL: Plan created, awaiting user approval and potential iteration\n- PLAN_APPROVED: Plan validated and approved (set by judge_coding_plan)\n- IMPLEMENTING: Implementation phase in progress (set when coding starts)\n- REVIEW_READY: Implementation complete and ready for code review\n- TESTING: Testing/validation phase after code review approval\n- COMPLETED: Task completed successfully (set by judge_coding_task_completion)\n- BLOCKED: Task blocked by external dependencies (manual override)\n- CANCELLED: Task cancelled (manual override)",
"enum": [
"created",
"planning",
"plan_pending_approval",
"plan_approved",
"implementing",
"testing",
"review_ready",
"completed",
"blocked",
"cancelled"
],
"title": "TaskState",
"type": "string"
},
"WorkflowGuidance": {
"description": "Canonical workflow guidance model used across the system.\n\nReturned by tools to provide consistent next steps and instructions for\nthe coding assistant. This is the single source of truth for the\nWorkflowGuidance schema.",
"properties": {
"next_tool": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Next tool to call, or None if workflow complete",
"title": "Next Tool"
},
"reasoning": {
"default": "",
"description": "Clear explanation of why this tool should be used next",
"title": "Reasoning",
"type": "string"
},
"preparation_needed": {
"description": "List of things that need to be prepared before calling the recommended tool",
"items": {
"type": "string"
},
"title": "Preparation Needed",
"type": "array"
},
"guidance": {
"default": "",
"description": "Detailed step-by-step guidance for the AI assistant",
"title": "Guidance",
"type": "string"
},
"research_required": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether research is required for this task (only determined for new CREATED tasks)",
"title": "Research Required"
},
"research_scope": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Research scope: 'none', 'light', or 'deep' (only determined for new CREATED tasks)",
"title": "Research Scope"
},
"research_rationale": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Explanation of research requirements (only determined for new CREATED tasks)",
"title": "Research Rationale"
},
"internal_research_required": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether internal codebase analysis is needed (only determined for new CREATED tasks)",
"title": "Internal Research Required"
},
"risk_assessment_required": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether risk assessment is needed (only determined for new CREATED tasks)",
"title": "Risk Assessment Required"
},
"design_patterns_enforcement": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether design patterns are required (only determined for new CREATED tasks)",
"title": "Design Patterns Enforcement"
},
"plan_required_fields": {
"description": "Structured specification of required fields for judge_coding_plan tool",
"items": {
"$ref": "#/$defs/PlanRequiredField"
},
"title": "Plan Required Fields",
"type": "array"
}
},
"title": "WorkflowGuidance",
"type": "object"
}
},
"properties": {
"approved": {
"description": "Whether the validation passed",
"title": "Approved",
"type": "boolean"
},
"required_improvements": {
"description": "List of required improvements if not approved",
"items": {
"type": "string"
},
"title": "Required Improvements",
"type": "array"
},
"feedback": {
"description": "Detailed feedback about the validation",
"title": "Feedback",
"type": "string"
},
"suggested_diff": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Unified Git diff patch with suggested changes (optional). Provide when rejecting with concrete fixes or when proposing minor refinements.",
"title": "Suggested Diff"
},
"reviewed_files": {
"description": "Per-file reviews. Must include an entry for every file changed in the diff.",
"items": {
"$ref": "#/$defs/FileReview"
},
"title": "Reviewed Files",
"type": "array"
},
"current_task_metadata": {
"$ref": "#/$defs/TaskMetadata",
"description": "ALWAYS current state of task metadata after operation"
},
"workflow_guidance": {
"anyOf": [
{
"$ref": "#/$defs/WorkflowGuidance"
},
{
"type": "null"
}
],
"default": null,
"description": "LLM-generated next steps and instructions from shared method"
}
},
"required": [
"approved",
"feedback"
],
"title": "JudgeResponse",
"type": "object"
}Use after judge_code_change is approved. Follow workflow_guidance.next_tool for the next step.
Always use the exact task_id; recover it via get_current_coding_task if missing.
If test_files is empty or test_execution_results does not look like raw runner output, this tool will return approved: false and request real evidence (copy/paste the test run output and list the test files).
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | ||
| test_files | Yes | ||
| test_summary | Yes | ||
| manual_test_notes | No | ||
| testing_framework | No | ||
| test_coverage_report | No | ||
| test_execution_results | Yes | ||
| test_types_implemented | No | ||
| performance_test_results | No |
| Name | Required | Description |
|---|---|---|
| approved | Yes | Whether the validation passed |
| feedback | Yes | Detailed feedback about the validation |
| reviewed_files | No | Per-file reviews. Must include an entry for every file changed in the diff. |
| suggested_diff | No | Unified Git diff patch with suggested changes (optional). Provide when rejecting with concrete fixes or when proposing minor refinements. |
| workflow_guidance | No | LLM-generated next steps and instructions from shared method |
| current_task_metadata | No | ALWAYS current state of task metadata after operation |
| required_improvements | No | List of required improvements if not approved |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full transparency burden and does disclose important behaviors: it requires real test evidence, returns approved:false when evidence is missing, and warns about token inefficiency if skipped. It does not explicitly describe side effects on task metadata, though the embedded response schema implies current_task_metadata is updated.
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 prose is organized and front-loaded, but the description is severely bloated by embedding the entire JudgeResponse JSON schema in the Returns section even though an output schema is already provided. Critical warnings and task_id guidance are also repeated across sections, making the description longer than 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?
For a high-complexity tool with 9 parameters and a rich output schema, the description is complete: it covers when to call it, prerequisites, required evidence, parameter semantics, failure behavior, and task_id recovery. The embedded output schema is redundant but does not leave the agent without needed 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 bare input schema has 0% description coverage, but the description's Args section fully compensates by explaining each parameter's meaning and providing concrete examples, such as 'Raw test runner output (required). For example, pytest/jest/mocha/go test/JUnit logs including pass/fail counts.' This adds substantial value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Validate test quality, coverage, and execution results after code review is approved.' It also clearly distinguishes this from sibling judge tools by tying invocation to workflow_guidance.next_tool and to appearing after judge_code_change is approved.
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 gives an explicit trigger condition ('Called when workflow_guidance.next_tool == "judge_testing_implementation"'), states it must be used after judge_code_change is approved, and explains when the tool will reject input (empty test_files or non-raw test_execution_results). It also warns against skipping it and tells the agent to recover task_id via get_current_coding_task if missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | ||
| session_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all configured MCP server connections.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It states 'all configured' which clarifies scope (configuration vs. active connections) and implicitly indicates a read-only operation. However, it doesn't mention whether it includes credentials or status, but for a simple list operation this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no extraneous words. It front-loads the action and resource immediately, making it easy to parse and fully sufficient for the tool's simplicity.
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, the lack of parameters, and the presence of an output schema, the description is complete. It fully explains what the tool does, and the sibling tools provide enough context for an agent to select it appropriately.
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, so the baseline is 4. The description doesn't need to explain parameter meanings, and the schema is empty, which aligns perfectly. No additional semantic value is required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and clearly identifies the resource as 'all configured MCP server connections.' It distinguishes itself from sibling tools like 'connect_mcp_server' and 'list_mcp_tools' by focusing on listing configured connections rather than managing or inspecting 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 explicit guidance is given on when to use this tool versus alternatives such as 'list_mcp_tools' or 'connect_mcp_server.' While the purpose is clear, the description doesn't mention related tools or provide context on when this is the preferred choice, so usage is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List available tools on a connected MCP server.
| Name | Required | Description | Default |
|---|---|---|---|
| server_name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states the basic listing action and does not disclose potential side effects (though likely none), error behavior, authentication needs, or what 'connected' implies. This is a minimal disclosure that adds little beyond the tool's name.
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 filler, making it concise and easy to parse. However, it is slightly under-specified for a 0%-coverage schema, so it does not fully earn the top score.
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 one parameter and an output schema (which likely lists return values), the description is a minimum viable summary. It lacks contextual details about prerequisites (e.g., server must be connected) and error cases, but for a simple listing tool, this may be acceptable.
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 0%, and the description does not explicitly reference the server_name parameter or add meaning beyond the schema. The phrase 'connected MCP server' hints at the parameter but does not explain requiredness, format, or how to identify valid server names. The description fails to compensate for the lack of 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 tool's function with a specific verb ('List') and resource ('tools on a connected MCP server'). It distinguishes itself from sibling tools like list_mcp_servers (which lists servers) and call_mcp_tool (which calls a tool), making its 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?
Usage context is implied: use this tool when you need to see what tools are available on a particular connected MCP server. However, it does not explicitly mention alternatives (e.g., list_mcp_servers) or provide exclusions or prerequisites, leaving the agent to infer when this is the right choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Log an event to a session.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | ||
| details | No | ||
| message | Yes | ||
| session_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations to rely on, the description carries the full burden of disclosing behavior. It only states the action without mentioning side effects, whether an active session is required, or what the output contains, leaving significant ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words, which is concise. However, it is so under-specified that it borders on being unhelpful, offering little more than a restatement of the tool's name.
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 and an output schema, but the description lacks crucial context such as valid kind values, required session state, or expected details structure. An agent would struggle to invoke this tool correctly based solely on the description.
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 0%, and the description does not explain the meaning of session_id, kind, message, or details beyond the generic action. The property names provide some clues, but the description fails to compensate for the lack of schema details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb 'log' and a resource 'event to a session', clearly conveying the core action. It distinguishes itself from sibling tools that focus on coding, memory, or management tasks, though it could be more specific about what constitutes an event.
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, such as start_session or other session-related tools. The description lacks any context about prerequisites or suitable use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a document or entire namespace from memory.
| Name | Required | Description | Default |
|---|---|---|---|
| doc_id | No | ||
| namespace | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 explicitly says 'Delete', which conveys destructive intent, but it does not disclose whether namespace deletion also removes contained documents, irreversibility, or any side effects. The core action is clear but additional behavioral context is missing.
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 states the action and scope efficiently. No filler or redundant information; every word contributes to 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?
The tool is a destructive mutation with no annotations, and the description is minimal. It does not mention the effect of deleting a namespace on its contents, irreversibility, or any requirements. An output schema exists, so return values are covered, but for a delete operation the description lacks important safety and effect details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no descriptions (0% coverage), but the description compensates by explaining the two modes: deleting a document (doc_id) or an entire namespace (namespace). The word 'or' clarifies the relationship between doc_id and namespace, which adds meaning beyond the raw schema structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Delete' and clearly identifies two resources: a document or an entire namespace. It is immediately clear what the tool does and how it distinguishes from siblings like memory_search or memory_index.
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 given about when to use this tool versus alternatives. It does not mention prerequisites, when deletion of a namespace is appropriate, or when other memory tools should be preferred. The description only states the action without contextual advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Index texts into the local memory store using embeddings.
| Name | Required | Description | Default |
|---|---|---|---|
| texts | Yes | ||
| doc_ids | No | ||
| metadatas | No | ||
| namespace | Yes | ||
| session_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits, but it only mentions the action and embedding mechanism. It does not state whether the operation is a write, whether existing texts are replaced or appended, whether the operation is idempotent, any permission requirements, or the return/response format. This is a major transparency gap 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?
The description is concise and front-loaded, but it is under-specified. For a tool with five parameters and no annotations, this single sentence does not provide enough information to be considered effective. It is minimal to the point of being unhelpful.
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 (5 parameters, no annotations) and the existence of an output schema, the description should at least outline the indexing behavior and parameter roles. It does not, making the tool effectively unusable without relying on external knowledge or guessing.
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 0%, and the description does not explain the parameters at all. Beyond the implicit 'texts' and 'namespace', optional parameters like doc_ids, metadatas, and session_id are completely undocumented, leaving the agent to guess their meaning and usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool's purpose with a specific verb ('index'), a resource ('local memory store'), and a method ('using embeddings'). It clearly differentiates from sibling tools like memory_search and memory_delete, but does not explicitly contrast with configuration tools like configure_memory, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidelines are provided. The description does not specify when this tool should be used over alternatives, nor does it mention any prerequisites, exclusions, or typical scenarios. The only implied guidance is that this is for adding texts to memory.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search memory with embeddings and optional reranking.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| top_k | No | ||
| rerank | No | ||
| namespace | Yes | ||
| session_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It reveals that the search uses embeddings and optional reranking, which hints at the underlying methodology, but it does not state whether the operation is read-only, what it returns, or any side effects. This leaves significant behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that gets directly to the point. It is perfectly front-loaded with the verb 'Search' and includes no filler. Every word contributes to conveying the core action and its optional features.
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?
Although an output schema exists, which somewhat relieves the need to describe return values, the description is still inadequate for a tool with five parameters, two required and no annotations. It does not clarify the relationship between namespace and session_id, nor does it explain how the search handles different namespaces or session contexts. The description leaves too many contextual gaps for an agent to use the tool confidently.
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 0%, so the description must compensate, but it only mentions 'embeddings' and 'optional reranking.' The reranking reference is essentially the same as the rerank boolean parameter, adding no new meaning. The description fails to explain the purpose or format of via parameters such as namespace, top_k, and session_id, leaving much of the parameter semantics undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: searching memory, with a specific method (embeddings) and an optional feature (reranking). It distinguishes itself from sibling tools like memory_delete and memory_index, which are clearly different operations. However, it lacks a defined scope or any details about the memory being searched.
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 specify when to use this tool versus alternatives, nor does it mention any context in which this search should be invoked. It only states the action, leaving the agent without guidance on selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Elicit missing requirements and clarifications from the user when details are insufficient for implementation.
current_request: string — Current understanding of the user’s request
identified_gaps: list[string] — Missing requirement gaps
specific_questions: list[string] — Targeted questions to clarify gaps
decision_areas (optional): list[string] — Fundamental decisions to confirm (e.g., database, framework, ui_type, app_type, api_style, auth, hosting)
options (optional): list[string] — Candidate options to present with pros/cons
constraints (optional): list[string] — Known constraints or non-negotiables
string: summary text of clarified requirements and context from the user
| Name | Required | Description | Default |
|---|---|---|---|
| options | No | ||
| task_id | Yes | ||
| constraints | No | ||
| decision_areas | No | ||
| current_request | Yes | ||
| identified_gaps | Yes | ||
| specific_questions | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the transparency burden. It describes the interaction style ('elicit... from the user') and the return value, but doesn't disclose any side effects, prerequisites (e.g., needing a task_id), or whether it blocks for user input. The omission of task_id in the Args section also reduces 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 well-structured with a purpose statement, argument list, and return description. It is about the right length and each section adds value, though the markdown formatting is slightly irregular with inconsistent indentation.
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 covers the tool's purpose, parameters (mostly), and return value, but misses the required task_id and doesn't explain how the tool integrates with the broader workflow (e.g., when to use versus raise_obstacle). The lack of annotation context also leaves the tool's behavior partially 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 schema has no descriptions (0% coverage), so the description must explain all parameters. It provides helpful explanations for current_request, identified_gaps, specific_questions, decision_areas, options, and constraints, but completely omits task_id, which is required. This is a significant gap that could lead the agent to omit a required argument.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Elicit missing requirements and clarifications from the user when details are insufficient for implementation.' This is a specific verb+resource and distinguishes it from sibling tools like raise_obstacle or request_plan_approval, though it doesn't explicitly name alternatives.
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 a clear usage context: 'when details are insufficient for implementation.' This tells the agent when to invoke it, but it doesn't explicitly exclude alternatives or name sibling tools, so it lacks explicit when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Involve the user to resolve blockers or conflicts by presenting options and context.
problem: string — Clear description of the obstacle
research: string — What has been investigated (alternatives, prior art)
options: list[string] — Possible approaches or next steps
decision_area (optional): string — Name of the decision area involved (e.g., database, framework)
constraints (optional): list[string] — Known constraints or non-negotiables
string: user's decision and any additional context for proceeding
| Name | Required | Description | Default |
|---|---|---|---|
| options | Yes | ||
| problem | Yes | ||
| task_id | No | ||
| research | Yes | ||
| constraints | No | ||
| decision_area | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description conveys the general behavior (presenting options and context to the user) and return value, but does not disclose important traits such as whether the call blocks execution, waits for user response, or has side effects. With no annotations, additional behavioral context would be valuable.
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 well-organized with clear sections (Description, Args, Returns) and is concise. The only structural flaw is the nested indentation that ambiguously places decision_area and constraints under options rather than as top-level args, which slightly hurts readability.
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 covers purpose, most parameters, and return value, but misses the task_id parameter and does not clarify interaction behavior (e.g., blocking, waiting for user). This is adequate but incomplete for a tool with 6 parameters, no annotations, and an output schema that merely specifies a string.
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 meaningful definitions for 5 of 6 parameters (problem, research, options, decision_area, constraints), filling the gap left by the schema's lack of descriptions. However, the task_id parameter is completely omitted, preventing 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 tool's purpose with a specific verb ('Involve the user') and resource ('resolve blockers or conflicts'). It distinguishes from siblings like raise_missing_requirements and request_plan_approval through the concept of 'obstacles', but does not explicitly name alternative tools or exclusions.
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 gives clear context for when to use the tool: when there are blockers or conflicts that require user involvement. However, it lacks explicit when-not-to-use guidance or comparisons with alternative tools, so it earns a 4 rather than a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scan and index local codebase.
| Name | Required | Description | Default |
|---|---|---|---|
| path_pattern | No | **/*.py |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must explain behavior on its own. It only states the action without disclosing side effects, such as whether it writes to an index, changes files, or requires specific 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 sentence with no waste, earning high marks for efficiency. However, it errs on the side of under-specification rather than describing necessary context, so it is not perfect.
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 an output schema, the description lacks essential behavioral and usage context. For a tool that presumably modifies an index, it should clarify side effects and when to invoke it. The minimalism leaves significant 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?
The tool description contains no parameter information. With 0% schema description coverage, the description does not compensate by explaining path_pattern or its default value, leaving parameter semantics entirely to 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 uses a specific verb ('scan') and resource ('local codebase'), clearly stating the tool's function. It distinguishes from sibling memory tools by focusing on the codebase, though it doesn't explicitly name alternatives.
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 about when to use this tool versus alternatives like memory_index. There is no mention of prerequisites, use cases, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Present a completed plan to the user for approval before proceeding to AI judge validation. This tool enables human-in-the-loop plan review and iterative refinement based on user feedback.
After creating a detailed implementation plan but before calling judge_coding_plan
When the task is in PLANNING state and a complete plan has been prepared
To enable user review and approval of plans before AI validation
Task must be in PLANNING state
Complete plan, design, and research must be prepared
Task metadata must exist (call set_coding_task first if needed)
plan: string — Detailed implementation plan with step-by-step approach (required)
design: string — Technical design and architecture decisions (required)
research: string — Research summary and findings (required)
task_id: string — Task UUID (required)
research_urls: list[string] — URLs from external research sources (optional)
problem_domain: string — Problem domain statement (optional)
problem_non_goals: list[string] — Non-goals and scope boundaries (optional)
library_plan: list[dict] — Library selection map with purpose, selection, source (optional)
internal_reuse_components: list[dict] — Internal components to reuse with paths (optional)
approved: boolean — Whether the user approved the plan
user_feedback: string — User's feedback or modification requests
next_action: string — Recommended next step based on user decision
The tool presents three options to the user:
Approve — Proceed with the plan as-is (transitions to PLAN_APPROVED state)
Modify — Request changes to the plan (returns to PLANNING state with feedback)
Reject — Start over with a different approach (returns to PLANNING state)
On Approval: Task remains in PLAN_PENDING_APPROVAL state, ready for judge_coding_plan AI validation
On Modification: Task returns to PLANNING state with user feedback integrated
On Rejection: Task returns to PLANNING state for complete plan revision
This tool uses the MCP elicitation system to present plans in a user-friendly format
User feedback is automatically integrated into task requirements for plan iteration
The tool maintains full audit trails of user decisions and feedback
Always use the exact task_id; recover it via get_current_coding_task if missing
| Name | Required | Description | Default |
|---|---|---|---|
| plan | Yes | ||
| design | Yes | ||
| task_id | Yes | ||
| research | Yes | ||
| library_plan | No | ||
| research_urls | No | ||
| problem_domain | No | ||
| problem_non_goals | No | ||
| internal_reuse_components | No |
| Name | Required | Description |
|---|---|---|
| approved | Yes | Whether the plan was approved |
| next_action | Yes | Next action to take based on user decision |
| user_feedback | No | User's feedback or modification requests |
| workflow_guidance | Yes | LLM-generated next steps and instructions from shared method |
| current_task_metadata | Yes | ALWAYS current state of task metadata after operation |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It thoroughly explains the user options (Approve/Modify/Reject), workflow state transitions, audit trails, and the elicitation system. This goes well beyond a basic mutation statement.
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 well-structured with clear sections (Description, When to use, Prerequisites, Args, Returns, etc.) and is appropriately front-loaded. It is long but avoids redundancy; each section earns its place for a complex human-in-the-loop 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?
The description is exceptionally complete for a tool with 9 parameters and an output schema. It explains return values, user options, workflow integration, state transitions, and prerequisites, making it fully actionable 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 description coverage is 0%, so the description compensates by listing all 9 parameters with brief definitions. While some definitions are somewhat tautological (e.g., 'research_urls: URLs from external research sources'), most add meaning beyond the raw schema, such as 'library_plan: Library selection map with purpose, selection, source'.
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 opens with a specific verb and resource: 'Present a completed plan to the user for approval before proceeding to AI judge validation.' This clearly states what the tool does and distinguishes it from sibling tools like judge_coding_plan, which handles AI validation.
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?
An explicit 'When to use' section lists exact conditions ('After creating a detailed implementation plan but before calling judge_coding_plan') and prerequisites. This clearly communicates when to use the tool versus alternatives, such as judge_coding_plan or set_coding_task.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Main brain chat tool with optional memory + workflow guidance.
| Name | Required | Description | Default |
|---|---|---|---|
| top_k | No | ||
| rerank | No | ||
| message | Yes | ||
| task_id | No | ||
| session_id | Yes | ||
| use_memory | No | ||
| system_prompt | No | ||
| brain_override | No | ||
| memory_namespace | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only mentions optional memory and workflow guidance, but does not disclose potential side effects, dependencies on session state, or whether it may trigger other tools. This is thin for a central orchestration tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single compact sentence with no wasted words. It front-loads the key identity as 'Main brain chat tool' and keeps optional features brief, earning every word.
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 9 parameters, no annotations, and a central orchestration role, a one-sentence description is insufficient. It doesn't explain the purpose of brain_override, how memory integration works, or what constitutes 'workflow guidance', leaving significant gaps for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so all parameter semantics must come from the description. The description vaguely hints at memory (use_memory, memory_namespace) and workflow (task_id), but it does not explain required parameters like session_id or message, nor does it clarify top_k, rerank, brain_override, or system_prompt. The compensation is minimal.
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 identifies the tool as the 'Main brain chat tool', establishing it as the primary conversational interface. It adds scope with 'optional memory + workflow guidance' which helps distinguish it from sibling tools like memory_search and agent_llm_request, though the verb is implicit rather than 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?
The phrase 'Main brain chat tool' implies it is the go-to tool for general chat, but there is no explicit guidance on when to use it versus alternatives like agent_llm_request or start_session. No when-not-to-use scenarios 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.
Create or update coding task metadata and receive dynamic workflow guidance. This is the mandatory entry point for any coding work.
Skipping this tool causes severe token inefficiency and wasted iterations.
Always invoke this tool at the appropriate stage to avoid extreme token loss and redundant processing.
Do not rely on assistant memory for identifiers. Always pass the exact task_id and recover it via get_current_coding_task if missing.
Any user request requiring logical code changes or creation of new files (new apps, features, refactors, bug fixes)
user_request: string — Original user request (required for new tasks)
task_title: string — Task title (required for new tasks)
task_description: string — Detailed description (required for new tasks)
task_size: enum — One of xs|s|m|l|xl (default m)
task_id: string — Task UUID when updating an existing task (optional)
user_requirements: string — Updated requirements (optional)
state: enum — Optional state transition when updating an existing task. Valid transitions are enforced (e.g., plan_approved → implementing).
tags: list[string] — Task tags (optional)
Response JSON schema (TaskAnalysisResult):
{
"$defs": {
"LibraryPlanItem": {
"properties": {
"purpose": {
"description": "Non-domain concern or integration point this library addresses",
"title": "Purpose",
"type": "string"
},
"selection": {
"description": "Chosen library or internal utility (name and optional version)",
"title": "Selection",
"type": "string"
},
"source": {
"description": "Source of solution: 'internal' for repo utility, 'external' for well-known library, 'custom' for in-house code",
"title": "Source",
"type": "string"
},
"justification": {
"default": "",
"description": "One-line rationale for the selection and any trade-offs",
"title": "Justification",
"type": "string"
}
},
"required": [
"purpose",
"selection",
"source"
],
"title": "LibraryPlanItem",
"type": "object"
},
"PlanRequiredField": {
"description": "Specification for a required field in judge_coding_plan.",
"properties": {
"name": {
"description": "Field name in the judge_coding_plan tool",
"title": "Name",
"type": "string"
},
"type": {
"description": "Expected data type (string, list[str], list[dict], etc.)",
"title": "Type",
"type": "string"
},
"description": {
"description": "What this field should contain",
"title": "Description",
"type": "string"
},
"required": {
"description": "Whether this field is required",
"title": "Required",
"type": "boolean"
},
"conditional_on": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Task metadata field this requirement depends on (e.g., 'design_patterns_enforcement')",
"title": "Conditional On"
},
"example_value": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Example of what this field should contain",
"title": "Example Value"
}
},
"required": [
"name",
"type",
"description",
"required"
],
"title": "PlanRequiredField",
"type": "object"
},
"RequirementsVersion": {
"description": "A version of user requirements with timestamp and source.",
"properties": {
"content": {
"title": "Content",
"type": "string"
},
"source": {
"title": "Source",
"type": "string"
},
"timestamp": {
"title": "Timestamp",
"type": "integer"
}
},
"required": [
"content",
"source"
],
"title": "RequirementsVersion",
"type": "object"
},
"ResearchScope": {
"description": "Research scope enum for workflow-driven research validation.\n\nDetermines the depth and requirements for research validation:\n- NONE: No research required for this task complexity\n- LIGHT: Light research required (1+ authoritative domain source)\n- DEEP: Deep research required (2+ authoritative domain sources)",
"enum": [
"none",
"light",
"deep"
],
"title": "ResearchScope",
"type": "string"
},
"ReuseComponent": {
"properties": {
"path": {
"description": "Repository path to the reusable component",
"title": "Path",
"type": "string"
},
"purpose": {
"default": "",
"description": "What part of the task this component will support",
"title": "Purpose",
"type": "string"
},
"notes": {
"default": "",
"description": "Any integration notes or caveats",
"title": "Notes",
"type": "string"
}
},
"required": [
"path"
],
"title": "ReuseComponent",
"type": "object"
},
"TaskMetadata": {
"description": "Lightweight metadata for coding tasks that flows with memory layer.\n\nThis model serves as the foundation for the enhanced workflow v3 system,\nreplacing session-based tracking with task-centric approach.",
"properties": {
"task_id": {
"description": "IMMUTABLE: Auto-generated UUID, primary key for memory storage",
"title": "Task Id",
"type": "string"
},
"created_at": {
"description": "IMMUTABLE: Task creation timestamp (epoch seconds)",
"title": "Created At",
"type": "integer"
},
"title": {
"description": "Display title for coding task (updatable)",
"title": "Title",
"type": "string"
},
"description": {
"description": "Detailed coding task description (updatable)",
"title": "Description",
"type": "string"
},
"user_requirements": {
"default": "",
"description": "Current coding requirements (updatable)",
"title": "User Requirements",
"type": "string"
},
"state": {
"$ref": "#/$defs/TaskState",
"default": "created",
"description": "Current task state (updatable, follows TaskState transitions)"
},
"task_size": {
"$ref": "#/$defs/TaskSize",
"description": "Task size classification for workflow optimization (XS=simple fixes, S=minor features, M=standard, L=complex, XL=major changes)"
},
"user_requirements_history": {
"description": "History of requirements changes",
"items": {
"$ref": "#/$defs/RequirementsVersion"
},
"title": "User Requirements History",
"type": "array"
},
"accumulated_diff": {
"additionalProperties": true,
"description": "Code changes accumulated over time",
"title": "Accumulated Diff",
"type": "object"
},
"modified_files": {
"description": "List of file paths that were created or modified during task implementation",
"items": {
"type": "string"
},
"title": "Modified Files",
"type": "array"
},
"test_files": {
"description": "List of test file paths that were created during testing phase",
"items": {
"type": "string"
},
"title": "Test Files",
"type": "array"
},
"test_status": {
"additionalProperties": {
"type": "string"
},
"description": "Status of different test types (unit, integration, e2e, etc.)",
"title": "Test Status",
"type": "object"
},
"updated_at": {
"description": "Last update timestamp (epoch seconds)",
"title": "Updated At",
"type": "integer"
},
"tags": {
"description": "Coding-related tags",
"items": {
"type": "string"
},
"title": "Tags",
"type": "array"
},
"problem_domain": {
"default": "",
"description": "Concise statement of the problem domain and scope for this task",
"title": "Problem Domain",
"type": "string"
},
"problem_non_goals": {
"description": "Explicit non-goals/boundaries to prevent scope creep and re-solving commodity concerns",
"items": {
"type": "string"
},
"title": "Problem Non Goals",
"type": "array"
},
"library_plan": {
"description": "Planned libraries/utilities per purpose; prefer internal reuse and well-known libraries; custom code only with justification",
"items": {
"$ref": "#/$defs/LibraryPlanItem"
},
"title": "Library Plan",
"type": "array"
},
"internal_reuse_components": {
"description": "Existing repository components/utilities to reuse with paths and purposes",
"items": {
"$ref": "#/$defs/ReuseComponent"
},
"title": "Internal Reuse Components",
"type": "array"
},
"research_required": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether research is required by workflow guidance (None=undetermined, True=required, False=optional)",
"title": "Research Required"
},
"research_scope": {
"$ref": "#/$defs/ResearchScope",
"default": "none",
"description": "Research scope determined by workflow: none|light|deep"
},
"research_completed": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Epoch seconds when research validation passed",
"title": "Research Completed"
},
"research_rationale": {
"default": "",
"description": "Explanation of why research was required and how the scope was determined",
"title": "Research Rationale",
"type": "string"
},
"expected_url_count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "LLM-determined expected number of research URLs based on task complexity",
"title": "Expected Url Count"
},
"minimum_url_count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "LLM-determined minimum acceptable URL count for adequate research",
"title": "Minimum Url Count"
},
"url_requirement_reasoning": {
"default": "",
"description": "LLM-generated explanation of why specific URL count is needed for this task",
"title": "Url Requirement Reasoning",
"type": "string"
},
"research_complexity_analysis": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Detailed complexity analysis factors from LLM (domain, tech maturity, integration scope, etc.)",
"title": "Research Complexity Analysis"
},
"internal_research_required": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether internal codebase research is needed (None=undetermined, True=required, False=not needed)",
"title": "Internal Research Required"
},
"related_code_snippets": {
"description": "Related code snippets from the codebase that are relevant to this task",
"items": {
"type": "string"
},
"title": "Related Code Snippets",
"type": "array"
},
"risk_assessment_required": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether risk assessment is needed (None=undetermined, True=required, False=not needed)",
"title": "Risk Assessment Required"
},
"identified_risks": {
"description": "Areas that could be harmed by the proposed changes",
"items": {
"type": "string"
},
"title": "Identified Risks",
"type": "array"
},
"risk_mitigation_strategies": {
"description": "Strategies to mitigate identified risks",
"items": {
"type": "string"
},
"title": "Risk Mitigation Strategies",
"type": "array"
},
"design_patterns_enforcement": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether design patterns are required for this task (None=undetermined, True=required, False=not needed)",
"title": "Design Patterns Enforcement"
},
"plan_approved_at": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Timestamp when plan was approved by judge_coding_plan (None=not approved)",
"title": "Plan Approved At"
},
"plan_rejection_count": {
"default": 0,
"description": "Number of times the plan has been rejected (max 1 allowed)",
"title": "Plan Rejection Count",
"type": "integer"
},
"code_approved_files": {
"additionalProperties": {
"type": "integer"
},
"description": "Dictionary mapping file paths to approval timestamps from judge_code_change",
"title": "Code Approved Files",
"type": "object"
},
"testing_approved_at": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Timestamp when testing was approved by judge_testing_implementation (None=not approved)",
"title": "Testing Approved At"
},
"all_approvals_validated": {
"default": false,
"description": "Whether all required approvals (plan, code, testing) have been validated",
"title": "All Approvals Validated",
"type": "boolean"
}
},
"required": [
"title",
"description",
"task_size"
],
"title": "TaskMetadata",
"type": "object"
},
"TaskSize": {
"description": "Task size classification for workflow optimization.\n\nSizes are based on estimated complexity and time requirements:\n- XS: Extra Small - Simple fixes, typos, minor config changes (< 30 minutes)\n- S: Small - Minor features, simple refactoring (30 minutes - 2 hours)\n- M: Medium - Standard features, moderate complexity (2-8 hours) - DEFAULT\n- L: Large - Complex features, multiple components (1-3 days)\n- XL: Extra Large - Major system changes, architectural updates (3+ days)\n\nThis classification determines planning complexity and validation depth:\n- XS/S: Basic planning requirements, streamlined validation\n- M: Standard planning and validation\n- L/XL: Comprehensive planning with enhanced validation (library plans, risk assessment, design patterns)\n\nAll tasks follow the unified workflow: CREATED \u2192 PLANNING \u2192 PLAN_APPROVED \u2192 IMPLEMENTING \u2192 REVIEW_READY \u2192 TESTING \u2192 COMPLETED",
"enum": [
"xs",
"s",
"m",
"l",
"xl"
],
"title": "TaskSize",
"type": "string"
},
"TaskState": {
"description": "Coding task state enum with well-documented transitions.\n\nState Transitions:\n- CREATED \u2192 PLANNING: Task created, ready for planning phase (XS/S may skip to IMPLEMENTING)\n- PLANNING \u2192 PLAN_PENDING_APPROVAL: Plan created, awaiting user approval\n- PLAN_PENDING_APPROVAL \u2192 PLANNING: User requests plan changes\n- PLAN_PENDING_APPROVAL \u2192 PLAN_APPROVED: User approves plan\n- PLAN_APPROVED \u2192 IMPLEMENTING: Implementation phase started\n- IMPLEMENTING \u2192 IMPLEMENTING: Multiple code changes during implementation\n- IMPLEMENTING \u2192 REVIEW_READY: Implementation complete, ready for code review\n- REVIEW_READY \u2192 TESTING: Code review approved, ready for testing validation\n- TESTING \u2192 TESTING: Multiple test iterations\n- TESTING \u2192 COMPLETED: All tests validated; task completed successfully\n- Any state \u2192 BLOCKED: Task blocked by external dependencies\n- Any state \u2192 CANCELLED: Task cancelled\n- BLOCKED \u2192 Previous state: Unblocked, return to previous state\n\nUsage:\n- CREATED: Default state for new tasks, all tasks proceed to planning (unified workflow)\n- PLANNING: Planning phase in progress (set when planning starts)\n- PLAN_PENDING_APPROVAL: Plan created, awaiting user approval and potential iteration\n- PLAN_APPROVED: Plan validated and approved (set by judge_coding_plan)\n- IMPLEMENTING: Implementation phase in progress (set when coding starts)\n- REVIEW_READY: Implementation complete and ready for code review\n- TESTING: Testing/validation phase after code review approval\n- COMPLETED: Task completed successfully (set by judge_coding_task_completion)\n- BLOCKED: Task blocked by external dependencies (manual override)\n- CANCELLED: Task cancelled (manual override)",
"enum": [
"created",
"planning",
"plan_pending_approval",
"plan_approved",
"implementing",
"testing",
"review_ready",
"completed",
"blocked",
"cancelled"
],
"title": "TaskState",
"type": "string"
},
"WorkflowGuidance": {
"description": "Canonical workflow guidance model used across the system.\n\nReturned by tools to provide consistent next steps and instructions for\nthe coding assistant. This is the single source of truth for the\nWorkflowGuidance schema.",
"properties": {
"next_tool": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Next tool to call, or None if workflow complete",
"title": "Next Tool"
},
"reasoning": {
"default": "",
"description": "Clear explanation of why this tool should be used next",
"title": "Reasoning",
"type": "string"
},
"preparation_needed": {
"description": "List of things that need to be prepared before calling the recommended tool",
"items": {
"type": "string"
},
"title": "Preparation Needed",
"type": "array"
},
"guidance": {
"default": "",
"description": "Detailed step-by-step guidance for the AI assistant",
"title": "Guidance",
"type": "string"
},
"research_required": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether research is required for this task (only determined for new CREATED tasks)",
"title": "Research Required"
},
"research_scope": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Research scope: 'none', 'light', or 'deep' (only determined for new CREATED tasks)",
"title": "Research Scope"
},
"research_rationale": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Explanation of research requirements (only determined for new CREATED tasks)",
"title": "Research Rationale"
},
"internal_research_required": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether internal codebase analysis is needed (only determined for new CREATED tasks)",
"title": "Internal Research Required"
},
"risk_assessment_required": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether risk assessment is needed (only determined for new CREATED tasks)",
"title": "Risk Assessment Required"
},
"design_patterns_enforcement": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether design patterns are required (only determined for new CREATED tasks)",
"title": "Design Patterns Enforcement"
},
"plan_required_fields": {
"description": "Structured specification of required fields for judge_coding_plan tool",
"items": {
"$ref": "#/$defs/PlanRequiredField"
},
"title": "Plan Required Fields",
"type": "array"
}
},
"title": "WorkflowGuidance",
"type": "object"
}
},
"properties": {
"action": {
"description": "Action taken: 'created' or 'updated'",
"title": "Action",
"type": "string"
},
"context_summary": {
"description": "Summary of the task context and current state",
"title": "Context Summary",
"type": "string"
},
"current_task_metadata": {
"$ref": "#/$defs/TaskMetadata",
"description": "ALWAYS current state of task metadata after operation"
},
"workflow_guidance": {
"$ref": "#/$defs/WorkflowGuidance",
"description": "LLM-generated next steps and instructions from shared method"
}
},
"required": [
"action",
"context_summary",
"current_task_metadata",
"workflow_guidance"
],
"title": "TaskAnalysisResult",
"type": "object"
}Always call this first for coding work. Use the exact task_id returned for all later tools; recover with get_current_coding_task if missing.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | ||
| state | No | created | |
| task_id | No | ||
| task_size | No | m | |
| task_title | Yes | ||
| user_request | Yes | ||
| task_description | Yes | ||
| user_requirements | No |
| Name | Required | Description |
|---|---|---|
| action | Yes | Action taken: 'created' or 'updated' |
| context_summary | Yes | Summary of the task context and current state |
| workflow_guidance | Yes | LLM-generated next steps and instructions from shared method |
| current_task_metadata | Yes | ALWAYS current state of task metadata after operation |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and delivers operational details: it warns about token inefficiency, mandates exact task_id usage, and notes enforced state transitions. It also clarifies the return structure, giving the agent a strong sense of behavior.
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 well-structured with clear headings, but includes a very large embedded JSON schema under Returns that may be redundant with the actual output schema. The token-waste warnings are slightly repetitive, though the overall organization keeps it navigable.
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 and lack of annotations, the description is remarkably complete: it covers purpose, usage, parameters, return structure, and operational notes like task_id recovery. It provides enough workflow context for an agent to invoke it appropriately.
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 Args section explicitly outlines each parameter with type, required status, and meaning (e.g., task_size enum values, state transition example, task_id for updates). Since schema coverage is 0%, this description fully compensates and adds significant semantic 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 tool creates or updates coding task metadata and returns workflow guidance, explicitly naming it the 'mandatory entry point for any coding work.' It distinguishes itself from siblings like get_current_coding_task by documenting the task_id recovery pattern.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use the tool ('any user request requiring logical code changes or creation of new files') and warns against skipping it. It also references get_current_coding_task as an alternative for recovering task_id, providing clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a new agent session with a goal and optional constraints.
| Name | Required | Description | Default |
|---|---|---|---|
| goal | Yes | ||
| context | No | ||
| task_id | No | ||
| metadata | No | ||
| constraints | No | ||
| brain_config | No | ||
| memory_settings | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full burden of disclosing behavioral traits. It states the action 'start' but does not explain what starting a session entails: side effects, return values, persistence, or whether it overwrites existing sessions. This is a significant gap for a tool that likely creates state.
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 unnecessary words. It immediately states the main action and the key parameters, making it highly concise and easy to parse. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 7 parameters and no annotation context, the description is too minimal. It does not explain the session lifecycle, the purpose of configuration parameters, or any relationship to sibling tools. While an output schema exists (per context signals), the description alone is insufficient for an agent to fully understand when and how to use the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It mentions two of seven parameters ('goal' and 'constraints'), adding minimal meaning by indicating that goal is central and constraints are optional. However, it leaves the other five parameters (context, task_id, metadata, brain_config, memory_settings) completely unexplained, failing to provide sufficient semantics for the parameter set.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('start') and resource ('new agent session'), clearly stating the tool's action. It implies scope by mentioning 'goal' and 'optional constraints', which distinguishes it from retrieval tools like get_session_context. However, it does not explicitly differentiate from all sibling tools, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 such as get_session_context or configure_brain. It is only implied that 'new' sessions are started here, but there is no mention of prerequisites, conditions, or exclusions. No exclusions or alternative tool references are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0agent_llm_requestcall_mcp_toolconfigure_brainconfigure_memoryconnect_mcp_serverget_brain_configget_current_coding_taskget_session_contextjudge_code_changejudge_coding_planjudge_coding_task_completionjudge_testing_implementationlink_tasklist_mcp_serverslist_mcp_toolslog_eventmemory_deletememory_indexmemory_list_namespacesmemory_searchmemory_statsraise_missing_requirementsraise_obstaclerefresh_codexrequest_plan_approvalrouter_chatset_coding_taskstart_sessionScored across 28 tools
Some tool clusters overlap in purpose: router_chat vs agent_llm_request both make LLM calls, list_mcp_servers vs list_mcp_tools are easy to confuse, and the judge_* family shares a similar naming pattern despite targeting different phases. Most tools are distinct, but the boundaries between some are unclear without reading the full descriptions.
The vast majority of tools follow a verb_noun snake_case pattern (start_session, set_coding_task, judge_code_change). Exceptions like the memory_* noun-prefixed family, router_chat, and agent_llm_request deviate, but the overall convention is still fairly uniform.
At 28 tools, this server exceeds the 25-tool threshold and spans many subdomains (memory, sessions, MCP, coding workflow). Each tool appears purposeful, but the large surface area creates context and selection overhead for an agent.
The server covers the full coding task lifecycle (plan, code review, testing, completion) and provides robust memory, session, and MCP management. Minor gaps like no session teardown or MCP disconnect exist, but agents can work around them.
An MCP memory server. One memory your agents share — across models, devices and apps.
MCP server for building and testing AI agents with multi-model experimentation and insights.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
Hosted MCP server for LLM cost estimation, model comparison, and budget-aware routing.
