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

readOnlyHint=true already tells the agent this is a safe read, so the description's added burden is modest. It does add useful scoping behavior (is_custom=True plus workspace_id selects workspace-scoped prompts), but says nothing about result volume, paging of the 'menu' listing, or visibility rules for 'public/system' versus private prompts.

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 single scoping sentence followed by two short numbered modes; the mode selector is front-loaded and there is no filler or repetition of schema types.

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?

An output schema exists, so return values need not be described, and most parameters are semantically covered. The definition is nearly complete for a read-only two-mode tool; only pagination/volume expectations and validation rules (what happens if prompt_id is omitted with request='prompt_details') are unaddressed.

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 0%, so the description must carry parameter meaning, and it largely does: both enum values of request are defined, prompt_id is tied to fetching a body, and is_custom/workspace_id/prompt_type are explained in terms of workspace prompts and optional filtering. Remaining gap is that prompt_type's allowed values and any coupling (e.g. is_custom required when workspace_id is set) are not stated.

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?

'Browse the Slack prompt catalog' names a specific verb and resource, and the two enumerated request modes clarify that it both lists and fetches prompt bodies. It is distinguishable from the generic siblings (query_data, query_contexts), though it never names them explicitly to reinforce the contrast.

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?

The numbered list gives clear intra-tool routing: use 'menu' to list, 'prompt_details' to fetch a body, with the workspace-prompt variant spelled out. However, there is no guidance on when to choose this tool over the sibling tools query_data/query_contexts/execute_action, so the cross-tool decision is left to inference.

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