counterpart_print_route

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

The description discloses two things annotations do not: that 'Sends nothing to the printer' (the mutation is local, not a device command) and that the change 'is saved to the .env file in this server's working directory when that file exists (savedTo; null otherwise).' That explains the otherwise surprising destructiveHint=true on a tool about printer routing, so there is no contradiction. It does not say whether the .env write preserves unrelated entries or rewrites the file wholesale, leaving the precise blast radius of the destructive hint unstated.

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?

All of the content is substantive — return fields, side effects, route meanings — but it is delivered as one dense paragraph riddled with parentheticals and internal jargon ('counterpart/1', 'FULU's BambuNetwork bridge', 'BAMBU_DEFAULT_CONNECTION_MODE'). The read/write split, which is the single most important fact, is buried mid-paragraph rather than front-loaded, and ~130 words is heavy for a one-parameter tool.

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?

There is no output schema, and the description compensates by describing the returned shape (route, options, choices, mode, type, savedTo), which an agent would otherwise have to discover blindly. Side effects, persistence behavior, and the 'sends nothing to the printer' guarantee are all covered. The only gap is error behavior — what happens when a route is not choosable is hinted at via 'whether it can be chosen here (and why not)' but never spelled out.

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 100% and the schema already enumerates lan/cloud/developer, so the baseline is 3; the description goes beyond it by explaining what each enum value physically means (bridge vs. cloud vs. direct LAN in Developer Mode, and that Developer Mode Pause/Resume/Stop 'need no Bambu app') and by clarifying the omit-to-read behavior. It also previews the returned 'options' entries with 'whether it can be chosen here (and why not),' which tells the agent some values may be rejected.

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?

The opening clause identifies the resource precisely — 'how this server reaches the printer for prints and for Stop/Pause/Resume' — and the three route ids are enumerated, so an agent can tell this is the print-route control rather than a status or job tool. It loses a point because it never states the operation as a clean verb+object ('read or change the print route'); the reader must infer from 'Pass route to change it' and 'Omit to read it' that this is a combined getter/setter.

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?

It gives clear operational context: omit route to read, pass route to change, and the change 'applies to the next print and control at once,' which tells the agent the effect is immediate and persistent rather than scoped to a queued job. It also explains what each route value means (LAN bridge, Bambu Cloud, LAN Only + Developer Mode), which is the selection guidance an agent needs. It stops short of naming specific sibling tools to prefer when the intent is only diagnostic, so no exclusions are stated.

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