Cheap Labor

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

With no annotations provided, the description carries full burden, and it delivers: discloses exact snapshot scope ('HEAD + working tree, tracked AND untracked'), cost characteristics ('Free local git plumbing — no Codex cost'), and non-destructive guarantees ('Never touches branches, history, or remotes'). This is exemplary disclosure of tool behavior and side effects.

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

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

Four tightly-packed sentences, each earning its place: what it does, cost implication, when to use, and what it never does. Front-loaded with the core purpose; zero fluff or repetition.

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 tool with 0 required parameters and no output schema, the description covers all essential aspects: what gets snapshotted, cost, usage timing, and constraints. Nothing material is left undisclosed for this tool's complexity level.

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 baseline 3 applies. The description does not add parameter-level detail about note/project/session_token, but the schema already documents these thoroughly. No transformation or format information needed; the description doesn't need to compensate, so baseline 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 uses a specific verb+resource+outcome pattern: 'Snapshot the current repo state (HEAD + working tree, tracked AND untracked) into a local checkpoint so it can be rolled back.' It distinguishes from siblings by stating 'Never touches branches, history, or remotes,' differentiating it from git_commit and clarifying rollback semantics relative to the rollback sibling.

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 when-to-use guidance: 'Take one before risky edits or implement runs (implement takes one automatically).' The exclusion 'Never touches branches, history, or remotes' implies when NOT to expect persistence semantics, though it doesn't name an explicit alternative tool like git_commit for history preservation.

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 of behavioral disclosure. 'List' implies a read-only operation and 'free local git plumbing' adds useful context, but it does not describe what exactly is returned, whether anything is hidden, or any limitations of the local git-based mechanism.

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 one concise sentence with an informative clarifying parenthetical. Every word earns its place and nothing redundant or filler is included.

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?

Given the simplicity of the list operation and the rich parameter descriptions in the schema, the description is mostly sufficient. It doesn't mention output shape or pagination, but for a simple checkpoint listing tool this is not a major 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 both parameters already have detailed descriptions about pass explicitly, never guessing project, and re-arm session tokens. The tool description itself adds minimal parameter meaning beyond the word 'this project'.

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 ('List') and clear resource ('recorded checkpoints for this project'), making the tool's purpose immediately obvious. It also differentiates from sibling tools like checkpoint (likely creation) and rollback (likely restoration) by focusing on the listing action.

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 clear context that this is for the current project and implies listing use, but it never explicitly states when to use this over alternatives such as git_log or checkpoint. No when-not-to-use guidance or exclusion conditions are provided.

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?

No annotations are provided, so the description carries the burden. It explains the tool's purpose (relay approvals, push forward) but doesn't disclose any potential side effects, such as whether the session might execute commands, or any rate limits. The behavior of triggering further actions is implicit but not explicitly stated.

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, each packed with useful info: purpose, examples, and thread id provenance. No fluff. Front-loaded with the main action.

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-param tool with full schema coverage, the description covers purpose, usage context, and clarifies where thread IDs come from. It could mention what happens after a reply (e.g., that the session may continue executing), but it's adequate.

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 has 100% coverage for both params (threadId and prompt). The description adds context about prompt format (e.g., approval decisions) and source of threadId, which slightly enhances the meaning, but the schema already explains them adequately. 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?

The description clearly states the tool continues an existing Codex session by thread id, with specific examples of usage (approval/denial relays). It distinguishes from siblings like implement/deep_explore by focusing on continuing a session rather than creating one.

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 states when to use it: to relay approval decisions and push a session forward. Also specifies that thread ids come from implement/deep_explore results, giving clear context for usage. This distinguishes it from session creation tools.

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 of behavioral disclosure — and it exceeds expectations. It discloses the return value (session_token), side effect ('arms the chat exactly like init'), the no-double-confirm behavior, refusal conditions (existing paths, missing parents), and path-resolution rules (expand ~, home-relative interpretation). This provides far more than the annotation-level safety data would have, fully compensating for the absence of structured 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?

