Slim Mode & Output Verbosity

← Back to Index

Optimize context usage with two complementary modes that reduce token consumption by up to 75% while maintaining full functionality.

Overview
Tool Selection (Slim Mode)
Output Verbosity
Configuration
Migration Guide

Overview

The HacknPlan MCP server supports two optimization strategies:

Tool Selection (HACKNPLAN_SLIM_MODE): Reduce tool count from 89 → 26 (~71% reduction)
Output Verbosity (HACKNPLAN_OUTPUT_VERBOSITY): Reduce response size while adding quick-access index

Combined impact: ~75% token reduction for typical workflows

When to Use Each Mode

Scenario	Tool Selection	Output Verbosity
Development & Prototyping	Full (89 tools)	Full (complete objects)
Production API Integration	Full (89 tools)	Slim (minimal + index)
Interactive CLI Usage	Slim (26 tools)	Slim (minimal + index)
Tight Token Budgets	Slim (26 tools)	Slim (minimal + index)
Advanced Features Needed	Full (89 tools)	Either

Tool Selection (Slim Mode)

Control which tools are loaded into the MCP interface.

Full Mode (Default): 89 Tools

Complete API coverage including:

✅ All CRUD operations for every entity type
✅ Advanced batch operations
✅ Metadata management (create stages, categories, tags)
✅ File attachments
✅ Time tracking and dependencies
✅ Template systems
✅ Advanced search and queries

Slim Mode: 26 Core Tools

Essential operations only (~71% reduction):

✅ Core CRUD: Projects, boards, work items, design elements
✅ Essential queries: List, get, search
✅ Workflow shortcuts: start_task, complete_task, create_subtask
✅ Configuration: List stages, categories, tags, users
✅ Deletion and recovery tools

Excluded from Slim Mode:

❌ File attachments
❌ Metadata creation (stages, categories, custom tags)
❌ Advanced batch operations
❌ Template systems
❌ Milestone management (create/update)
❌ Board/project closing/reopening

Tool List Comparison

Slim Mode (26 Tools)

Projects & Boards:

list_projects, get_project
list_boards, get_board, create_board

Work Items:

list_work_items, get_work_item
create_work_items, update_work_items, delete_work_items
search_work_items

Design Elements:

list_design_elements, get_design_element
create_design_elements

Configuration:

list_stages, list_categories, list_tags
list_importance_levels, list_users

Workflow Shortcuts:

start_task, complete_task, create_subtask
get_my_current_tasks

Deletion & Recovery:

recover_deleted_items
get_deletion_cache_stats, export_deletion_cache, import_deletion_cache

Queries:

get_sprint_summary, get_sprint_progress

Full Mode Only (Additional 63 Tools)

Extended CRUD:

create_project, update_project, delete_project
update_board, delete_board, close_board, reopen_board
update_design_element, delete_design_element

Metadata Management:

create_stage, update_stage, delete_stage
create_category, update_category, delete_category
create_tag, update_tag, delete_tag

Milestones:

create_milestone, update_milestone, delete_milestone
close_milestone, reopen_milestone

File Attachments:

list_attachments, upload_attachment, download_attachment, delete_attachment

Advanced Batch:

Individual setters (tags, assignments, parents, design elements)
Batch log work

Templates:

list_templates, create_from_template

Output Verbosity

Control the detail level of list operation responses.

Full Mode (Default): Complete Objects

Returns all fields for each item:

