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 value is the conditional requirement that workspace-scoped prompts need is_custom=True alongside workspace_id — a non-obvious behavioral rule an agent would otherwise get wrong. It does not discuss result size or pagination, but an output schema exists to cover return shape.

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 numbered breakdown per request mode, with the scoping constraint attached to the mode it applies to. Every sentence carries new information and the structure mirrors how an agent must choose a branch.

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 5-parameter, two-mode tool this covers the decision points well, and the read-only annotation plus the output schema relieve it of explaining safety and return values. The remaining hole is the undocumented allowed values of prompt_type, which an agent may need to filter the menu correctly.

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 carries the full burden and largely discharges it: it explains both request values, ties prompt_id to the details mode, ties is_custom and workspace_id to workspace prompts, and marks workspace_id and prompt_type as optional filters for the menu. It falls short only on prompt_type, whose accepted values are never 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?

The description names a specific verb and resource ("Browse the Klaviyo prompt catalog") and immediately enumerates the two operating modes: 'menu' for listing public/system prompts and 'prompt_details' for fetching a prompt body. That contrast makes the tool's scope unambiguous. It does not explicitly contrast with siblings (execute_action, query_contexts, query_data), but those are conceptually distant enough that the gap is minor.

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?

Each enum value is paired with a condition: use 'menu' to list, use 'prompt_details' with prompt_id to fetch a body, and add is_custom=True + workspace_id for workspace prompts. This is effectively when-to-use guidance at the mode level. There is no stated guidance about when not to use this tool or what to use instead, which keeps it below 5.

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