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

Annotations already provide idempotentHint=true and destructiveHint=false; the description adds non-obvious context by promising atomic persistence and scoping to an 'allowed bridge-owned data namespace'. No contradiction with annotations, but overwrite/conflict behavior is not detailed.

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

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

A single, front-loaded sentence with no filler. The key guarantee ('Atomically') and the resource scope are presented first, and every phrase adds meaning.

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?

Despite concise atomic-write context and useful annotations, there is no output schema and no description of return values, path conventions, or error/overwrite behavior. For a required three-parameter write tool, an agent is left to infer too much.

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?

Input schema parameter descriptions are 0% covered, so the description must compensate. It tells the agent that content is text or structured and that the namespace is bridge-owned/allowed, but it says nothing about path semantics and gives only a vague type hint for content.

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 precise verb ('Atomically persist') and a specific resource ('text or structured reconstruction/source-registry artifact under an allowed bridge-owned data namespace'). It clearly separates this write tool from sibling read/search/review tools such as repo_read, repo_search, and rva_review_result.

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 is given about when to prefer this tool over alternatives or when not to use it. It never references sibling tools or conditions such as 'use repo_read for reading' or 'use research_publish_knowledge for knowledge publication'.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds context by specifying what is checked (bridge configuration and connectivity), but it does not describe the output format, error behavior, or what constitutes 'healthy'. It does not contradict 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?

The description is a single, front-loaded sentence with no filler. It conveys the essential purpose in seven words.

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-only health check with annotations covering safety, the description is adequate. It states what is checked but does not specify the return value or success criteria. Given the tool's simplicity, this is reasonably complete, though a note on what 'healthy' means could improve it.

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 are no parameters, so schema coverage is trivially 100%. The description adds no parameter info because there are none, which is appropriate. Baseline for zero parameters is 4.

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 'Check' and a clear resource 'bridge configuration and target repository connectivity'. It clearly differentiates from sibling tools like repo_snapshot or repo_read, which focus on repo content rather than health.

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 is given on when to use this tool versus alternatives. It does not mention any prerequisites, alternatives, or conditions for use, leaving the agent to infer usage from the name and description.

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

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

Annotations already flag the operation as destructive and non-read-only. The description adds the qualification that only queued or running tasks can be canceled, which is useful behavioral context. It does not detail side effects or response behavior, but the annotation coverage lowers the burden.

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

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

One short sentence that immediately communicates the action and scope. No filler words or redundant 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 single-parameter cancellation tool with destructive annotations, the description provides enough to understand the basic call. Gaps include no information about expected response, error behavior for invalid task IDs, or side effects beyond the destructive hint. Given the annotations carry safety information, this is acceptable but not thorough.

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 0%, and the description does not mention task_id at all. The parameter is self-evident from the tool name and required schema, but the description adds no meaning beyond the schema's type and format constraints.

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 ('Request cancellation') on a specific resource ('Codex task') with a scoping qualifier ('queued or running'). It clearly distinguishes itself from sibling tools like codex_status and codex_start_task.

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 context for when to use it (queued or running tasks), implying not to use it for completed tasks. It does not explicitly name alternative tools or provide when-not conditions beyond the state qualifier.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds some behavioral scope by naming what is checked and listed, but it doesn't disclose output shape, failure modes, or whether 'check' implies validation against a reference.

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, compact sentence with no filler or redundant phrasing. It front-loads the core purpose and uses parallel structure effectively, though the dual-action phrasing could be slightly clearer.

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 one-parameter read-only tool, the description gives a reasonable idea of what the call accomplishes, but it lacks detail about return format and when to use it in a workflow. With no output schema, a small amount of extra context about what the caller receives would make it more 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 0%, and the description never mentions task_id or explains how it relates to the artifact paths being checked. The parameter is simple and self-descriptive by name, but the description provides no additional semantic value to compensate for the missing schema documentation.

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 clear action ('check' and 'list') on specific resources ('expected artifact paths' and 'currently changed repository paths'). It is not a tautology, though it doesn't explicitly differentiate itself from sibling tools like repo_snapshot or codex_diff.

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 guidance on when to prefer this tool over alternatives or what conditions warrant its use. It does not mention exclusions, prerequisites, or relationships to sibling tools, leaving the agent to infer 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 readOnlyHint and idempotentHint already covering the safety profile, the description contributes 'bounded page' pagination semantics, a machine-readable return format, and a concrete output claim (research-bridge paths). It adds meaningful context beyond the annotations and does not contradict them.

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 13-word sentence with the verb front-loaded. 'Bounded page,' 'machine-readable,' and 'research-bridge paths' each add a distinct constraint with no filler or 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?

