claude-codex-mcp-bridge

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

With no annotations, the description carries the full behavioral burden. It usefully discloses worktree isolation and that the task is bounded to one unit of work, but it never says the run writes to the repository, whether changes are committed or left in the worktree, what permissions the worker needs, or what happens to worktree artifacts afterward. Those are meaningful gaps for a code-mutating tool.

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 sentences, zero waste, and the core action plus the 'simple entry point' framing are both front-loaded. Nothing is repeated from the title or schema.

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 7-parameter tool with no annotations and no output schema, the description covers purpose and routing but not the return shape or the async/mailbox fallback result, nor the side effects on the repo. The schema's waitSeconds text hints at the mailbox behavior, but the description itself leaves a caller unsure what comes back on a timeout.

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 each of the 7 parameters is already documented (defaults for threadId, projectPath, useWorktree, waitSeconds, coordinatorAgent, and the mailbox hand-off). The description adds no parameter-level meaning beyond that, 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?

States a specific verb and resource: sending one bounded implementation/investigation/verification task to a saved Codex worker in an isolated worktree. The second sentence positions it against the mailbox/thread siblings, so an agent can tell it apart from bridge_orchestrate_codex and bridge_continue_codex without opening a 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?

Explicitly frames itself as 'the simple everyday entry point' where 'no mailbox or thread management is required', which is a clear when-to-use signal against the heavier bridge_* alternatives. It stops short of naming those alternatives or stating when NOT to use this tool (e.g. multi-step orchestration), so it is strong but not complete.

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?

With no annotations, the description carries the full behavioral burden. It usefully discloses that 'History is kept' – i.e. acknowledgment is non-destructive – but is silent on auth requirements, idempotency, and how already-acknowledged or invalid ids behave.

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 short sentences with the core action front-loaded; the 'History is kept' clause is informative rather than filler. 'for an agent' is slightly redundant against the schema's agent parameter, but overall it is tight.

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 2-parameter mutation tool with no annotations and no output schema, the description conveys the action and its effect. It leaves behavioral edge cases (idempotency, auth, error conditions) uncovered.

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 both parameters are already documented in the schema. The description adds no syntax or format detail beyond that, 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?

States a specific verb and resource ('mark messages as handled') and pins down the concrete effect ('drop out of the unread inbox'), which distinguishes this from bridge_inbox and bridge_send. It does not explicitly name a sibling alternative, so it falls short of full differentiation.

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 'so they drop out of the unread inbox' implies when to use it (clearing unread messages), but there is no explicit when-to-use vs when-not guidance, no prerequisites, and no named alternative such as bridge_inbox.

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?

With no annotations, the description carries the full behavioral burden. It usefully discloses the default filtering behavior (retired agents hidden unless requested) and the fields returned, but omits permissions, pagination, ordering, or explicit confirmation that this is a read-only list operation.

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 sentences, front-loaded with the core listing behavior and then the default filter. No wasted words; every sentence 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 simple one-parameter list tool with no output schema, the description compensates by listing returned fields and explaining the default filter. Minor gaps like pagination or ordering are not critical here, but their absence keeps it from a 5.

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 meaning beyond the schema by clarifying that retired agents are hidden by default unless the parameter is set, which is not stated in the schema itself.

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 'List' and resource 'registered agents', and enumerates returned fields (unread counts, last activity, ping binding, recent ping health). It does not differentiate from siblings such as bridge_register or bridge_sessions, 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?

No guidance on when to use this tool versus alternatives. The only conditional detail is the default hiding of retired agents, which is about parameter behavior, not tool selection.

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?

With no annotations, the description carries the full burden and does well: it discloses that the exact session and worktree are resumed, that the first-turn sandbox is kept, and enumerates terminal states plus a round limit. It does not state permission/auth requirements or what execution side effects occur in the worktree while running.

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 sentences, fully front-loaded: resume action first, precondition second, termination behavior last. No filler or restatement of the name.

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 an async execution tool with no output schema and no annotations, the description covers resumption, sandbox persistence, and terminal outcomes; the mailbox delivery behavior is covered in the schema's waitSeconds description. What is missing is how the resumed result is surfaced and whether the run can be re-continued after blocking.

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 runId, fableAnswer, and waitSeconds (including default 240s and the 285s cap behavior) are already documented in the schema. The description adds no parameter-level detail such as format constraints or what a malformed answer does, so 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?

