Prompt Engineering Tips

How to phrase requests to get reliable, accurate tool usage from Claude + Pharlo.

Be specific about which channel

If you have multiple connections, always name the channel explicitly. When Claude calls list_connections, it picks the best match — an ambiguous name may cause a confirmation step or the wrong channel to be selected.

Less reliable	More reliable
"Upload this video to YouTube"	"Upload this video to my TechReviews YouTube channel"
"Post to Facebook"	"Post to the Acme Corp Facebook Page"
"Check my channel stats"	"Show subscriber count for my TechReviews channel"

To see all your channel names, ask: "What channels do I have connected?" — Claude will call list_connections and show you the full list.

Always state the privacy setting

⚠️

YouTube's default privacy in the API is private. If you don't specify, Claude will use this default — your video will be uploaded but not publicly visible. Always state the privacy explicitly.

Good examples:

"Upload this video as public"
"Schedule this as unlisted until the launch date, then I'll make it public manually"
"Publish this privately so I can review it in YouTube Studio first"

The create_assignment tool requires privacy to be set explicitly in the payload to override the default. When in doubt, Claude will ask — but it's faster to include it upfront.

Give timezone context upfront

State your timezone once at the start of a scheduling conversation:

"I'm in Kyiv (UTC+3 in summer). Schedule this video for Friday at 6 PM."

Claude will convert to the correct RFC 3339 offset (e.g. 2026-05-02T18:00:00+03:00) before calling create_assignment. Without timezone context, it will ask for clarification before proceeding.

For recurring schedules, stating it once at the start is enough:

"All times are Kyiv time (UTC+3). Schedule the first video for Monday at 10 AM, the second for Wednesday at noon, the third for Friday at 6 PM."

Provide the media URL directly

Claude cannot access your local file system. Always provide a publicly accessible direct download URL:

"Upload https://cdn.example.com/video.mp4 to my TechReviews channel"

⚠️

Google Drive and Dropbox share links are not direct download URLs — they open a web page, not the raw file. The platform API needs a link that resolves directly to the media bytes. Use a CDN, S3 presigned URL, or any public direct-download link.

If you paste a non-direct link, Claude will warn you and ask to confirm before proceeding, since the upload would likely fail.

Separate connect from publish

Connecting a channel via OAuth is a two-step process that requires you to open a browser and complete a consent screen. Keep it as a separate task from publishing:

Step 1 — Connect:

"Connect my second YouTube channel to Pharlo."

Claude calls get_oauth_connect_url, gives you a URL to open, and waits. After you complete the OAuth screen, ask Claude to run list_connections — the new channel should appear there.

Step 2 — Publish (new conversation or after confirmation):

"Now upload this video to the new channel."

Combining both steps in a single prompt can confuse the flow because publishing depends on the connection existing first.

See Workflows — Connect a new channel for the full step-by-step pattern.

Use idempotency keys for retries

If you ask Claude to retry a failed prompt (e.g. a network issue caused the conversation to cut off), there is a risk of duplicate assignments being created. Explicitly mention idempotency:

"Create this assignment — use idempotency key launch-video-2026-04-25 to prevent duplicates."

Claude will pass this key to create_assignment. If the same key is submitted again within 24 hours, the API returns the original assignment instead of creating a new one.

Confirm before destructive actions

For cancellations or privacy changes on already-public content, add explicit intent so Claude understands the action is intentional:

"Cancel the scheduled video I set up for this Friday — I want to move it to next week."

"Change the privacy of the video I uploaded yesterday to private."

Claude will confirm before calling cancel_assignment, since it is marked destructive in the tool definition.

Cancelled assignments cannot be restarted. If you need to re-publish, you'll have to create a new assignment. See cancel_assignment in the Tool Reference.

Useful context phrases

These phrases reliably map to specific tool calls:

What you say	What Claude calls
"What channels do I have?"	`list_connections`
"What can I post on YouTube?"	`get_platform_capabilities`
"Check the status of my last upload"	`list_assignments` + `get_assignment`
"Show me failed uploads"	`list_assignments(status: "failed")`
"How many subscribers does my channel have right now?"	`get_channel_stats`
"How is my latest video performing?"	`get_post_stats`
"Why did my webhook fail?"	`list_webhook_deliveries(status: "failed")`
"Retry my failed upload"	`get_assignment` + `retry_assignment`

Multi-step workflows

Give Claude the full context upfront rather than one step at a time. This lets it plan all the tool calls before asking for confirmation:

"I want to upload 3 videos this week — all to my TechReviews channel, all public, all Kyiv time (UTC+3):

Monday at 10 AM: https://cdn.example.com/v1.mp4 (opens in a new tab) — title 'April Launch'

Wednesday at 10 AM: https://cdn.example.com/v2.mp4 (opens in a new tab) — title 'Behind the Scenes'

Friday at 6 PM: https://cdn.example.com/v3.mp4 (opens in a new tab) — title 'Q2 Recap'

Please confirm each one before creating."

Claude will call create_assignment three times in sequence, confirming each before proceeding.

For end-to-end workflow patterns (publish, connect channel, update published content), see Workflows.

Handling errors gracefully

If Claude reports a failed assignment, provide both intent in one message:

"The upload failed. Check why and retry it."

Claude will call get_assignment to read the errors array, summarize the root cause (e.g. quota exceeded, bad media URL, expired token), and then call retry_assignment if appropriate.

For token expiry errors, Claude will suggest re-authorizing the connection via get_oauth_connect_url.

For a guide on common error codes and recovery steps, see Error Handling.