With no output schema and zero parameter documentation, the burden falls on the description for return shape and cursor semantics. It hints the output contains research-bridge paths but never explains what those are, nor how after_seq and limit drive paging, so an agent can make a basic call but cannot page correctly or anticipate the response structure.

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 0%, so the description must explain the three parameters to compensate. It only vaguely gestures at pagination with 'bounded page'; task_id — the sole required parameter — and the after_seq cursor are never mentioned, leaving their semantics to inference.

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 ('Read') and a specific compound resource ('a bounded page of machine-readable audit events ... research-bridge paths'). The output focus on 'research-bridge paths' sets it apart from generic event readers like codex_events and the writer codex_record_audit_event, though it never names those siblings explicitly.

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 when-to-use guidance appears in the description. An agent choosing between codex_audit, codex_events, and codex_status gets no selection criteria, and the relationship to codex_record_audit_event is never clarified.

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

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

Annotations are all false, so the description carries the burden of explaining side effects, but it only says 'Return.' It does not disclose whether the tool modifies state, updates the baseline reference, or requires special permissions. The readOnlyHint=false creates ambiguity with the read-like phrasing, though not a direct contradiction.

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

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

The description is a single, front-loaded sentence with no filler. It states the core operation and scope immediately, making it easy to parse.

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

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

With no output schema and ambiguous annotations, the description is too thin. It does not define 'task baseline reference,' specify the output format, or clarify side effects and selection context. An agent can guess the basic operation but lacks enough detail to confidently choose this tool among siblings.

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 provides no description for task_id (0% coverage), and the description only loosely references 'task baseline reference.' It does not explain how task_id is used, what valid values represent, or what happens if it is missing or invalid. The name and UUID format give some clues, but the description adds little meaning.

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 ('Return') and a precise resource: 'current repository-wide staged and unstaged diff plus the task baseline reference.' This clearly distinguishes it from sibling tools like repo_read or repo_snapshot by naming the exact scope and output.

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

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

The description implies a task-oriented diff use case but never states when to prefer codex_diff over alternatives such as repo_snapshot or repo_read. There is no explicit when/when-not guidance, only an implied reason for using the tool.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description does not need to repeat those. The description adds 'ordered, append-only' which clarifies the event stream nature, and 'after a sequence cursor' explains pagination. However, it does not disclose details like what happens when the cursor is out of range or whether events are ephemeral or persisted. Given annotations cover the safety profile, a 3 is appropriate.

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

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

The description is a single, lean sentence that front-loads the core operation and immediately mentions key constraints ('ordered, append-only') and the pagination mechanism. No 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?

The tool has 3 parameters (1 required), no output schema, and no enums. The description conveys the core concept but does not explain the return format, the meaning of 'bridge' events, or how 'after_seq' interacts with ordering. For a read-only tool with annotations covering safety, it is adequate but could benefit from clarifying the return structure and edge cases.

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 0%, so the description must compensate. It mentions 'sequence cursor' which maps to the 'after_seq' parameter, giving some meaning. It also implies ordering. However, it does not explain 'limit' or 'task_id' beyond what the schema names suggest. The description adds the concept of a cursor but leaves 'task_id' and 'limit' to be inferred.

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 clear verb ('Read') and a specific resource ('ordered, append-only bridge and Codex events') with a mechanism ('after a sequence cursor'). It distinguishes the tool's purpose but does not explicitly differentiate it from siblings like codex_audit or codex_status, which could also involve reading events or status.

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

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

The description implies usage by mentioning 'after a sequence cursor' which indicates a cursor-based pagination pattern, but it does not explicitly state when to use this tool versus alternatives like codex_audit or codex_status. It gives no explicit guidance on when not to use it or what conditions lead to using a sibling.

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 governance restrictions, atomic task_closed requirements, idempotency of duplicate closure, the requirement that both PASS and exit_code=0 must hold, and the audit-only status of legacy prose. These are meaningful behavioral facts beyond the annotations, which only provide basic read/write/destructive hints.

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

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

Every sentence carries useful contract information, but the description is a dense, unstructured block mixing governance rules, payload schemas, and validation conditions. It lacks a brief purpose statement up front and would benefit from more explicit 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?

The description covers the most important governance and payload contract details needed to call the tool correctly, including atomicity, idempotency, and evidence verification rules. It leaves gaps around return values, task_id semantics, and related_paths usage, but the core event payload contracts are well specified.

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

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

