cassette_config

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden and handles it well: it discloses session-scoped persistence, effect timing (applies from the next run_job turn), the default (GPT-5.6 Luna with xhigh thinking), and the read-versus-write dual mode. Minor gaps remain, such as behavior on invalid model ids or partial-change semantics, but the operational behavior an agent needs to predict side effects is present.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Five sentences, roughly 70 words, with the trigger condition front-loaded in the second sentence and every sentence carrying load: purpose, when, how, persistence, default. There is no filler, no repetition of schema fields, and no wasted phrasing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a moderate-complexity config tool with an output schema, the description covers all operational essentials: trigger, both modes, parameter meaning, persistence, timing, and the default. The presence of an output schema covers return-value details, so nothing critical is missing for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, and it clarifies each parameter: session_id alone triggers view mode, model accepts 'id or label' (a format not present in the schema), and thinking_level is a changeable option with its enum values left to the schema. It adds mode-distinction semantics that the bare property names do not convey, though it stops short of giving concrete examples.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource framing ('On-demand model picker for the session') and narrows the scope with an explicit trigger: 'Call only when the user asks to view or change the Cassette model.' It distinguishes itself from execution siblings like cassette_run_job by describing the dual view/change behavior on the model configuration.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to invoke — 'Call only when the user asks to view or change the Cassette model' — and further branches by mode: with only session_id (view), or with model/thinking_level (change). It also gives timing context by noting the change 'applies from the next cassette_run_job turn,' connecting the tool to its execution sibling. No inference is required to select this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.