auto_recover

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

With no annotations, the description carries the full burden and largely does so: it discloses that the tool may command the printer (upload/start/pause/resume/set speed), that it is two-phase (proposes actions and runs nothing, then executes via run_actions=actions_digest), and that execution is delegated through Kiln's own tools with their checks. Gaps remain around reversibility and what happens to the in-progress job, but this is unusually rich for an unannotated tool.

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?

Purpose is correctly front-loaded and the two-phase instruction is tight, but the middle paragraph is largely promotional upsell (tier feature list plus an upgrade URL) that consumes a full paragraph without helping selection or invocation. The one operationally useful fact buried there, the Kiln Pro requirement, is stated ambiguously.

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 19-parameter, no-output-schema, no-annotation mutation tool, the description covers the execution model well but leaves the bulk of the input surface and the shape of the first-call 'actions' response unexplained. It is enough to understand the mechanism but not enough to drive the tool confidently on a first attempt.

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?

The description explains only run_actions (the actions_digest handshake); the other 18 parameters are unaddressed. The schema's nominal 63% coverage is misleading because most 'descriptions' are bare defaults (Default: ""), and the nested free-form objects (job_info, telemetry, plate_objects, failed_objects, telemetry_history, alternative_printers) have no semantic guidance anywhere. An agent cannot know what to supply for the core inputs like failure_id, job_info, or retry_mode.

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 sentence states a specific verb+resource ('recover a failed print') and adds a scope qualifier ('in one guided operation') that hints at consolidation versus the many multi-step siblings (plan_print_recovery, start_print_recovery, confirm_print_recovery). It is clear what the tool does, but it never names or contrasts with those siblings, so the agent must guess which recovery entry point applies.

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?

Usage is implied by the name and the failure context, and the third paragraph gives concrete invocation mechanics (first call proposes, second call executes). However, there is no explicit when-not guidance and no routing to alternatives among the dense recovery-tool cluster, so selection remains inferential.

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