With 0% schema description coverage, the description carries the burden, and it provides detailed JSON shapes for major event types and the task_closed preconditions. It still does not clarify task_id or related_paths semantics, and leaves some event_type values (chatgpt.review, chatgpt.semantic_review) without explicit content contracts, so it is strong but incomplete.

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 name and input schema clearly identify this as an audit-event recording tool, and the description adds precise event_type-specific payload contracts for final_verdict, completion_obligation_settled, and bridge.test_evidence. However, there is no explicit verb+resource sentence in the description itself, and it does not directly differentiate itself from siblings like codex_audit or codex_events.

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 a strong access boundary ('Trusted ChatGPT/bridge governance only') and states that executors cannot certify evidence or acceptance, which implies when it may be used. It does not explicitly name alternatives or define triggering conditions, leaving usage guidance mostly implicit.

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 adds significant behavioral context beyond annotations, such as invalidating prior verdict/obligation settlements and rejecting followups on completed turns. It also directs the user to inspect followup.steered or followup.delivery_failed events for delivery confirmation.

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 concise, front-loading the primary action, and the conditional details are packed into a single sentence. It is not verbose, though the second sentence is dense with multiple conditions.

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 provides adequate context for typical use, including success/failure detection through events, but does not detail error scenarios or what happens if the turn is not active beyond a brief mention, leaving some edge cases unspecified.

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 input schema has 0% coverage from the description, and the description does not explain the semantics of task_id or instruction. It implies the correction content, but does not explicitly map parameters to their roles, leaving the agent to infer.

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 'Send a correction immediately to the active Codex turn' with a specific verb and resource, and distinguishes itself by addressing conditions like awaiting_closure vs completed, which sets it apart from siblings like codex_start_task.

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 states when to use it: 'awaiting_closure accepts followups' and 'completed rejects followups (create a new task)', giving clear alternatives. It also notes the condition for starting a follow-up when no turn is active.

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

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

Annotations only indicate readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description adds substantial behavioral detail: it mentions the TRUSTED_EXECUTOR_AUTO_ADVANCE mechanism, worker-owned DoD, error conditions for omitted/deprecated inputs, and the specific default completion policies. This goes well beyond the sparse annotations, though it does not describe the return value or potential side effects in detail.

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 dense paragraph but is not overly long relative to the complexity. It front-loads the core action ('Start a background Codex turn') and then packs constraints efficiently. No unnecessary filler; every sentence conveys a specific constraint or behavior. It could benefit from bullet points for readability, but the content is appropriately sized.

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?

Despite covering workstream logic and completion policies, the description leaves many parameters unexplained, including nested objects like research_program and research_contract, which are essential for RESEARCH workstreams. With only 13% schema description coverage and no output schema, an agent would lack sufficient context to correctly construct the full request. The description is inadequate for the tool's complexity.

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

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

With schema description coverage at only 13%, the description compensates for the most critical parameters: it explains the next_workstream structure, the requirement for accepted_handoff_path/sha256 in EXECUTION_ONLY, and the behavior of completion_policy. However, it does not clarify many other parameters such as research_program, research_contract, expected_artifacts, or rva_fallback_policy, leaving a significant gap for a tool with 23 parameters.

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: 'Start a background Codex turn.' It uses a specific verb ('Start') and resource ('background Codex turn'), and the details about workstream types and policies distinguish it from sibling tools like codex_send_followup or codex_abort, which serve different lifecycle stages. The purpose is unmistakable.

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 context on when different configurations apply (e.g., EXECUTION_ONLY vs RESEARCH) and clarifies error conditions, but it does not explicitly name alternative tools or conditions under which an agent should choose this over a sibling. The guidance is more about parameter requirements than tool selection, leaving the agent to infer alternatives from the tool name and sibling list.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering the safety profile. The description goes beyond by explaining nuances: 'never inferred' for next_workstream, null for legacy/missing, DRAINED consumes no executor slot, and COMPLETED means manual/bridge policy closure. This adds rich behavioral context and is consistent with annotations.

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

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

The description is dense but front-loaded with the primary purpose. It efficiently packs multiple status semantics into a few sentences without fluff. It could be slightly better structured (e.g., bullet points) but remains appropriately concise for the information it conveys.

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?

Despite lacking an output schema, the description explains the return fields and their meanings comprehensively, including edge cases like legacy/v1 behavior and the 'never inferred' rule. It covers the key behavioral aspects an agent needs to interpret results correctly, making it complete for a status 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?

The input schema has a single required task_id with 0% description coverage. The description never mentions task_id, its format, or its semantics. Since schema coverage is low, the description must compensate, but it does not address the parameter at all, leaving the agent to infer from the schema's format field alone.

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 ('Return') and a clear resource ('persisted task') with detailed fields (execution_status, execution_binding, closure_status, etc.). It clearly identifies the tool's function and its scope is distinct from siblings by focusing on codex task status, making it easy to select appropriately.

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 explicitly state when to use this tool versus alternatives. It provides contextual meaning of statuses (e.g., DRAINED, COMPLETED) which aids understanding, but it does not mention any exclusions or alternative tools. Usage is implied by the name and the fact that it returns status details, not explicit 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?

