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

readOnlyHint=true is already declared by annotations, and 'browse'/'fetch' is consistent with it. The description adds that 'menu' returns public/system prompts and that workspace prompts require is_custom + workspace_id, which is real behavioral context. It says nothing about result size, pagination, or what happens if prompt_id is missing.

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 one-line purpose followed by a compact numbered mode list, front-loaded and free of filler. Every sentence carries actionable routing information.

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 no explanation, and the mode dispatch is fully covered. The remaining hole is the unconstrained prompt_type string and the implicit conditional requirement on prompt_id, which an agent could get wrong.

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 the load, and it does map most parameters to modes: workspace_id/prompt_type for menu and prompt_id/is_custom/workspace_id for prompt_details. Gaps remain for prompt_type (no enum, no valid values listed) and for the fact that prompt_id is effectively required in the second mode.

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: 'Browse the Stripe prompt catalog', with the two supported operations enumerated. It is clearly distinguishable from siblings like query_data or execute_action by virtue of being prompt-specific, though it never explicitly contrasts itself with them.

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 entries tell the agent which mode to use for listing versus fetching a body, and which parameters accompany each. It stops short of stating exclusions or prerequisites (e.g. when NOT to use this versus query_contexts).

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