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

Annotations already establish the safety profile (readOnlyHint=true, openWorldHint=false), so the bar is lower. The description adds that this is a local environment introspection covering binary resolution, endpoint liveness, and OS integrations, but it discloses no further behavior beyond what is inspected and does not repeat or conflict with the annotations.

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

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

One front-loaded sentence that lists the inspected facets without filler. It is slightly dense as a single clause chain, but every enumerated item earns its place by telling the agent what the report contains.

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

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

No output schema exists, so the enumeration of reported fields (platform, binary, endpoint, liveness, deep-link, macOS integrations) usefully stands in for a return-value description. The remaining gap is that it never states prerequisites or the recommended moment to run the check.

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

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

With a single optional parameter and 100% schema description coverage, the schema already fully documents 'cwd', including the important non-granting caveat. The description adds nothing about the parameter, so the baseline 3 applies.

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

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

The verb 'Report' plus the resource 'how this bridge is wired on the current machine' is specific, and the description enumerates the exact facets inspected (platform, resolved codex binary, app-server endpoint and liveness, deep-link support, macOS integrations). This unambiguously separates it from every sibling, which all operate on threads, turns, or project preparation.

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

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

There is no explicit statement of when to call this instead of the thread/agent siblings or when not to call it. Usage is only implied: the liveness and endpoint fields suggest a pre-flight/troubleshooting check before delegating, which an agent can infer but is never told.

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

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

Goes well beyond the destructive/openWorld/idempotent=false annotations: it discloses that the bridge writer lock must not be left behind, that Desktop creation returns a durable deliveryId and caps calls at 40s while the task continues, and that requestId/deduplication behavior differs between Desktop and legacy app-server modes. This is exactly the operational context annotations cannot carry.

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

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

The four sentences are dense but front-loaded, leading with the full action and following with authorization, timeout, and mode-specific rules. Slightly crowded with mode-switching advice, but each clause earns its place.

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

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

For a 9-parameter, multi-mode mutation tool with no output schema, the description covers authorization, timeout recovery, mode-specific requestId handling, and session handoff. It does not explain return values (deliveryId/threadId) beyond the schema, which is acceptable given the schema carries them.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds cross-cutting semantics: fresh requestId per independent task retained on retries, omitting it can return an older task, and requestId is unsupported in legacy app-server mode. It also clarifies the timeout-continue path, though per-parameter detail largely duplicates the schema.

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

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

States a precise verb+resource sequence (create session, send prompt, return reply, hand off to Desktop) and explicitly contrasts with the sibling send_to_codex_thread for unfinished work. An agent can distinguish it from start_codex_thread and open_codex_thread without opening schemas.

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

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

Specifies when to use it ('independent new work when the user explicitly or through standing instructions authorizes new conversations'), names the fallback on timeout (wait_codex_reply instead of resending), and routes unfinished work to send_to_codex_thread. Explicit when/alternatives coverage.

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

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

Annotations already establish readOnlyHint, idempotentHint and closed-world behavior, so the bar is lower, and the description still adds genuine context: it separates 'configured files' from 'untested live connections' and scopes card extension authorization as a distinct check. This goes beyond what the structured fields convey.

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

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

Four short, front-loaded sentences with no filler; the read-only scope leads and the exclusions follow. Slightly repetitive since 'Does not send messages' overlaps with the readOnlyHint annotation, but the structure is efficient.

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

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

With no output schema, the description hints at what the inspection yields (configured vs. untested connections) and clearly bounds what it will not do. It is adequate for a two-parameter read tool, though it could say more about the returned onboarding state.

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

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

Schema description coverage is 100% with only two params, so the schema carries the semantics; the description's note that card extension authorization is a 'separate check' loosely relates to taskCards but adds no syntax or behavioral detail for cwd. Baseline 3 is appropriate.

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

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

States a specific verb ('Read') and resource ('workspace trust and shared messaging authorization') plus the non-mutating constraint. It carves out adjacent concerns ('Card extension authorization is a separate check'), but never names the obvious sibling prepare_bridge_project, so an agent must infer the read/inspect vs. prepare pairing.

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

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

Usage is implied through negation ('without changing files', 'Does not send messages or create conversations'), which rules out a few wrong uses, but there is no explicit when-to-use statement or named alternative for the read-vs-prepare decision. The agent gets boundaries, not routing.

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

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