Annotations already declare readOnlyHint and idempotentHint, so the description only needs to add context beyond those. It does add the UTF-8 text file requirement and the bounded line range behavior, which is useful. However, it does not disclose error behavior, encoding handling, or edge cases like out-of-bounds lines, so it only partially covers the burden with the low bar set by 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?

The description is a single, tight sentence that states the action and key constraints without filler. It is appropriately concise, though it could front-load the parameter semantics to be more useful. No excess words, so it earns a 4.

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 tool with four parameters (one required), no output schema, and zero schema descriptions, the description is minimal. It does not explain the start_character parameter, line indexing conventions, file-not-found behavior, or how bounds are interpreted. An agent cannot reliably call this tool correctly without additional inference, so completeness is low.

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 has zero descriptions for all four parameters, so the description must compensate. It only mentions a 'bounded line range', which explains start_line and end_line at a high level, but leaves start_character entirely unexplained, and doesn't clarify whether lines are zero-based, inclusive, or what happens with missing bounds. This is insufficient given the 0% 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 a specific verb (read), a precise resource (a bounded line range from a UTF-8 text file inside the target repository), and the constraints (bounded, UTF-8, repository-scoped). This distinguishes it from siblings like repo_search or repo_snapshot without needing to inspect schemas.

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

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

The description implies usage for reading a specific file's lines but does not explicitly state when to use this versus alternatives like repo_search, repo_snapshot, or codex_diff. There is no when/when-not guidance or named sibling, leaving the agent to infer based on the verb.

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 annotations already establish readOnlyHint and idempotentHint, so the safety profile is covered. The description adds useful scope context ('text files', 'without leaving its root'), but does not disclose how search behaves with binary files, hidden paths, symlinks, or what output format is returned.

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 filler: it names the action, resource, and constraint efficiently. It is not scored as 5 because it is too terse relative to the four-parameter complexity and leaves important guidance unsaid.

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 four parameters, 0% schema description coverage, and no output schema, the description gives only the bare purpose. An agent still cannot determine path_prefix format, case-sensitivity defaults, result limits/behavior, or return shape, so the tool is not fully callable from the description alone.

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 0%, and the description adds no per-parameter meaning. It does not explain query syntax, how path_prefix is interpreted, the default for case_sensitive, or what max_results controls. With four parameters and no schema descriptions, the description fails to compensate.

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 ('Search text files'), a clear resource ('under the target repository'), and a distinguishing constraint ('without leaving its root'). This lets an agent separate it from siblings like repo_read or repo_snapshot without opening schemas.

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

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

The description clearly implies when to use the tool: when you need text-file search scoped to the repository root. It does not explicitly name alternatives or say when not to use it, so it stops short of a 5, but the context is clear enough for 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description says 'Return' which aligns with these annotations. It does not add context beyond the annotations—no mention of what 'dirty status' means, how top-level entries are presented, or any edge cases. Given the annotations, a score of 3 is appropriate: consistent but not additive.

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, concise sentence that front-loads the core purpose. Every word earns its place with 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?

For a zero-parameter, read-only snapshot tool, the description is adequately complete. It names the four elements returned (branch, commit, dirty status, top-level entries). The absence of an output schema and the simplicity of the tool mean the description carries the full burden, and it does so sufficiently. Slightly more detail about the format of 'dirty status' or 'top-level entries' could push it to a 5, but it is not critically missing.

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

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

The tool has zero parameters, and the schema description coverage is 100% (since there is nothing to describe). The baseline for no parameters is 4, and the description does not need to explain any parameter semantics. No credit lost here.

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 returns repository branch, commit, dirty status, and top-level entries. It is specific about the resource and the data provided, distinguishing it from sibling tools like repo_read (which likely reads file contents) and repo_search (which searches). However, it does not explicitly name alternatives, 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?

The description provides no guidance on when to use this tool versus alternatives such as repo_read or repo_search. It does not mention any conditions, prerequisites, or scenarios where this snapshot tool is preferable. The agent is left to infer its use case from the name and description alone.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds some context by naming the categories of returned data, but it discloses no edge-case behavior, error conditions, or whether results are scoped to a specific cycle.

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

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

The description is a single sentence, front-loaded with the action verb, and contains no redundant filler. It is concise, though the domain jargon like 'durable research-cycle artifacts' and 'gate settlements' reduces clarity.

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 one-parameter tool with no output schema, the description is too thin: it omits task_id semantics, output structure, and how this status tool relates to the many sibling tools. The broad list of return categories is helpful but not sufficient for confident invocation.

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

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

