ps_catalog

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 disclose the return shape in both modes: categories with counts and operation names when `category` is omitted, versus full parameter lists for one category. It doesn't explicitly state read-only safety or any limits, but 'List' strongly implies a side-effect-free inspection call.

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?

Four short clauses, front-loaded with the core action, then the two modes, then the usage trigger. Every sentence adds a distinct decision-relevant fact with no filler.

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 must explain returns, and it does for both modes (counts and names vs. per-operation parameters). For a single optional-parameter listing tool that is nearly complete; only the exact response format/pagination is unspecified.

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% and the enum-like category list is already in the schema, so the baseline is 3. The description adds real meaning the schema does not: what omitting `category` produces versus what supplying it produces, which is the key semantic decision for this parameter.

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 ('List Photoshop operations') and explicitly scopes it to operations available through ps_do, which distinguishes it from the executor sibling. An agent can tell immediately that this is the discovery/introspection tool, not an execution tool.

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?

Gives an explicit trigger condition: 'Call it before using an operation you have not used in this session,' which names both when to use it and the implicit alternative (skip it for already-used operations). The with/without `category` branching further tells the agent which variant to choose based on need.

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