photoshop_guard_cycle_auto

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

With no annotations, the description still discloses real behavioral traits: it is a stateful review loop requiring previous_operation_id + previous_observation at the critic checkpoint, returns a job_id that must be polled, mutates through bounded passes with document_id pinning that must never be removed, and that a decision-loop stall is advisory rather than a mutation blocker. It does not describe the returned payload shape, failure/rollback semantics, or what 'report the exact blocker' yields.

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?

A long run-on block of imperative fragments and policy that is not front-loaded with what the tool does; the tool's own name appears mid-paragraph after session routing rules. Much of the content (focus permission etiquette, imagegen prohibition) is session policy that does not belong in a single tool's description and dilutes the callable contract.

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 a very complex, stateful tool with no annotations and no output schema, the description does cover the review-closure protocol and the polling handoff, which is the hardest part. But it leaves the return value, error surface, and the choice between the two large input modes unexplained, and spends its budget on cross-tool policy instead.

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 67% across 6 heavily nested top-level parameters, so the schema does substantial work. The description adds the crucial sequencing semantics (previous_operation_id + previous_observation with optional next_pass; critic_review at its checkpoint) and document_id pinning, but never explains the painting_intent vs next_pass split or when each of the two mutually-shaped entry modes is required.

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 operative sentence, 'Draw through photoshop_guard_cycle_auto,' does identify this as the execution/dispatch tool for a bounded painting pass, and 'one bounded semantic pass, not an entire artistic stage' hints at scope. But the opening frames it as session-wide routing policy ('When the user requests PaintPilot Photoshop/MCP drawing...') rather than stating 'submits one Guard painting pass and returns a job to review', so an agent must infer the core verb+resource from a parenthetical.

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 sequences siblings: start with photoshop_get_state, use photoshop_guard_resume for interrupted runs, discover photoshop_set_active_document via photoshop_guard_capabilities, fetch images via photoshop_guard_review_image and poll job_id via photoshop_guard_job_poll. It also states prohibitions (no external imagegen, no silent focus switching). It lacks explicit routing versus other dispatch-adjacent siblings like photoshop_guard_lint_next_pass.

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