list-templates tool exceeds Claude Code's 25k token limit - returns 386k+ tokens without pagination support

[DivineFarm]

Description

The list-templates MCP tool returns responses that significantly exceed Claude Code's maximum token limit of 25,000 tokens, making the tool unusable. The response contains 386,560 tokens, which is over 15x the allowed limit.

Error Message

Error: MCP tool "list-templates" response (386560 tokens) exceeds maximum allowed tokens (25000). Please use pagination, filtering, or limit parameters to reduce the response size.

Steps to Reproduce

1. Install and configure the MCP server in Claude Code
2. Attempt to use the list-templates tool
3. The tool fails immediately with the token limit error

Expected Behavior

The list-templates tool should:

• Return a paginated response that stays within the 25k token limit
• Support optional limit and offset parameters for pagination
• Provide filtering options to reduce the result set
• Return template metadata by default with an option to fetch full details separately

Actual Behavior

The tool attempts to return all templates at once (386,560 tokens), causing an immediate failure in Claude Code.

Environment

• Claude Code Version: [Add your version - run claude --version]
• MCP Server Version: [Add version if available]
• Operating System: [Your OS]
• Context: Production environment with large template library

Proposed Solutions

1. Implement pagination (Recommended):

   {
     "limit": 50,  // Default to 50 templates per page
     "offset": 0,  // Starting position
     "include_content": false  // Return metadata only by default
   }

2. Add filtering options:

   {
     "filter": {
       "category": "construction",
       "search": "keyword",
       "date_range": "last_30_days"
     }
   }

3. Separate list and detail endpoints:

   • list-templates - Returns template IDs and metadata only
   • get-template-details - Fetches full content for specific template(s)

Impact

This issue makes the list-templates tool completely unusable in Claude Code, blocking our ability to browse and select templates programmatically.

Additional Context

• Claude Code has a hard limit of 25,000 tokens per MCP tool response ([Reference](Error: File content (28375 tokens) exceeds maximum allowed tokens (25000). Please use offset and limit parameters to read specific portions of the file, or use the GrepTool to search for specific content. anthropics/claude-code#4002))
• This limit applies regardless of the Claude model being used (Sonnet, Opus, etc.)
• Other MCP servers have successfully implemented pagination to work within this constraint

Workaround

Currently, there is no workaround as the tool fails before returning any data. Manual access to templates outside of Claude Code is required.