# Michat Context Aware Tool Design

> Design or revise MiChat toolsets/tools for unambiguous contracts, strict scope gating, and context-efficient outputs. Use when adding new toolsets/tools, changing tool schemas/outputs, debugging tool misuse or context bloat, or refactoring toolset boundaries.

- Skill: `filmicgaze/michat-context-aware-tool-design` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add filmicgaze/michat-context-aware-tool-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/filmicgaze/michat-context-aware-tool-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: filmicgaze (https://skillmd.com/u/filmicgaze)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/filmicgaze/michat-context-aware-tool-design

---


# MiChat Tool Design (Context-Aware)

MiChat tools are contracts for a non-deterministic caller. Constrain capability and scope, not reasoning.

## Core principles

1. Profiles are worlds  
   Treat tool availability as profile-scoped. Only expose tools from enabled toolsets (plus always-on core/scratchpad).

2. Bounded capability  
   Give every tool a hard blast radius (root folder, allow-list, API scope). Prefer "unavailable unless configured" to "available but be careful."

3. Navigate before ingest  
   Design tools so the agent can target information before pulling large text into context (search -> section -> slice, cursor/pagination, stable IDs).

4. Context-safe by default  
   Default outputs to minimum sufficient structure: IDs, counts, short snippets, and navigation hints. Avoid dumping large artifacts by default.

5. Workspace for large artifacts  
   When full text is needed for editing/review, route it to a workspace surface (scratchpad) and return a stub + metadata to the model.

6. Verbosity is explicit  
   When outputs can be large, add explicit controls:
   - format: "concise" | "detailed" (or "summary" | "full")
   - fields: request subsets when helpful
   - max_chars / max_items + cursor/start for continuation  
   Default to the smallest practically useful payload; require explicit opt-in for full or high-volume outputs.

7. Schema stability (tool arguments)  
   Never define an argument as `type: object` with empty/no `properties`. Provide at least a minimal property set, even if you allow extra keys via `additionalProperties`, or the field may be dropped from model-visible schemas.

8. Errors must enable recovery  
   Make errors actionable: what was invalid/missing, expected format, and whether retrying helps (rate limits, transient errors). Avoid generic failures.

## Tool description template (MiChat style)

Tool descriptions are contracts, not mini-skills. Keep them clear and functional; put workflow and judgment in skills.

A good description answers:
- What it does (specific, non-vague)
- When to use it (trigger conditions)
- Inputs (what they control; defaults)
- Outputs (shape; what format/verbosity changes; truncation behavior)
- Errors (names + recovery hints)
- Safety boundary (scope gate; what it cannot do)

Keep descriptions short and information-dense. If guidance applies to multiple tools, put it in a skill. Avoid overlapping tool purposes.

## Toolset design (toolsets + primitives + skills)

Keep each toolset coherent with a clear domain and blast radius. Keep tools as primitives with non-overlapping contracts; use skills to teach sequencing and judgment.

Consolidate only when it removes real ambiguity:
- If a human cannot confidently pick between two tools, the agent will not either.
- If a split workflow is repeatedly misused, bundle it into a clearer primitive.

Prefer pipelines of distinct intent (e.g., parse -> search -> commit). Avoid near-duplicate tools that differ only by naming or subtle behavior.
Toolsets must not import other toolsets; resolve dependencies at runtime via `get_toolset_module`.

## Toolset docs

When adding or modifying a toolset, ensure `toolsets/<toolset_id>/TOOLSET.md` exists and is updated to the canonical format.

## Output policy (model vs transcript vs workspace)

When outputs can be large, prefer a three-channel model:

A) Model payload (default)
- concise, structured, navigational
- stable IDs and "where to zoom next"

B) Transcript/details payload (optional)
- human-readable audit
- still bounded

C) Workspace payload (when needed)
- full artifact in scratchpad (or other UI)
- tool returns a stub/receipt to the model

Use this pattern for long docs, large lists, and heavyweight state inspection.

## Hard caps (robustness)

If output could be large enough to swamp context or UI, implement hard caps with truncation + continuation. Prefer:
- truncated=true + cursor/start token
- clear guidance on how to continue

## Naming and conventions

- Tool names: verb_noun, consistent across toolsets
- Parameters: consistent names (path, query, top_k, max_chars, format)
- Return fields: consistent keys (items, count, next_cursor, truncated, summary)
- Avoid cryptic abbreviations

## Testing / verification (smoke test)

For each new or changed tool, do:
- 1-2 happy-path calls
- 1 failure case (missing gate / invalid input)
- 1 large-output case (confirm truncation / format controls)
- check unintended exposure for profiles that do not enable it

## Anti-patterns to avoid

- Dumping full objects into model context by default
- Overlapping tools with unclear choice
- Side effects at import time (toolsets should be definition-only on import)
- "Safety" implemented as reasoning constraints instead of capability scoping
- Silent destructive edits (writes without clear intent / preview)