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)