AgentCost has 3 tools with basic schemas and descriptions, but significant gaps in parameter documentation, output schema clarity, and error handling. Tool names are descriptive (agentcost_preview, agentcost_analyze, agentcost_sample) but descriptions lack actionable context for LLM selection. The 'tier' enum in agentcost_analyze is well-constrained, but the 'logs' parameter in two tools lacks format guidance (JSONL structure, expected fields, size limits). No output schemas are documented, LLMs cannot predict response structure or plan downstream operations. Error handling is absent: apiRequest() returns raw API responses without recovery guidance. All three tools accept user-provided logs but lack input validation or injection safeguards.

• Document output schemas for all three tools. Specify the JSON structure returned (e.g., {cost_breakdown: {model: string, tokens: number, ...}, top_expensive_turns: [...]}). This enables LLMs to extract and chain results.
• Enhance 'logs' parameter description: 'JSONL session log content from ~/.claude/projects/. Each line must be valid JSON with fields: timestamp, model, input_tokens, output_tokens, tool_calls. Max 10MB. Encoding: UTF-8.'
• Add error handling with recovery guidance. Catch API errors and return: {error: true, message: 'API error: <status>', recovery: 'Check logs format with agentcost_sample first, or try agentcost_preview for free analysis'}.
• Validate JSONL input: parse each line, check required fields, reject malformed JSON early with clear error messages. Prevent injection by rejecting lines with suspicious patterns.
• Clarify tool selection in descriptions. agentcost_preview: 'Use this first to see cost breakdown without payment.' agentcost_analyze: 'Use this for detailed waste detection and optimization recommendations (paid via x402).' agentcost_sample: 'Call this to see expected output format before uploading real logs.'