How access is checked
Code mode keeps your credential’s project scope, OAuth consent and account feature access. DevTune checks access before each operation, and again before it returns a program’s output or replays a recorded one. If access to an operation the program used has changed, the output is withheld. The receipts and yourexecutionId remain, so you can still recover.
Each operation keeps the project permissions and feature access of its classic MCP tool. Writes act as a member: an API key acts as its creator and an OAuth connection as its consenting user. That member must still be a project member with the manage permission unless the operation says otherwise. Discovery leaves out a write family when DevTune cannot verify its authorization.
Output is also withheld when something the program returned has since changed or gone, including when a later step of the same program changed it. The sections below say which changes withhold output for each family.
Receipts
Each operation records a receipt with its method, argument hash, the resource ID when known, and status. Receipts never contain code, arguments, result data, signing secrets, webhook destinations or events. A write whose receipt would not fit in the 16 KB receipt is refused before anything changes. If an authorization or receipt check fails after a write returns, the receipt isuncertain. It keeps the returned resource ID when there is one, or the input action or prompt ID otherwise, and the output stays withheld. Read the resource before deciding what to do next.
Reads
get_agent_run returns the complete stored Markdown of a completed action, brief or report. Output that would exceed the code-mode limits fails with a budget error. To read a larger artifact, use classic MCP devtune_get_agent_run or GET /api/v2/projects/{projectId}/agents/runs/{runId} with agents.read; these return the whole artifact, subject to hosting and client response limits.
Content-draft Markdown is not in agent-run reads. Read it with get_action_draft and actions.read, or the Library tools with both library.read and actions.read.
Agent-run output is withheld if a returned run is no longer visible to the project, including on replay. A replayed list is also withheld if your content-draft access has changed, even when the list was empty. Custom agents in the output must still be current and active. Library output rechecks the acting member’s Library permissions, including Library management for write results.
list_prompts and list_topics refuse a page over the 256 KB operation limit with operation_response_budget_exceeded; request a smaller pageSize. get_connection_context replays the context as it was recorded; call it again for current access.
Actions
change_action_status returns a receipt of the transition as it applied, naming every action it moved. A later read of the same execution returns that receipt, not the action’s current state, and it can stay available after a refresh retires or deletes the suggestions. Output is withheld if the acting member or credential loses access, a recorded source is no longer available, or an action moves to another project, account or source. A merged suggestion can move up to 40 actions; a program whose receipts would not fit is refused before the change.
Creating an action from a prompt is free. Brief generation, including generateBrief: true, uses the content-credit policy and keeps credit refusals. A failed optional brief leaves the action saved with briefStatus: "failed". A succeeded receipt means the call returned, not that a brief was queued or completed: generate_action_brief can return a refusal as {error, reason} without failing. Check the returned reason and status, and creation’s briefStatus, before reporting that brief work started.
start_action_draft uses the dedicated agent-run rate limit, checks brief readiness and locked pages, and returns runId with queue status. The acknowledgement does not contain the draft; follow it with get_action_draft. Keep its requestIdempotencyKey stable along with the execution ID.
Output from these operations is withheld if the referenced action, the creation prompt or the draft run is removed or hidden, or if feature or member access is lost. Receipts keep the action ID, or the draft’s run ID. Queue status is the recorded acknowledgement; read the resource for its current state. Agent content still needs human approval before publication.
Managed agents
run_agent needs agents.run. Show the human the agent, instructions, model and target page before approval. Search for run_agent to get its current schema, then call it in an approved execution:
requestIdempotencyKey stable after losing a connection. Replay does not launch again or use another agent-run allowance.
The result returns queue status and taskId; it does not wait for the agent to finish. Successful receipts keep the task ID, including when the program later times out. Follow the task with get_agent_run, classic MCP devtune_get_agent_run or the REST agent-run endpoint. Agent output still waits for human approval.
create_custom_agent, update_custom_agent, archive_custom_agent, restore_custom_agent, set_agent_schedule and turn_off_agent_schedule need agents.write. Show the human the agent definition or schedule first. Retrying create_custom_agent with a new execution ID creates a second agent.
Dex conversations
Dex conversations stay private to the member attributed to your credential. Your account must have Dex. Reads needagents.read; starting, messaging, renaming and deleting chats, and deciding handoffs or memory offers, need agents.run.
- Starting a conversation and sending a message spend credits under the same policy as classic MCP and use the agent-run rate limit. Keep
messageIdstable along with the execution ID. - Confirming a handoff queues a credit-metered specialist run. If credits refuse it, the result is
not_startedwith its outcome and the handoff stays pending. A handoff that is no longer pending returnsnot_pending. - Memory saves check the offered text against the Dex reply.
- Reads return the same pagination cursors and truncation flags as classic MCP.
{"status":"deleted"} are still returned while your access remains. Replay never sends a message, starts or confirms work, saves memory, renames or deletes again.
Prompt-set analysis
start_prompt_set_analysis and review_prompt_set_proposal need actions.write.
To start an analysis, read get_prompt_set_analysis, show the human its credit estimate and pass that exact value as approvedEstimatedCredits. A changed estimate is refused until the human approves the new one. The start reserves agent credits and returns the queued run, or the run already in progress; it does not wait for the analysis. If an adopted run finishes before the start returns, the start returns its results.
review_prompt_set_proposal applies, undoes, dismisses or restores one proposal. Show the human the proposed change first.
Output is withheld when a returned run or proposal has since changed or been deleted, including later in the same program, so a program that reads a proposal and then dismisses it does not return the earlier read. Receipts still record the review. Replay never starts, charges or reviews again.
Prompts, topics and project setup
Show the human the prompts, topics, brands, domains, terms or page you will change first. Pausing stops every probe, agent and crawl for the project. These operations behave like their classic MCP tools.
Library and Knowledge
upload_library_item, update_library_item, update_knowledge_profile and review_knowledge_proposal need library.write.
- Uploads accept at most 12,000 bytes of JSON-encoded content, including quotes and escapes.
searchreports this limit. Use classic MCP for larger documents. - Direct edits accept
company_context,toneorsaved_instructionsand apply immediately. Proposal review acceptsapprove,dismissorrestore. - OAuth members need the current project grant, project membership and
devtune.manage, including before saved output is returned. API keys keep their project-scoped Library write policy. - Interrupted writes can remain uncertain. Do not repeat them automatically.
Webhooks
list_webhooks needs webhooks.read. create_webhook, delete_webhook and rotate_webhook_secret need webhooks.write. Show the human the destination and events, or the subscription being rotated or deactivated, first. The same API key or OAuth checks as classic MCP apply.
Create and rotate return the signing secret once, in the response to the original execution. DevTune does not save it: reusing the execution ID returns signing_secret_not_replayable with the receipt instead of output, and nothing is created or rotated again. If you lose that response, read the receipt for the subscription ID and rotate the secret in a new approved execution. Only the most recent secret is valid.
Output is withheld if a subscription the program created or rotated has since been deactivated, including later in the same program. list_webhooks output is withheld if a returned subscription has changed since the read; subscriptions added afterwards do not withhold it. A list too large to record is refused rather than shortened; use classic MCP devtune_list_webhooks or GET /api/v2/projects/{projectId}/webhooks. A delete acknowledgement stays available on replay while your credential keeps webhook access.
Other writes
Code mode cannot start a paid Agent Picks test or enable a schedule, so one execution cannot quote and spend. The other Agent Picks test, setup and job writes are classic MCP only. Publishing is not available in code mode.