photoshop_get_state

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

No annotations are provided, so the description carries the full burden, and it does declare the key behavioral trait: the call reads state 'without mutation.' The fail-closed behavior on document_id mismatch and the refusal to auto-switch tabs are documented only in the schema parameter description, and the description says nothing about error modes or what the returned state contains beyond the phrase 'document/layer/selection state.'

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 text is dominated by workflow policy that belongs to other tools (drawing via guard_cycle_auto, imagegen prohibition, decision-loop stalls, capability discovery), while this tool's own definition is a single trailing sentence. The structure is also back-loaded: the purpose appears last, after several paragraphs of unrelated directives, so the reader must scan to the end to learn what the tool does.

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 one-optional-parameter read tool with 100% schema coverage and no output schema, the essentials (purpose, when to start with it, non-mutating nature) are present. But the description spends most of its length on policies that do not govern this call, and it describes the returned state only as a three-word enumeration, leaving the agent to infer what 'state' actually includes.

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 100% for the single optional document_id, including the fails-closed semantics and the no-auto-switch guarantee, so the schema already does the work. The description adds no parameter-level detail beyond implying a 'confirmed target' is reused. Baseline 3 is appropriate.

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 closing sentence states a concrete verb and resource set: 'Read current document/layer/selection state without mutation; establish or recover the document target.' That distinguishes it from siblings like photoshop_list_documents and photoshop_guard_resume. However, the actual purpose is buried at the end of a paragraph dominated by orchestration policy, so an agent must read through unrelated instruction text to find it.

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?

Explicitly says to start here to establish the document, names the alternative for the interrupted-run case (photoshop_guard_resume), and instructs reuse of an already confirmed target. It also names the next step (photoshop_guard_cycle_auto) and the authorization condition for document switching. The only weakness is that this guidance is entangled with policy for many other tools rather than kept to this one's decision point.

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