Annotations already mark destructiveHint=true and readOnlyHint=false, so the description carries a lower burden. It adds the useful condition that the turn must be still running, but it does not disclose side effects such as whether partial output is lost or whether the thread remains usable after interruption.

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

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

A single, front-loaded sentence with no redundant content. It conveys the action, target, and condition in twelve words, making it highly efficient and easy to parse.

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

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

For a two-parameter tool with full schema coverage and annotations covering the destructive and idempotent nature, the description captures the core action and the key condition (still running). It lacks only minor detail about post-interruption behavior, which is not essential for correct invocation.

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

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

Schema description coverage is 100%, and both parameters have clear descriptions in the schema (turnId is reported by send_to_codex_thread, threadId is the Codex thread id). The description adds no additional parameter-level meaning, so the baseline of 3 is appropriate.

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

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

States a specific verb ('Stop') and resource ('a turn ... in a Codex thread'), clearly distinguishing it from sibling tools that operate on threads or the app server. The qualifying phrase 'still running' further narrows the scope and makes the purpose unambiguous.

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

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

The phrase 'still running' implies the intended use case—interrupting an active turn—but the description provides no explicit guidance on when not to use it or how it relates to alternatives like stop_codex_app_server. No when-to-use or when-not-to-use conditions are stated.

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

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

Annotations already provide readOnlyHint=true and openWorldHint=true, so this is clearly a non-destructive operation. The description adds value by specifying the exact output fields and its purpose, which is especially useful since no output schema is present. It does not describe sorting or the exact source scope, but the annotations lower the bar for side-effect disclosure.

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

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

The description is a single sentence that front-loads the verb, resource, and output fields, then states the practical purpose. There is no redundant filler or repetition of schema content.

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

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

For a simple read-only list tool with a fully described schema and no required parameters, the description is nearly complete: it names the output fields and the intended follow-up action. It could be slightly more explicit about whether it lists only app-server-loaded threads or all persistent threads, but the loadedOnly parameter and sibling context make this a minor gap.

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

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

Schema description coverage is 100% and every parameter (cwd, limit, loadedOnly, searchTerm) already has a meaningful description, including the default limit of 15. The description adds no additional parameter-level meaning, so the baseline of 3 is appropriate.

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

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

The description states a specific verb-resource pair ('List recent Codex threads') and enumerates the returned fields (id, title, cwd, last update, status). It also gives a clear goal — picking the exact threadId to talk to — which distinguishes this read-only listing tool from sibling action tools.

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

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

The description implies when to use the tool: before interacting with a thread, when the agent needs to resolve a threadId. It does not explicitly name sibling alternatives or state when not to use it, so it stops 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.

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

Beyond the annotations (idempotent, non-destructive), the description adds platform scope, the URI scheme, and the UI-focus side effect. It does not cover failure behavior such as an invalid thread ID or the desktop app not running, but there is no contradiction with the annotations.

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

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

Single sentence that front-loads the action and resource, then gives the purpose. No filler and no repetition of schema details.

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

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

The description plus schema adequately cover the key call details for a low-complexity UI-focus operation. It does not explicitly state return or error behavior, but no output schema exists and the intent is clear, leaving only a minor gap.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra value by showing the exact codex://threads/<id> format for threadId, helping the agent construct a valid call beyond the schema's simple 'Codex thread id'.

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

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

