Codex Control Plane MCP
Server Quality Checklist
Latest release: v0.2.1
- Disambiguation5/5
Each tool has a clearly distinct purpose with detailed descriptions that specify when to use it and what to do next. Overlaps like codex_execute_plan vs codex_approve_plan are resolved by marking the former as a compatibility wrapper. No two tools perform the same action.
Naming Consistency5/5All tools follow the consistent pattern codex_<verb>_<noun> with lowercase and underscores. Verbs like get, list, start, submit are used uniformly, and there is no mixing of styles.
Tool Count4/538 tools is high but each serves a distinct operation within the control plane domain, covering workflow lifecycle, diagnostics, chat, worker, and project management. A few redundancies exist for backward compatibility, but overall the count is justified by the breadth of functionality.
Completeness5/5The tool surface covers the complete lifecycle: health checks, diagnostics, planning, execution, review, chat management, project discovery, and cleanup (archive/unarchive). Missing operations like deletion are not essential for a control plane, and the set provides no dead ends for common workflows.
Average 3.6/5 across 38 of 38 tools scored. Lowest: 2.9/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 44 commits in the last 12 weeks
- Last stable release on
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under Apache 2.0.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
This repository includes a glama.json configuration file.
If you are the author, simply .
If the server belongs to an organization, first add
glama.jsonto the root of your repository:{ "$schema": "https://glama.ai/mcp/schemas/server.json", "maintainers": [ "your-github-username" ] }Then . Browse examples.
Add related servers to improve discoverability.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It correctly indicates a read operation and adds a behavioral caveat about not misinterpreting active locks. However, it lacks details on permissions, rate limits, or side effects, which would be helpful for a diagnostic tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The structure is front-loaded with the purpose, then guidance. However, the second sentence is somewhat terse and could benefit from slight expansion for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, return values are not required in the description. However, the tool has two undocumented parameters, and the description does not cover their semantics. This incompleteness lowers the overall utility, despite good usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must explain the parameters. It does not mention `include_locks` (boolean) or `limit` (integer), leaving the agent to guess their roles. This is a major gap that hinders correct usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Read' and the resource 'active turn counts and scheduler resource locks', which directly aligns with the tool name 'concurrency status'. However, it does not explicitly differentiate from sibling tools like get_queue_status or get_operation_status, though the mention of 'parallel work' provides some distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises using this tool 'with queue status when diagnosing parallel work', which gives context for when to invoke it. It also cautions that 'Active locks are not a retry instruction by themselves', preventing misuse. However, it does not specify when not to use it or list alternative tools for other types of status checks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It mentions using 'safe fallback sources' but does not detail what those are, nor does it address auth, rate limits, or data freshness. The caution about active turns adds some transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (two sentences) with no waste, but it omits parameter details, making it under-informative for a tool with many parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description fails to cover the 11 parameters, no annotations, and no parameter semantics. This is severely incomplete for a search tool with complex filtering and pagination.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the tool description provides no explanation of any of the 11 parameters (query, match_mode, etc.). The description is silent on parameter behavior, leaving agents without guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches chat history via MCP-owned index and fallback sources, specifying the use case for discovery/recovery when IDs are lost. This distinguishes it from sibling tools like codex_get_chat or codex_list_active_chats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Guidelines specify when to use (discovery/recovery of lost IDs) and include a caution not to use results as proof of active turns. However, it does not explicitly mention when to avoid this tool in favor of siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It only states the action and a follow-up step. It does not disclose side effects, error behavior, authorization needs, or rate limits. For a mutating tool, more transparency is needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, under 50 words, and front-loads the core action. It is concise but the first sentence could be clearer about 'Plan Mode candidate' and 'workflow thread' for a broader audience.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 parameters (3 required) with no descriptions, and an output schema not explained, the description is incomplete. It provides purpose and a usage hint but fails to cover parameter meanings, return values, or error handling. The agent would need external knowledge to use this tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not explain any of the 6 parameters. Parameter names are somewhat self-explanatory (e.g., workflow_id, candidate_turn_id), but the lack of any description or hints means the agent must guess. This is inadequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'adopt' and the resource 'valid newer Plan Mode candidate', and specifies it is within a workflow thread. It provides a condition for usage, which adds context. However, it does not explicitly differentiate from sibling tools like codex_approve_plan or codex_execute_plan, leaving slight ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit conditions: 'Use this only when status or diagnostics reports an adoptable plan' and advises 'Next poll codex_get_workflow_status'. This provides clear context on when to use and what to do afterward. It lacks mention of when not to use or alternative tools, but still offers strong guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It states the tool collects diagnostic snapshots and does not execute repairs, implying it is a read-only operation. However, it does not explicitly state that it does not modify any state, leaving some ambiguity about potential side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, consisting of two sentences that state purpose and usage context without any wasted words. It is well-structured for quick reading.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 11 parameters with zero schema descriptions and no annotations, the description should provide more guidance on scoping and optional behavior. It only mentions 'scoped diagnostic snapshot' without explaining how to control scope via parameters, leaving significant gaps for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It contains no information about any of the 11 parameters (e.g., operation_id, since_minutes, include_logs), leaving the agent without guidance on how to specify the scope or customize the diagnostic snapshot.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Collect' and resource 'diagnostic snapshot', clearly stating the tool's purpose. However, it doesn't explicitly differentiate from sibling tools like 'codex_get_diagnostic_logs' or 'codex_health_summary', though the mention of 'compact evidence and guidance' hints at a distinct output.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use ('before repair when status reports failed, stale, orphaned, or degraded state') and what the tool does not do ('does not execute repairs'). This provides clear context, but it does not mention alternative tools or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description must disclose behavioral details. It mentions 'compatibility write' and 'delegates to durable workflow execution', but lacks specifics on side effects, modifications, or return behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise at two sentences, no wasted words. However, the first sentence could be more informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (12 parameters, enums, output schema), the description is too sparse—missing purpose of parameters, output details, and complete usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 17% (2 of 12 parameters have descriptions). The tool description does not explain any parameters, failing to compensate for the low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states it is a compatibility write for executing an approved plan, which is clear but uses jargon. It distinguishes from siblings by mentioning alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises preferring codex_approve_plan or codex_submit_task with operation_type='execute_plan', providing clear when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description adds some behavioral info (read-only, no retries). Yet it omits details like pagination, rate limits, or side effects. The statement 'Read bounded chat content' hints at limits but does not explain bounding behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, each earning its place. It front-loads the core purpose and immediately adds usage guidance. No fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (14 params, nested range object, many options), the description is far too sparse. It does not explain how to use the range modes, include flags, formatting, or budget parameters. The output schema exists but the description offers no guidance on interpreting results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides no explanation of any of the 14 parameters, despite 0% schema description coverage. Key parameters like chat_id, range, include_* flags, format, and budgets are completely unaddressed, forcing the agent to rely solely on parameter names and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads bounded chat content from specific sources (hook history, transcripts, legacy fallback), and mentions use cases (context recovery, final report inspection). It distinguishes from sibling getters by specifying 'bounded chat content' rather than status or diagnostics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides when to use ('context recovery', 'final report inspection') and what not to do ('not a write path', 'should not trigger retries'). However, it does not explicitly contrast with sibling tools or mention when to avoid it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must disclose all behavioral traits. It mentions dry-run by default and a stopping condition, but fails to warn about potentially destructive actions (e.g., force_restart_app_server) or explain what allowlisted means. More detail is needed for safe use.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences, front-loading the core purpose and usage condition. It could be slightly more structured but is efficient overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema (making return value documentation unnecessary), the tool has 15 parameters and the description is too brief to be complete. It does not explain how different actions relate to parameters or provide sufficient context for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no meaning to any of the 15 parameters. Parameters like diagnosis_id, thread_id, etc., are not explained, leaving the agent without guidance on how to set them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs an allowlisted repair action with dry-run first by default. It distinguishes from sibling tools like codex_collect_diagnostics or codex_get_* status tools by specifying repair actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use only when diagnostics or agentGuidance recommends an action, and to stop when loopGuard.allowed is false. This provides clear conditions for use, though it doesn't explicitly name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It mentions asynchronous operation via command lane and return of commandId, but lacks details on destructive effects, reversibility (though a sibling unarchive tool exists), auth requirements, or side effects. The description does not contradict annotations but is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loading the purpose and then adding a precondition and follow-up. Every sentence adds value; no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters with 0% schema coverage, no annotations, and an output schema, the description is incomplete. It addresses use precondition and follow-up but does not document parameter meanings or detailed behavior. The agent would need to infer too much.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description must explain parameters. It only mentions that a commandId is returned, but gives no guidance on thread_id, project_id, timeout_seconds, or refresh_catalog. The agent has no help understanding parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Archive') and the resource ('a known Codex thread'), and specifies the mechanism ('through the worker or app-server command lane'). It distinguishes from the sibling tool 'codex_unarchive_thread' by indicating the thread should have no active work, implying a complementary use case.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool ('only when the thread has no active work') and recommends a follow-up action ('Next poll codex_get_worker_command_status when commandId is returned.'). It does not explicitly list when not to use or alternatives, but the precondition is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only mentions 'compatibility write' and delegation. Lacks details about side effects, return behavior, idempotency, or mutation scope. The parameter description (in schema) reveals that tool returns immediately, but this is not in the main description. Insufficient disclosure for a write tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is three sentences, no fluff, and front-loaded with purpose and usage guidance. However, it sacrifices necessary detail for brevity. Still, it is appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 11 parameters, no annotations, and many siblings, the description is grossly incomplete. It does not explain parameters, output schema, error conditions, or lifecycle. A tool of this complexity requires far more context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 9%; most parameters have no description. The tool description adds no parameter meaning—it doesn't explain any of the 11 parameters, their defaults, or relationships. Fails to compensate for low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states tool is for starting a new Codex chat ('Compatibility write for starting a new Codex chat'). It distinguishes itself from codex_submit_task, which is preferred for durable long work, and mentions delegation behavior in client mode. This differentiates it clearly from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance to prefer codex_submit_task with operation_type='start_chat' for durable long work, and notes that in client mode it delegates to durable queue. This tells the agent when not to use this tool and suggests an alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that the workflow is durable and returns immediately, implying asynchronous behavior and need for polling. However, it does not mention side effects, state changes, or constraints like idempotency, which would be helpful for understanding the tool's impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at three sentences with front-loaded purpose and clear follow-up action. No redundant information; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 15 parameters and an output schema, the description is incomplete. It omits guidance on how to configure parameters like target_type, sandbox, or instructions, which are essential for correct usage. The return value is partially covered by mentioning workflowId, but not fully detailed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description provides no information about the 15 parameters, their meanings, or how they affect behavior. This is a critical gap, as the agent must rely solely on the schema, which lacks descriptive text. The description should summarize key parameters like target_type and delivery.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool starts a durable Codex review workflow and returns a workflowId immediately. It specifies the action (start), the resource (review workflow), and the context (code review tasks), effectively distinguishing it from sibling tools like codex_start_plan_workflow and codex_start_chat.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description tells users to use this tool for code review tasks and to poll codex_get_workflow_status afterward. However, it does not explicitly mention when not to use it or provide alternatives, such as when to use codex_start_plan_workflow instead, which is a guideline gap given the number of sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It implies mutation ('Answer') and consequence ('so a turn can continue'), but does not disclose side effects, authorization needs, or behavior of individual parameters. Basic transparency but incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at two sentences, front-loaded with the core action, and avoids redundancy. However, it lacks parameter documentation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema and 10 parameters, the description is minimal. It does not explain the 'answer' process, decision options, or how the output schema relates, leaving the agent underinformed for a moderately complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description mentions only 'interaction id' without explaining other critical parameters (decision, action, answers, etc.). It fails to add meaning beyond the schema for the 10 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Answer' and the resource 'pending Codex interaction', and the purpose 'so a turn can continue'. This distinguishes it from siblings like codex_list_pending_interactions (list) and codex_interrupt_turn (different action).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises to use only for a listed interaction id and to poll the owning operation, turn, or workflow next. This provides clear context and next steps, though it lacks explicit when-not-to-use or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that the tool reads safe progress and terminal evidence, and warns against inferring stall from row age. Yet it lacks details on side effects (none), authorization, rate limits, or output format. The warning adds value but the description could be more comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, no unnecessary words. Purpose is front-loaded, followed by usage hint and a warning. Excellent efficiency for a read operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given six parameters and an output schema, the description is too sparse. It does not explain what 'terminal evidence' means, how the parameters control output (e.g., message count limits), or summarize the return structure. The agent is left with significant gaps despite the output schema existing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% (six parameters have no inline descriptions). The description only indirectly references turn_id and thread_id ('use this when you have threadId and turnId'), but says nothing about the other four parameters (last_messages, message_max_chars, progress_events, progress_max_chars). This forces the agent to rely solely on schema types and defaults, which is insufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads a tracked Codex turn, with specific verb 'Read' and resource 'one tracked Codex turn'. It mentions included data (safe progress, terminal evidence). While it distinguishes from sibling 'get' tools by specifying 'turn', it does not explicitly contrast with similar status tools, but the name and context suffice.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage context: 'Use this when you have threadId and turnId.' Additionally adds a caution: 'Do not infer stalled state from row age alone.' This helps the agent decide when to use it. However, it does not list alternative tools or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are empty, so the description carries the burden. It discloses that the tool is a read operation that does not start the app-server, which is useful. However, it does not mention permissions, rate limits, or behavior if the worker is unavailable, leaving some transparency gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the core function. Efficient, though the second and third sentences could potentially be merged. No unnecessary wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has two parameters with no schema descriptions and no parameter info in the description, which is a major gap for completeness. While the output schema exists (so return values are assumed covered), the parameter ambiguity undermines overall completeness. For a read tool, more detail on parameters is expected.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no explanation for either parameter ('include_recent_commands' and 'limit'). The agent cannot determine what these parameters control or how to use them, severely impacting tool invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reads central worker heartbeat and execution-mode state, distinguishing it from starting the app-server. It provides context for when to use (health or queue guidance says inspect_worker_health) and suggests follow-up with queue and concurrency status, effectively differentiating from sibling tools like codex_get_queue_status and codex_get_concurrency_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies a condition for use ('when health or queue guidance says inspect_worker_health') and advises comparing results with queue and concurrency status. It does not explicitly list when not to use or provide alternative tool names, but the guidance is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears the full burden of disclosing behavior. It only says 'Interrupt a running Codex turn' and suggests polling after. It does not describe whether the interrupt is synchronous or asynchronous, whether it requires authentication, what side effects occur (e.g., resource cleanup), or any rate limits. This is insufficient for an agent to understand the full behavioral implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences covering purpose and a usage hint. It is front-loaded with the core action. There is no extraneous information, though the phrase 'Next poll status until terminal evidence is visible' could be considered slightly ambiguous but still efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, no annotations, and an output schema (not described), the description lacks completeness. It does not explain valid parameter combinations, the meaning of timeout_seconds, or the expected output (though output schema exists). The instruction to poll is helpful but insufficient to fully guide an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It vaguely groups parameters into 'direct ids' (likely thread_id and turn_id) and 'durable operation/workflow context' (operation_id and workflow_id), but does not individually define them. The timeout_seconds parameter is not mentioned at all. An agent would not know the meaning or valid combinations of these parameters from the description alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Interrupt a running Codex turn'. It specifies the verb (interrupt) and resource (running Codex turn) and indicates two ways to specify the target (direct ids or durable operation/workflow context). This distinguishes it from sibling tools like codex_get_turn_status or codex_start_chat, which serve different functions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear use case: 'Use this for explicit cancellation or stop conditions.' It also provides a follow-up action: 'Next poll status until terminal evidence is visible.' However, it does not explicitly state when not to use this tool or mention alternatives, but given its unique function among siblings, this is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description bears full responsibility. It states the workflow is durable and returns immediately, but fails to disclose side effects, error handling, rate limits, or any behavioral traits beyond the high-level flow. Insufficient for a complex tool with 15 parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—two sentences with no fluff. It front-loads the core action. Could be slightly more informative without losing efficiency, but remains effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (15 parameters, many with enums, no annotations, low schema coverage), the description is incomplete. It omits explanation of output schema, parameter usage, and full lifecycle details beyond the one-liner.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 27%, requiring the description to compensate. However, the description adds no parameter-level information beyond implying project_id and message. Most parameters (e.g., model, sandbox, approval_policy) remain unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb 'start' and resource 'durable Plan Mode workflow', clearly distinguishes from sibling tools by outlining the workflow lifecycle (start, poll, approve), and states when to use: 'when a plan must be prepared before implementation'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit next steps: poll codex_get_workflow_status, then call codex_approve_plan. Clearly implies usage context (plan preparation before implementation), but does not explicitly list when not to use or mention alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It reveals that the tool polls durable operations and advises against concurrent retries, but does not disclose behaviors like rate limits, idempotency, or response to missing operations. The description is adequate but leaves room for ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two concise sentences that front-load the core action and quickly move to usage guidance. Every sentence adds value without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters and an output schema, the description is relatively sparse. It covers usage sequence and a key constraint but omits details about parameter semantics and what to expect in the response. The output schema mitigates some gaps but the description still feels incomplete for a polling tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides no information about any of the 6 parameters (schema coverage 0%). Although parameter names like 'operation_id' and 'last_messages' are somewhat self-explanatory, the description adds no extra meaning or constraints beyond the schema defaults and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Poll a durable operation from storage,' which clearly identifies the action and resource. However, among sibling tools like codex_get_worker_command_status and codex_get_workflow_status, the description does not explicitly differentiate this tool from other status-polling tools, though it does specify usage after codex_submit_task.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance: 'Use this after codex_submit_task' and instructs to 'follow nextRecommendedAction, pollRecommended, queueState, and agentGuidance.' It also warns 'Never create a new retry while an existing operation is active.' However, it does not mention alternative tools or scenarios where this tool should not be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It correctly identifies the operation as a read and discloses the side effect of refresh: 'In client mode refresh queues a worker command.' However, it does not detail other behaviors like idempotency or the scope of capabilities returned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences. The first sentence states the purpose, and the second adds a behavioral note. It is front-loaded, but could benefit from structured bullet points for readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lists what is read (capabilities, models, permissions, hooks, account state, supported methods) but omits skills, which are controlled by an include_skills parameter. It also does not address cwd or timeout. Given the existence of an output schema, the lack of output details is acceptable, but parameter coverage is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds no information about the 7 parameters (refresh, cwd, timeout_seconds, include_*). The only implicit hint is that refresh triggers a worker command, but no parameter details are provided, leaving the agent to rely solely on the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Read compact runtime capabilities, models, permissions, hooks, account state, and supported methods,' specifying a read verb and listing the resources. This distinguishes it from sibling tools like codex_health_summary (which checks health) and other read tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides usage context: 'Use this after health or before new work.' It gives a sequential positioning but does not explicitly exclude cases or mention alternatives beyond the implicit distinction from health checks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It reveals the tool lists pending interactions but lacks details on limits, pagination, or side effects. It does not contradict annotations (none exist).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two focused sentences: first states the action, second provides usage context and next steps. No extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 optional parameters and an output schema, the description is insufficient. It does not explain filtering or parameter usage, leaving gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the 6 parameters (e.g., thread_id, status, limit). The agent must infer meaning from names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists pending interactions including approvals, input requests, and elicitation requests. It distinguishes from siblings by naming the types and providing next steps.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use context ('when operation or workflow status reports pending interaction') and suggests next actions (answer or ask human), but does not explicitly mention when not to use or compare to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description lacks detail on what checks are performed, whether it's read-only, or side effects. Only mentions skipped worker-managed account checks.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no fluff. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having output schema, description fails to cover parameter semantics and behavioral details, leaving significant gaps for an 8-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and description does not explain any of the 8 parameters, including enums. Agent has no guidance on parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb (check) and resource (project safety). It distinguishes from siblings by being a preflight check, not execution or management.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'after project discovery and before write operations.' Also provides guidance on handling skipped checks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states the tool is 'passive' (indicating read-only behavior) but lacks details on authentication requirements, error conditions, or whether the agent guide is always available. With empty annotations, more behavioral context would be beneficial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the action. However, it could include brief parameter guidance without losing conciseness. Currently, it omits essential parameter context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the output schema exists (reducing need to describe return values), the tool's three parameters are completely undocumented. The description's use cases ('full contract examples') do not link to parameter values, leaving the agent guessing. This is insufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description provides no information about the three parameters (detail, client_type, include_examples). The agent cannot infer how to set these based on the description alone, which is a critical gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reads a machine-readable agent guide for this MCP server. It specifies two distinct use cases: when tools/list metadata is unavailable or when full contract examples are needed. This distinguishes it from sibling tools like codex_get_runtime_capabilities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly specifies when to use the tool ('when tools/list metadata was unavailable or when a client wants the full contract examples') and mentions the next normal startup call (codex_health_summary). This provides clear context for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior but only notes that it polls a command and provides a parameter hint. It does not mention idempotency, error handling, authentication requirements, or rate limits. The polling nature is implied but not detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with purpose, and contains no redundant information. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and the listing of command types, the description is adequate for basic usage. However, it lacks depth on parameter specifics and error scenarios. The output schema may compensate for return value details, but the description itself is only partially complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should compensate. It only provides semantic guidance for the include_result parameter ('Keep include_result=false unless needed'), leaving command_id and max_result_chars unexplained. This is insufficient for a tool with three parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Poll' and the resource 'worker command created by a client-mode control action'. It lists specific command types (archive, unarchive, compaction, etc.) which helps distinguish this tool from siblings like codex_get_worker_status or codex_get_thread_compaction_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly lists the types of commands to use this for (archive, unarchive, compaction, etc.) and advises on when to set include_result=false. It does not provide explicit when-not-to-use guidance or alternative tools, but the context is clear enough for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It states the operation is durable and returns immediately, and mentions idempotency via client_request_id. It does not discuss potential side effects, rate limits, or failure behavior, which is a gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, efficiently front-loading the core action and key usage notes without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 29 parameters and many siblings, the description is too brief. It does not explain how to choose operation types, the meaning of many parameters, or the overall workflow, leaving much to the schema and agent's interpretation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 45%, so many parameters are already documented. The description adds value by highlighting client_request_id and project_id importance, but does not elaborate on most other parameters beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool queues a durable write operation and returns an operationId. It mentions the return behavior and project-scoped work, but does not clearly differentiate from sibling tools like codex_start_chat or codex_send_message, which may be specific operation types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance: pass project_id for project-scoped work, always provide client_request_id, and poll codex_get_operation_status. However, it does not mention when not to use this tool or list alternatives for specific use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With empty annotations, the description must disclose behavioral traits. It mentions 'queue execution' but does not elaborate on side effects, permissions required, or whether the plan is locked after approval. The description is functional but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, direct and front-loaded with the action. Every sentence serves a purpose, and there is no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having 8 parameters and an output schema, the description is too sparse. It does not explain optional parameters like message, approval_policy, or timeout_seconds, nor does it describe the return value or expected outcome. More detail is needed for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25% (2 of 8 parameters have descriptions). The tool description does not add any parameter-specific meaning beyond the schema. It mentions workflowId in the narrative but without clarifying its role. For a tool with many parameters, more guidance is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Approve the latest ready plan and queue execution.' It specifies the resource (plan) and verb (approve), and distinguishes it from sibling tools like codex_adopt_workflow_plan and codex_execute_plan.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use this tool: after codex_get_workflow_status reports plan_ready and a valid latestPlan. It also indicates the next step: poll codex_get_workflow_status with the same workflowId. It does not explicitly state when not to use it, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are empty, so description must cover behavior. It states it's a read-only operation ('without starting it'), but does not detail side effects, authorization, or error conditions. Adequate but lacks depth expected from absent annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, no filler. Front-loaded with the core action and key differentiator. Missing parameter detail slightly reduces conciseness value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With output schema present, return format is covered elsewhere. However, the description omits parameter documentation and does not address prerequisites or edge cases, leaving some gaps for a tool with moderate complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description does not mention the parameter 'include_recent_events' or its effect. The agent must infer meaning from the parameter name alone, which is insufficient for informed invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads app-server status without starting it, and distinguishes it from related tools by specifying its use with worker, queue, and concurrency status. The phrase 'MCP-owned' clarifies the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly recommends using with worker, queue, and concurrency status to verify active work, and advises preferring worker-derived active turns in client mode. Does not explicitly list alternatives or situations to avoid, but provides clear contextual guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that logs are redacted and that raw payload mode remains 'secret-redacted', but does not address destructive behavior, authentication, rate limits, or idempotency. The read-only nature is implied but not explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loading the purpose and then providing usage guidelines. Every sentence adds value with no repetition or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description lacks sufficient detail for a tool with 10 parameters and no parameter descriptions. It does not explain the structure of the output, the effect of filters, or error conditions, leaving significant gaps for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description mentions 'filters' and 'raw payload mode' but does not explain any of the 10 parameters individually. Given 0% schema description coverage, the description should compensate, but it only hints at the purpose without detailing source, severity, time filters, or other inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads redacted diagnostic logs and app-server audit entries with filters, specifying the verb 'Read' and the target resources. It differentiates from siblings like codex_collect_diagnostics by emphasizing targeted troubleshooting rather than normal polling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this only for targeted troubleshooting, not normal polling,' providing clear usage context. It also explains that raw payload mode is for local audit, but does not name alternative tools for polling, which prevents a score of 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the burden. It mentions the evidence sources (tracked, hook, transcript, cached) but does not disclose if the operation is read-only or any side effects. The behavior is implied to be non-destructive, but not explicitly stated, leaving room for ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first describes purpose, second provides usage guidance. No unnecessary words. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (7 parameters, output schema exists), the description covers core purpose and usage but lacks details on how activity is determined, pagination, sorting, or result set behavior. It's minimal but passes the threshold for basic understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any parameters. Parameters like 'include_waiting_for_user', 'active_window_minutes', and 'title_max_chars' have self-explanatory names but could benefit from annotation. The description adds no value beyond the schema, which is insufficient for a tool with 7 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it lists chats that look active based on various evidence sources, and specifies use for operator inspection. However, it does not explicitly differentiate from sibling tools like codex_list_project_chats or codex_search_chats, missing a chance to clarify when to choose this over alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('operator inspection'), when not to ('not for creating retries'), and provides next-step suggestions ('Next call codex_get_turn_status or codex_get_operation_status when ids are available'). This is clear, actionable guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It mentions 'bounded read model' hinting at scope, but omits behavioral traits like pagination, authorization, or mutability. Does not contradict annotations (none).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each serving a clear purpose: first defines function, second gives usage guidance. No fluff, front-loaded effectively.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, no annotations, but output schema exists. The description covers primary function and usage but lacks details on pagination, filtering, and preview options. Adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description adds no detail on parameters like include_archived, cursor, limit, etc. Beyond stating 'list chats,' it fails to compensate for empty schema descriptions, leaving agents guessing about optional controls.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as listing chats for one project from a bounded read model, distinguishing it from siblings like codex_list_active_chats (cross-project) and codex_search_chats (search). The verb 'list' and object 'chats' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states use case: 'find existing threads before continuation or review.' Also suggests next calls. Lacks explicit when-not-to-use or alternatives, but the provided context is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals that in client mode the action is delegated to the worker command lane, and implies that active work should be absent, indicating potential disruption. However, it does not explain other behavioral traits such as whether the restart is graceful, what happens to app state, or authorization requirements. With empty annotations, more transparency would be beneficial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at three sentences, immediately stating the core purpose ('Restart only the MCP-owned codex-app-server subprocess'), then providing usage and behavioral context. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the primary purpose, usage conditions, and a special behavioral note for client mode. However, it lacks details on parameter semantics, return values (though output schema exists but is not described), and safety considerations beyond the active-work caveat. Given the tool's moderate complexity (3 optional parameters) and no annotations, the description is partially complete but leaves important questions unanswered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has three parameters (start_after_restart, timeout_seconds, force) with no descriptions (0% coverage). The tool description does not explain or expand on any of these parameters, leaving the agent without guidance on their purpose or impact. This is a significant gap for a tool with optional parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action (restart) and the target (MCP-owned codex-app-server subprocess), which is a specific verb+resource combination. It distinguishes from related tools like codex_get_app_server_status by focusing on restarting the subprocess, a unique operation among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: only when guidance recommends restart and active work is absent or handled. It also notes behavior differences in client mode, helping the agent understand context. No alternative is mentioned, but no alternative exists among siblings, so it's sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes the mechanism (worker or app-server command lane) and that it returns a commandId, but does not detail side effects, permissions, or state changes beyond 'unarchive'. With no annotations, more detail would be helpful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences that efficiently convey purpose, usage condition, and follow-up step. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers core purpose and a follow-up step, but lacks details on parameter semantics and prerequisite conditions. Given the 4 parameters and no schema descriptions, more completeness would be warranted despite the presence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 4 parameters with 0% description coverage. The description does not explain any parameter beyond the core action, leaving timeout_seconds and refresh_catalog ambiguous. The parameter names provide some hints, but the description adds no value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (unarchive) and the resource (Codex thread), and the phrase 'known Codex thread' distinguishes it from similar tools like codex_archive_thread.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (only for existing archived thread) and provides a next step (poll codex_get_worker_command_status). No explicit when-not-to-use, but the condition is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are empty, so description carries burden. It labels as 'Compatibility write' and mentions delegation, but does not clarify that the call returns immediately (only hinted in parameter description) or other behavioral traits like error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with front-loaded purpose and clear guidance. Minimal waste, but could be slightly more structured to include parameter or behavior highlights.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given complexity (10 params, enums, output schema), the description covers purpose and a sibling alternative but omits parameter semantics, prerequisites (existing thread), and return value orientation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 10% (one parameter described). The description adds no parameter explanations, leaving the agent to infer from names and enums, which is insufficient for many parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sends a message to an existing Codex thread and distinguishes from codex_submit_task by noting preference for durable long work. It uses specific verbs and resource references.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises when to avoid this tool ('Prefer codex_submit_task...') and mentions delegation to durable queue in client mode, providing clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must carry the burden. It implies read-only behavior via 'inspect' and 'safe previews,' but does not explicitly guarantee idempotence or declare lack of side effects. The term 'lightweight' hints at low cost, but more explicit safety assurances would be better.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences plus a guidance sentence. No filler, front-loaded with purpose. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema (exists) and only three parameters (one required), the description is functionally complete for a simple read operation. However, it lacks parameter descriptions and does not elaborate on the preview behavior (e.g., default char limit). Adequate but not rich.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It mentions 'previews' hinting at preview_max_chars, but does not explain chat_id or project_id semantics. The parameter roles and how they affect behavior are left to inference.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Read') and resource ('lightweight chat status and safe previews'). It distinguishes from siblings by explicitly naming alternative tools (codex_get_chat, codex_submit_task) and their different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Use this to inspect a known thread without starting live work.' And provides clear next steps: 'Next call codex_get_chat for content or codex_submit_task for a new operation.' This helps the agent decide among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are empty, so description carries full burden. It labels the tool as 'passive' and says it returns 'bounded status or guidance', indicating read-only behavior and predictable output. No side effects disclosed, but this suffices for a polling tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action verb 'Poll'. Every line adds essential context: purpose then usage and behavior. No redundancies.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema, return values are covered. However, the description doesn't mention the optional parameter or elaborate on what 'bounded status' means. It could more clearly differentiate this from generic status tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description only implicitly addresses the action_id parameter by noting its source, but the optional include_events parameter is completely unexplained. This leaves an agent guessing about the boolean's effect.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool polls a thread compaction action and ties it to 'codex_start_thread_compaction'. This differentiates it from other status tools like 'codex_get_operation_status' by specifying the resource and verb.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description instructs to use the actionId from codex_start_thread_compaction, giving clear context for when to invoke. It implies a sequential usage pattern but stops short of listing when not to use or suggesting alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description discloses multiple data sources and the mapping from references to canonical projectId. However, it does not mention side effects, permissions, or the behavior of the refresh parameter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is two sentences, front-loads the main purpose, and includes actionable guidance. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Overall context is good with usage flow, but parameter semantics are missing. Output schema exists but is not described. The complexity of 5 undocumented parameters is not addressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and description provides no explanation for any of the 5 parameters (compact, limit, refresh, include_private_details, roots). Despite the requirement to compensate, no parameter details are given.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'List', resource 'Codex projects', and data sources (registry, hook history, transcripts, cached state). It distinguishes from sibling tools by noting this is used before preflight/submit to obtain project references.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this before preflight or submit when you need a project reference' and recommends next call to codex_preflight_project_run. Also explains that later tools accept projectId, name, or path.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description provides key behavioral traits: it recommends actions (not executes), defers to agentGuidance, and is analytical in nature. It lacks details on side effects (likely none) and doesn't explicitly state it's read-only, but the context implies non-mutative behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each purposeful. First sentence states purpose, second gives usage context, third provides behavioral guidance. No unnecessary words, front-loaded effectively.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of 10 optional parameters and no schema descriptions, the description is insufficient. It does not help the agent understand how to scope diagnostics using the parameters. The output schema exists but doesn't compensate for missing input guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description fails to explain any of the 10 parameters. Despite 0% schema description coverage, it does not mention problem_text, operation_id, since_minutes, etc. or how to use them. The agent has no guidance on parameter selection beyond defaults in schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: analyze scoped diagnostics and recommend safe next actions. It specifies the verb 'analyze', the resource 'scoped diagnostics', and the outcome. It also distinguishes from sibling tools by mentioning after collect_diagnostics and for compact root-cause summary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: after collect_diagnostics or when a human needs a compact root-cause summary. Also provides a behavioral constraint: 'Follow agentGuidance rather than inventing retries', which guides correct usage and prevents inappropriate retries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It declares a read operation ('Read') and gives behavioral advice (do not retry). While it doesn't cover auth or rate limits, it sufficiently describes the read nature and outputs for this 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose, no fluff. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, so return values are covered. However, the description lacks guidance on input parameters (status filter, limit) which is needed for proper use. It is borderline adequate but missing key parameter context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description should explain parameters. However, the description mentions 'queued reasons, running operations, worker assignment' but does not describe the 'status' filter or 'limit' pagination parameter. These are significant omissions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads 'durable queue state, queued reasons, running operations, and worker assignment', specifying a verb and resource. This distinguishes it from sibling tools like codex_get_worker_status and codex_get_operation_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: 'Use this to understand slot pressure or lock waits' and a clear directive: 'Do not retry when queued work already exists'. This helps the agent decide when to invoke the tool and what not to do.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With empty annotations, the description carries full behavioral burden. It reveals default polling behavior ('from storage by default'), passive nature (via refresh_live descriptions), and usage rule ('do not create replacement work'). This adds significant value beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, containing no fluff. Every sentence adds meaning: purpose, usage context, and a critical behavioral guideline. It is front-loaded with the primary action and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters (1 required), empty annotations, and an output schema, the description provides sufficient context for usage. It covers polling behavior, live refresh nuances, and usage boundaries. The output schema covers return values, so no need to elaborate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 33% (only refresh_live and refresh_live_goal have descriptions). The overall description does not elaborate on the other four parameters (workflow_id, last_messages, message_max_chars, include_events). The refresh_live descriptions are well-covered, but the majority lack additional meaning from the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Poll workflow state from storage by default' with a specific verb and resource. It further distinguishes usage by specifying contexts: 'Use this for Plan Mode, execution, and review workflows.' This effectively differentiates it from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage contexts ('Plan Mode, execution, and review workflows') and behavioral guidance ('Follow nextRecommendedAction and do not create replacement work'). While it does not mention alternatives, the context is clear enough for the agent to decide when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It clearly labels the tool as a 'Read' operation, implying no side effects or destructive actions. However, it does not mention caching, latency, or any rate limits, which is acceptable for a lightweight health read.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The first sentence states the core purpose, and the second provides clear usage guidance. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists, return values need not be described. However, with 10 parameters and a health-check tool, more context on parameter usage (e.g., filters, defaults) would improve usability. The description is adequate for the simplest use but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning no parameter descriptions exist in the schema. The tool description adds no information about any of the 10 parameters (e.g., operation_id, since_minutes). The agent must infer their meaning from names alone, which is insufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Read' and identifies clearly the resource: 'compact MCP readiness and contract metadata'. It also distinguishes this tool as a first-step health check among many sibling tools like codex_get_runtime_capabilities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Use this first on startup, reconnect, and after MCP restart.' It also provides follow-up actions: 'Next inspect runtime capabilities or follow agentGuidance if health is degraded,' guiding the agent in decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes the operation as starting compaction (async) and returning actionId. No annotations exist, but the description gives essential behavioral context. Minor gap: no mention of failure modes or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff, front-loaded with purpose and usage. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Provides essential flow but lacks details on preconditions (e.g., thread must be active), error conditions, or output format beyond actionId. Output schema exists but description doesn't leverage it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description adds no meaning for thread_id, project_id, or timeout_seconds. The agent must guess parameter roles beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool starts context compaction for a known thread and returns an actionId. Differentiates from sibling tools by specifying the next step to poll compaction status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use after active work is terminal and instructs to poll codex_get_thread_compaction_status next, providing clear context for when and how to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/aresyn/codex-control-plane-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server