The schema has one required task_id parameter with 0% description coverage, and the description never mentions task_id at all. It does not explain what task_id identifies, how it relates to the research cycle, or what values are meaningful, leaving the agent to guess.

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 clear verb ('Return') and a specific resource: durable research-cycle artifacts, gate settlements, reviews, and linked finite Codex tasks. This is more informative than a generic status description, though it does not explicitly differentiate itself from sibling research/rva tools.

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

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

No guidance is given about when to use this tool versus alternatives such as research_knowledge_status, rva_review_result, or research_record_settlement_decision. The read-only annotations imply a status-checking use case, but the description itself provides no selection criteria 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?

Annotations already declare readOnlyHint and idempotentHint, so the description does not need to restate safety. It adds that this is the 'authoritative' snapshot and that migration candidates are 'separately listed,' which is useful context. However, it does not disclose output format, freshness, or what the snapshot actually contains.

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

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

The description is a single sentence with the verb and resource front-loaded, containing no filler. The phrase 'separately listed' is slightly awkward, but overall the description is efficient and scannable.

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 no-argument read-only tool with safety annotations, the core action is covered. However, the return content is vague—'snapshot' and 'separately listed migration candidates'—and the description does not clarify how this differs from sibling status tools. With no output schema, a bit more detail about what the returned data contains would improve completeness.

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 and the input schema is empty, so parameter semantics are inherently complete. The description appropriately focuses on what is read rather than inputs.

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

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

The description clearly identifies a read operation ('Read') and the resource ('authoritative research graph/ledger snapshot and separately listed migration candidates'). It is distinguishable from mutation siblings, though 'separately listed migration candidates' is somewhat vague and could overlap with research_migration_scan.

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 explicit guidance is given on when to use this tool over alternatives such as research_cycle_status or research_migration_scan. The read-only nature implies a status-checking use case, but no conditions, exclusions, or sibling comparisons 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?

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds that the action is 'auditable' (requires actor and reason), which is a behavioral trait not in annotations. It also clarifies it applies to 'PROPOSED' candidates, implying a state transition. No contradiction with annotations.

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

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

A single, front-loaded sentence that states the purpose without waste. The key elements (confirm/reject, candidate, auditable) are all present in a compact form.

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 the core action but omits what happens after the call (e.g., state change, return value) and any prerequisites (e.g., candidate must exist and be in a certain state). With no output schema and a write operation, more context would be needed for full completeness, though the idempotent hint and non-destructive annotation mitigate some risk.

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 0%, so the description must compensate. It mentions 'actor' and 'reason' indirectly via 'auditable actor and reason', but does not explain candidate_id or the meaning of action beyond the enum. The action enum is self-explanatory, but candidate_id is undocumented. This is a significant gap for a 4-param required tool.

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 (confirm/reject) and the resource (PROPOSED migration candidate), and distinguishes it from siblings like research_migration_scan (which likely scans) and workstream_accept_candidate. The verb+resource combination is specific and unambiguous.

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

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

The description implies when to use it: when you need to explicitly confirm or reject a proposed migration candidate. It doesn't explicitly exclude alternatives, but the context of sibling tools (scan, review, etc.) makes the intended use clear. Slight deduction for not naming alternatives directly.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: the scan is 'offline' and 'bounded', and extracted artifacts remain 'PROPOSED'—clarifying that nothing is finalized or written. This goes beyond the annotations and helps an agent understand 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?

Two sentences, no filler, and the most important qualifiers ('offline bounded', 'PROPOSED') are front-loaded. Every word 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 read-only scan with idempotentHint and no output schema, the description covers the key behavioral facts: offline, bounded, and non-final artifacts. However, it does not explain what the output looks like, how results are returned, or how path_prefix and max_files shape the scan. Given the tool's moderate complexity and zero schema description coverage, a bit more detail would be warranted.

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 0%, so the description carries the burden, but it only explains the source parameter implicitly ('default' vs bridge-owned data). It does not explain max_files or path_prefix semantics, though their names are fairly self-explanatory. The description adds some context for source but leaves the other two parameters to be inferred from names and schema constraints.

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 ('scan') and resource ('target repository' or 'bridge-owned data'), and adds the key qualifier 'offline bounded'. It distinguishes itself from siblings like repo_read and repo_search by emphasizing the scan is offline and bounded, though it doesn't explicitly name an alternative.

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

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

The description implies usage context: it is a scan of the target repository or bridge-owned data, and the 'default' wording suggests the source parameter is optional. However, it does not explicitly state when to prefer this over repo_read, repo_search, or repo_snapshot, nor does it provide exclusion criteria.

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 explains that the tool projects a reviewed ResultClaim into deterministic Evidence)Skip and publishes it directly, and that the action is idempotent with no separate confirmation required. This aligns with and adds context beyond the idempotentHint annotation fran. It does not cover permissions or failure behavior, but the annotations already signal non-read-only and non-destructive 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?

The description is dense but every sentence earns its place: it front-loads the tool's mandatory role, then explains ordering, task_id selection, action semantics, and idempotence. There is no filler or repetition beyond what is structurally necessary for the complex workflow.

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-complexity workflow tool with no output schema, the description covers the key invocation context, parameter semantics, action variants, and idempotence. It does not describe return values, possible errors, or what happens if the latest ResultClaim is not acceptable, but it explicitly says no confirmation is required, which reduces that ambiguity.

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

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

With 0% schema description coverage, the description carries the full burden for parameters. It explains task_id must be the latest execution task UUID, specifically the latest executionTaskIds entry or ResultClaim.executionTaskId, and never the research cycle UUID. It also gives semantic meaning to both action enum values and specifies that a non-empty reason is needed for NO_KNOWLEDGE_TO_PUBLISH.

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 defines this as a required post-result publishing step, with a specific resource ('publish it directly to the authoritative Knowledge Graph') and two concrete action modes. It also disambiguates its position in the research cycle by stating it runs after RESULT_REVIEW and before follow-up decisions or cycle closure.

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 ordering conditions: call after an accepted settled RESULT_REVIEW and before follow-up decisions, next-experiment proposals, cycle closure, or linked execution. It also gives clear conditional guidance for NO_KNOWLEDGE_TO_PUBLISH. It does not explicitly name alternative sibling tools, so the boundary is clear in pipeline terms but not tool-comparison terms.

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 conveys that this is a state-recording write action with workflow sequencing constraints. However, it does not disclose whether an existing decision is overwritten, what the response looks like, or what happens if called in the wrong state. Annotations provide no read-only or idempotency protection, so more behavioral detail would have helped.

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 with no filler. The core action and allowed values are front-loaded, and the routing caveat is placed second. 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 two-parameter state-recording tool, the description plus schema provides enough to select and invoke it correctly: when it applies, what to pass, and how it relates to the sibling workflow tool. Missing details like overwrite semantics and return values are minor given the tool's low complexity and absence of an output 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 0%, so the description must carry the parameter-semantics burden. It does add workflow context to the decision parameter by enumerating the valid choices and routing NEXT_EXPERIMENT_PROPOSED elsewhere, but it never defines task_id's referent or explains the practical meaning of DEFERRED versus NO_NEXT_EXPERIMENT. This is only partial compensation.

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 ('record') with a clear resource ('followup decision') and explicitly names the two allowed outcomes. It also differentiates this tool from rva_review_next_experiment, so an agent can tell them apart without inspecting schemas.

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

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

It states when the tool applies ('after settled result review'), which decisions belong here, and which decision belongs to a sibling tool. The condition that NEXT_EXPERIMENT_PROPOSED must settle before closure/linking gives actionable workflow ordering.

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

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

Annotations already declare this as a non-readonly, idempotent, non-destructive write, so the description does not need to restate that safety profile. The description adds meaningful behavioral constraints: every objection from both rounds must be addressed with evidence, unsupported conclusions must be preserved, experiments must be bounded, and FAIL_CLOSED provider-failure gates cannot be cleared through this tool. This is valuable context beyond what the annotations or schema 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, and each sentence earns its place: purpose, required timing, content obligations, and the fail-closed exception. The core purpose is front-loaded before policy details and alternative routing. There is no filler or redundant restatement of schema 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?

This tool has a complex nested decision schema, but the description supplies the missing policy context: when the call is required, what content obligations apply, and which gate failure must be routed to rva_retry_unavailable_review. The schema already documents structure, enums, required fields, and additionalProperties constraints. No critical invocation information is absent.

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 0%, so the description carries the burden, and it compensates well for the nested decision object: 'Address every objection... with evidence, preserve unsupported conclusions, and bound any experiment' maps to objections, evidenceRefs, unsupportedConclusions, and experimentBudget. It also links 'bound to the latest settled gate outcome' to outcomeId. It does not explicitly discuss task_id, but the parameter name and UUID schema make its role unambiguous.

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 opening verb 'Record' names the action and the object: 'the orchestrator's content-based conclusion and next step, bound to the latest settled gate outcome.' It clearly distinguishes this from review/follow-up/retry siblings by specifying a distinct record-keeping operation with a specific trigger condition. This is not a tautology and gives the agent a concrete sense of what the tool does.

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 explicitly states when the tool is required: 'after scientific RVA budget exhaustion before publication, closure, or next execution.' It also provides an explicit exclusion and alternative: 'A decision cannot clear a FAIL_CLOSED provider-failure gate; use rva_retry_unavailable_review after provider recovery.' This gives the agent clear selection guidance versus a sibling tool.

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

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

