Skip to content

Collapse configure's 36-property schema — it costs ~1.9k context tokens every session #2

Description

@jphein

Problem

MCP tool schemas are fixed per-session context overhead — they live in the model's system prompt for the entire session whether or not the tool is ever called. Measured via Claude Code's /context:

  • configure = 1.9k tokens — the single largest tool in the server
  • Whole speech-to-cli server = ~4.5k tokens
  • So configure alone is ~42% of the server's footprint

The schema enumerates 36 properties, each with a full description (key, region, tts_region, player, recorder, mic_source, all the chime_*, subtitle_color_*, barge_in_*, etc.).

Why it's avoidable

handle_request already treats configure as a generic key→value setter ("Pass any setting as a key-value pair to update it"). The 36-property schema is effectively documentation stored in the most expensive place possible — re-sent every session.

Proposal

  1. Replace the 36 enumerated properties with a single free-form object:
    {"settings": {"type": "object", "description": "Key→value settings to update. Call with no args to list all available settings + current values."}}
  2. Make configure() with no args return the full catalog (key, type, current value, one-line doc) — discovery moves to runtime, on demand.
  3. Move the per-key reference into README.md / docs/.

Impact

Reclaims ~1.7k tokens of always-on context (~90% of this tool). No behavior change — the handler already accepts arbitrary keys.

Filed from a context-footprint audit of the MCP tool surface.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions