Loading ToolBench

Reading the current corpus…

codex-headless MCP server · F · ToolBench

codex-headless

Codex headless orchestration: MCP tools (review/implement/probe), profiles, and agent skills for review, implementation, computer-use, and built-in codex MCP.

2025-06-18+STDIO3 tools

46/100

Definition Quality58

Protocol Readiness45

Supportability25

Spec posture

Inferred effective spec 2025-06-18+·current baseline 2026-07-28

Static source inference · medium confidence · evidence: structured output

No deprecated protocol patterns detected

Summary

Three tools with complete input schemas and descriptions, but descriptions are verbose (200+ chars) and lack LLM-optimized clarity. Tool names follow verb_noun pattern (codex_headless_*) but are generic and don't clearly distinguish review vs implement vs probe intent. Parameters are well-typed with enums and defaults, but descriptions bury key constraints in prose. Output schemas are not documented. Error handling is mentioned but not detailed in tool definitions.

Tools (3)

codex_headless_implementdestructivesource verified58/100

Codex implementation via codex exec (workspace-write; default --ephemeral). Default profile implement (gpt-5.6-luna, xhigh). Pass profile=engineer for gpt-5.6-sol high. Optional brief (typed change/files/writeScope/…). Optional ephemeral=false + resumeThreadId for exec resume. Optional persistentSessionKey for opt-in app-server reuse (not combined with resumeThreadId). Write-scope validation reported only when structured changed_files parse reliably — never enforced/rolled back. Legacy prompt-only calls unchanged.

codex_headless_proberead onlysource verified58/100

Codex probe via codex exec --profile probe (read-only; default --ephemeral). Lightweight agent for exploration, analysis, and structured queries. Optional brief (typed change/files/writeScope/…). Optional ephemeral=false + resumeThreadId for exec resume. Optional persistentSessionKey for opt-in app-server reuse (not combined with resumeThreadId). Write-scope validation reported only when structured changed_files parse reliably — never enforced/rolled back. Legacy prompt-only calls unchanged.

codex_headless_reviewread onlysource verified58/100

Read-only Codex review via codex exec --profile review (default --ephemeral) --ignore-user-config --ignore-rules (gpt-5.6-sol, high; no global MCP/rules). Use review_uncommitted/review_base for built-in diff review, or prompt for custom scope. Set structured=true for reviewer-verdict JSON schema. JSONL capture + usage telemetry on by default.

Issues (5)

HIGHtool-naming ↗

Tool names lack action clarity. 'codex_headless_review', 'codex_headless_implement', 'codex_headless_probe' are domain-specific but do not convey intent (read-only vs destructive) at a glance. LLMs must read full descriptions to distinguish them.

codex_headless_reviewcodex_headless_implementcodex_headless_probe

HIGHtool-description ↗

Descriptions are verbose (200+ chars) and bury key constraints in prose. E.g., 'structured=true for reviewer-verdict JSON schema' is buried in a 300+ char description. Should be: 'Review code with Codex. Returns structured JSON verdict when structured=true.' Constraints belong in parameter descriptions, not tool description.

codex_headless_reviewcodex_headless_implementcodex_headless_probe

HIGHresponse-shaper ↗

Output schemas are not documented. Tool definitions describe inputs but do not specify what fields are returned (e.g., does review return 'verdict', 'issues', 'score'?). LLMs cannot plan downstream calls without knowing response structure.

codex_headless_review

Recommendations

Rename tools to clarify intent: 'review_code_with_codex' (read-only), 'implement_changes_with_codex' (destructive), 'analyze_code_with_codex' (read-only). Add risk annotations (readOnlyHint, destructiveHint) to tool definitions.
Trim tool descriptions to 50 - 150 chars. Move constraints to parameter descriptions. E.g., tool: 'Review code with Codex. Returns structured JSON verdict when structured=true.' Parameter 'structured': 'Return structured reviewer-verdict JSON schema (default false).'
Document output schemas for each tool. Specify: what fields are returned (e.g., 'verdict', 'issues', 'changed_files'), their types, and which are always present vs conditional.
Standardize parameter descriptions. Every parameter should state: (1) what it controls, (2) valid values/format, (3) when to use it, (4) default behavior. E.g., 'brief: Typed implementation brief (change + files/writeScope). Assembled into prompt; timeoutMs maps to maxWallMs. Provide brief and/or prompt.'
Add error handling guidance to tool descriptions. E.g., 'If Codex fails, returns error with recovery hint. Retryable errors include timeout; non-retryable include invalid prompt syntax.'

Score history

Overall score trend

First recorded score · v2 rubric

46/100

Scored	Grade	Overall	Spec posture	Rubric
2026-09-23	F	46	2025-06-18+	v2