Clearvoyance

Launch a campaign

launch_campaign

Creates the campaign and makes it live at once, charging its flat price from your balance (quote_campaign tells you the price). open_link returns shareUrl — the link to put in front of the people you want to hear from; it closes at responseCap or on expiry. targeted sends one invitation per address in cohortEmails from clearvoyance.ai (a sandbox account gets inviteLinks back instead and nothing is emailed). The flat price for the campaign's size is charged from your balance in full at launch, whatever it receives; it is not refunded for fewer answers. Refused with INSUFFICIENT_BALANCE (shortfallCents) if the balance does not cover the tier, or INVALID_CAMPAIGN (problems[]) if the quote would fail.

Input Schema

TableJSON Schema

Name	Required	Description
`kind`	Yes	open_link: a share link anyone can answer, closing at responseCap — put it in your own post-purchase email. targeted: we email one invitation per address in cohortEmails.
`title`	Yes	Shown to participants, e.g. 'How was your order?'
`apiKey`	Yes	Your Clearvoyance API key (cv_live_… or cv_test_…), from create_account
`giftText`	No	Shown to a participant after answering: a promo code, a thank-you, a link. Optional.
`questions`	Yes	1–10 questions participants answer by voice or text. No links or phone numbers.
`minPercent`	No	targeted only: results unlock once this share of the list has answered. Floored at 50.
`senderName`	No	Who is asking, as participants see it (your shop or product name). Required for open_link.
`description`	Yes	What you want to learn. Steers the AI analysis; participants do not see it.
`responseCap`	No	open_link only: 10, 50, 100 or 200 — the link closes at that many answers. Sets the tier: $4.99 / $17.99 / $29.99 / $49.99.
`cohortEmails`	No	targeted only: the addresses to invite (10–200). Duplicates are folded. The list is discarded once every invitation is queued; only hashes are kept.
`expiresInDays`	No	1–42. Default 14 for open_link, 7 for targeted.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`ok`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedSep 27, 2026

TDQS

A4.7/5.0

Behavior5/5

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

The description goes well beyond the annotations: it discloses immediate live activation, full non-refundable balance charge, sandbox behavior (inviteLinks instead of emails), and the specific error payloads INSUFFICIENT_BALANCE (shortfallCents) and INVALID_CAMPAIGN (problems[]). These are exactly the side effects an agent must know.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded: the core launch-and-charge action is in the first sentence. Subsequent sentences each add a distinct piece of behavior (modes, payment, errors) without filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-param, output-schema-backed tool, the description covers the essential behavioral contract: payment, non-refundability, sandbox mode, and error conditions. Combined with the full schema and output schema, an agent has everything needed to call and interpret the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining how kind maps to different behaviors (shareUrl vs emailed invitations), that responseCap closes the link, and that cohortEmails are used per-address – meaning beyond the bare schema definitions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Creates the campaign and makes it live at once, charging its flat price from your balance', naming the specific verb, resource, and immediate effect. It further distinguishes open_link vs targeted behavior and references quote_campaign for pricing, which separates it from sibling create_campaign and quote_campaign tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly points to quote_campaign as the price source, implying a prerequisite call, and clarifies the two modes (open_link vs targeted). However, it does not explicitly name alternatives like create_campaign for draft creation or validate_campaign for pre-flight checks, leaving the when-not-to-use guidance implicit.

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

All Clearvoyance tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?