{
  "items": [
    {
      "workItemId": 2,
      "title": "[Hybrid Pipeline] Design ray marching integration",
      "description": "Design integration of ray marching with hybrid pipeline",
      "categoryId": 5,
      "categoryName": "Design",
      "stageId": 12,
      "stageName": "Planned",
      "estimatedCost": 8,
      "assignedUsers": [],
      "tags": [],
      "boardId": 650299,
      "boardName": "Sprint 2: Rendering Pipeline",
      "createdAt": "2025-01-15T10:30:00Z",
      "updatedAt": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 131,
  "offset": 0,
  "limit": 50,
  "hasMore": true
}

Pros:

Complete information in single request
No additional lookups needed
Ideal for comprehensive dashboards

Cons:

Higher token usage
Redundant fields for simple operations

Slim Mode: Minimal Fields + Quick-Access Index

Returns essential fields plus full dataset index:

{
  "items": [
    {
      "workItemId": 2,
      "title": "[Hybrid Pipeline] Design ray marching integration",
      "categoryName": "Design",
      "stageName": "Planned",
      "estimatedCost": 8,
      "assignedUsers": []
    }
  ],
  "totalCount": 131,
  "index": [
    [2, "[Hybrid Pipeline] Design ray marching integration"],
    [3, "[Hybrid Pipeline] Implement RT resource binding"],
    [4, "[Data Pipeline] Run benchmark on current impl"],
    ... // All 131 items as [id, title] pairs
  ]
}

Key Features:

Minimal Item Fields:
- workItemId, title, categoryName, stageName
- estimatedCost, assignedUsers
- Removes: description, dates, full tag objects, board objects
Quick-Access Index:
- [[id, title], ...] for ALL items (not just current page)
- Enables instant ID lookup without pagination
- Solves "opaque pagination" problem

Example Usage:

const result = await callTool('list_work_items', {
  projectId: 230954,
  verbosity: 'slim',
  limit: 10
});

// Items: 10 work items with minimal fields
console.log(result.items.length);  // 10

// Index: All 131 items as [id, title]
console.log(result.index.length);  // 131

// Find specific task by partial title
const task = result.index.find(([id, title]) =>
  title.includes('ray marching')
);
console.log(`Found task #${task[0]}: ${task[1]}`);

Pros:

~60% token reduction on responses
Full dataset visibility via index
Instant ID lookup for all items
Reduced network transfer

Cons:

Requires additional get_* call for full details
Index overhead for very small result sets (<10 items)

Configuration

Enable Slim Tool Mode

# CLI Configuration
claude mcp add hacknplan -s user \
  -e HACKNPLAN_API_KEY=your-key \
  -e HACKNPLAN_SLIM_MODE=true \
  -- node /path/to/hacknplan-mcp/dist/index.js

Or manually in ~/.claude.json:

{
  "mcpServers": {
    "hacknplan": {
      "command": "node",
      "args": ["/path/to/hacknplan-mcp/dist/index.js"],
      "env": {
        "HACKNPLAN_API_KEY": "your-api-key",
        "HACKNPLAN_SLIM_MODE": "true"
      }
    }
  }
}

Enable Slim Output Verbosity

# CLI Configuration
claude mcp add hacknplan -s user \
  -e HACKNPLAN_API_KEY=your-key \
  -e HACKNPLAN_OUTPUT_VERBOSITY=slim \
  -- node /path/to/hacknplan-mcp/dist/index.js

Or in ~/.claude.json:

{
  "env": {
    "HACKNPLAN_API_KEY": "your-api-key",
    "HACKNPLAN_OUTPUT_VERBOSITY": "slim"
  }
}

Recommended: Combined Configuration

Maximum context efficiency (~75% reduction):

claude mcp add hacknplan -s user \
  -e HACKNPLAN_API_KEY=your-key \
  -e HACKNPLAN_SLIM_MODE=true \
  -e HACKNPLAN_OUTPUT_VERBOSITY=slim \
  -- node /path/to/hacknplan-mcp/dist/index.js

Or in ~/.claude.json:

{
  "mcpServers": {
    "hacknplan": {
      "command": "node",
      "args": ["/path/to/hacknplan-mcp/dist/index.js"],
      "env": {
        "HACKNPLAN_API_KEY": "your-api-key",
        "HACKNPLAN_SLIM_MODE": "true",
        "HACKNPLAN_OUTPUT_VERBOSITY": "slim"
      }
    }
  }
}

Per-Request Verbosity Override

Override global setting for specific requests:

// Global: HACKNPLAN_OUTPUT_VERBOSITY=slim

// Request full output for this call only
const fullDetails = await callTool('list_work_items', {
  projectId: 230954,
  verbosity: 'full'  // Override
});

// Request slim output (explicit)
const slimResults = await callTool('list_work_items', {
  projectId: 230954,
  verbosity: 'slim'
});

Migration Guide

Switching to Slim Mode

Step 1: Audit Tool Usage

Identify which tools you're currently using:

// Check your codebase for callTool() invocations
grep -r "callTool\(" .

Step 2: Check Slim Mode Coverage

Review 26 core tools list above. If all your tools are covered, you're good to go!

Step 3: Update Configuration

Add HACKNPLAN_SLIM_MODE=true to your environment.

Step 4: Restart Server

# Restart MCP server
claude mcp restart hacknplan

Handling Missing Tools

If you request a tool not available in slim mode:

Error: Tool "upload_attachment" is not available in slim mode (26 core tools).

This tool requires full mode (89 tools). To enable it:

1. Stop the MCP server
2. Update your configuration:
   claude mcp add hacknplan -s user \
     -e HACKNPLAN_API_KEY=your-key \
     -e HACKNPLAN_SLIM_MODE=false \
     -- node /path/to/hacknplan-mcp/dist/index.js

Or remove HACKNPLAN_SLIM_MODE to use full mode by default.

Core tools: Projects, boards, work items, design elements, queries, workflow shortcuts.
Full tools: +Attachments, batch operations, metadata management, advanced features.

Solutions:

Switch to full mode temporarily
Use alternative core tools (if available)
Stay in full mode permanently

Adapting to Slim Output

Before (Full Mode):

const items = await callTool('list_work_items', { projectId: 230954 });

items.items.forEach(item => {
  console.log(item.description);  // Full description available
  console.log(item.createdAt);    // Timestamp available
});

After (Slim Mode):

const items = await callTool('list_work_items', {
  projectId: 230954,
  verbosity: 'slim'
});

// Slim fields only
items.items.forEach(item => {
  console.log(item.title);  // ✅ Available
  console.log(item.categoryName);  // ✅ Available
  // item.description  // ❌ Not in slim mode
});

// Use index for ID lookup
const taskId = items.index.find(([id, title]) =>
  title.includes('OAuth')
)?.[0];

// Fetch full details if needed
if (taskId) {
  const fullItem = await callTool('get_work_item', {
    workItemId: taskId
  });
  console.log(fullItem.description);  // Full details
}

Best Practices

When to Use Slim Tool Mode

✅ Use Slim Mode For:

Interactive CLI workflows
Budget-constrained API integrations
Simple task management (create, list, update)
Read-only querying and reporting

❌ Use Full Mode For:

File attachment management
Custom metadata creation
Advanced batch operations
Template-based workflows

When to Use Slim Output

✅ Use Slim Output For:

Large result sets (>50 items)
ID lookup and filtering
Dashboard overviews
List-and-select workflows

❌ Use Full Output For:

Single-item queries
Comprehensive reports
When all fields needed immediately
Small result sets (<10 items)

Hybrid Approach

Combine both modes for optimal efficiency:

// Step 1: List with slim output (fast, low tokens)
const tasks = await callTool('list_work_items', {
  projectId: 230954,
  verbosity: 'slim',
  limit: 100
});

// Step 2: Use index to find specific task
const targetId = tasks.index.find(([id, title]) =>
  title.includes('Authentication')
)?.[0];

// Step 3: Fetch full details for selected item only
const fullTask = await callTool('get_work_item', {
  workItemId: targetId
});

// Now have complete details for one task, used minimal tokens

See Also:

Tool Search Guide - Claude API tool search optimization
Array-Based API - Unified batch operations
Configuration Guide - Environment variables

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Slim Mode & Output Verbosity

Table of Contents

Overview

When to Use Each Mode

Tool Selection (Slim Mode)

Full Mode (Default): 89 Tools

Slim Mode: 26 Core Tools

Tool List Comparison

Slim Mode (26 Tools)

Full Mode Only (Additional 63 Tools)

Output Verbosity

Full Mode (Default): Complete Objects

Slim Mode: Minimal Fields + Quick-Access Index

Configuration

Enable Slim Tool Mode

Enable Slim Output Verbosity

Recommended: Combined Configuration

Per-Request Verbosity Override

Migration Guide

Switching to Slim Mode

Handling Missing Tools

Adapting to Slim Output

Best Practices

When to Use Slim Tool Mode

When to Use Slim Output

Hybrid Approach

FilesExpand file tree

slim-mode.md

Latest commit

History

slim-mode.md

File metadata and controls

Slim Mode & Output Verbosity

Table of Contents

Overview

When to Use Each Mode

Tool Selection (Slim Mode)

Full Mode (Default): 89 Tools

Slim Mode: 26 Core Tools

Tool List Comparison

Slim Mode (26 Tools)

Full Mode Only (Additional 63 Tools)

Output Verbosity

Full Mode (Default): Complete Objects

Slim Mode: Minimal Fields + Quick-Access Index

Configuration

Enable Slim Tool Mode

Enable Slim Output Verbosity

Recommended: Combined Configuration

Per-Request Verbosity Override

Migration Guide

Switching to Slim Mode

Handling Missing Tools

Adapting to Slim Output

Best Practices

When to Use Slim Tool Mode

When to Use Slim Output

Hybrid Approach