Guide agents toward workflows for long-running work

[kentcdodds]

Summary

• Add timeout-aware workflow guidance to the execute MCP tool description and base MCP server instructions.
• Strengthen workflow_run_list discoverability for timeout-avoidance, migrations, and background status inspection.
• Update user/contributor docs with concise guidance on when to prefer workflows.create over chained execute calls.
• Add a short inline-code workflow example with params and a follow-up workflow_run_list status check.

Validation

• npx vitest run packages/worker/src/mcp/tools/execute.node.test.ts packages/worker/src/mcp/capabilities/jobs/job-schedule.node.test.ts packages/worker/src/package-runtime/package-workflows.node.test.ts packages/worker/src/package-runtime/package-app.node.test.ts packages/worker/src/mcp/run-kody-registry.node.test.ts ✅
• npm run validate ✅

Post-deploy verification

• Inspect the execute MCP tool description and confirm it warns about the ~90s hard timeout and recommends one workflows.create({ code, params }) for batch sweeps, migrations, polling loops, or >~60s work.
• In docs/use/workflows.md, confirm the inline workflow example queues code with params and the status example calls workflow_run_list.

System recap — composes existing primitives (low risk)

Mode: recap · Base: main @ d16fce76 · Head: c0f5618e

Classification: composes — updates guidance and capability descriptions without changing primitive behavior or data contracts.

Primitives touched

Primitive	Group	Impact
mcp-server	surfaces	composes — clearer execute/server instruction guidance
workflows	assistant	composes — docs teach when to queue durable workflow work
jobs	assistant	composes — workflow_run_list description/keywords clarify inspection use

System map

flowchart LR
	mcpServer["mcp-server"]:::touched --> workflows["workflows"]:::touched
	workflows --> jobs["jobs / workflow_run_list"]:::touched
	classDef touched fill:#1a7f37,color:#fff
	classDef extended fill:#9a6700,color:#fff
	classDef added fill:#cf222e,color:#fff
	classDef untouched fill:#57606a,color:#fff

Loading

Change flow

sequenceDiagram
	participant Agent as Agent reading guidance
	participant Execute as execute MCP tool
	participant Workflow as workflows.create
	participant List as workflow_run_list
	Agent->>Execute: quick operation? run plain execute
	Agent->>Workflow: long-running sweep/migration? queue durable workflow
	Agent->>List: inspect status later

Loading

Invariants

• No user data read/write paths changed.
• No workflow runtime behavior changed in this follow-up; this is guidance and description text only.

  

Summary by CodeRabbit

• Documentation
  • Clarified when to use execute versus workflows for longer-running or durable tasks.
  • Added guidance to use workflows for batch sweeps, migrations, polling loops, and other work that may exceed execute timeouts.
  • Expanded workflow docs with examples for starting runs and checking progress later.
  • Improved workflow-related tool guidance and searchability with updated descriptions and keywords.

[coderabbitai]

📝 Walkthrough

Walkthrough

Documentation and MCP tool/capability description strings are updated to recommend using workflows.create instead of chained execute calls for durable, long-running, or retryable work. The workflows.create request fields runAt and idempotencyKey are changed from required to optional in documentation. No code logic, schemas, or exported entity signatures change.

Changes

Workflows-over-execute guidance update

Layer / File(s)	Summary
Workflows.create usage and field semantics docs/use/workflows.md	Replaces the workflows.create example to emphasize code/params, adds a workflow_run_list inspection snippet, and changes runAt/idempotencyKey from required to optional/accepted fields.
Execute docs and tool description updates docs/use/execute.md, packages/worker/src/mcp/tools/execute.ts	Adds guidance on execute's ~90s timeout and recommends submitting durable work via workflows.create({ code, params }) instead of chaining tool calls.
Server instructions and capability metadata wording packages/worker/src/mcp/server-instructions.ts, packages/worker/src/mcp/capabilities/jobs/workflow-list.ts, docs/contributing/cloudflare-agents-sdk.md	Rewords workflow_run_list and execute bullets in server instructions, updates workflow-list capability description/keywords, and adds Kody runtime usage guidance in contributing docs.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related PRs

• kentcdodds/kody#476: Both PRs update MCP guidance text in packages/worker/src/mcp/tools/execute.ts and packages/worker/src/mcp/server-instructions.ts, though for different topics.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: steering agents to use workflows for long-running work.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch cursor/workflows-create-undefined-gettime-189c

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

🔎 Preview deployed: https://kody-pr-659.kody-a99.workers.dev

Worker: kody-pr-659
D1: kody-pr-659-db
KV: kody-pr-659-oauth-kv

Mocks:

• cloudflare: https://kody-pr-659-mock-cloudflare.kody-a99.workers.dev/__mocks (kody-pr-659-mock-cloudflare)

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

docs/contributing/cloudflare-agents-sdk.md (1)

189-191: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Move the Kody runtime guidance to docs/use.

As per path instructions, docs/use/**/*.md: End-user and MCP usage documentation belongs under docs/use/, not in the contributor guidance files. This bullet is user-facing MCP guidance, so it belongs with the workflow docs rather than in the Cloudflare Agents contributor guide.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/contributing/cloudflare-agents-sdk.md` around lines 189 - 191, This Kody
runtime guidance is misplaced in the contributor guide and should be moved into
the end-user documentation under docs/use. Remove the bullet from the Cloudflare
Agents SDK contributing doc and add the same content to the appropriate
workflow/MCP usage doc that covers workflows.create and workflow_run_list,
keeping user-facing guidance out of contributor-only docs.

Source: Path instructions

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/use/workflows.md`:
- Around line 48-52: Tighten the idempotency wording in the workflows docs so it
does not imply the key alone guarantees reuse; the behavior in
`workflows.create` also depends on normalized request fields such as `runAt`.
Update the sentence around `idempotencyKey` to say that reusing the same key for
the same user returns the existing workflow only when the normalized request
identity matches, and keep the quota note for the concurrent workflow limit
unchanged.
- Around line 7-10: The queueing description in the workflows docs is
attributing the handoff to the wrong API call; update the wording in the
workflow guidance to point to workflows.create as the call that queues the
workflow, and keep execute described only as the launcher/entry point. Use the
workflows.create and execute references in this section to make the distinction
explicit and accurate.

---

Nitpick comments:
In `@docs/contributing/cloudflare-agents-sdk.md`:
- Around line 189-191: This Kody runtime guidance is misplaced in the
contributor guide and should be moved into the end-user documentation under
docs/use. Remove the bullet from the Cloudflare Agents SDK contributing doc and
add the same content to the appropriate workflow/MCP usage doc that covers
workflows.create and workflow_run_list, keeping user-facing guidance out of
contributor-only docs.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 57afd457-5b8f-4697-91b5-1c3c40076711

📥 Commits

Reviewing files that changed from the base of the PR and between d16fce7 and 74faa44.

📒 Files selected for processing (6)

• docs/contributing/cloudflare-agents-sdk.md
• docs/use/execute.md
• docs/use/workflows.md
• packages/worker/src/mcp/capabilities/jobs/workflow-list.ts
• packages/worker/src/mcp/server-instructions.ts
• packages/worker/src/mcp/tools/execute.ts