Tool Descriptions are Written for Humans, Not AI. It's Too Long!

[Jaesun23]

Problem: Tool Descriptions are Written for Humans, Not AI

Current Issue

Desktop Commander's tool descriptions consume ~15,000-20,000 tokens of Claude's context window before any actual conversation begins. This is because descriptions are written as if humans will read them, not the AI that actually uses the tools.

Key Insight

The actual user of MCP tools is Claude, not the human. Therefore, descriptions should be optimized for AI comprehension and token efficiency, not human readability.

Measured Impact

• 21 tools with verbose descriptions
• ~15,000-20,000 tokens consumed by tool metadata alone
• ~30-40% of total context budget (assuming 190k limit) used before conversation starts
• Longest descriptions: start_search (83 lines), start_process (61 lines), interact_with_process (58 lines)

Proposed Solution

1. Base descriptions: Minimal, AI-optimized format

   • Tool name, parameters, return values, constraints
   • 1-2 sentences maximum

2. Detailed docs: Available on-demand

   • get_tool_docs(tool_name) - returns full documentation
   • Only loaded when Claude needs clarification
   • Keeps context clean by default

Example Comparison

Before (33 lines):

Read the contents of a file from the file system or a URL...
Prefer this over 'execute_command' with cat/type...
Supports partial file reading with:
- 'offset' (start line, default: 0)
  * Positive: Start from line N...
  * Negative: Read last N lines...
[... 25 more lines of examples and edge cases]

After (1 line):

Read file contents with optional offset/length. Supports URLs and images.

Token savings: ~500 tokens per tool → ~10,000 tokens total

Benefits

