register_printer

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

No annotations are provided, so the description carries the full burden. It discloses key behaviors: free registration, successful registration even with concurrency limits, printer targeting by name, and tier-based concurrency enforcement. It fails to specify side effects (e.g., connection attempts, failure modes in registration) or return format, which would be valuable given the lack of annotations. The mention of verify_connection providing a 'proof summary' hints at response structure but doesn't fully cover all behaviors.

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?

The description is long but densely informative. It front-loads purpose, then explains tier logic in a clear two-paragraph structure, then details args in a bullet-like list. That said, the tier discussion is somewhat verbose — the first two paragraphs could be tightened while preserving key points. The parameter list is efficient with examples and context. Overall, the length is justified by the tool's complexity, but a few sentences could be trimmed.

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?

Given 10 parameters with 0% schema coverage, no output schema, and complex tier logic, the description is fairly complete — it covers all parameter semantics, tier implications, and post-registration capabilities. However, it lacks details on failure scenarios (e.g., connection timeout, invalid credentials) and does not explicitly state the return value structure, though verify_connection hints at a summary. For a registration tool, it might also mention whether duplicate names are rejected or how the fleet state is updated. Still, it's stronger than many tool descriptions.

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 for all 10 parameters. It does an excellent job: explains host meaning for USB (port path), api_key requirements per type (required for OctoPrint/Bambu, optional for some, unused for USB), serial needs for Bambu, verify_ssl behavior including TLS pin mode mapping, baudrate defaults and caveats (Marlin boards at 250000), and persist semantics. The only minor gap is printer_model's deeper purpose ('safety/profile key') which is a bit vague, but overall it adds substantial meaning beyond the schema.

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 description clearly states the tool registers a printer into a fleet, with a specific verb ('register') and target resource ('printer in the fleet'). It also includes scope details like naming and targeting by printer_name, distinguishing it from sibling tools like set_printer_light, discover_printers, and printer_status. The first line 'Register a new printer in the fleet' is direct and unambiguous.

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?

The description explicitly addresses when to use this tool versus alternatives, including tier-based rules (Free/Pro run 1 printer at a time, Business starts at 3, Enterprise uncapped) and notes that registration always succeeds even when concurrency limits exist. It also clarifies that targeting by name is available at every tier, while fleet_status is Business+ — providing explicit context for when this tool applies and what alternatives exist.

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