agent-intern

Overview Schema Source Related Servers Discussions Admin

Ask Codex (new session)

codex_ask

Ask OpenAI Codex a question or coding task in a new session and get its final answer as text; set workspace to a project dir for context-aware answers.

Instructions

Ask OpenAI Codex (codex exec) a question or task in a NEW session.

Uses your existing Codex login (ChatGPT or API key — see codex login status). Returns the agent's final message as text, read from codex's --output-last-message file (no stdout scraping). Codex is a capable coding agent, so this suits heavier reasoning and real code work, not just cheap tool-calling. Point workspace at a real project dir for context-aware answers.

Input Schema

Name	Required	Description	Default
`model`	No	Optional model override (`-m`); omit to use codex's configured default.
`watch`	No	If true, open a live "watch" view in your browser that streams codex's steps (reasoning, the commands it runs, file changes) from its `--json` event stream. codex still runs headless; the same final text is returned. Best-effort — if the browser can't open, the run completes normally. Default false.
`prompt`	Yes	Question or instruction for Codex.
`sandbox`	No	Filesystem policy — "read-only" (default: reads and answers but writes nothing), "workspace-write" (may edit files under the workspace), or "danger-full-access" (no sandbox — avoid). `codex exec` has no interactive approval gate, so this is the real safety boundary; opt into write access deliberately. WINDOWS CAVEAT (codex 0.149.1-0.162.1): sandboxed runs there currently refuse EVERY command, both policies, down to `pwd` — codex's policy engine cannot classify the `pwsh -Command <...>` wrapper it builds. Shell commands are how codex reads files, so it sees none of the workspace and ANSWERS ANYWAY, from its own knowledge or a web search, with no hint that it read nothing. The bridge appends a visible "[agent-intern] WARNING" to any answer whose run had commands refused: if you see it, treat the answer as unsourced.	read-only
`timeout_s`	No	Max seconds to wait for codex to complete. Default 180.
`workspace`	No	Working root for the session (`-C`). Defaults to the server cwd.

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.33.0Oct 21, 2026

changedInput schema / properties / sandbox / description

Previous value: -"Filesystem policy — \"read-only\" (default: reads and answers but\n     writes nothing), \"workspace-write\" (may edit files under the\n     workspace), or \"danger-full-access\" (no sandbox — avoid). `codex\n     exec` has no interactive approval gate, so this is the real safety\n     boundary; opt into write access deliberately.\n\n     WINDOWS CAVEAT (codex 0.149.1): sandboxed runs there currently\n     refuse EVERY command, both policies, down to `pwd` — codex's\n     policy engine cannot classify the `pwsh -Command <...>` wrapper it\n     builds. Shell commands are how codex reads files, so it sees none\n     of the workspace and ANSWERS ANYWAY, from its own knowledge or a\n     web search, with no hint that it read nothing. The bridge appends\n     a visible \"[agent-intern] WARNING\" to any answer whose run had\n     commands refused: if you see it, treat the answer as unsourced."New value: +"Filesystem policy — \"read-only\" (default: reads and answers but\n     writes nothing), \"workspace-write\" (may edit files under the\n     workspace), or \"danger-full-access\" (no sandbox — avoid). `codex\n     exec` has no interactive approval gate, so this is the real safety\n     boundary; opt into write access deliberately.\n\n     WINDOWS CAVEAT (codex 0.149.1-0.162.1): sandboxed runs there currently\n     refuse EVERY command, both policies, down to `pwd` — codex's\n     policy engine cannot classify the `pwsh -Command <...>` wrapper it\n     builds. Shell commands are how codex reads files, so it sees none\n     of the workspace and ANSWERS ANYWAY, from its own knowledge or a\n     web search, with no hint that it read nothing. The bridge appends\n     a visible \"[agent-intern] WARNING\" to any answer whose run had\n     commands refused: if you see it, treat the answer as unsourced."

Changed1 schema field changedv0.28.0Aug 26, 2026

changedInput schema / properties / sandbox / description

Previous value: -"Filesystem policy — \"read-only\" (default: reads and answers but\n     writes nothing), \"workspace-write\" (may edit files under the\n     workspace), or \"danger-full-access\" (no sandbox — avoid). `codex\n     exec` has no interactive approval gate, so this is the real safety\n     boundary; opt into write access deliberately."New value: +"Filesystem policy — \"read-only\" (default: reads and answers but\n     writes nothing), \"workspace-write\" (may edit files under the\n     workspace), or \"danger-full-access\" (no sandbox — avoid). `codex\n     exec` has no interactive approval gate, so this is the real safety\n     boundary; opt into write access deliberately.\n\n     WINDOWS CAVEAT (codex 0.149.1): sandboxed runs there currently\n     refuse EVERY command, both policies, down to `pwd` — codex's\n     policy engine cannot classify the `pwsh -Command <...>` wrapper it\n     builds. Shell commands are how codex reads files, so it sees none\n     of the workspace and ANSWERS ANYWAY, from its own knowledge or a\n     web search, with no hint that it read nothing. The bridge appends\n     a visible \"[agent-intern] WARNING\" to any answer whose run had\n     commands refused: if you see it, treat the answer as unsourced."

Addedv0.12.2Jun 23, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations cover only readOnlyHint/openWorldHint/idempotentHint; the description goes well beyond them with auth requirements (existing ChatGPT or API key login), the exact return mechanism (--output-last-message, no stdout scraping), and the sandbox as the real safety boundary absent an approval gate. The Windows caveat describing silently-refused commands and the '[agent-intern] WARNING' marker is unusually valuable operational context.

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?

Five sentences, each doing distinct work: purpose/newness, credentials, return format, capability framing, and workspace advice. Front-loaded with the tool's identity and no padding.

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?

Covers everything an agent needs before calling a non-idempotent, open-world agent: what it does, what credentials it uses, what comes back, and the sandbox safety trade-off. With an output schema present it correctly avoids re-specifying the return shape.

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, but the description adds meaning the schema doesn't: that `workspace` should be a real project dir for context-aware answers and that `sandbox` is the genuine safety boundary rather than a cosmetic flag. It stops short of describing model/timeout/watch choice guidance, which the schema already handles.

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?

States a specific verb and resource ('Ask OpenAI Codex a question or task') and immediately scopes it as a NEW session, which is exactly the axis that separates it from codex_continue. The parenthetical `codex exec` names the underlying mechanism, so the agent knows what it is invoking.

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?

Gives clear context for use: heavier reasoning and real code work, not cheap tool-calling, plus the practical hint to point `workspace` at a real project dir. The 'NEW session' phrasing implicitly routes continuation to codex_continue, but that sibling is never named explicitly, leaving one inference step.

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