Server Quality Checklist

Tool Scores

• codex_interruptA
  4.2/5.0
  Behavior4/5

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

  Annotations already indicate destructive and idempotent hints, but the description adds valuable context by clarifying that the interrupt does not stop or restart Bridge/app-server processes. This reduces risk of misuse, even though it doesn't specify async behavior or effects on already-completed turns.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Two sentences, front-loaded with the action, and every part adds value. No filler or redundancy.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple two-parameter tool with annotated destructiveness, the description sufficiently covers purpose and boundaries. No output schema means return-value details are not expected. Minor gap: no mention of whether interrupt is asynchronous or what happens if the turn is not active.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100% with clear descriptions for thread_id and turn_id. The description merely repeats 'active thread and turn' without adding meaning beyond the schema, so baseline 3 is appropriate.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description uses a specific verb phrase ('Directly request turn/interrupt') and names the exact resource ('specified active Codex thread and turn'). It clearly distinguishes from sibling tools by stating it does not stop or restart processes, matching the interrupt-only 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/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Provides clear context: it is for sending an interrupt request to an active thread/turn. The exclusion of process-level control is stated, which implicitly differentiates from broader lifecycle tools. However, it does not explicitly name alternatives or situations where a different tool would be preferred.

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

• codex_respondA
  4.2/5.0
  Behavior4/5

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

  Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds useful behavioral context by noting that unsupported methods 'remain pending and observable' and that each call answers exactly one request, which goes beyond the annotation data.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is compact at two sentences. The first sentence conveys the core action and target; the second adds critical constraints (supported methods, behavior for unsupported ones). No wasted words.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the tool's complexity (8 parameters, nested objects, no output schema), the description captures the essential purpose, supported method types, and a key behavioral trait. It could emphasize destructive side effects more, but the annotations already indicate destructiveness, so the description is sufficiently complete.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, so the baseline is 3. The description adds a little semantic grouping (e.g., 'command/file approval methods' for decision/execpolicy_amendment, 'item/tool/requestUserInput' for answers/response) but does not significantly go beyond the schema's own descriptions.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's verb ('Answer') and resource ('one currently pending app-server request') with specific scope markers (original JSON-RPC id, exact thread/method). It also distinguishes itself from siblings by focusing on approval/response methods and explicitly noting that unsupported methods remain pending and observable.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description provides clear context on when to use the tool (when there is a pending request) and explicitly excludes unsupported methods ('Supports only...'; unsupported methods remain pending). It does not name alternatives directly, but the scope and exclusions are clear.

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

• codex_threadsA
  4.2/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context beyond this by specifying the threads are 'persistent local' and clarifying that the tool does not reconstruct live events. This is substantial but does not cover all edge cases (e.g., pagination errors, data source specifics), so a 4 is appropriate.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Two sentences, front-loaded with an unambiguous summary, and no wasted words. Every sentence earns its place: the first states the main actions, the second clarifies an important behavioral boundary.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the tool's dual mode (list/read) and the presence of six documented optional parameters plus comprehensive annotations, the description adequately covers the main purpose and an important caveat. It could briefly mention what the read returns when include_turns is false, but the schema handles this. Overall, it is complete enough for an AI agent to select and invoke correctly.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, so the schema already documents all parameters. The description adds a small amount of context by naming 'thread/list' and 'thread/read' modes, but this is largely redundant with the schema's thread_id description. Baseline 3 applies because the description does not substantially compensate beyond the schema.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description uses specific action verbs 'List or search' and 'read', names the resource ('persistent local Codex threads'), and explicitly scopes behavior with 'This does not reconstruct live Bridge events.' It clearly distinguishes from siblings by indicating it handles listing/reading rather than per-thread 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/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description states when to use the tool (to list/search/read persistent local threads) and provides an exclusion ('does not reconstruct live Bridge events'). However, it does not explicitly name an alternative sibling or provide a direct contrast with other tools, so it falls short of a 5.

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

• codex_turnA
  4.2/5.0
  Behavior4/5

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

  The description adds valuable behavioral details beyond annotations: it returns as soon as the turn is accepted, meaning it is asynchronous, and it warns that thread_id is not a permanent task identity. Annotations already mark the tool as destructive/open-world, so this context complements them without contradiction.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is three sentences with the core action front-loaded, followed by important nuances about thread reuse and asynchronous behavior. Every sentence earns its place with no redundancy.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given no output schema, the description appropriately clarifies the return value ('returns as soon as turn/start is accepted') and where to get actual results ('observe separately'). It doesn't cover error cases or param interactions, but the schema descriptions and annotations adequately cover those aspects.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The schema already covers all 7 parameters with descriptions (100% coverage), setting a baseline of 3. The description adds a useful caveat about thread_id not being permanent, but does not significantly enrich parameter understanding beyond what the schema provides.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool starts or resumes a Codex turn on a persistent thread, using a specific verb+resource. It distinguishes itself from siblings by being the entry point to initiate/continue turns, unlike interrupt/observe/steer.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  It provides explicit guidance on when to reuse a thread ('Prefer continuing the same native thread when its context remains useful') and when a fresh thread is allowed. It also directs the agent to 'observe separately for events and completion', indicating this tool is not for getting results directly.

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

• codex_steerA
  4.4/5.0
  Behavior4/5

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

  While annotations already indicate destructive behavior, the description adds context by specifying the expected_turn_id precondition and clarifying that the operation modifies the existing turn rather than creating one. No contradictions with annotations.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is concise and well-structured: the first sentence states the action, the second clarifies scope, and the third provides targeted usage guidance. Every sentence earns its place with no redundancy.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the tool's moderate complexity and lack of output schema, the description covers purpose, usage guidelines, and key behavioral details. It could mention error scenarios or postconditions, but the destructive annotation and clear action make it sufficiently complete for an agent.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The schema already provides 100% coverage with descriptions for all three parameters. The description reinforces the role of expected_turn_id as a precondition and text as appended content, but adds little novel semantic information beyond what the schema includes.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool appends text to the same active Codex turn, using a specific method (turn/steer) and a precondition. It explicitly says it does not create a new turn, distinguishing it from siblings like codex_turn or codex_threads.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description provides explicit when-to-use and when-not-to-use guidance: steer only for semantic redirect or correction based on new evidence or changed intent, and not merely because reasoning takes long or no new command appeared. This helps the agent choose appropriately among sibling tools.

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

• codex_observeA
  4.7/5.0
  Behavior5/5

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

  The description goes well beyond the annotations by documenting fallback behavior ('After Bridge process loss, falls back to persistent thread/read history'), the precise semantics of wait_ms ('one bounded event-driven wait only when the live turn is active'), and the caveat that a long interval without new commands is not evidence of a stall. It reveals useful runtime behavior such as 'inProgress' snapshots and live-state unreconstructability without contradicting the read-only/idempotent 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/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is long but front-loaded with the core action, followed by wait semantics, fallback behavior, and a supervision workflow. Every sentence carries actionable information, though there is minor redundancy with the schema's wait_ms explanation; the density is appropriate for the tool's complexity.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Despite having no output schema, the description explains the categories of returned data ('Bridge runtime events, pending requests, and terminal output'), the fallback path, and how the agent should react after each wake/deadline. It could be more explicit about the exact shape of the returned 'events/state' snapshot, but it provides strong contextual coverage for a complex observation tool.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The schema already fully describes all four parameters (100% coverage), including wait_ms's event-driven nature. The tool description adds meaningful nuance by restricting wait_ms to 'only when the live turn is active' and emphasizing 'one bounded' wait, which clarifies the operational contract beyond the schema text.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description uses a specific verb ('Read') and precisely names the resources: 'Bridge runtime events, pending requests, and terminal output for a thread.' It clarifies the observational scope with 'bounded incremental sanitized' and clearly distinguishes this from the sibling turn-management tools by framing it as the supervision/observation primitive.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description explicitly states when to use it: 'When actively supervising an in-progress turn, use repeated bounded-wait observe calls until terminal unless the user explicitly pauses or stops.' It also provides exclusions ('it is not polling or stall detection') and warns against treating inactivity as a stall, while naming follow-up actions (steer, respond, interruption).

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

• codex_checkpointA
  4.8/5.0
  Behavior5/5

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

  Annotations only say readOnlyHint=false, but the description adds rich behavioral context: key semantics (not a permanent task identity), update triggers (semantic event, material change), storage restrictions (never prompts/transcripts), and the requirement to read before final acceptance. This goes far beyond the annotations and is consistent with them.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is longer than average (~180 words), but every sentence earns its place by covering purpose, usage, exclusions, storage policy, and update semantics. It is well-structured, with clear statements and prohibitions, though some length could be trimmed without losing content.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the tool's complexity (11 parameters, multiple update conditions, acceptance process), the description is complete: it explains when to use, what to store, how updates work, and the read-before-acceptance rule. No output schema is present, but the description focuses on behavior and constraints, which is sufficient 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.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The schema already describes all 11 parameters (100% coverage). The description adds semantic meaning beyond the schema by explaining the immutable-vs-mutable distinction (original vs current/effective goal, original constraints, etc.), what should not be stored, and the relationship between parameters like original and effective goals. This adds value without repeating schema details.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's purpose: an optional, bounded supervisor cognition memory keyed to a Codex thread_id, used to protect the original goal, constraints, acceptance, and supervisor state. It distinguishes this tool from siblings by emphasizing it is uncoupled and optional, and by being specific about its function as a checkpoint for supervision context.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description gives explicit when-to-use guidance (long/complex supervision with context dilution or goal drift) and when-not-to-use guidance (one-shot work, no hard duration thresholds). It also notes the tool is optional and uncoupled from other tools, helping an agent decide when to invoke it versus alternatives.

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