printer_status

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

With no annotations provided, the description carries the full burden and does so admirably. It discloses the exact return structure (printer, job, capabilities), how `lite` alters the payload, that both levels include 'every warning,' and rationalizes the design to prevent client confusion. This goes beyond generic statements and gives an agent a solid mental model of the tool's behavior.

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 well-structured with a clear opening, a 'Returns' section, and 'Args' explanations. It is longer than strictly necessary, especially the final paragraph explaining the history of `print_status_lite`, but that narrative directly supports understanding the `detail` parameter and avoids future confusion. Every sentence adds value, even if the historical note 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 there is no output schema and no annotations, this description is quite complete for a status tool. It covers what to expect in the response, how to interpret `detail`, and even mentions warnings. It could be slightly more exhaustive (e.g., elaborating on the 'warnings' field or edge cases), but for a first-call tool it provides all necessary context for an agent.

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?

Despite 0% schema description coverage, the description fully documents both parameters. It explains `printer_name` (omit for default) and `detail` (accepted values, defaults, and behavioral impact). It even clarifies the difference between 'full' and 'lite' with concrete examples of what is included/omitted, which is far more than the schema provides.

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 opens with a specific verb+resource ('Get printer state, temperatures, job progress, and capabilities') that clearly states what the tool does. It differentiates itself from siblings by mentioning it should be used as the 'first call' and explicitly contrasts itself with the retired `print_status_lite`, making its scope and positioning unmistakable.

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 explicitly says 'Use this as the first call to understand what the printer is doing,' providing clear when-to-use guidance. It also explains the `detail` parameter for 'frequent polling during a print' versus full inspection. However, it does not mention alternatives beyond the retired `print_status_lite`, so it lacks an explicit when-not-to-use or discussion of other sibling tools.

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