Token Calculator Suite has well-structured schemas and clear parameter types, but suffers from critical naming and description gaps. Tool names lack action verbs (calculateTokens, calculateFixedData, formatTokenResult are noun-heavy or ambiguous). Descriptions exist but are generic and lack WHEN/WHY guidance. No error handling documentation. Parameters are typed but descriptions are minimal. Output schemas are documented in TypeScript interfaces but not exposed in tool registration. The suite reads as a utility library, not an agent-optimized tool collection.

• Rename tools to start with action verbs: 'estimate_tokens' (instead of calculateTokens), 'estimate_fixed_overhead', 'estimate_conversation_tokens', 'estimate_file_tokens', 'format_token_estimate', 'convert_words_to_tokens', 'convert_chars_to_tokens'. This makes intent clear from the name alone.
• Expand descriptions to 100-150 characters with WHEN/WHY context. Example: 'Estimate total token usage for a conversation plus files. Use this for end-to-end cost/context planning. Returns min/max estimates with error margins and context window usage.'
• Add parameter constraints to descriptions. Example: 'messageCount: Number of messages (0 or positive integer). If negative, returns error.' 'language: Tokenization language (es=Spanish, en=English). Defaults to es if unrecognized.'
• Document error cases and recovery paths. Example: 'Throws error if messageCount, userWords, or assistantWords are negative or non-numeric. Retry with valid non-negative integers.'
• Expose output schemas in tool registration. Add a 'returns' field documenting the TokenCalculationResult structure: {totalTokens: number, minEstimate: number, maxEstimate: number, errorMargin: number, breakdown: {fixedData, conversationVisible, files, other}, contextUsage: {tokensUsed, tokensAvailable, percentageUsed}, confidence: 'high'|'medium'|'low'}.