Every sentence earns its place: purpose, behavioral caveat, side effects, call conditions, path semantics, and refusal conditions are each covered once with no redundancy. The description is front-loaded with the core purpose and tapers into increasingly specific operational details, which is ideal for an agent scanning under time pressure.

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 1-parameter, no-output-schema, no-enum, no-nested-object tool, the description is complete: it covers the function, the return value, the state change, the error/refusal conditions, and the tricky interactive behavior (no second confirmation). The reference to 'exactly like init' conveniently routes the agent to sibling context without bloating the description. Nothing material is left unaddressed for its complexity profile.

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% (the `project` param's description is rich: 'Absolute path for the NEW project directory (must not exist yet; its parent must exist)'), which sets the baseline at 3. The tool description earns an additional point by contributing path-resolution semantics not in the schema — how to expand ~, interpret 'Desktop'/'Documents' as home-relative, and the instruction to resolve the absolute path autonomously. This is a genuine value-add 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?

Uses a specific verb+resource pair ('Create a brand-new project DIRECTORY') and immediately clarifies the scope — git is NOT initialized, distinguishing it from the sibling `init`. The reader instantly knows what this does and how it differs from related tools. The parenthetical on git non-initialization specifically disambiguates from the sibling tool, satisfying the differentiation requirement.

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?

Explicit 'Call when...' language tells exactly when to invoke it, and 'Never suggest shell commands like mkdir instead' is an explicit exclusion of the alternative. The description also gives operational context about when to use this over the `init` sibling with the 'exactly like init' reference and explains the direct-call flow (no second ask). This is textbook when-to-use/when-not-to-use guidance.

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

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

No annotations are provided, so the description carries the full burden. It discloses the tool runs in a READ-ONLY sandbox with capped scope and returns findings only, plus the cost factor. This covers safety and cost, though it doesn't describe what happens on failure or how findings are structured, which would be useful but not essential given the read-only nature.

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 purpose and alternatives. Every sentence earns its place, covering purpose, behavior, cost, and fallback directive with zero 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?

While there is no output schema, the description says 'returns findings only' – vague but acceptable given the tool's nature as a fallback for open-ended investigation. It leaves some ambiguity about the exact output format, but the tool's purpose is inherently open-ended. Considering the complexity and the rich parameter documentation, this is reasonably complete.

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 baseline is 3. The parameter descriptions add significant value beyond schema: path is clarified as scope restriction, model includes explicit user-confirmation requirement and cost warning, project must be named by user and passed explicitly, session_token required and re-armed per chat. These are practical usage hints that greatly help the agent invoke correctly.

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?

Description states precisely that this is a fallback for questions the free bridge tools can't answer, with a concrete example ('trace how auth is wired across 30 files'). It clearly identifies the tool as the heavyweight investigation option, distinct from simpler siblings like list_tree/read_file/grep.

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 instructs to try list_tree/read_file/grep/git_* first before using this tool, and notes the cost implication ('Costs Codex usage'). This gives the agent a clear decision rule for when to use it vs alternatives.

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 transparency burden. It discloses key behaviors: exact-match requirement, refusal without writing on stale/ambiguous matches ('refuses with nothing written'), and the need to re-read the file. It also adds the notable context that this operation is free and does not consume Codex usage.

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 long and front-loaded with the core action and mechanism. Every sentence adds value: match semantics, failure behavior, and usage boundaries. There is no filler or redundant repetition of schema properties.

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?

Given six parameters and full schema coverage, the description provides sufficient operational context: exact-match behavior, failure mode with no partial write, retry guidance, and scope boundaries. It does not describe return values, but no output schema exists and the behavior on failure is already disclosed.

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 six parameters. The description adds helpful context about exact-match semantics and replace_all's 'exactly one must match' rule, but it does not add per-parameter syntax or format details beyond what the schema already 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?

The description clearly states the tool's purpose: 'Edit an existing file directly via exact-match replacement.' It goes beyond a bare verb by specifying the mechanism (exact-match) and the resource (existing file), and it differentiates from siblings by scoping it to small, well-defined edits and delegating large multi-file work to implement.

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 explicit guidance: 'Use for small, well-defined edits ChatGPT can make itself; delegate large multi-file work to implement.' It also instructs the agent to re-read and retry after a stale or ambiguous match, providing clear operational 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 burden. It discloses atomicity ('if ANY item fails, NOTHING is written'), validation against current on-disk content, ordering ('Same-file edits chain in order'), and constraints ('Max 20 items per pack'). It also notes it's free. This covers key behavioral aspects comprehensively.

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-loading the core purpose and key traits. Every sentence adds value: atomicity, validation, chaining, usage context, and limit. No fluff.

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 tool has moderate complexity (2 arrays, atomic behavior) and no output schema. The description explains the atomicity, validation, ordering, and constraints. It does not describe return values, but that's acceptable without an output schema. It could mention error handling or prerequisites for project/token, but the schema covers those.

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% with descriptions for each param. The description adds extra semantics: 'Same-file edits chain in order' clarifies the edits array behavior, and 'Max 20 items per pack' is a constraint not present in the schema. It enhances understanding beyond the structured fields.

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 clearly states the function: 'Batch several edits and/or new files into ONE all-or-nothing operation.' It distinguishes from siblings by emphasizing atomicity and batching, and contrasts with 'implement' for heavy work. The verb is specific and resource defined.

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?

Explicit guidance: 'Use for multi-file changes that are still small and well-defined; delegate heavy work to implement.' This indicates when to use and suggests an alternative. It could have explicitly mentioned edit_file for single edits, but the context of batching makes it implicit, so it's clear but not exhaustive.

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 behavioral burden and does so well: it discloses shallow scan locations, max depth of 2, hidden-dir skipping, local-only I/O, and the required user-confirmation step. It does not describe the exact output format or error cases, but the core safety and behavioral profile is clearly stated.

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 compact and front-loaded: one sentence states purpose, one states scan constraints, and one states usage protocol. Every sentence adds essential information with no filler or repetition.

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, the description is complete: it covers purpose, scan scope, fidelity constraints, cost/IO implications, and the expected interaction flow. The only omitted details (like output formatting) are adequately implied by 'candidate paths' and the schema's parameter documentation.

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% and the query parameter is already described as a case-insensitive substring with empty-list behavior. The description adds the 'fuzzy project name' framing, a concrete example, and the notion of candidate paths, which helps the agent understand how the parameter maps to real user intent beyond raw schema syntax.

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: 'Resolve a fuzzy project name... to candidate paths,' which clearly distinguishes this from siblings like deep_explore or init. It also immediately clarifies that this is a candidate-finding tool, not a direct project-opening or creation 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?

The description gives explicit usage conditions: 'Use ONLY after the user has named a project in chat — never preemptively.' It also specifies the workflow of showing candidates and asking the user which directory is correct before calling init, giving clear when-to-use and when-not-to-use guidance.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does so well by revealing important non-obvious behavior: the .codex-bridge/ folder is never staged, commits require explicit user approval, and the tool never touches remotes or pushes. This gives the agent the safety and side-effect context it needs for a mutating git 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?

Three focused sentences front-load the purpose and then layer critical constraints without filler. Every sentence earns its place: the main operation, the important .codex-bridge exclusion, the user-approval requirement, and the never-push guarantee.

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 is complete for a commit tool: it states what happens, what is excluded, when to call it, and what it will never do. While there is no output schema or annotations, the behavior an agent needs to safely select and invoke this tool is fully covered, with parameters described thoroughly in the input schema.

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 handles most parameter clarity. The description goes further by explaining the files default behavior ('or all changes') and adding the special exclusion that .codex-bridge/ is never staged. The project and session_token parameters remain covered mainly by the schema, which is sufficient given the high schema 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?

The description clearly states the tool's action with a specific verb and resource: "Stage the named files (or all changes) and commit them with the given message." It also distinguishes this from git inspection or push behavior via the .codex-bridge exclusion and the "Never pushes" instruction, which makes the tool's role unambiguous among its siblings.

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 clear, explicit when-to-use guidance: "Call ONLY after the user explicitly approved the message and the files in chat." It also provides a firm when-not-to-use constraint with "Never pushes — remotes are never touched." However, it does not explicitly mention alternative tools such as git_status or git_diff for inspecting changes before committing, so it stops short of full sibling-to-sibling guidance.

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?

The description discloses that git diff operates on unstaged changes by default and describes the operation as 'free local I/O,' implying it is read-only and side-effect-free. However, it does not mention prerequisites like the session token or project path, nor the output format, leaving gaps given no 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?

Two short sentences; the first front-loads the core action, and the second adds usage context. The second sentence is slightly vague ('Free local I/O — the review loop') but not wasteful.

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 is brief and lacks explicit mention of output format or required invocation context (project/session), but given the schema and the standard nature of git diff, it is minimally adequate. No output schema exists, so the description should have stated what the tool returns.

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 covers all six parameters with meaningful descriptions, so the description adds minimal additional meaning. The only extra context is 'unstaged by default,' which complements the `cached` parameter but is already implied by schema descriptions.

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 clearly states the tool runs `git diff` inside a project root and defaults to unstaged changes. This is specific and identifiable among sibling tools, though it does not explicitly name alternatives.

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 says 'the review loop: ChatGPT reads this and decides next steps,' which provides a clear context for when to use the tool. However, it does not explicitly state when not to use it or name alternative tools like git_status or git_log.

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?

No annotations are provided, so the description carries full burdens. It states 'Free local I/O' suggesting a read-only, local operation, but does not explicitly say whether modifications occur or what auth/session requirements exist. The tool actually requires a project and session_token (per schema descriptions), but the tool description omits these behavioral constraints entirely, leaving the agent unaware of setup prerequisites.

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, front-loaded sentence with no redundancy. It conveys the core purpose immediately and wastes no words. It is appropriately sized for a simple read tool, though the trade-off is a lack of detail elsewhere.

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?

Given the tool has 4 parameters, two of which (project, session_token) are necessary for project tools, and no output schema, the description is incomplete. It does not mention the requirement to pass session_token or the need for the project to be armed. The description also does not specify return format or edge cases. It heavily relies on schema descriptions for critical operational detail, making the overall context inadequate.

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 parameter (path, count, project, session_token) is documented. The description adds the 'project root' context, which implies the path is relative to root, but does not elaborate on parameter interactions. It adds marginal value beyond the schema, 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 clearly states what the tool does: 'Recent commit history (oneline) of a project root.' It uses a specific verb (get/recent) and resource (commit history), and distinguishes from sibling tools like git_status (status) and git_diff (diff) by focusing on log at project root. The 'oneline' format is also specified.

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 no explicit guidance on when to use this tool versus alternatives. It mentions 'Free local I/O,' which hints at low cost, but does not compare against git_status, git_diff, or other read tools. Sibling tools are numerous, but the description fails to indicate scenarios or 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 must carry the behavioral burden. It adds useful context by calling it 'Free local I/O,' implying no network cost and no side effects, but it does not disclose output shape, exit behavior, or any edge cases. For a simple read-only status tool this is adequate but not rich.

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, front-loaded with the core purpose, and the second sentence provides decision-relevant guidance. No redundant or filler 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?

Given no output schema, the description could have explained the return format, but 'Working-tree status' is conventionally understood and sufficient for an agent to invoke correctly. The 'first thing to check' guidance completes the practical context, and the schema fills in parameter details.

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 three parameters. The description adds general context about 'project root' but no specific parameter details beyond what the schema provides, justifying the baseline 3.

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 clearly states the tool reports 'Working-tree status of a project root via git' and pairs it with a specific use case: 'the first thing to check before planning or reviewing.' This distinguishes it from sibling review tools like git_diff and git_log even though those aren't named.

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 explicit timing guidance: 'the first thing to check before planning or reviewing.' It does not, however, name when not to use it or explicitly point to alternatives such as git_diff or git_log, so it falls short of a full 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?

No annotations are provided, so description carries the burden. It discloses that it skips hidden dirs, node_modules, .git, and binaries, which is valuable. However, it doesn't mention any side effects (none expected), behavior on no matches, or whether it follows symlinks. It gives basic transparency but lacks depth for a search tool that could have performance implications.

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 two sentences, highly concise, and front-loaded with key info. Every sentence adds value: first defines purpose and exclusions, second gives usage guidance. No fluff. Perfect compactness.

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?

Given no output schema and 100% parameter schema coverage, description covers the essential aspects: what it searches, what it skips, and when to prefer it. It doesn't explain return format or error behavior, but for a search tool with full schema, this is acceptable. It could mention that results are truncated but max_results param covers that. Slightly incomplete regarding output structure, but overall solid.

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% (all 7 parameters have descriptions). The description adds context about skipping binaries but doesn't detail parameter usage beyond schema. It mentions default max_results efficiently, and hints that project and session_token are required for context, but schema already covers that. With full schema coverage, 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?

The description clearly states the tool performs regex search across files under a path, distinguishing it from generic 'grep' by specifying project context. It mentions skipping certain directories and binaries, adding specificity. However, it doesn't explicitly contrast with siblings like deep_explore, though it does hint at preference.

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 explicitly says 'prefer over deep_explore for locating symbols/strings', providing direct comparison with a sibling tool. It also notes free local I/O, implying when to use it (cheap operation). It clearly signals when to use this tool versus an alternative, which is excellent.

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 of disclosure — and it excels. It reveals this is a workspace-write operation in a sandbox, enumerates mutation side effects (edits repo, runs builds/tests, fixes breakage), and explains the output contract (git diff appended for review). It even flags idempotent-ish behavior ('reads .codex-bridge/ plan files if present') and cost implications. All side-effect domains an agent would need to know before invoking are disclosed.

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 that front-load the core purpose and flow logically through prerequisites, mechanics, and caveats — every clause earns its place. The emphasis via ALL-CAPS 'DETAILED' and the cost warning are placed near the end where they're instructive, not distracting. Minor deduction for slight redundancy between 'Reads .codex-bridge/ plan files if present' and the later re-explanation of the task plan format; these could be tightened into one thought.

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 high-stakes mutation tool with no annotations and no output schema, this description is admirably complete: side effects, prerequisites, failure semantics, cost, and output destination are all covered. It tells the agent what not to delegate to it ('never thinks or designs') and when to decline (if plan isn't written). Sibling tools like write_file, run_command, and git_commit make similar repo mutations, yet this description fully distinguishes the delegated-execution model without padding.

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 per the rubric — the schema already documents all four parameters, including practical notes like 'never guess' on project and 'new chat must be re-armed' on session_token. The description reinforces the 'task' semantics (detailed step-by-step, executed literally) which echoes the schema's 'Codex follows it literally' language, but adds no genuinely new parameter-level insight beyond what structured fields already state.

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 opens with a clear verb+resource ('Run Codex...on the current task') and details the full scope of behavior: reads plan files, edits repo, runs builds/tests, fixes breakage, appends diff for review. It distinguishes itself from siblings by emphasizing execution over planning ('never thinks or designs') and explicitly warns 'Only call after ChatGPT has written that plan' — differentiating from plan_write/plan_read. No ambiguity about what this tool does or where it fits in the workflow.

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 when-to-call guidance: 'The task must be a DETAILED step-by-step plan' and 'Only call after ChatGPT has written that plan.' It also signals when NOT to use it ('never thinks or designs'), establishes a hard prerequisite (plan must exist first), and notes the operational cost of invocation ('Costs Codex usage'). For an agent choosing between this and the planner siblings, the decision rule is crystal clear.

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?

The description discloses the key side effect (arming the session and returning a token) and is consistent with no annotations. It lacks details on potential permissions or failure modes, but for a simple init tool, transparency is adequate.

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 moderately verbose but each sentence adds valuable context (when, when not, alternative). It is structured logically, with no redundancy, making it efficient for the given complexity.

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 covers all necessary context: prerequisites, action, return value, and fallback behavior. It is complete for the tool's purpose and complexity, leaving no gaps for the agent.

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 parameter 'project' is fully described in the schema (absolute path, must exist, user-confirmed). The tool description adds no additional semantic meaning beyond referencing it, so it remains at baseline for 100% schema 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?

The description clearly states the tool's function: approving an existing project and returning a session token. It also distinguishes it from the sibling create_project, satisfying the verb+resource+distinction criterion.

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?

Explicit when-to-use instructions are provided: call after user @mentions and confirms directory, and when project doesn't exist, use create_project instead. Also includes a never condition, making usage unambiguous.

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. It adds the contextual detail 'Free local I/O,' which hints at non-destructive, local behavior, but it does not explicitly state that the operation is read-only or non-mutating. It also does not mention error conditions, permission requirements, or what happens to inaccessible directories. The phrase is helpful but leaves room for ambiguity in a tool that could touch the filesystem.

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 two sentences: the first states the core purpose, the second provides a crucial usage note. Every word adds value. It is front-loaded with the most important information and does not waste tokens on redundant 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?

Given the tool's moderate complexity (6 parameters, no output schema, no annotations), the description covers the primary context: what it does and when to prefer it. It could elaborate on the output format (e.g., how entries are sorted or truncated), but the combination of a clear schema and a concise description is largely complete for most usage scenarios. The missing output details slightly lower the score 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 description coverage is 100% (all 6 parameters have descriptions). Per the rubric, when coverage is high, the baseline is 3. The description adds no additional parameter semantics beyond the schema, which is acceptable given the schema already documents each field (e.g., 'path', 'depth', 'max_entries').

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 clearly states the tool lists directory structure under a path within a project root: 'List the directory structure under a path inside a project root.' It uses a specific verb ('List') and resource ('directory structure'), and immediately differentiates from the sibling tool by stating 'prefer over deep_explore for any directory layout question.' This directly addresses purpose and provides sibling distinction.

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 explicitly names an alternative sibling tool ('deep_explore') and gives a clear usage recommendation: 'prefer over deep_explore for any directory layout question.' This is an explicit 'use this instead' guidance, matching the calibration example that earned a 5. It tells the agent when to choose this tool over a known alternative.

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?

No annotations are present, and the description only mentions 'Free local I/O' without clarifying side effects, read-only nature, error behavior, or permissions. This lacks transparency for a tool without annotation support.

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, clear sentence with no unnecessary words. It directly conveys the tool's purpose and structure.

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?

Without an output schema, the description does not explain what the tool returns (e.g., file contents) or handle error cases. This leaves the user without essential context for using the tool effectively.

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% with each parameter having a description. The tool description adds no extra meaning to the parameters, so the baseline score of 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 clearly states the tool reads specific handoff files (PLAN.md, SPEC.md, TASKS.md) in .codex-bridge/, distinguishing it from general file reading tools like read_file. The verb 'read' and resource are explicit.

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 does not provide guidance on when to use this tool versus alternatives such as read_file, nor does it mention conditions or prerequisites. It only states what it reads, leaving the user to infer usage.

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 behavioral burden. It explicitly discloses that the tool replaces the file's entire contents (destructive overwrite), which is the most important side effect. It also explains the content contract for downstream execution by implement, though it does not mention prerequisites like init/arming or return behavior.

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

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

Three sentences, each earning its place: purpose and scope, overwrite behavior, and content requirements. No filler or redundant 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?

For a write tool with no annotations and no output schema, the description covers the key operational aspects: target location, overwrite semantics, and the content standard needed for successful handoff to implement. It relies on the schema for auth/session details, which is acceptable given the schema is complete.

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 reinforces that content should be detailed step-by-step instructions, but it does not add meaning beyond what the schema already provides for file, content, project, and session_token.

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 ('Write a .codex-bridge/ plan file'), names the exact file types (PLAN.md, SPEC.md, TASKS.md), and clearly distinguishes itself from generic file tools like write_file by framing this as the handoff that implement consumes on its next run.

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 clear usage context: this is the handoff mechanism for implement, and plan files must contain executable step-by-step instructions. It doesn't explicitly name alternatives or exclusions, but the .codex-bridge/ scope and implement handoff make the intended use case clear.

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 fully carries the behavioral disclosure burden. It adds valuable context: 'Free local I/O' signals no side effects, 'size-capped and line-ranged' describes output limitations, and 'Refuses binary files' indicates error behavior. It could be more explicit about the consequences of hitting limits or error scenarios, but it covers the critical aspects of safety and scope.

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, information-dense sentences with no fluff. The first sentence states the core purpose and constraints; the second gives usage prioritization and refusal conditions. Every word contributes to understanding.

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 straightforward read operation without an output schema, the description covers the essentials: what it does, when to use it, and key limitations. It could mention error handling for missing files or encoding, but given the tool's simplicity and the coverage of parameters, it's sufficiently complete. The lack of an output schema is acceptable because the return value is obviously file content.

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 adds the term 'size-capped and line-ranged' which loosely relates to limit/offset/max_chars, but the parameter definitions already provide this clarity. No significant extra meaning is added beyond what the schema documents.

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 ('Read a file inside a project root') and immediately adds scoping details ('size-capped and line-ranged'). It also differentiates itself from the sibling tool by explicitly recommending itself 'over deep_explore for any file-content question', which directly addresses sibling distinction.

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 explicit usage guidance: 'prefer over deep_explore for any file-content question' names the alternative and clarifies when to use this tool. It also implies when not to use it ('Refuses binary files and paths outside the approved project'), covering both positive and negative cases.

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 full responsibility for behavioral disclosure. It prominently warns 'DESTRUCTIVE', requires explicit user approval, and explains that it takes a fresh checkpoint first so the rollback is reversible. This is strong transparency for a destructive 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?

The description is three focused sentences with no filler. The danger warning is front-loaded, followed by the usage constraint and the undo mechanism. Every sentence contributes critical information.

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 destructive, 3-parameter tool with no output schema, the description covers the essential context: what it does, when it is safe to call, and how the operation can be undone. The schema provides the remaining per-parameter details, making the combined context 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?

Schema description coverage is 100%, so the baseline is 3. The description reiterates the default-latest behavior already present in the id schema, but does not add significant meaning beyond the parameter descriptions. No deduction is needed because the schema handles parameter semantics thoroughly.

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 clearly states the action ('Restore the working tree to a checkpoint') and identifies the resource and default behavior ('default: the latest'). This distinguishes it from sibling tools like checkpoint (which creates) and checkpoints (which lists).

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 explicit usage context: it must only be called after the user explicitly approves the rollback in chat. However, it does not explicitly discuss when not to use it or contrast with alternatives like git_commit or restore-by-checkout.

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?

No annotations are provided, so the description carries the safety disclosure burden. It explicitly discloses that risky categories (writes, network, git mutations, interpreter one-liners) are delegated to Codex, which 'never full access, no user interruption', and that there is no shell. Missing details about output/error behavior prevent a 5.

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 tight sentences: purpose, read-only behavior, risky delegation, and no-shell constraint. Every sentence earns its place, information is front-loaded, and there is zero fluff.

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 and no annotations, the description should state what the tool returns (stdout/stderr, exit codes). It covers safety and execution model but omits return/error details, which is a notable gap for command execution. The project and session_token requirements are documented in the schema, so that gap is less severe.

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 a baseline of 3 applies. The description adds the 'No shell — pass the executable and args separately' guidance, which clarifies how command and args relate and that command is an executable path, not a shell string. This is meaningful extra semantics 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?

The description opens with 'Run a verification command (tests, build, typecheck) in a project' — a specific verb, object, and scope. It distinguishes from sibling file/plan tools by focusing on process execution, and even clarifies the tool can handle risky commands via a delegation 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?

The description gives clear context on when to use it: read-only commands run 'directly (free)', while risky commands are delegated to Codex with auto-review approval. It does not explicitly name alternatives or state when not to use it, but the read-only vs risky distinction provides practical routing guidance.

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 of disclosing behavior. It clearly states that the tool updates a status in a specific file, errors when the task line is not found, and matches by substring—these are key behavioral traits. It also notes the file is authored via plan_write, providing workflow context. It does not detail return values or authorization, but for a simple mutation tool this is adequate.

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 concise two-sentence block that front-loads the core action and immediately adds the most critical operational detail (substring matching and error condition). Every phrase earns its place; there is no redundancy or 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?

Given the tool's moderate complexity (5 parameters, 2 required) and absence of an output schema, the description covers the key behavioral semantics: what it does, where, how matching works, and how to handle missing entries. It does not mention the success return value, but this is a minor gap for a tool whose only logic is updating a file. The schema fully documents the project and session_token requirements, so that gap is already filled.

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 does not add significant meaning beyond the schema; the substring matching clause is already present in the schema's description of the 'task' parameter, and the other parameters are thoroughly documented in the schema. No additional clarification or examples are supplied.

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 clearly specifies the action ('Update a task's status'), the resource ('.codex-bridge/TASKS.md'), and the allowed values ('todo / in-progress / done / blocked'). It also notes the matching mechanism ('substring'), which distinguishes it from sibling tools like plan_write and plan_read.

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 concrete usage context: it explains that the tool errors if the task line isn't found and explicitly states that TASKS.md is authored via plan_write, so adding tasks should be done by rewriting the file (implying the use of plan_write instead). This gives clear when-to-use / when-not-to-use guidance, though it does not explicitly mention alternatives like plan_read for checking tasks.

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?

No annotations provided, so description carries the burden. It discloses key behaviors: free/no Codex usage, auto-creates parent directories, refuses overwrite, and writes content exactly as given. It doesn't cover failure modes but is quite transparent for a file-write tool.

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

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

Two concise sentences, front-loaded with the core action and key distinction from edit_file. Every sentence adds value without redundancy.

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 write tool with no output schema, the description covers creation, overwrite refusal, directory creation, and usage boundaries. It omits error handling details but overall is sufficient for an agent to use 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 covers 100% of parameters. The description adds no new parameter semantics beyond what the schema already provides (e.g., 'path to NEW file' mirrors schema). 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 clearly states the tool creates a NEW file, distinguishing it from edit_file which modifies existing files. It also notes the refusal to overwrite, making 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?

Explicitly says 'Use this for small, well-defined additions' and 'delegate large multi-file work to implement', giving clear when-to-use and when-not-to-use guidance. Also points to edit_file for changes.

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