catalog_preview_notification_config

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

Annotations declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the agent knows this is a non-destructive POST — but the critical behavioral question for a "preview" endpoint is unanswered: does it mutate or persist anything, and does it deliver a real notification? That ambiguity is sharpened by the sibling catalog_send_test_notification. The description adds nothing beyond the URL.

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?

Two lines, no padding, and purpose is front-loaded — but one of those lines is the raw endpoint, which duplicates the annotations title and consumes space that should have carried usage or behavioral context. Concise but not efficiently allocated.

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?

With no output schema, the description owes the agent an explanation of what a preview returns (rendered subject/body? validation errors?), and that is entirely absent. Combined with a nested body parameter and no mutation/return semantics, an agent cannot call this confidently without guessing.

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 100% — scenarioId is documented as a path parameter and the nested body object documents subject/body, with `data` left as a free-form object. The description contributes only the path template, so the schema does essentially all the semantic work; baseline 3 applies.

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 verb ("Preview") and resource ("Notification Scenario Config") and echoes the HTTP endpoint, so the general purpose is inferable. But "preview" is never explained — it does not say whether it renders a notification body/subject for inspection or actually dispatches something, and it does nothing to distinguish itself from siblings like catalog_send_test_notification or catalog_get_scenario_config.

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?

There is no when-to-use guidance at all: no preconditions, no statement of when a preview is appropriate versus fetching the stored config (catalog_get_scenario_config) or sending a test notification (catalog_send_test_notification). Only the raw POST path is given, which the agent must reverse-engineer into usage rules.

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