States a specific verb+resource (resume the saved Codex session and worktree) and pins it to a unique precondition (status waiting_for_fable) that no sibling tool covers. An agent can distinguish this from ask_codex and bridge_orchestrate_codex without opening the 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?

The trigger condition is explicit: use this after Codex asked for a decision and is in waiting_for_fable state, and it states the run continues until completed/blocked/failed/round limit. It does not name alternatives or explicitly say when not to use it (e.g., versus bridge_wait or bridge_orchestration_wait).

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?

With no annotations, the description must carry the full behavioral burden. It usefully discloses ordering, default hiding of acknowledged messages, and pagination behavior, but omits read-only/side-effect status, auth requirements, and full return shape.

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 tight sentences front-load the core list operation and pagination rule. Every sentence contributes directly, with 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 an eight-parameter read tool with no annotations and no output schema, the description covers pagination and acknowledged-message defaults but does not describe return fields beyond hasMore or address safety/permissions. Gaps remain for an agent needing full context.

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 documents all eight parameters in detail. The description adds only minor usage context for afterId and acknowledged-message defaults, not enough to exceed the baseline.

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 ('List') and resource ('messages addressed to an agent'), plus ordering ('oldest first') and pagination. It clearly identifies an inbox read, but does not explicitly differentiate itself from siblings such as bridge_outbox or bridge_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?

Gives pagination guidance for when hasMore is true, including acknowledging handled messages or passing afterId. However, it does not explain when to choose bridge_inbox over sibling tools like bridge_thread, bridge_wait, or bridge_outbox, nor does it state prerequisites.

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?

With no annotations, the description carries the full burden and does so well: network off, isolated worktree, timestamped wait limit with mailbox fallback on timeout, and independent-call semantics. It also enumerates the actions the tool never authorizes (commit, push, deploy, publish, external send, credential change, data deletion, production mutation), which is exactly the safety context annotations would otherwise provide.

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 sentences with the core purpose front-loaded, followed by state routing and the safety list. The permission enumeration is long but earns its place given absent annotations; otherwise there is no padding.

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 an 8-parameter orchestration tool with no annotations and no output schema, the description covers the operational states and the authorization boundary an agent most needs. The remaining gap is that 'structured result' is never characterized, and since there is no output schema the caller must infer the return shape from the mailbox/continuation flow.

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 all 8 parameters are already documented in the schema, making 3 the baseline. The description reinforces waitSeconds timeout semantics and the mailbox fallback, but adds no format, default, 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 saved Codex worker in an isolated git worktree (network off)' and waits up to waitSeconds for its structured result. It also distinguishes itself from the follow-up sibling by naming bridge_continue_codex, so an agent can separate it from ask_codex/review_with_codex by its 'saved worker + worktree' framing.

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 explicit conditional routing: waiting_for_fable -> answer then call bridge_continue_codex; running_codex -> result arrives in the coordinator's mailbox. It also notes independent calls create separate runs. It does not, however, say when to prefer this over ask_codex or review_with_codex, so the alternative-selection guidance is incomplete.

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?

With no annotations, the description must fully disclose behavior. It states the tool retrieves state and audit events, implying a read-only action, but it does not explicitly confirm no side effects or describe the exact return structure. This is moderate transparency.

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, focused sentence with no redundancy. It front-loads the primary action and delivers the key information efficiently.

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 one-parameter tool with no output schema, this description covers the core purpose and key usage scenarios, naming the two deliverables (state and audit events). It lacks explicit detail on response structure or potential errors, but is otherwise sufficient.

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 schema already provides a 100% description for the sole parameter runId ('Orchestration run ID'). The tool description adds minimal semantic value beyond this, as the connection between runId and the retrieved state is implicitly obvious.

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 ('Recover') and identifies a clear resource ('durable run state and its audit events'). It distinguishes this inspection tool from execution-focused siblings like bridge_orchestrate_codex and bridge_continue_codex.

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 provides clear usage context ('after a restart or when checking progress'), indicating when to use this tool. However, it does not explicitly mention when not to use it or name alternative tools, stopping short of full exclusions.

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?

