photoshop_get_painting_method_capabilities

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

With no annotations, the description carries the full burden but does add real traits: the map is derived from tools actually registered in this runtime and unsupported methods are reported explicitly rather than fabricated. That is useful trust context, yet it says nothing about cost, side effects, or the fail-closed document-id verification behavior (which lives only in the schema).

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?

Two tight sentences, front-loaded with the action and resource, with the second sentence carrying the trust guarantee. No filler, though the phrasing is slightly abstract ('capability map derived from tools actually registered').

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?

There is no output schema, so the description is the only source on return shape, and 'capability map' is left unelaborated — an agent cannot tell whether it gets a list of method names, per-method flags, or metadata. Combined with the missing usage routing, it is adequate but leaves gaps an agent must probe at runtime.

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?

Only one optional parameter exists and the schema documents it at 100% coverage, including the fail-closed active-document check. The description contributes nothing about document_id, so the schema baseline of 3 applies.

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?

States a specific verb and resource: 'Return the executable painting-method capability map'. The 'painting-method' qualifier implicitly separates it from the generic photoshop_get_capabilities and photoshop_guard_capabilities siblings, but the description never names those alternatives, so the distinction is inferred rather than asserted.

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 only implied: an agent can infer it should call this before selecting a painting method, since the map tells it which methods are actually executable. There is no explicit when/when-not statement and no pointer to photoshop_select_painting_method or to the generic capability tools it overlaps with.

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