compare

Render two artifacts side-by-side with an optional A/B vote.

When to use

Call compare_create when the agent has two versions of something — two screenshots, two markdown variants, two diffs — and wants the user to pick one or just look at them together.

Example user prompts

• Show me both mockups side by side and let me vote.
• Compare the two screenshots before you choose one.
• Send me an A/B view of the old and new onboarding copy.

MCP tool signature

compare_create(
    a: ShareRef | bytes,
    b: ShareRef | bytes,
    project: str | None = None,
    kind: Literal['image', 'markdown', 'csv', 'diff', 'html'],
    question: str | None = None,
    allow_vote: bool = True,
) -> CompareHandle   # {compare_id, url, expires_at}

Example call

# Compare two design variants
a = upload_content(filename='v1.png', content_b64=img_a_b64)
b = upload_content(filename='v2.png', content_b64=img_b_b64)

result = compare_create(
    a={'share_id': a['id']},
    b={'share_id': b['id']},
    kind='image',
    question='Which button style do you prefer?',
    allow_vote=True,
)
print(result['url'])

Return value

Returns a CompareHandle with compare_id, url, and expires_at. When allow_vote=True, the page also completes like an ask — the agent can poll for the user's choice.

Credit cost

3 actions per create call.

Notes

When allow_vote=True and the user picks A or B, the result is accessible via get_decision(compare_id) — same pattern as ask.

Recipes

See all recipes for copy-paste patterns that use compare and other tools together.