Annotations already indicate a non-read-only, non-idempotent operation. The description adds the side effect of queueing a generic mandatory review gate and accepting any typed disposition, which is useful context. However, it does not explain what the queued gate does, whether the operation can be retried, or what downstream effects occur.

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 terse sentence with no filler, and the alias status is front-loaded. It is compact and scannable, though the brevity comes at the cost of important operational detail.

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 a complex required result_claim object, no output schema, and minimal annotations, yet the description does not explain what fields are required, what dispositions are allowed, or what the result-review gate entails. An agent would not have enough context to construct a valid invocation without external knowledge.

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

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

With 0% schema description coverage, the description should explain task_id and result_claim, but it only vaguely references 'typed result disposition'. It does not mention task_id, the required nested fields, or the meaning of the disposition values, leaving agents to infer the structure entirely from the raw 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 specifies a concrete action: record any typed result disposition and queue the mandatory result-review gate. It is not a tautology and includes alias status, but it does not explicitly name the tool it aliases or differentiate itself from siblings like rva_review_result.

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

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

There is no guidance on when to use this tool versus alternatives such as rva_review_result or rva_review_next_experiment. The phrase 'Backward-compatible alias' hints at legacy usage but does not state conditions, exclusions, or when another tool would be more appropriate.

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 adds meaningful behavioral context beyond the annotations: the original artifact and failure remain auditable, settlement cannot replace a successful review, and scientific review rounds keep their original limit. Since annotations declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, the description's extra constraints on auditability and round limits are valuable and do not contradict the annotations.

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

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

Four tight sentences, each adding distinct value: the action, the audit preservation, the settlement exclusion, and the round-limit preservation. It is front-loaded with the core behavior and has no filler or redundant restating 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 two-parameter retry tool, the description is largely complete: it states the trigger, the target gate types, and important invariants. It does not describe what happens if there is no previous failed review or mention the return/error behavior, but those gaps are acceptable given the focused scope and the presence of annotations covering safety characteristics.

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 0%, so the description must carry parameter meaning. It explains the gate_type values by naming RESULT_REVIEW and NEXT_EXPERIMENT_REVIEW, and 'latest' implies task_id identifies the task whose most recent failed review should be retried. However, it never explicitly describes task_id's role or how it relates to the gate_type, leaving the agent to infer that from the tool name and context.

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 ('retry'), a precise resource ('the latest RESULT_REVIEW or NEXT_EXPERIMENT_REVIEW'), and a clear condition ('after a FAIL_CLOSED RVA provider failure'). This distinguishes it from the sibling review tools like rva_review_result and rva_review_next_experiment, which initiate rather than retry a review.

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 explicitly scopes usage to FAIL_CLOSED provider failures and warns that settlement decisions, including BOUNDED_EXPERIMENT, cannot substitute for a successful RVA review. It does not explicitly name the alternative tools to use in other situations, but the conditions and exclusions are concrete enough for an agent to route correctly.

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

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

Annotations indicate non-read-only (write operation) and no idempotency, but description adds that the contract is 'persisted' and the task is 'queued for execution'. This is useful context beyond annotations. However, it doesn't disclose if this overwrites existing contracts, whether it requires existing task state, or any 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?

Description is one sentence, front-loaded with the core action and scope. It clearly states the result (persisted, queued). It adds the key distinction 'without RVA review' upfront. No wasted words.

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 complexity and nested objects, the description is minimal. It doesn't explain the difference between this and rva_review_next_experiment or how the research_program fits in. With no output schema, it doesn't describe return values or errors. But annotations cover mutation semantics partially, and the schema provides structure. Agent might need more context to select 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 0%, but the schema itself defines required fields and structure. The description mentions 'typed Research Contract' which implies the research_contract parameter structure, and the task_id is referenced by 'the task'. However, it does not explicitly describe research_program parameter, which is not required but present. Baseline 3 is appropriate as the schema is rich enough.

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: 'Submit a new or revised typed Research Contract without RVA review'. It clarifies that the contract is persisted and the task is queued. However, it doesn't fully distinguish from sibling tools like rva_review_next_experiment or rva_challenge_result, and the term 'without RVA review' is an important distinguishing trait but not explicitly contrasted with 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 implies usage when submitting a contract without RVA review, but provides no explicit guidance on when to use this versus rva_review_next_experiment or other RVA tools. No exclusions or alternative conditions are mentioned.

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

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

Annotations are all false (readOnly, idempotent, destructive), so the description carries the full behavioral burden and does well: it discloses the at-most-two-rounds constraint, the immediate gate release on final rejection, and the preservation of objections. No contradiction with annotations. It leaves out auth requirements or reversibility, but the disclosed gate/round semantics are genuinely useful context beyond the structured fields.

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 with the purpose front-loaded in sentence one and workflow context following. It is compact with no redundancy, though the dense domain jargon (RVA rounds, 'releasing the gate', 'preserving objections') slightly reduces immediate readability for an agent without RVA context.

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?