• ✅ More conversation space for users
• ✅ Faster tool loading
• ✅ Claude understands tools instantly (doesn't need tutorials)
• ✅ Detailed docs still available when needed

Implementation

The verbose descriptions feel like they're addressing AI capability concerns from 2-3 years ago. Modern LLMs like Claude 3.5+ understand tools immediately from minimal descriptions. The extensive examples and tutorials should be opt-in, not mandatory context.

[wonderwhy-er]

They are built based on iteration to make AI use those tools well and actually built trough iterating on prompts base don chats where AI fails to use them right. So solution proposed here will not do. Its not about it being written as if for humans. That is probably AI judgment.

But problem that prompt got too big is correct. We will need to work on optimizing the tool. May be removing less used methods and combining some of the methods in to single tools. We already did that for code/file search by unifying them.

[Jaesun23]

I understand exactly what you're saying. From my own experience, getting the highest quality and flawless results from Claude really does require providing all the details. That's why I've also created my own "methodology" - essentially a book's worth of guidelines - that I have Claude reference at each work stage, along with pre-made templates to reduce errors.

I have an idea that might help, though I'm not sure. When talking with Claude, I've noticed it sometimes explains complex concepts using code-like structures, which Claude calls "pseudocode." When I asked why it uses pseudocode, Claude told me something interesting: even when we think we're being precise, "human language" often creates ambiguous decision points for Claude. When faced with ambiguity without clear options, Claude either ignores the instruction entirely or creates self-protective logic that leads to completely unexpected results. In my case, when defining system prompts or sub-agents, I have Claude define work specifications in pseudocode that Claude itself finds unambiguous.

But yes, you're right - we can't make everything pseudocode! So let's use another thing Claude loves: "structure." Pseudocode has strengths in conditional logic and precision, but for simple rules or lists/classifications, pseudocode doesn't add much value. That's when we use structured descriptions, like tree formats.

Let me show you an example:

Current Format (~500 tokens)

Start a new terminal process with intelligent state detection.

PRIMARY TOOL FOR FILE ANALYSIS AND DATA PROCESSING
This is the ONLY correct tool for analyzing local files (CSV, JSON, logs, etc.).
The analysis tool CANNOT access local files and WILL FAIL - always use 
processes for file-based work.

CRITICAL RULE: For ANY local file work, ALWAYS use this tool + 
interact_with_process, NEVER use analysis/REPL tool.

REQUIRED WORKFLOW FOR LOCAL FILES:
1. start_process("python3 -i") - Start Python REPL for data analysis
2. interact_with_process(pid, "import pandas as pd, numpy as np")
3. interact_with_process(pid, "df = pd.read_csv('/absolute/path/file.csv')")
...
[continues with many more lines of examples and edge cases]

Hybrid Format: Pseudocode + Structure (~150 tokens)

// ═══════════════════════════════════════════════════
// TOOL: start_process(command, timeout_ms, shell?, verbose_timing?)
// ═══════════════════════════════════════════════════
// PURPOSE: Execute persistent interactive sessions (REPL/shell)
// PLATFORM: macOS, default_shell: zsh

// DECISION LOGIC (Pseudocode):
IF task.involves(local_file_analysis):  // CSV, JSON, Excel, logs
    CRITICAL: NEVER use analysis_tool (no filesystem access)
    REQUIRED_WORKFLOW:
        pid = start_process("python3 -i", timeout=30000)
        interact_with_process(pid, "import pandas as pd")
        interact_with_process(pid, f"df = pd.read_csv('{absolute_path}')")
        interact_with_process(pid, "print(df.describe())")
    CONSTRAINT: paths = absolute (/Users/...), NOT relative (./...)

ELSE IF task.involves(interactive_repl):
    // SUPPORTED ENVIRONMENTS (Tree Structure):
    SUPPORTED:
        python3 -i → data_analysis, scripting
        node -i    → JSON_processing, JavaScript  
        R          → statistical_computing
        bash       → shell_scripting
    AUTO_DETECTION: exits_on_prompts(>>>, >, $)
    
ELSE IF task.involves(single_command):
    ALTERNATIVE: bash_tool (simpler for one-time operations)

// UNIVERSAL RULES (Simple Declarations):
STATES: waiting_for_input | finished | running
PATHS: Always absolute, never relative
DETECTION: Smart early exit prevents unnecessary timeout

Result: ~70% token reduction (500 → 150) while maintaining all information

Why This Hybrid Approach Works

• Conditional Logic → Pseudocode (IF/ELSE) - Most precise
• Lists/Categories → Tree Structure - Most visual
• Simple Rules → Short Declarations - Most concise
• Workflows → Code Format - Most clear

Each type of information gets its optimal format rather than forcing everything into prose.

---

This approach might help you reduce token count while maintaining the same error-prevention benefits you've built through iteration. Please don't feel pressured by this suggestion - I'm simply sharing what I've learned about Claude's tendencies and characteristics while working together.

Desktop Commander has enabled me to accomplish so much with Claude, and will continue to do so. The moment I first used the edit_block function - I'll never forget that sense of wonder. That's why I'm always grateful to the DC team, and I sincerely wish you continued success.

[Zate]

I like the idea of slimming down token usage in MCP tool descriptions, it is a big problem all over the place.

i like your example, but here is my question, how can we measure whether the tool usage is just as effective, or even more effective after the change? it's not all about lower token counts, we want lower tokens and as effective or more effective tool use.

[Jaesun23]

Yes, I understand exactly what you mean. "Claude goes off track when instructions are too simple, but avoids them when they're too complex."

If you try to control Claude's behavior with hundreds of meticulously detailed rules in a comprehensive workflow, Claude will absolutely refuse to follow it. When I asked why, Claude told me it felt suffocated by too many rules and just shut down.

So what happens if you give Claude just a few key guidelines and let it fill in the rest with its expertise? Claude becomes incredibly confident, insisting it can do everything perfectly. But in practice, context limitations cause it to lose track mid-task, asking itself "What am I even doing here?" and then doing something completely unrelated. This gets worse and more inconsistent as projects grow larger.

The conclusion is frustratingly obvious but true: Claude produces its best results when given the right balance of structure and freedom.

That's why my proposed hybrid format (Pseudocode + Structure) was an attempt to find that balance: precise conditional logic for critical paths, combined with structured environment that naturally guides Claude's behavior, allowing autonomous capability within those boundaries.

For measurement, I think the most practical approach would be creating regression tests using the failure cases DC team has collected over time, then comparing Before/After performance.