With no annotations, the description carries the full burden, and it does disclose the key trait: the call blocks up to a timeout and returns the run's result. However, it never states what happens when the timeout elapses (error vs. partial result), nor that the schema caps the wait at 285 seconds, leaving the most failure-prone behavior unexplained.

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 tight sentences with the blocking scope front-loaded and the eligibility note second. Nothing is wasted and no sentence is redundant.

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?

There is no output schema and no annotations, so the description must carry return and safety context. It states that a result is returned, but for a wait tool the agent still needs to know the timeout-expiry outcome and what 'result' contains; the essentials are covered, the edges are not.

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 runId and timeoutSeconds (with its default) are already fully documented in the schema. The description only echoes timeoutSeconds by name and adds no format or semantics beyond it, 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?

Specific verb (wait) plus resource (a running Codex run) and the precise scope ('finish its current round'). It is distinguishable from the similarly-named bridge_wait by tying the wait to a Codex orchestration run, though it never names the sibling it should not be confused with.

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?

'Works for runs started by any bridge process' clarifies which runs are eligible, which is real guidance. But there is no when-to-use versus when-not guidance, and no mention of the obvious alternative (bridge_orchestration_status) for checking a run without blocking.

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?

With no annotations, the description carries the full burden and does disclose meaningful behavior: sort order (newest first), the default filter (unacknowledged only), and the per-entry payload (ping outcome plus recipient liveness state). It omits pagination/truncation behavior and whether results are capped silently at the limit.

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 sentence that front-loads the resource and scope, then appends the return payload. No filler, no repetition of the tool name.

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?

