ratel-improve-tools

Ratel Improve Tools

Goal

Use Ratel tool usage logs to propose practical improvements to the user's MCP tool setup. Focus on what the agent actually tried to do, where tool use failed or repeated, and which upstream MCP servers or Ratel configuration changes would reduce friction.

Do not print raw log entries unless the user explicitly asks. Treat logs as private local telemetry and redact secrets, tokens, request headers, file contents, and customer data in summaries.

Log Location

Read tool usage from:

${RATEL_HOME:-$HOME/.ratel}/tool-usage/tool-usage.jsonl

Each line is JSON with schemaVersion, timestamp, host, event, toolName, optional toolInput, optional outcome, and hook payload metadata. Handle missing files, empty files, and malformed lines gracefully.

If no logs exist, say that there is no tool usage data yet and suggest enabling/trusting the Ratel Local plugin hooks, then running normal agent work before trying again.

Analysis Workflow

1. Inspect recent logs first. Prefer a bounded window such as the last 500-2000 lines unless the user asks for a full history.
2. Parse JSONL structurally. Do not rely on ad hoc text matching when JSON parsing is available.
3. Group by toolName, host, event type, success/error signal, and repeated input patterns.
4. Compare the observed usage against configured Ratel scopes when useful:

~/.ratel/config.json
<project>/.ratel/config.json
<project>/.ratel/config.local.json

1. Run ratel-local retrieval status when capability-search quality is part of the problem. BM25 is the default; recommend semantic or hybrid retrieval only when the observed misses justify model setup, memory, and privacy tradeoffs.
2. Look for:

• high-frequency tools that deserve first-class upstreams, aliases, or better descriptions;
• repeated search_capabilities calls that do not lead to useful invoke_tool calls;
• failed or denied tool calls that indicate missing auth, missing tools, weak schemas, or bad defaults;
• direct non-Ratel Local tool usage that should be imported into Ratel;
• similar tools split across upstreams where a curated choice would reduce noise;
• workflows where a new MCP server, skill, or Ratel CLI helper would be more effective than another tool.