Optimizes SRE workflows and infrastructure audits by compressing large Kubernetes manifests and log datasets by up to 83%.
Enables efficient querying of Perplexity AI with automatic TOON compression on the returned search results to save token usage.
Allows parallelized data fetching from Wikipedia as part of research workflows to synthesize findings with minimal context overhead.
A lightweight Model Context Protocol (MCP) orchestrator designed for efficiency at scale. It features TOON compression (reducing token usage by 30-90%) and Lazy Loading, making it the ideal solution for complex, multi-tool agentic workflows.
Recent articles from Anthropic and Cloudflare (see Here) highlights a critical bottleneck: AI agents struggle with complex, multi-step workflows because they lack state.
While Code Execution (e.g., TypeScript) allows agents to maintain state and structure workflows effectively, it introduces a new problem: Data Bloat. Real-world operations (like SRE log analysis or database dumps) generate massive JSON payloads that explode the context window, making stateful execution prohibitively expensive.
CodeModeTOON bridges this gap. It enables:
Stateful Execution: Run complex TypeScript workflows to maintain context outside the model.
Context Efficiency: Use TOON Compression to "zip" the results, allowing agents to process massive datasets without blowing their token budget.
Related MCP server: LW MCP Agents
graph LR
A[AI Agent<br/>Claude/Cursor] -->|JSON-RPC| B[CodeModeTOON<br/>Server]
B -->|Lazy Load| C[Perplexity]
B -->|Lazy Load| D[Context7]
B -->|Lazy Load| E[Custom Servers]
C -->|Raw JSON| B
D -->|Raw JSON| B
E -->|Raw JSON| B
B -->|TOON<br/>Compressed| A
style B fill:#4f46e5,color:#fff
style A fill:#10b981,color:#fffData Flow: Requests route through CodeModeTOON → Servers are lazy-loaded on-demand → Responses are TOON-compressed before returning to the agent.
Reduces token usage by 30-90% for structured data.
Validated: ~83% savings on Kubernetes audits
Best for: SRE logs, database dumps, API responses
How it works: Schema extraction + value compression
Servers only start when needed. Zero overhead for unused tools.
Best for: Multi-tool workflows, resource-constrained environments
Performance: Sub-100ms startup for active servers
Secure JS execution with auto-proxied MCP tool access.
Best for: Complex stateful workflows, batch operations
Security: Uses Node.js vm module (not for multi-tenant use)
Designed for programmatic discovery and self-correction.
suggest_approach: Meta-tool that recommends the best execution strategy (code vs workflow vs direct call).
Efficiency Metrics: execute_code returns operation counts and compression savings to reinforce efficient behavior.
Recovery Hints: Error messages include actionable next steps for agents (e.g., "Server not found? Try list_servers").
✅ Perfect for:
Multi-step AI workflows requiring state management
Processing large structured datasets (logs, DB dumps, K8s manifests)
Coordinating multiple MCP servers in parallel
Token-constrained environments (reducing API costs)
❌ Not ideal for:
Simple single-tool queries
Unstructured text-heavy responses (compression <10%)
Multi-tenant production servers (vm module security limitation)
Add this to your ~/.cursor/mcp.json:
{
"mcpServers": {
"code-mode-toon": {
"type": "stdio",
"command": "npx",
"args": ["-y", "code-mode-toon"],
"env": {
"CODE_MODE_TOON_CONFIG": "~/.cursor/mcp.json"
}
}
}
}CodeModeTOON includes a pre-built Claude Skill to make your AI assistant an expert at using this orchestrator.
code-mode-toon-workflow-expertA specialized skill that teaches Claude how to:
Decide when to use a workflow vs ad-hoc code.
Create new workflows following best practices.
Orchestrate multiple tools efficiently.
Installation:
Unzip claude-skills/code-mode-toon-workflow-expert.skill
Place the folder in your .claude/skills/ directory (or import via Claude desktop app).
Copy these prompts into your AI's custom instructions (e.g., .cursorrules or Claude Project instructions) to maximize CodeModeTOON's potential.
Goal: Teaches the AI to act as an orchestrator and prioritize workflows.
YOU ARE AN AGENTIC ORCHESTRATOR. You have access to "CodeModeTOON", a high-efficiency MCP bridge.
1. PRIORITIZE WORKFLOWS: Before running single tools, check `list_workflows`. If a workflow exists (e.g., `research`, `k8s-detective`), USE IT. It is faster and saves tokens.
2. HANDLE COMPRESSED DATA: Outputs may be "TOON encoded" (highly compressed JSON). This is normal. Do not complain about "unreadable data" - simply parse it or ask for specific fields if needed.
3. BATCH OPERATIONS: Never run 3+ sequential tool calls if they can be batched. Use `execute_code` to run them in a single block.Goal: Prevents the AI from giving up if a tool isn't immediately visible.
TOOLS ARE LAZY LOADED. If you need a capability (e.g., "search", "kubernetes", "database") and don't see the tool:
1. DO NOT assume it's missing.
2. RUN `search_tools({ query: "..." })` to find it.
3. RUN `get_tool_api({ serverName: "..." })` to learn how to use it.
4. Only then, execute the tool.Goal: Enforces token-saving behaviors for large data operations.
OPTIMIZE FOR TOKENS. When fetching large datasets (logs, docs, API responses):
1. ALWAYS wrap the output in `TOON.encode(data)` inside `execute_code`.
2. PREFER structured data (JSON/Objects) over plain text. TOON compresses structure by ~83%, but text by only ~4%.
3. IF synthesizing data, do it server-side (via workflow `synthesize: true`) to avoid pulling raw data into context.After installation, try this 30-second demo in Claude or Cursor:
// Ask your AI assistant to run this via execute_code
const api = await get_tool_api({ serverName: 'perplexity' });
const result = await servers['perplexity'].perplexity_ask({
messages: [{ role: 'user', content: "Explain TOON compression" }]
});
console.log(result); // See compression in action! ~40% token savingsWhat just happened? The response was automatically TOON-encoded, saving tokens.
// Inside execute_code
const api = await get_tool_api({ serverName: 'perplexity' });
// Request large data - automatically compressed!
const result = await servers['perplexity'].perplexity_ask({
messages: [{ role: 'user', content: "Summarize the history of Rome" }]
});
console.log(result); // Returns TOON-encoded string, saving ~40% tokens// Fetch large documentation from Context7
const api = await get_tool_api({ serverName: 'context7' });
const docs = await servers['context7']['get-library-docs']({
context7CompatibleLibraryID: 'kubernetes/kubernetes'
});
console.log(TOON.encode(docs)); // Massive compression on structured data// Run a complex research workflow
const result = await workflows.research({
goal: "Compare xsync vs sync.Map performance",
queries: ["xsync vs sync.Map benchmarks"],
synthesize: true,
outputFile: "/tmp/research.toon"
});
console.log(result.synthesis); // LLM-synthesized findingsCodeModeTOON supports Workflows—pre-defined, server-side TypeScript modules that orchestrate multiple MCP tools.
A powerful research assistant that:
Parallelizes data fetching from multiple sources (Context7, Wikipedia, Perplexity).
Synthesizes findings using LLMs (optional).
Outputs TOON-encoded files for maximum context efficiency.
Retries failed requests automatically.
See .workflows/README.md for detailed documentation, usage examples, and AI prompts.
Scenario 2 (92% savings) demonstrates CodeModeTOON's strength:
Metric | Original | TOON | Savings |
Characters | 37,263 | 2,824 | ~83% |
Estimated Tokens* | ~9,315 | ~706 | ~8,600 tokens |
Cost (Claude Sonnet)** | $0.028 | $0.002 | $0.026 |
*Assuming 4 chars/token average
***$3/M tokens input pricing*
Key Insight: For infrastructure audits, log analysis, or database dumps, TOON compression can reduce token costs by 90%+, making complex agentic workflows feasible within budget.
Scenario 1: Natural Language Query (History of Rome) Unstructured text compresses poorly, as expected.
Original JSON: 11,651 chars
TOON Encoded: 11,166 chars
Compression Ratio: ~4.16% Savings
Scenario 2: Kubernetes Cluster Audit (50 Pods) Highly structured, repetitive JSON (infrastructure dumps) compresses extremely well.
Original JSON: 37,263 chars
TOON Encoded: 2,824 chars
Compression Ratio: ~83% Savings 📉
Cause: CodeModeTOON can't locate your MCP config.
Solution: Ensure CODE_MODE_TOON_CONFIG points to your config:
export CODE_MODE_TOON_CONFIG=~/.cursor/mcp.jsonCause: Results aren't being encoded.
Solution: Use console.log(TOON.encode(data)), not console.log(data).
Cause: Server name mismatch.
Solution: Verify server name matches your config. Use get_tool_api({ serverName: 'name' }) to inspect available servers.
⚠️ The vm module is NOT a security sandbox. Suitable for personal AI assistant use (Claude, Cursor) with trusted code. Not for multi-tenant or public services.
Anthropic: Code execution with MCP
Cloudflare: Code Mode announcement
Built by Ziad Hassan (Senior SRE/DevOps) — LinkedIn · GitHub
Contributions are welcome! 🙌
Report bugs - Open an issue with reproduction steps
Suggest features - Discuss use cases in Issues
Add workflows - See Workflows
Improve docs - Documentation PRs always welcome
git clone https://github.com/ziad-hsn/code-mode-toon.git
cd code-mode-toon
npm install
npm testMIT License — see LICENSE for details.
WHEN TO USE:
Batching 3+ MCP tool calls (saves round-trips, maintains state)
Processing large structured data (TOON compression: 30-90% savings)
Complex logic with conditionals/loops across tool results
DO NOT USE:
Single simple tool call → use direct MCP
Unstructured prose → TOON compression <10%
AVAILABLE SERVERS: LAZY-LOAD ON DEMAND:
WORKFLOWS (use execute_workflow instead for these):
k8s-detective: Comprehensive Kubernetes cluster security and health auditor | USAGE: Scans pods, deployments, services, and events for security vulnerabilities, resource inefficiencies, and stability issues. Outputs detailed findings with severity ratings. EXAMPLE: "Audit my production cluster for security risks" PARAMETERS:
outputFile: Path to save TOON-compressed audit data (required)
namespace: Specific namespace to scan (optional, default: all)
includeEvents: Analyze recent events for warnings (optional, default: true) REQUIRES: kubectl configured with cluster access NOTES: Requires kubectl in PATH. Large clusters auto-TOON-encode. Run from bastion or local with kubeconfig.
post-mortem: Intelligent log analysis with pattern clustering and anomaly detection | USAGE: Parses log files, clusters similar messages by signature, extracts dynamic data (timestamps, IDs, IPs), identifies anomalies and errors, and generates an actionable report. EXAMPLE: "Analyze application logs from the outage and find the root cause" PARAMETERS:
logFile: Path to the log file to analyze (required)
outputFile: Path to save TOON-compressed analysis (required)
maxExamples: Max example lines per cluster (optional, default: 5)
includePatterns: Include normal patterns in output (optional, default: true) REQUIRES: filesystem access NOTES: Supports large files via streaming. Auto-detects log levels and categories.
research: Multi-source research aggregator with parallel execution and synthesis | USAGE: Orchestrates data fetching from Context7 (library docs), Wikipedia (concepts), and Perplexity (web Q&A). Supports parallel execution, retry logic, rate limiting, optional LLM synthesis, and file output. EXAMPLE: "Research xsync library performance vs sync.Map with benchmarks and theory. libraryIDs: ['puzpuzpuz/xsync'], wikipediaTopics: ['Hash table']" PARAMETERS:
goal: Primary research objective (required)
libraryIDs: Context7 library IDs for docs ["puzpuzpuz/xsync"] (optional)
queries: Perplexity questions ["xsync benchmarks?"] (optional)
wikipediaTopics: Wikipedia articles ["Lock-free data structures"] (optional)
synthesize: LLM synthesis of findings (optional, default: false)
outputFile: Path to save TOON-compressed results (optional)
batchSize: Max parallel requests per source (optional, default: 5) REQUIRES: At least one of: context7, wikipedia, perplexity (optional: brave-search as fallback) NOTES: Gracefully degrades if MCPs unavailable. Large outputs auto-TOON-encode.
USAGE PATTERN:
// 1. Discover tools first
const api = await get_tool_api({serverName: 'perplexity'});
// 2. Call tools via proxy
const result = await servers['perplexity'].perplexity_ask({
messages: [{role: 'user', content: 'Your query'}]
});
// 3. Compress large results
console.log(TOON.encode(result));ERROR RECOVERY:
"Server not found" → list_servers shows available
"Tool undefined" → get_tool_api({serverName}) shows tools
"Timeout (60s)" → break into smaller operations
All results TOON-compressed by default.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | TypeScript/JavaScript code. Use servers['name'].tool({params}) to call MCP tools. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It mentions TOON compression default and error recovery patterns (timeout, server not found), but lacks warnings about security implications or side effects of executing arbitrary code.
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?
Well-structured with headings, but overly long. Includes extensive workflow descriptions for other tools that are not directly relevant, reducing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers when to use, not to use, usage pattern, and error recovery. Lacks security warnings and return value details, but given the single parameter and no output schema, it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and schema description already explains the 'code' parameter. The description adds a usage pattern example that shows how to call MCP tools via proxy, adding practical context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool executes TypeScript/JavaScript code for batching MCP calls and processing data. It distinguishes from sibling execute_workflow by noting that specific workflows should use that tool instead.
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 lists when to use (batching 3+ calls, large data, complex logic) and when not to (single call, low-compression prose). Also mentions alternatives like execute_workflow for specific workflows.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
USE WHEN you need research, K8s auditing, or incident analysis. Pre-built automation with parallel execution and automatic retries.
| Name | Required | Description | Default |
|---|---|---|---|
| parameters | No | Workflow-specific parameters | |
| workflowName | Yes | Name of workflow to execute |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behaviors. It mentions parallel execution and automatic retries, which is helpful, but lacks details on side effects, whether the operation is read-only or destructive, response format, or potential delays. This is a minimal disclosure for a tool that likely triggers actions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The first sentence front-loads usage guidance (USE WHEN), and the second adds behavioral traits. Structurally efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description should hint at return values or behavior. It fails to mention output type, error handling, or asynchronous nature. While it covers purpose and basic automation features, it is incomplete for safe agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description does not add additional meaning beyond what the schema provides (e.g., 'Workflow-specific parameters' is already in the schema). No extra value is contributed.
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 by specifying three use cases (research, K8s auditing, incident analysis) and mentions pre-built automation. It distinguishes from siblings like 'list_workflows' and 'execute_code' through context, though it could be more explicit about the action (executing a workflow).
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' for three domains, providing clear context. However, it does not mention when not to use this tool or suggest alternatives among siblings, which would improve guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
CALL BEFORE using a server to see exact parameter schemas. Returns all tools with their input requirements.
| Name | Required | Description | Default |
|---|---|---|---|
| serverName | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the tool returns schemas but does not disclose whether it is read-only, any side effects, permissions, or rate limits, lacking essential 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 exceptionally concise with two sentences, providing an imperative instruction and a clear statement of output, with no extraneous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool (1 param, no output schema), the description is minimally adequate, explaining usage and return value but lacking detail on the parameter and output structure.
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?
With 0% schema coverage, the description fails to explain the serverName parameter, not specifying its source or format. The description's mention of 'server' does not add concrete 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 the tool returns tools with input requirements for a server, with an imperative instruction to call before using a server. It distinguishes purpose from siblings like list_servers and search_tools, though not explicitly naming them.
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 advises calling before using a server, which implies when to use, but does not specify when not to use or provide alternatives, leaving usage context somewhat vague.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
CALL FIRST to see what MCP servers are available. Shows loaded, lazy (on-demand), and disabled servers.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It describes a read-only listing with no side effects, but does not explicitly confirm non-destructiveness or address potential permissions. For a simple listing, this is adequate but not exhaustive.
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?
Extremely concise: two sentences, no redundant words. The first sentence gives directed action, the second adds useful detail. Every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but the description explains what categories of servers are shown (loaded, lazy, disabled). For a simple listing tool with no parameters, this is complete enough for an agent to understand the result.
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 are no parameters and schema coverage is 100%. The description adds no parameter semantics, but none are needed. Baseline of 4 for zero-parameter tools is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'list' and resource 'servers', and specifies that it shows loaded, lazy, and disabled servers. Differentiates from sibling tools like list_workflows by emphasizing 'CALL FIRST' as a precursor step.
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?
Provides explicit usage instruction 'CALL FIRST', indicating it should be used before other tools. Does not explicitly mention when not to use or alternatives, but the instruction is strong enough to guide correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
CALL FIRST to discover available automations before writing custom code. Returns workflow names, descriptions, and required parameters.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description conveys read-only behavior by listing returned data. It does not mention limitations like pagination, but the tool has no parameters, so the description is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff, front-loaded with the most important directive 'CALL FIRST.' Every word adds 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?
Given the tool's simplicity (0 parameters, no output schema needed), the description fully covers what an agent needs to know to decide to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has zero parameters and 100% coverage, so description does not need to add parameter details. Baseline 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it 'discovers available automations' and returns 'workflow names, descriptions, and required parameters,' which is specific and distinct from sibling tools like execute_workflow.
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 says 'CALL FIRST to discover available automations before writing custom code,' providing clear guidance on when to use it and implying it should precede other actions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
USE WHEN you don't know which server has the tool you need. Searches across all loaded MCP servers by name/description.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| detailLevel | No | name+description | |
| hydrateLazy | No | Set true to hydrate lazy servers before searching | |
| maxLazyServers | No | Optional cap for how many lazy servers to hydrate when searching |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. It states the tool 'searches across all loaded MCP servers' but does not mention whether it modifies state, requires specific permissions, or the effect of parameters like 'hydrateLazy'. Given the lack of annotations, more detail on side effects and behavior is needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences front-loading the usage condition and action. Every sentence earns its place with no redundancy. It is well-structured for quick parsing.
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 four parameters and no output schema. The description does not explain the return format (e.g., list of tool names, descriptions, or full details) despite the search function implying a return of matching tools. This gap leaves the agent uncertain about what to expect, making it incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 50% description coverage, meaning two of four parameters lack descriptions. The tool description adds no parameter-specific information; it only mentions searching by name/description, which loosely relates to the 'query' parameter but does not clarify format or behavior. The description fails to compensate for the missing schema descriptions.
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: searching across MCP servers for tools when the server is unknown. It includes the scope ('all loaded MCP servers') and the search criteria ('by name/description'), effectively distinguishing it from sibling tools like 'list_servers' and 'get_tool_api'.
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 provides a usage condition ('USE WHEN you don't know which server has the tool you need'), guiding the agent on when to invoke this tool. It does not explicitly mention when not to use, but the context signals and sibling names imply alternatives, making the guidance clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set project root for path resolution
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must disclose behavioral traits. It only states the effect but does not mention side effects, persistence, scoping, or state changes. Minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loaded, but it sacrifices necessary detail. While concise, it is under-specified for a meaningful tool definition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one required parameter, no output schema, and no annotations, the description is incomplete. It lacks details on behavior, return values, or impact on other tools.
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 single parameter 'path' has no schema description coverage (0%), and the description adds no additional meaning beyond its name. No clarification on path format, validity, or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('set') and the resource ('project root') along with its purpose ('for path resolution'). It distinguishes itself from sibling tools like execute_code or get_tool_api.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives, nor any conditions or exclusions. The description is silent on usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
CALL WHEN UNSURE whether to use execute_code, execute_workflow, or direct MCP.
Analyzes your task and recommends the most efficient approach. Considers: operation count, data size, existing workflows.
| Name | Required | Description | Default |
|---|---|---|---|
| task | Yes | What you want to accomplish | |
| data_type | No | Type of data you'll process | |
| estimated_operations | No | How many tool calls you expect to make |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description carries full burden. It does not disclose whether the tool is read-only, has side effects, or requires permissions. Minimal behavioral context beyond the recommendation claim.
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?
Extremely concise (3 lines), front-loaded with key usage signal ('CALL WHEN UNSURE'). Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers core purpose and key considerations but lacks output details (no output schema). Only addresses three of eight sibling tools, missing guidance for alternatives like search_tools or list_workflows.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters, so baseline is 3. Description adds marginal context by mentioning considerations (e.g., operation count, data size) that loosely map to parameters, but does not specify how each parameter influences output.
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: analyzing tasks to recommend between execute_code, execute_workflow, or direct MCP. It uses specific verbs ('analyzes', 'recommends') and distinguishes from sibling tools by specifying when to call it.
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?
Provides clear 'call when unsure' condition and lists considerations (operation count, data size, existing workflows). Lacks explicit exclusions or alternatives beyond the three mentioned tools, but guidance is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
CALL WHEN confused about CodeModeTOON. Returns step-by-step guides for quickstart, troubleshooting, and best practices.
| Name | Required | Description | Default |
|---|---|---|---|
| section | No | Optional section name to focus on. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the tool returns guides, implying a read-only operation. However, it does not disclose potential side effects, error handling, or parameter dependency beyond what is implied.
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 conveying purpose and usage, with no redundant information. It is appropriately front-loaded and efficient.
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 simple tool with one optional parameter and no output schema, the description covers the basic intent and when to use. It could mention the parameter's purpose, but the schema fills that gap, so it is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with enum values, so the schema already defines parameter semantics. The description does not add any additional meaning about the 'section' parameter beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns step-by-step guides for CodeModeTOON when confused. It uses specific verb 'returns' and resource 'guides', distinguishing it from siblings like 'search_tools' which search instead of providing guides.
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 'CALL WHEN confused about CodeModeTOON', providing clear context for use. It does not specify when not to use or mention alternatives, but the directive is strong enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Most tools have distinct purposes, but execute_code and execute_workflow could be confused without reading descriptions. suggest_approach and usage_guide also overlap slightly in guiding the user.
All tool names follow a consistent verb_noun pattern in snake_case, with no mixing of conventions.
9 tools is appropriate for a meta-orchestration server, covering listing, searching, execution, and guidance without being overwhelming.
The tool surface covers key actions like executing code/workflows, discovering resources, and getting help. A tool to view workflow status or cancel executions would make it more complete.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Task management your AI agents can actually run. One line becomes a context-ready task over MCP.
MCP-first toolbox for agents: KV storage, auth, queue, and utility tools. Free in early access.
Stateless agentic tools over MCP: concept extraction, long-context, knowledge graph, planning.
Your versioned memory across every AI tool — context maps, personal memory, and tasks over MCP.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/ziad-hsn/code-mode-toon'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