As a mutation tool with no output schema, sparse annotations, and 0% parameter coverage, the description must compensate heavily but does not. It explains workflow sequencing well but omits what the response contains, what success/failure looks like, and any guidance on the complex proposal structure. For a tool with a highly nested required object, this is incomplete.

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 0%, and the proposal parameter is a deeply nested object with 13+ fields (abstractionLevel, discriminativeValue, decisionUnlocked, cleanValidationDataCost, etc.) that are entirely unexplained. The description does not clarify any parameter's meaning, format, or how required fields interrelate. For a nested object of this complexity, the lack of parameter guidance is a severe gap.

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 opening sentence 'Record a next-experiment proposal' states a clear verb+resource pair. However, with siblings like rva_review_contract, rva_review_result, and rva_challenge_result present, the description does not differentiate what makes this proposal distinct from those review/challenge records, so it stops short of full sibling disambiguation.

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 genuine procedural guidance: a two-round cap per execution step, the final rejecting round's gate-release behavior, and an explicit ordering prerequisite ('record research_record_settlement_decision before linking execution'). This names a specific sibling prerequisite, though it never states explicit exclusions or alternative conditions, so it earns a 4 rather than a 5.

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

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

Annotations already indicate a non-read-only, non-idempotent operation, so the description need not repeat that. It adds valuable context by specifying the binding to the latest execution and canonical artifact hashes and the mandatory queueing of review, which are not in the annotations. However, it doesn't disclose side effects like overwriting previous results or failure modes.

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 entire description is a single sentence that front-loads the action and the allowed dispositions. It is concise and to the point, with no wasted words.

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 tool with a complex nested parameter and no output schema, the description is too high-level. It omits essential details such as the required fields within result_claim (schemaVersion, claim, evidenceSummary, contractId, limitations, proposedResearchStateAdvance) and the meaning of task_id. An agent would need to inspect the schema to construct a valid call, which the description does not compensate for.

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 0%, and the description does not elaborate on task_id or the required structure of result_claim. It only hints at binding to hashes, leaving the agent to infer that the nested object contains artifact and hash fields. This is insufficient given the complexity of the result_claim object with multiple required 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 action: 'Record a FAVORABLE, NULL, ADVERSE, INCONCLUSIVE, or FEASIBILITY_ONLY result bound to the latest completed execution and canonical artifact hashes, then queue mandatory RVA result review.' It specifies a verb, resource, and the distinct disposition set, distinguishing it from sibling tools like rva_review_contract and rva_challenge_result.

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

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

The description implies a clear use case (recording a result and queueing review) but does not explicitly mention when not to use it or contrast it with alternatives like rva_challenge_result or rva_retry_unavailable_review. There is no guidance on conditions that would make another tool more appropriate, so the agent must infer from 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?

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description adds meaningful behavioral details: the created handoff is 'immutable', the advancement is 'atomic', and idempotency is reiterated for the same committed transition. It also warns about authorization boundaries. These traits are not present in structured annotations, so the description adds real value here.

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: it starts with the governance constraint, then the primary action, then prerequisites and a guardrail. Each sentence provides distinct information. It is slightly dense but not wasteful. A small trim would improve it, but it remains appropriately structured and informative.

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?

This is a complex, 7-parameter mutation tool with no output schema and no parameter descriptions. The description omits essential operational context such as what each parameter means, how the 'configured target repository' is identified, what success/failure responses look like, and how the tool uses the provided SHA-256 values. An agent would struggle to construct a correct invocation without additional documentation. The description is not complete enough for the tool's complexity.

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 0% and the description does not explain the individual parameters. It references 'candidate', 'prior current SHA-256/revision/handoff', and 'next task' at a conceptual level, but does not map them to the 7 required parameters (e.g., review_task_id, review_event_seq, workstream_id, candidate_path). The nested object next_task_ref also lacks a clear relationship to the described workflow. With no schema-level descriptions, the description should compensate but does not.

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 specifies an exact action ('Accept a reviewed agent-workstream-context-v1 CANDIDATE'), the resource type, and the subsequent effects ('create its immutable accepted handoff, and atomically advance the configured target repository'). It also adds a governance boundary ('Trusted ChatGPT/bridge governance only') that distinguishes it from general-purpose tools. This clearly identifies the tool's unique role among the 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 explicit prerequisites ('Requires a persisted chatgpt.review ACCEPTED JSON binding candidate, prior current SHA-256/revision/handoff, and next task') and a clear when-not ('Task completion/auto-close never authorizes this action'). It also specifies the trusted governance context, which indicates who may use it. However, it does not name alternative tools or state when to prefer a sibling, so it's not a full 5.

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