token-optimization

Token optimization

First inspect the current tool inventory. Use a named token-optimizer MCP tool only when that exact schema is visible; an installed plugin or MCP config is not proof that its server registered successfully. If the tool is absent, keep the native operation available, bound its output, and do not retry an unavailable schema.

When registered, these tools cache, diff, and bound context. The native hook refuses a built-in call only after positive registration evidence and injects applicable graph findings; the active model still makes every MCP tool call.

When to use which tool

• smart_read instead of a plain file read when a file is large (roughly >400 lines / >25 KB) or you have read it before this session. It caches file content and, on re-reads, returns only a diff of what changed — often a handful of tokens instead of the whole file. Pass path; optionally enableCache, diffMode, maxSize, includeMetadata.

• smart_glob instead of a content grep for finding files in a big or unfamiliar tree. It returns paths only (no content) with filtering, sorting, and pagination — a fraction of the tokens of listing with content. Pass pattern (e.g. src/**/*.ts) and optionally cwd, extensions, limit.

• smart_edit instead of a raw edit for large files: it applies the edit and returns a compact unified diff rather than echoing the whole file. (For very small files a plain edit is fine — smart_edit's diff overhead is only worth it once the file is sizeable.)

• optimize_session / get_session_stats when the context window is filling up or after a burst of file operations. optimize_session batch-compresses prior file operations and stores them out-of-context; get_session_stats reports tokens saved so far.

• get_optimization_report when the user asks how much they've saved (or to show it proactively). Returns total tokens saved, overall savings %, approximate cost saved, and a full breakdown by action, by hook phase, and by MCP server, plus a pre-rendered formatted text summary you can display as-is.