photoshop_guard_capabilities

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

With no annotations, the description carries the full burden and does so: it discloses the mutation-safety rule (discovered commands still run through photoshop_guard_cycle_auto, 'never a raw bypass'), caching/revision semantics (matching revision returns unchanged=true), error behavior ('Unknown names return guard_tool_contract_unknown with supported alternatives; incompatible argument modes are rejected'), and negative scope (does not paint, restart, or reconcile).

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 front-loaded and nearly every clause carries real information, but the body is a single dense run of semicolon-chained clauses that mixes return contents, caching policy, sibling disambiguation, and error behavior without structure. A reader must parse it repeatedly to extract the mode-selection rules.

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 four-parameter, zero-required discovery tool with no annotations and no output schema, the description is largely self-sufficient: it names the returned fields (Guard mode, protocol/runtime revisions, running deployment, command_sets, discovery_revision) and covers error and freshness paths. It stops short of describing the shape of a per-command contract response, which an agent must discover at call time.

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 coverage is 100%, so the schema already documents all four parameters thoroughly. The description still adds value by stating the tool_name/tool_names exclusivity and batching rationale, and by clarifying that if_revision should be used 'only for a deliberate recheck' and that it returns unchanged=true on a match. It adds the deployment_health exclusion rule ('omit tool names and if_revision') that the schema does not state, though most other detail duplicates schema text.

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 ('Discover Guard workflow/recovery rules and exact registered command contracts') and immediately scopes itself against siblings: 'this is not document readiness (photoshop_guard_status) or Photoshop version-derived feature flags (photoshop_get_capabilities).' It also distinguishes the execution path ('Mutating commands discovered here still run through photoshop_guard_cycle_auto'), so an agent can separate this from both status and capability-feature tools without opening a schema.

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 maps argument modes to situations: no arguments = full discovery, tool_name = one contract, tool_names = batch up to 8, deployment_health = 'after activation or a freshness blocker' with instructions to 'omit tool names and if_revision', and if_revision = 'only for a deliberate recheck.' It also names exclusions ('Does not paint, restart components or reconcile operations') and routes mutation execution to a specific alternative.

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