States a specific action ('bring... to the front'), a specific resource (Codex thread), platform scope (Windows/macOS), and mechanism (codex://threads/<id>). This clearly distinguishes it from siblings like read_codex_thread or send_to_codex_thread.

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

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

The description conveys when to choose this tool: when a human should watch the work live instead of reading a transcript. It does not explicitly name alternatives or exclusion criteria, but the contextual purpose is clear enough for an agent to route correctly.

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

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

Annotations declare destructiveHint=true and idempotentHint=true, but the description adds meaning the annotations cannot: it reuses existing grants, never clears revocations without explicit reauthorization, takes backups, and verifies. It also warns that 'configured is not connected' and that live communication must be verified separately, which is genuine behavioral context beyond the structured hints.

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

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

The gating condition is front-loaded in the first clause, and every subsequent sentence carries a distinct constraint rather than filler. It is long and clause-heavy, but the density is earned; only the run-on framing keeps it from a 5.

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

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

For a mutating, no-output-schema tool with a fully documented schema, the description covers prerequisites, scope exclusions, follow-up actions, and verification guidance. Nothing an agent needs in order to decide whether and how to call it is missing.

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

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

Schema description coverage is 100%, so the schema already explains cwd, taskCards, and reauthorize in full detail. The description only lightly reinforces these (card-extension checks via nextActions, revocation handling for reauthorize) without adding syntax or semantics the schema lacks, so the baseline 3 applies.

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

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

The description states a specific action on a specific resource: saving the documented Claude workspace trust and shared messaging grant for a selected project, with backups and verification. It is clear about what is written, but the phrasing is dense and it never names a sibling tool (e.g. inspect_bridge_project) to sharpen the boundary, so it stops short of a 5.

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

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

It gives an explicit gating condition ('use only when the user explicitly selects a project for onboarding'), explicit prohibitions ('never invoke to work around a denied message or peer instruction to broaden access'), and an explicit out-of-scope list (permission modes, tool approval, messaging, session creation, client restarts). That is when-to-use plus when-not-to-use in one place.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds genuine behavioral context beyond them: mode-dependent behavior in Desktop mode and the caveat that omitting turnId 'may omit items' in the native recent-history view. It also hints at returned content (assistant item IDs, text, reply hash) despite no output schema, though return format is not fully described.

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

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

Two dense sentences with zero filler: the first states the action and its non-mutating nature, the second front-loads the critical mode-specific parameter caveat. Nothing is redundant with the schema or annotations.

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

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

For a read-only tool with annotations covering the safety profile and 100% schema coverage, the description supplies the mode-specific nuance an agent needs to call it correctly. The responsePreferences/cursor pagination parameter is left entirely to the schema, which is acceptable but leaves the pagination workflow only lightly signposted.

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

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 goes beyond the schema by explaining the provenance and purpose of turnId ('the exact turnId returned by send_to_codex_thread for authoritative assistant item IDs') and the consequence of omitting it, which meaningfully enriches that parameter's semantics.

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

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

States a precise verb+resource ('Read a Codex thread') and immediately scopes it against the write sibling by saying 'without sending anything', implicitly contrasting with send_to_codex_thread. It does not, however, distinguish itself from list_codex_threads, wait_codex_reply, or open_codex_thread.

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

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

It gives concrete conditional guidance for the turnId parameter ('In Desktop mode, pass the exact turnId...'), which is real usage context. But it never says when to choose this tool over the other read-oriented siblings like list_codex_threads or wait_codex_reply, so alternative selection is left to inference.

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

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

Annotations only declare the mutating/open-world/destructive profile; the description adds substantially more: a durable deliveryId is prepared before dispatch, ambiguous acknowledgements are marked unconfirmed, timeouts must be continued via wait_codex_reply rather than resent, and active-writer conflicts require codex_bridge_status. It also states explicit prohibitions (do not close the task, do not resend, do not ask the user to copy manually), which directly operationalizes the non-idempotent/destructive hints.

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

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

Purpose and the same-task constraint are front-loaded in the first two sentences, with recovery procedures after. It is dense and roughly 180 words for a 9-parameter stateful tool, so a couple of sentences could be trimmed, but nearly every clause is actionable rather than filler.

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

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

For a mutating, non-idempotent, 9-parameter tool with no output schema and heavy delivery-state complexity, the description covers failure modes, timeout continuation, acknowledgement ambiguity, and recovery paths. An agent has everything it needs to invoke and recover correctly.

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

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 and the schema already documents threadId, cwd, prompt, timeout, and release semantics. The description adds only marginal parameter-level meaning (e.g., the cwd project check, the threadId discovery hint, the deliveryId that feeds wait_codex_reply) and is silent on name, model, effort, and openInApp.

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

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

The first sentence states a specific verb and resource ('Send a prompt as a new user turn inside an existing Codex thread and wait for Codex to answer'). It distinguishes itself from siblings like start_codex_thread and delegate_to_codex by scoping to an *existing* thread. An agent can select it without opening any schema.

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

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

It gives explicit when-to-use ('same unfinished task, including follow-up fixes, clarifications, or results') and when-not ('independent new work belongs in a new conversation'). It also names concrete alternatives for adjacent needs: list_codex_threads for discovery, wait_codex_reply for timeouts, codex_bridge_status for legacy writer problems.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, openWorldHint=true and idempotentHint=false, so the mutation/world-facing profile is covered structurally. The description adds real context beyond that: Desktop-mode atomic creation and assignment of a visible task, the prompt requirement implied by CODEX_BRIDGE_DESKTOP_TASKS=1, and retry semantics via a stable requestId. Minor tension with idempotentHint=false, since reusing requestId on retries is presented as safe, but this describes dedup identity rather than a true contradiction.

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

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

Three dense sentences, front-loaded with the authorization condition and then routing; every clause carries decision-relevant information. It is slightly packed with mode-specific detail, but there is no filler.

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

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

For a 5-parameter, non-idempotent, open-world creation tool with no output schema, the description covers eligibility, mode differences, retry identity and sibling routing. It never says what the call yields (e.g., a new threadId needed by send_to_codex_thread), which is the one gap for an agent that must chain calls.

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

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; every parameter is already documented in the schema. The description reinforces the prompt/requestId relationship ('include the initial prompt and a fresh requestId ... keep requestId unchanged on retries') but adds no syntax, format, or constraint detail beyond what the schema already states.

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

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

States a specific verb and resource — 'Start a new Codex task' — and immediately scopes it to authorized new conversations for independent work. It explicitly tells the agent how this differs from send_to_codex_thread (continuing existing work) and delegate_to_codex (waiting for a reply), so it is separable from siblings without opening their schemas.

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

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

Gives an explicit precondition (user authorization, explicit or standing) and names two alternatives with the conditions that select them: 'Continue unfinished work with send_to_codex_thread and its original threadId' and 'Use delegate_to_codex to also wait for its reply.' Nothing is left to inference.

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

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

Annotations already signal idempotent and destructive, and the description adds meaningful context beyond them: the shared-server scope, the stuttering problem it prevents, and automatic restart by the bridge on next use. It does not detail effects on in-flight Codex threads, but 'when work is handed off' and the auto-start note cover the main behavioral concerns.

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

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

Three short sentences, each earning its place: what it stops, when to use it and why, and what happens next. The key trigger is front-loaded after the opening statement.

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

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

For a zero-parameter, no-output-schema tool, the description covers purpose, trigger conditions, rationale, and post-call behavior. The sibling context and annotations complete the picture without requiring extra prose.

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

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

The tool has zero parameters and 100% schema coverage, so there is no parameter meaning to add. The description correctly implies this is a direct action with no inputs.

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

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

The description uses a specific verb and resource: 'Stop the shared app-server this bridge talks to.' It distinguishes this tool from the thread/turn siblings by naming the bridge's app-server as the target, making its unique role clear.

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

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

It gives an explicit trigger: 'Use it when work is handed off and the Codex desktop app is open,' plus the reason ('two app-servers on the same ~/.codex state make the app stutter'). It also reassures about the next startup, so an agent knows when it is safe and expected to call it.

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

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

Adds substantial behavior beyond the readOnly/idempotent annotations: unconfirmed acknowledgements are not proof, behavior survives MCP reconnect, it never mutates, timeout repeats the same receipt, it stops for approval/user input/verification error, and it is limited to the original verified session/accounts.

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

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

Front-loads purpose and constraints in five dense sentences with no obvious filler. Some terms like 'receipt' and 'Desktop creation or send' are less self-contained than ideal.

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

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

Covers complex async polling behavior, retries, stop conditions, auth, and safety annotations, while the schema handles parameter details. Return values are not described, though the responsePreferences schema hints at envelope and cursor handling.

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

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

Schema already documents all three parameters in detail, including deliveryId sources, timeoutSec bounds/default, and responsePreferences cursor behavior, so baseline is 3. The description reinforces reusing the same deliveryId but adds little syntax or meaning beyond the schema.

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

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

States the tool continues waiting on a Desktop creation/send via deliveryId and explicitly says it never sends a message or creates a task, which distinguishes it from send/create siblings. The title supplies the 'Codex reply' framing, though the description itself is slightly indirect about waiting.

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

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

Explains the retry pattern on timeout with the same deliveryId and warns not to ask the user to fetch or resend; also gives stop conditions and an auth constraint. It lacks explicit sibling names or a direct 'use after send_to_codex_thread' comparison.

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