There is no output schema, so the description must describe returns, and it does name the ordering and the two per-entry signals. The one remaining gap is behavior at the limit boundary (pagination vs silent truncation), which matters for a 200-cap list tool.

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 all three parameters are already documented. The description usefully implies the default state of includeAcknowledged (excluded), but adds no syntax or format detail beyond what the schema provides.

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 (list direct messages an agent sent), plus the defining scope: unacknowledged by the recipient. The word 'sent' cleanly separates it from bridge_inbox and bridge_thread without needing to name them.

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 the situation the tool serves (checking on sent messages the recipient hasn't acknowledged) and the ordering, but never states when to reach for it instead of bridge_inbox, bridge_thread, or bridge_wait, nor any prerequisite for the 'agent' value.

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?

With no annotations, the description carries the full burden, and it does well: it discloses binding retention on omission, disabling behavior with null, and that registering again reactivates a retired agent. It still omits what happens when the requested name is already held by another conversation and whether an existing live registration is overwritten.

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 is front-loaded in the first sentence, followed by a single dense but well-structured sentence covering the wake branches. Every clause carries information; slightly dense formatting 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 registration tool with no output schema or annotations, the definition covers purpose, all three wake states, and re-registration semantics. It lacks only edge-case disclosure (name conflicts, overwrite behavior), which is a minor gap rather than a blocking one.

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 a genuinely new behavior not present in the schema: omitting 'wake' keeps the current binding. It also frames 'auto' as binding the exact app session for background pings, adding intent beyond the schema's mechanics.

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 names a specific verb and resource ('Register a unique agent name for this conversation') and clarifies scope as conversation-bound. It partially distinguishes itself from siblings by noting that re-registering 'reactivates a retired agent' (vs bridge_retire), but never names an alternative tool for the non-registration path.

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 clear conditional guidance for the wake options ('auto' vs explicit binding vs null vs omitted), which is effectively parameter-level usage guidance. However, it never states when to reach for bridge_register versus siblings like bridge_agents/bridge_sessions, so tool-selection guidance is only implied.

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?

With no annotations, the description carries the full behavioral burden and does so thoroughly: pings stop, unhandled messages are closed with a recorded reason, history is kept, recent senders get one notice, and re-registration reactivates. This tells the agent exactly what changes and that the action is reversible via re-registration.

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 sentences, front-loaded with the core action and then the key side effects. Every clause earns its place by conveying lifecycle consequences and reversibility without waste.

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 mutation tool with no annotations and no output schema, the description is nearly complete: it explains what gets closed, what is kept, who is notified, and how to undo. It lacks edge-case details such as behavior for an already-retired or nonexistent agent, but an agent has enough to invoke it 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 schema already documents all five parameters. The description contextualizes effects that correspond to note, closeBacklog, and notifySenders, but adds no syntax, defaults, or format details beyond what the schema provides. 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 and resource: 'Retire an agent'. It adds the scope condition 'whose task is over' and distinguishes from bridge_register by noting that registering the name again reactivates it. An agent can identify this as the lifecycle-ending tool.

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?

Provides a clear usage condition: 'Retire an agent whose task is over'. It does not explicitly name alternatives or when-not-to-use cases, but the condition is sufficient to route correctly among siblings like bridge_register and bridge_send.

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?

With no annotations, the description carries the full behavioral burden and does meaningful work: it discloses that pinging happens in the background, that unregistered recipients are rejected by default, that result warnings signal low pickup likelihood, and that broadcasts/wake:false suppress the ping. Remaining gaps are failure semantics and full return shape.

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 sentences, front-loaded with the core action, each adding a distinct constraint (registration requirement, warnings, ping suppression). No filler or restatement of the tool name.

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 annotations, no output schema, and 7 parameters, the description needs to do a lot and covers the key behavioral and result-signaling aspects (warnings on low pickup likelihood). It stops short of describing the full return payload or error cases, which is a minor gap for a send tool.

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 goes slightly beyond by framing allowUnregistered as a deferred-registration escape hatch ('only when it will register later') and clarifying wake:false as a silent save. That adds intent the schema text alone does not convey.

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 compound action – 'Save a message, then ping its bound recipient in the background' – which is a distinctive verb+resource pair. An agent can distinguish this from read-side siblings like bridge_inbox or bridge_wait because the save-and-ping semantics are spelled out up front.

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 a real precondition ('The recipient must be registered') and a conditional exemption ('use allowUnregistered only when it will register later'), which tells the agent when to reach for that flag. It does not explicitly name alternatives (e.g. bridge_inbox for reading), so it stops short of full sibling 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?

With no annotations provided, the description carries the full burden and does disclose the key behavioral trait: this is a read-only discovery call with no side effects ('does not wake anything'). It does not explain what is returned when the host does not expose a session, which would be the natural remaining question.

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 sentences, front-loaded with the positive behavior followed by the negative scope. Every clause earns its place and nothing is padded.

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 read tool with no output schema, the description covers what the tool reads and what it does not do. The only gap is the behavior when the host does not expose a session, which the 'when the host exposes it' clause gestures at but does not resolve.

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 takes zero parameters, so the schema requires no further semantic detail; the baseline of 4 applies. Nothing in the description conflicts with the empty input 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 specific verb and resource: read live Claude session IDs plus this conversation's own session, with a clear conditional qualifier ('when the host exposes it'). It is distinguishable from the wake/inbox siblings, though it does not name them directly.

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?

Explicitly scopes out adjacent behaviors ('Does not wake anything or read conversation content'), which routes the agent away from bridge_wake_status and content-reading siblings. It never states a positive when-to-use trigger, but the exclusion gives clear context.

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?

With no annotations, the description carries the full behavioral burden. It usefully discloses the default behavior (most recent messages) and the paging model, which goes beyond the schema, but says nothing about read-only nature, auth/permission requirements, ordering guarantees, or return shape.

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 tight sentences with zero filler. The core behavior (returns most recent by default) is front-loaded ahead of the paging instructions.

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 six-parameter read tool with no annotations and no output schema, the description covers pagination but omits return structure, ordering, and the truncation/budget behavior implied by maxChars and maxBodyChars. Adequate but with clear gaps.

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 all six parameters are already documented. The description reinforces the cursor semantics (olderBeforeId/newerAfterId) but adds little beyond what the schema states per parameter, matching the baseline for full coverage.

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 ('Read one page of a conversation thread'), and the 'one page' qualifier immediately scopes it. It does not explicitly distinguish itself from siblings like bridge_inbox or bridge_outbox, so it falls 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?

Gives clear operational context for the cursor parameters: no cursor returns the most recent messages, beforeId pages back, afterId pages forward. It does not state when to choose this tool over sibling read tools such as bridge_inbox, so it stops short of naming alternatives/exclusions.

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?

With no annotations, the description carries the full burden and does disclose two real traits: the call blocks/keeps the turn alive, and it cannot revive an already-ended turn. However it is silent on key behaviors such as what happens at timeout, whether returned messages are consumed, and what acknowledge defaults do, leaving meaningful gaps.

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 tight sentences with no redundancy. The core behavior is front-loaded, followed by the ordering constraint and the re-call instruction, each earning 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 blocking wait tool with no annotations and no output schema, the description covers the essential calling contract (when to call, when it fails, the loop pattern). It stops short of describing the returned message shape or timeout behavior, which for a no-output-schema tool leaves a small 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%, so the schema already documents all seven parameters including defaults, bounds, and the acknowledge semantics. The description adds only the vague notion of a 'matching' message, adding little meaning beyond the schema. 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?

States a specific verb+resource: keep the agent turn alive until a matching bridge message arrives. The phrase 'for agents without background pings' distinguishes it from a passive-ping mechanism, but it never names sibling tools such as bridge_wake_status or bridge_inbox, so an agent must still infer the boundary.

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 explicit lifecycle guidance — call it before going idle, and re-call it after handling and replying while the coordination thread is active. It also states a when-not condition: it cannot wake a chat whose turn has already ended. What it lacks is a named alternative for agents that DO have background pings or a comparison to bridge_wake_status.

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?

With no annotations, the description carries the full behavioral burden. It says the tool reads recent receipts, caps results at 100, clarifies that 'Accepted' does not mean work completion, notes permission checks for held/refused states, and states unknown outcomes are never replayed automatically. These are meaningful behavioral details beyond the schema, though read-only/no-side-effect guarantees are only implied.

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 three sentences, front-loaded with the core read operation and result limit. Each sentence adds useful clarification without waste.

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 status tool with no output schema, the description covers result-limit and state meanings reasonably well. However, it omits usage context and fails to explain the `agent` parameter, leaving gaps an agent must infer.

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?

There is one optional parameter, `agent`, with 0% schema description coverage. The description never mentions `agent` or explains whether it filters wake receipts by agent, so it fails to compensate for the missing schema 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?

The description states a specific verb and resource: 'Read up to 100 recent wake receipts with a per-state summary.' It clearly identifies the tool as an inspection/status reader, but it does not differentiate from siblings such as bridge_wait, bridge_ack, or bridge_inbox.

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 gives no explicit guidance on when to use this tool versus alternatives. It explains state semantics but never states when this status check is appropriate or when another bridge tool should be used instead.

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?

With no annotations, the description carries the burden and does reasonably well: it discloses that Codex runs in a read-only sandbox and that the bridge reports whether the workspace changed, which is real safety/behavioral context. It stops short of describing non-repo side effects or failure/long-running behavior beyond what the schema's waitSeconds note covers.

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 compact sentences with zero filler, front-loading the core action and then the safety/verification detail. Every 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?

No output schema exists, so the description should characterize the return value; it conveys that findings come with evidence and that workspace change is reported. It does not explain the mailbox/async delivery of results (only the schema's waitSeconds note hints at it), leaving a small gap for a potentially long-running tool.

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 all five parameters are already documented in the schema, establishing the baseline of 3. The description adds no parameter-level meaning (focus, threadId, coordinator routing, timing) beyond what the schema supplies.

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+resource+agent: a read-only repository review performed by Codex, yielding evidence and actionable findings. The 'read-only repository review' framing plausibly distinguishes it from the sibling ask_codex, though that distinction is left implicit rather than stated.

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 by the name and description (reach for this when you want Codex to review a repo), but there is no explicit when-to-use guidance, no conditions that select it over ask_codex, and no exclusions or prerequisites.

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