tc_set_mode

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

Annotations only declare idempotent/not-destructive/not-readonly; the description adds the substantive policy that escalation is capped at max_mode and must be confirmed so an agent cannot silently widen its own permissions. It stops short of stating failure behavior when the cap is hit or what the tool returns on a refused escalation.

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?

Three tight clauses with the mode enumeration front-loaded and the escalation rule immediately after; no filler sentences and nothing repeated from the schema.

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?

An output schema exists so return values need not be described. The description covers mode values, the lowering/escalation asymmetry, the max_mode ceiling and the confirmation requirement — sufficient to call it correctly — with only minor gaps around denial behavior and token acquisition.

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 coverage is 0% and the mode property has no enum, so the description's inline enumeration 'readonly | guarded | full' is essential and does real work. It also explains confirm_token's role (confirmation on escalation), though it never says how to obtain one or its format.

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?

States a specific verb (Switch) and resource (safety mode) and enumerates the three valid states (readonly | guarded | full), which no sibling tool offers — tc_safety_status reads status and tc_allow_write is a different control surface. An agent can tell this apart from every sibling without opening the schema.

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?

Gives clear when-conditions: lowering is free, escalating requires confirmation via prompt or confirm_token and is bounded by max_mode. It does not, however, point to the sibling that produces the confirmation (e.g. tc_request_confirmation) or explain what to do when escalation is refused.

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