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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds substantial non-obvious behavior: cancellation is a request rather than a guaranteed stop, cancelRequested is only an acknowledgement, pending Inbox is preserved, and subagent termination depends on parent-managed vs independent sessions. It stops short of describing what destructive state change actually occurs to the run.

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, front-loaded with the core action, and each sentence carries distinct behavioral information. The dense internal jargon ('native history', 'reconciled terminal cancelled state') adds reading cost but not padding.

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

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

For a destructive, idempotent mutation tool with no output schema, the description covers runtime semantics well but leaves both parameters, especially idempotencyKey, undocumented and gives no hint of what the acknowledgement response contains. It is adequate on behavior and thin on invocation detail.

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 burden for both parameters. It says nothing about runId (format, constraints) and never mentions idempotencyKey at all, despite discussing acknowledgement and repeat-request semantics where the key would be directly relevant. The description does not compensate for the coverage 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 description states a specific action on a specific resource ('Request cancellation through the public Host API') and the title names the target ('Cancel a Harness run'). It is distinguishable from siblings like close_run_terminals or stop_service by scoping it to a run's cancellation request. It loses a point because the object of cancellation ('run') is only implied by the title, not the description text.

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

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

There is no explicit when-to-use or when-not-to-use guidance relative to siblings such as close_run_terminals or stop_service. It does imply a usage stance by warning that the acknowledgement is not proof of stopping and pointing to native history inspection as the verification path. This is implied guidance rather than a clear decision rule.

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 destructive=true, idempotent=true, readOnly=false. The description adds real context beyond that: a 100-item bound, that it snapshots before removing (explaining idempotency semantics), that it never deletes history or stops an active turn, and that it reports new arrivals and remaining items. Missing are permission requirements and failure/error behavior, which is why it isn't 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, front-loaded with the operation, followed by reporting behavior, safety guarantees, and a caution. Each sentence carries information, though the phrasing is slightly telegraphic and could integrate the parameter 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?

For a destructive one-parameter mutation whose annotations carry the safety profile, the description covers scope limits, side-effect boundaries, and result reporting. The remaining gap is the undocumented sessionId and lack of error/permission detail, which the missing output schema does not fill.

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

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

There is a single required sessionId parameter with 0% schema description coverage, and the description says nothing specific about it. It is compensated only by the obvious self-documenting name and the tool's implicit session scope, so the description neither adds nor misleads.

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 gives a specific verb+resource (snapshot and remove pending queue IDs) and clarifies scope: a cap of 100 and removal limited only to occurrences present at snapshot time. That clearly separates it from item-level siblings like remove_queue_item and from read-only list_session_queue, though it never names a sibling 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?

Usage is implied: bulk-clear a session's pending items and then inspect unknown outcomes before proceeding. There is a caution ('Inspect unknown outcomes before further action') but no explicit when-to-use versus alternatives such as remove_queue_item or list_session_queue, and no stated preconditions.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, yet the description still adds substantial value: exactly what is destroyed (the published PTY snapshot, including shells retained from prior runs), what is preserved (other owners, unpublished/new terminal activity), the ordering constraint (reconcile the lease only after confirmed quiescence), the return value (updated original run), and the boundary 'Never clears Inbox/history.' That is well beyond what the annotations convey.

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

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

It is information-dense with little filler, but it is a run-on sequence of jargon fragments rather than front-loaded prose, and it leads with a conditional usage clause instead of the action. Structure impedes comprehension even though few words are wasted.

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, idempotent mutation with no output schema and one parameter, the description covers the essential behavioral facts: destruction scope, preservation scope, sequencing, and return value. The main gap is the runId parameter's semantics, which neither schema nor description explains.

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 0% and one required parameter, the description must carry the load. 'This exact Agent session' and 'return the updated original run' weakly imply runId names a run, but nothing states where the id comes from, its format, or that it must be an idle/non-native-agent run. The single parameter is effectively undocumented.

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 core action is inferable from the title ('Close one idle run owner's persistent terminals') and the phrase 'Discard this exact Agent session's published PTY snapshot,' so a verb+resource does exist. However the description itself opens with a usage condition ('Explicit permission recovery...') rather than a plain statement of what the tool does, and the jargon-heavy phrasing makes the purpose hard to extract. It also fails to distinguish itself from the sibling reconcile_permissions, which the 'permission recovery' wording overlaps with.

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

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

It gives real conditions for use ('Explicit permission recovery for a terminal run, or needs_attention with permission_restore_failed') and one exclusion ('Reject active native Agents'). But it never names an alternative sibling (reconcile_permissions, cancel_run) or explains how to choose between them, so the routing guidance is only implied.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds meaningful behavioral context beyond annotations, especially that it operates 'without reading credentials,' which is important for security-conscious agents. This extra disclosure makes the behavior more transparent than the schema alone.

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

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

The description is a single focused sentence that front-loads the tool's purpose and includes the most critical security-related caveat ('without reading credentials'). Every word earns its place, and the title provides useful additional framing without bloating the description.

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 tool, the description is mostly adequate and the annotations carry the safety context. However, there is no output schema and the description does not indicate what the return payload looks like, whether it is a simple status, a policy report, or a boolean pass/fail. This missing expected-output information leaves an agent slightly uncertain about how to interpret the result.

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 required parameters are zero, so the schema has 100% coverage trivially. There are no parameter semantics to document, and the description correctly avoids inventing meaningless parameter details. Baseline of 4 is appropriate for a no-parameter 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 uses a specific verb ('Check') and identifies a clear resource ('external Harness Host and relay policy'). It also distinguishes itself from sibling setup_doctor by framing this as a verification action rather than a setup action. It loses one point because it does not state what a successful check returns or what exact conditions are being validated.

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 this tool is for verifying external Harness connectivity and relay policy, and the sibling name setup_doctor suggests an alternative for installation/configuration. However, there is no explicit when-to-use versus when-not-to-use guidance, and no mention of when to prefer sibling tools such as status_run or get_operation.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the 'durable' qualifier and the request-scope, but does not disclose behavior like not-found handling or the exact response shape. It contributes some context beyond annotations without contradicting 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, front-loaded sentence with no filler. The verb and object appear first, the scoping qualifiers follow, and every phrase 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 one-parameter read tool with readOnly and idempotent annotations and no output schema, the description is nearly complete: it names the resource and the exact request types it covers. It stops short of describing response contents, but 'Read the ... operation record' sufficiently implies the return value for this simple read operation.

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 for the undocumented operationId parameter. It partially does by indicating that the ID refers to a durable operation record for start/reply/steer/cancel requests. However, it does not explain where the operationId comes from or otherwise enrich the parameter meaning much beyond the schema's name and uuid format.

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 ('Read') and a specific resource ('durable idempotent operation record'), and narrows the scope by enumerating the request types: start, reply, steer, or cancel. This makes the tool easy to distinguish from run-focused siblings like get_run or status_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 clearly implies when to use this tool: when you need the operation record for a start, reply, steer, or cancel request. It does not explicitly name alternatives or state when not to use it, but the request-type enumeration is strong contextual 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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine non-annotation value by stating the negative boundary ('does not grant permissions, run commands, or change services'), which disambiguates it from the mutating siblings like reconcile_permissions and start_service.

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 compact sentences, front-loaded with what it reports, then the override/inheritance rule, then the non-actions. No wasted text, though the 'reply_run inherits its parent run' clause assumes context the reader may not have.

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 inspection tool with full annotation coverage and no output schema, the description covers what is reported and what is explicitly not done. It is adequate; only the relationship to sibling capability-listing tools is unstated.

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

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

The tool takes zero parameters, so there is nothing for the description to document and the baseline of 4 applies. The mention of call-value override semantics is contextual rather than parameter-specific.

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 ('Describe') and enumerates the three resource categories it reports: supported operations, MCP permission defaults, and external path policy. This is far more precise than the title, though it never names or contrasts with the nearby sibling 'list_capabilities', so sibling differentiation is left implicit.

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

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

It gives a useful precedence rule ('explicit call values override defaults; reply_run inherits its parent run'), which implies when the reported values are authoritative. However, it offers no explicit when-to-use vs 'list_capabilities', 'doctor', or 'read_session_context', and no statement of preconditions.

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, idempotentHint=true, and destructiveHint=false, so the description's job is to add context beyond those. It does so well by disclosing the polling contract: a non-terminal status forces hostMustCallWaitRunAgain=true and forbids conclusion. It also notes the deprecation of status_run, which helps an agent understand expected 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 two sentences with no filler. The first sentence establishes purpose and preference, and the second delivers the critical behavioral contract. Every clause earns its place.

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

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

For a simple one-parameter read tool, the description covers the essential safety and polling behavior. It lacks an explicit return-value description and does not explain runId, but the 'run snapshot' phrase plus the schema's strongly typed runId keep the definition mostly 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%, so the description should compensate by explaining the runId parameter or how it is used. It never mentions runId, format expectations, or how the run snapshot is selected. The schema itself is self-descriptive with a UUID pattern, but the description adds no parameter-level 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 clearly states the tool's function: 'reconcile and return one run snapshot' and notes it replaces the deprecated status_run alias. It identifies a specific resource (a Harness run) and a read operation, though it does not explicitly distinguish itself from siblings like get_run_summary or open_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?

It frames get_run as the 'Preferred tool' for this task and calls out the deprecated status_run alternative. It also gives a concrete post-call condition: if status is running or unknown, the host must not conclude and must call wait_run again. It lacks explicit exclusions for other sibling tools, but the context is fairly 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds only modest context, that this is a derived 'current durable run snapshot' with 'stable' field names, and says nothing about staleness, caching, or how the projection relates to the live run state.

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 dense sentence with the output field list front-loaded and no filler. It is efficient, though the abstract phrasing ('project…snapshot…stable') costs some readability versus plain wording.

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 an output schema present and annotations covering the safety profile, the missing return-format detail is not a gap. What is missing is routing context: in a namespace crowded with run-inspection siblings, an agent gets no signal about why it would choose this summary projection over get_run or status_run.

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 runId, so it does not compensate for the undocumented parameter. The single required param is self-evidently a run identifier and the uuid pattern is enforced by the schema, keeping this at a middling baseline rather than poor.

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 the resource (a run) and enumerates the concrete fields the tool yields: status, model, permission, elapsed time, and next-action. That is enough to know what it produces, but the framing verb 'project…into stable…fields' is jargon and the entry does not distinguish this summary view from siblings such as get_run, status_run, or list_run_summaries.

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 statement of when to call this versus the many other run-reading tools in the namespace (get_run, status_run, wait_run, list_run_summaries). No prerequisites or trigger conditions are given; the agent must infer usage from the name 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 readOnly, idempotent, closed-world, non-destructive behavior, and the description adds that it queries live running Harness state rather than a proxy — genuinely useful context beyond the structured fields. It does not disclose failure behavior when no Harness is connected, which the title ('connected existing Harness') implies is a prerequisite.

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, no filler. The scope statement comes first and the differentiating clause second, which is the right front-loading for an agent scanning options.

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

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

No output schema exists, so the description's enumeration of what is returned (health, version, task limits) carries the return-value burden, and it does so concisely. With zero parameters and full annotation coverage of the safety profile, nothing essential is missing.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain; the baseline for a 0-param tool applies. The description correctly avoids inventing arguments.

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

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

States a specific verb ('Read') and resource set ('embedded Host health, version and task limits'), and explicitly contrasts itself with another diagnostic tool. The contrast target is named as 'proxy doctor' while the sibling list offers 'doctor'/'setup_doctor', a minor naming mismatch that slightly weakens the 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 phrase 'Unlike proxy doctor, this queries the running Harness' tells the agent when to pick this over the proxy-based alternative, which is clear routing context. It stops short of explicit when-not conditions or prerequisites (e.g., what happens if no Harness is connected).

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 cover read-only, idempotent, and non-destructive behavior, so the bar for extra disclosure is lower. The description adds that the tool returns canonical option names rather than guesses, which is useful, but it does not describe output format, ordering, or any environment-specific 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?

A single sentence that front-loads the verb and object, lists the option categories compactly, and closes with a meaningful behavioral qualifier. Every word adds value and nothing is redundant.

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

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

For a zero-parameter, read-only discovery tool, the description is complete: it names exactly what the agent will learn and gives no ambiguous invocation requirements. No output schema is present, but the description adequately conveys the return concept — available option names.

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, so the input schema is intentionally empty and there is no parameter burden to document. Baseline for zero-parameter tools is 4; the description adds relevant semantic context by naming the categories of values the tool exposes.

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 ('List'), resource (native Provider/model/reasoning, agent preset, and permission preset options), and a clear purpose ('without guessing names'). It distinguishes this tool from sibling list tools like list_services, list_workspaces, and list_runs by naming the exact option categories it covers.

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

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

The phrase 'without guessing names' implies this tool should be used when the agent needs authoritative option values before configuring or running something. It provides clear context for when to call it, though it does not explicitly name alternative tools or state when not to use it.

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

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

Annotations already declare read-only/idempotent/non-destructive, and the description adds substantial behavior beyond them: descriptor-anchored access rejecting symlink components and path escapes, the untrusted-data caveat, per-page reauthorization and rescan on cursor use, explicit failure on oversized directories, non-atomic (non-snapshot) results, and output size caps.

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

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

Purpose is front-loaded and each sentence carries distinct operational information (limits, cursor semantics, ordering, security). It is dense and slightly long for a list tool, but little of it is redundant with structured fields.

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, security-sensitive listing tool; the description covers pagination, limits, cursor behavior, ordering, hidden-file defaults, failure modes, and safety constraints, which exceeds what the schema and annotations convey. With an output schema present, it need not explain return shape, and it correctly doesn't.

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, and it largely does: it documents page size (100 entries), hidden-name handling (default exclusion matching includeHidden), cursor semantics (checksummed, stateless, revalidated per page), and path/workspace safety (descriptor-anchored, symlink rejection, path escapes). It never maps these behaviors explicitly to parameter names, so a small gap remains.

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

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

States a precise verb+resource (list names, relative paths, and kinds of immediate children in an authorized project directory) and immediately delimits scope with 'without recursion, contents or symlink targets.' An agent can distinguish this from read_project_text and search_project_text purely from the description.

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

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

Usage context is implied by the scope constraints (non-recursive, immediate children only, hidden excluded by default), which helps an agent decide when this fits. However, it never names an alternative tool or states when not to use it versus read_project_text/search_project_text, so routing is left to inference.

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

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

Annotations cover the safety profile (readOnly/idempotent/non-destructive), and the description adds non-obvious behavior: request content is untrusted data and not instructions, and an empty list does not grant permission. It also discloses a host-version prerequisite, which is genuinely 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?

Front-loaded with the core action, and the trust and empty-list caveats are stated as tight fragments. Every sentence carries weight, though the flow is a bit staccato and the host requirement could be folded in more economically.

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

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

With no output schema, the description does state what the results contain (tool call, reason, plan detail) and covers the empty-result case and a version prerequisite. It omits pagination/ordering behavior, which is a minor remaining gap for a list tool.

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

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

One required runId parameter with 0% schema description coverage, so the description must compensate. It alludes to run and client-principal scoping but never explains the parameter's role, format, or source, leaving the schema's uuid pattern as the only guidance.

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 gives a specific verb and resource ('Read live one-shot permission requests and user questions') and scopes them to 'this run and client principal.' It implicitly distinguishes from the sibling respond_to_run_interaction (which acts) rather than naming an alternative 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?

Usage is implied by the read-only framing, but there is no explicit when-to-use versus when-not-to-use routing against siblings like respond_to_run_interaction or wait_run. 'Requires the updated embedded Host' is a prerequisite rather than a selection rule.

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 read-only, idempotent, and non-destructive, so the description need not restate that. It adds a data-source context ('restored from durable relay state') but does not clarify what 'reconcile' does or how it relates to the read-only guarantee.

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 one-sentence description is efficiently front-loaded and contains no filler. However, its brevity comes at the cost of clarity around 'reconcile'.

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

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

With no output schema, the description should indicate what a caller receives (a list of runs) and whether serviceId filters results; neither is stated. The tool's role relative to other run tools is also underspecified.

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 single parameter serviceId is not mentioned in the description at all, and schema coverage is 0%. Since the schema only provides a UUID format, the description fails to explain the parameter's role (e.g., filtering runs by service) or its optionality.

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 title and description clearly identify a list operation for runs. The phrase 'reconcile and list' adds ambiguity, and the description doesn't explicitly distinguish this from siblings like get_run or status_run, so it stops short of a top score.

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 choose list_runs over the many run-related siblings (get_run, get_run_summary, status_run, open_run, wait_run). There is also no mention of whether the optional serviceId should be used to scope the 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 cover the read-only/idempotent/no-destruction profile, and the description adds substantial non-obvious behavior: cursor semantics (cursors bind filters and pin the newest key, so newer runs are excluded), and the consistency caveat that status changes between pages are best-effort rather than an immutable snapshot. That is exactly the kind of pagination/consistency disclosure an agent needs and cannot get from 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?

Dense but front-loaded: the read scope and ordering come first, then filter/page semantics, then the routing sentence. Every sentence conveys a distinct behavioral fact with no filler.

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

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

An output schema exists, so return values needn't be described, and the description covers what remains: ordering, content omitted, filter exactness, pagination/consistency caveats, and alternatives for detail. An agent has enough to call this correctly and interpret page-to-page drift.

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 0%, so the description carries the burden, and it only partly delivers: it explains cursor binding and workspace comparison semantics ('recorded absolute path without filesystem resolution or case folding') and that 'optional filters are exact.' It adds nothing specific for limit, status, serviceId, or sessionId, so half the parameters remain undocumented in both schema and description.

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

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

States a specific verb and resource ('Read compact recent runs') plus ordering ('newest first by startedAt and runId') and the explicit exclusions (no prompts, assistant text, raw errors or history). It routes detail-seeking to get_run/get_run_summary, but never differentiates itself from the very similar sibling list_runs, leaving one ambiguity.

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?

Clear usage context: this is the lightweight discovery/listing tool, and the description names get_run and get_run_summary for detail. The 'compact ... without prompts, assistant text, raw errors or history' phrasing implies when this is preferable over a full fetch, but no explicit exclusion vs. list_runs or search tools is stated.

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

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

Annotations already provide the safety profile (readOnly, idempotent, non-destructive), so the description only needs to add extra behavioral context. It adds an origin detail ('restored from durable relay state') but does not explain what restoration means for the returned data or what behaviors to expect. There is 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?

The description is a single concise sentence with no filler. It loses a point because the 'Host' vs 'Harness' terminology inconsistency and the obscure 'durable relay state' phrase reduce clarity despite the brevity.

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 list tool with rich annotations, the description is close to sufficient, but it leaves the relationship between 'services', 'Host attachments', and 'durable relay state' unexplained. Without an output schema or return-value details, an agent may still be unsure what exactly will be listed.

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 coverage is 100%, so the baseline is 4. The description adds no parameter-specific meaning because there are no parameters to describe, and none are needed.

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

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

The description names a specific action and resource ('List Host attachments'), but the resource is ambiguous and inconsistent with the tool name ('list_services') and title ('List Harness attachments'). It is not a tautology, but the meaning of 'Host attachments restored from durable relay state' is vague for an agent deciding what this tool returns.

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 about when to use this tool versus alternatives like list_workspaces or list_capabilities. The description does not mention any conditions, exclusions, or sibling tools, leaving the agent to infer usage from the name 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 readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds genuine context about what is read (projection IDs plus original content) and that queued input differs from active execution, but says nothing about ordering, pagination, or empty-queue behavior. A 3 fits given the lighter 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?

Two tight sentences with the verb and resource front-loaded and no filler. It is dense, jargon-heavy ("session.projections Inbox next-turn and next-step IDs") but every clause carries 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 one-parameter read-only tool with annotations covering safety and no output schema, the description is nearly adequate. The remaining gaps are the undefined sessionId semantics and absent queue-ordering/empty-state behavior, which matter for correct interpretation of the returned list.

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 semantics of sessionId and it does not — no format, length, or origin hints. The single parameter is only inferable from its self-evident name, leaving the low-coverage gap unaddressed.

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

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

States a specific verb (Read) and a well-defined resource (session.projections Inbox), plus the exact payload it surfaces: next-turn and next-step IDs and original content. It is clearly a queue-listing operation rather than a queue-mutation one, though it never names the mutating siblings (remove_queue_item, clear_session_queue).

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?

"Queued input is distinct from active execution" implies the tool is for inspecting pending work rather than running or steering it, which gives usable context. However, there is no explicit when-to-use, no prerequisites, and no sibling (e.g. read_session_context, clear_session_queue) is named as the 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds no additional behavioral details beyond the fact that it lists something, and it does 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?

The description is a single concise sentence that leads with the action and resource, then adds the relevant routing context. It contains no redundant wording and 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?

This is a simple zero-parameter list operation with no nested objects, a well-defined output schema, and annotations that cover idempotence and safety. The description is sufficient for an agent to select and invoke the tool 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?

The input schema has zero parameters, so there is nothing to document. A baseline score of 4 is appropriate because the description cannot add parameter meaning that does not exist.

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 ('List'), a clear resource ('native Harness workspace registry'), and a context qualifier ('used by Relay routing'). It is clearly about listing workspaces, not workspace sessions or services, though it does not explicitly name a sibling for contrast.

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

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

The phrase 'used by Relay routing' gives some contextual hint about when this tool is relevant, but the description does not explicitly state when to prefer this tool over alternatives like list_workspace_sessions or list_services. The usage guidance is implied rather than explicit.

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 cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds genuine value by disclosing that the tool deliberately avoids reading conversation content, which is a meaningful behavioral boundary not present in annotations. No contradiction found.

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 tightly worded sentence front-loaded with the action verb. Every phrase earns its place: reusable, native, registered, and without reading conversation content each add a distinct qualifier with no 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 one-parameter, read-only list tool with a rich annotation set and an output schema, the description is largely sufficient. The minor gaps are the absence of ordering or pagination notes and no explicit alternative routing, but these are mitigated by the output schema and the simplicity of the tool.

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

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

Schema description coverage is 0%, so the description must compensate. It does add meaning beyond the bare string schema by specifying that the workspace parameter must reference a 'registered Harness workspace,' but it doesn't explain how to obtain or format the identifier. The compensation is partial.

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

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

The description names a specific verb (List), a precise resource (reusable native sessions), a scope (one registered Harness workspace), and a meaningful constraint (without reading conversation content). It is clearly distinct from sibling tools that list services, workspaces, runs, or capabilities.

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 'one registered Harness workspace' qualifier implies the precondition that the workspace must already be registered, and the 'without reading conversation content' phrasing hints at a non-content-oriented use case. However, no explicit when-to-use or when-not-to-use guidance is given, and no sibling alternatives are named, so routing relies on inference from resource names.

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?

It adds an observable external behavior beyond the structured hints: a browser session is opened in the OS default browser. It also communicates that this is user-visible, not a background/API-only action, and gives an explicit guardrail for when it should be invoked.

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 uses two short sentences with no filler: one sentence states the action and the other states the when-condition. Every clause contributes to correct tool invocation.

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, side-effect tool, this is nearly complete: the agent knows the behavior, the trigger condition, and the schema supplies the required runId. It misses only the parameter-level explanation, which prevents a perfect score.

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 that the required runId is the run whose Harness Web page should be opened. Although the parameter name and schema format communicate part of the meaning, the description itself adds no semantic value for the one parameter.

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 precise behavior: opening a native Harness Web session in the operating system default browser. It distinguishes this from run execution, status, or service tools by naming the exact launch mechanism and target.

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 sets an explicit trigger condition: only call when the user explicitly asks to open or show the Harness page. It does not name alternative sibling tools, but the gate is narrow enough for correct 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?

The annotations already indicate this is not read-only and operates in an open world, yet the description does not disclose what state change or external effect occurs when the page is opened. It adds no behavioral context beyond the basic action name, and there is no contradiction with the annotations.

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

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

The description is a single front-loaded sentence with no filler, redundant examples, or restatement of the schema. Every word contributes to identifying the target resource.

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 low-complexity tool with one parameter and annotations, this is minimally viable: it names the action, target, and precondition. Clear gaps remain—'Harness page', 'stable loopback', and 'attached' are domain terms not explained, and no sibling differentiation is provided.

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 provides only the type and UUID format for serviceId, so the description's 'attached service' wording supplies minimal semantic meaning: the ID must refer to an attached service. It does not explain how to resolve the ID or what happens for invalid service IDs, but for a single self-named parameter this is marginally adequate.

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 ('Open') and a specific resource ('the stable loopback Harness page') scoped to an attached service, making the tool's core function clear. It does not explicitly contrast with sibling open_run, but the service-vs-run target makes the distinction reasonably clear.

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

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

No guidance is given about when to use this tool over alternatives such as open_run, start_service, or list_services. The phrase 'attached service' implies a precondition but does not state it as a requirement or explain how to confirm attachment.

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 cover readOnly/idempotent/non-destructive/closed-world, but the description adds substantive context beyond them: checks are instructions that 'have NOT run,' the tool validates scopes and operator policy, and it 'never grants approval.' This is meaningful for a plan-only tool and is fully consistent with readOnlyHint=true.

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

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

Three tight sentences with the core read-only purpose front-loaded, followed by validation scope and the key negative guarantee. No filler; every clause adds a distinct fact.

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 a 12-parameter contract, the description adequately covers the tool's behavior and the meaning of the plan it builds. It stops short of describing the return shape or persistence of the plan/receipt, and says nothing about workspace, objective, or path-scoping inputs.

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% across 12 parameters, so the description carries the burden. It meaningfully maps seven of them (files, backupDirectory, preflightChecks, applySteps, verificationChecks, rollbackSteps, receiptPath) to their role in the plan, but leaves workspace, objective, writePaths, contextPaths and externalPaths unexplained.

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

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

States a specific verb (read-only preparation and validation) and resource (a bounded deployment plan), and enumerates the artifacts produced: source-to-target mappings, backup location, preflight/apply/verification/rollback steps, receipt path. It implicitly separates itself from start_deployment via 'Never executes or grants approval,' but never names the execution sibling, so differentiation is by negation rather than explicit routing.

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 'Read-only preparation' framing and 'Never executes or grants approval' imply this is the pre-execution step, so usage is inferable. However, there is no explicit when-to-use, no stated prerequisite (e.g., call before start_deployment), and no named alternative, leaving the agent to infer the position in the workflow.

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

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

Adds genuinely useful behavior beyond the annotations: the call returns durable operation/rpc IDs and a queue receipt, not execution completion, which frames it as an async accept/reject rather than a synchronous run. It also gives retry-safety guidance for the idempotencyKey. It does not explain what the destructiveHint=true mutation actually destroys or whether queueing displaces pending work, leaving one meaningful gap against a destructive, open-world annotation set.

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, front-loaded with the action and scope, then return semantics, then disambiguation and retry rule. No filler; the only thin spot is the unelaborated 'Distinct from steer_run' clause, which reads as a placeholder.

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

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

There is no output schema, so the description usefully covers return values, and it addresses the retry/uncertainty case that matters for a destructive, open-world, non-idempotent call. What it omits is the operational difference from steer_run and what happens when the referenced run is no longer active.

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 only 25%, and runId and content carry no schema description at all. The description partially compensates by explaining the idempotencyKey contract ('reuse the same idempotencyKey and never resubmit under another key') and implying content is a next-turn instruction, but it says nothing about runId or the accepted content shapes, so the low-coverage gap is only half filled.

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

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

The verb+resource+scope is specific: 'Append a next-turn instruction while the run is active,' and it names the sibling it is not ('Distinct from steer_run'). However, it asserts the difference without saying how queue_run differs from steer_run, so the disambiguation is labeled rather than explained.

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 a precondition ('while the run is active') and concrete disposition guidance for the failure case ('Query queue/history after an uncertain response; reuse the same idempotencyKey and never resubmit under another key'). It names steer_run as the alternative but never states the condition that selects one over the other, which keeps it short of a 5.

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

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

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses hard limits (64 KiB per read, 16 MiB per file), the return format (base64 bytes, range, file metadata), and security behavior (symlink and escape rejection, Linux descriptor-anchored access). These are exactly the operational details annotations cannot convey.

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

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

Four short sentences, each front-loading a distinct concern: scope, security rejection, return format with limits, and access mechanism. Dense but every sentence carries information; 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?

With no output schema, the description usefully specifies the return payload (base64 bytes, range, metadata) and the size ceilings, so an agent knows what it will get back and when a read will be truncated. It stops short of describing error behavior (e.g., what happens on a rejected symlink) or how path resolves against workspace.

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 0%, so the description must carry parameter meaning. It partially compensates: the 64 KiB per-read cap maps to maxBytes and 'range' hints at offsetBytes, while the 16 MiB file ceiling and base64 return format add real semantics. However, workspace and path are never explained (e.g., relativity, containment rules), leaving half the parameters undocumented.

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

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

The description states a specific verb and resource ('Read regular files') plus a clear scope ('only inside authorized configured/registered projects'), so the agent knows it reads file content rather than metadata or sessions. It does not, however, distinguish itself from close siblings like read_scoped_artifact or read_project_text, which an agent could easily confuse it with.

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

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

Scope is implied through constraints ('regular files only', 'no shell or broad host file read'), which tells the agent what this tool is not for. But there is no explicit when-to-use guidance or pointer to the alternative tools (read_scoped_artifact, read_project_text, list_project_files) for cases outside this narrow scope.

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 readOnly and idempotent annotations, the description discloses meaningful behavior: the projection is bounded and in-process, and cursor gaps produce explicit resynchronization metadata. This adds substantive context without contradicting 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?

A single dense sentence front-loads the action and resource, then adds the key behavioral nuance. Every clause contributes semantic value with no filler.

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

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

The output schema covers return shape, annotations cover safety, and the description explains the main cursor behavior. The only notable gap is the behavior when cursor is omitted, which is not addressed in the description or schema descriptions.

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 cursor meaning. It does so by explaining that reads happen 'after a cursor' and that gaps trigger resynchronization metadata. It does not explain initial-cursor omission behavior, but the single optional parameter is otherwise well contextualized.

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 ('Read') and a specific resource ('bounded in-process notification projection'), and clearly scopes the operation with cursor semantics. This distinguishes it from the unrelated sibling tools and from any generic 'list notifications' operation.

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 makes the usage context clear: read notifications after a cursor, with specific resynchronization behavior on cursor gaps. It does not explicitly enumerate when-not-to-use or alternatives, but no close sibling alternative exists among the provided 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?

Adds substantial behavior beyond the readOnly/idempotent annotations: security model (descriptor-anchored access rejecting symlinks, traversal, nonregular files, malformed UTF-8, NUL), explicit limits (16 MiB, 200 lines, 32 KiB text, 64 KiB serialized), default of first 100 lines, tail semantics, nextStartLine boundary behavior, and the no-content-returned-on-hash-mismatch contract. This is exactly the deep context annotations cannot carry.

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

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

Front-loads the core purpose before the security and limit details, with no filler sentences. It is dense and packs many facts per sentence, but nearly every clause carries operational weight; a minor readability cost from over-compression.

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 an output schema exists (so return shape needn't be restated), the description covers purpose, limits, security, hashing, pagination, and alternatives, and explicitly notes 'No cursor or state'. Nothing an agent needs to invoke it correctly is missing.

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

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

With 0% schema description coverage the description must compensate, and it does for most parameters: tail (final lines, cannot combine with startLine), lineCount (200-line cap, oversized tail fails), expectedSha256 (change detection), and startLine (range start via 'range reads'). workspace and path semantics are largely left implicit.

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

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

States a specific verb and resource ('Read numbered whole UTF-8 lines of one authorized configured/registered project file') and names the distinguishing sibling to use instead for other cases ('Use read_artifact for binary files'). An agent can differentiate this from list_project_files, search_project_text, and read_artifact without opening any schema.

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

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

Explicitly routes to read_artifact for binary or oversized lines and explains the tail-vs-startLine exclusion plus expectedSha256 usage for change detection. Clear context for when to call it, though it never names search_project_text as the alternative for content-based lookup.

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 readOnly, idempotent, non-destructive and closed-world. The description adds meaningful context beyond that: it revalidates current operator policy, refuses caller-supplied grant expansion, honors excludedPaths, and enforces 64 KiB/16 MiB limits with descriptor/symlink checks. It stops short of documenting error/auth-failure 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?

Two dense sentences with no filler, front-loading the scope and security behavior. Slightly cramped: limits and checks are named but not fully unpacked, which hurts more than it saves given the zero schema coverage.

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 4 undocumented parameters (two required), no output schema, and pagination-relevant fields like offsetBytes untouched, the description is incomplete for correct invocation. Behavioral/security coverage is good, but the parameter story an agent needs is largely 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 coverage is 0%, so the description must carry the burden. It maps loosely to maxBytes (64 KiB) but never explains runId, offsetBytes, or pagination semantics, and 'excludedPaths' is not even a parameter. Two of four parameters (including both required ones) receive no clarification.

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

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

States a specific verb (Read) and resource (regular project or declared external file) scoped to a persisted run context/write scope. This implicitly differentiates it from the sibling read_artifact, which the description references for shared limits, though it never explicitly contrasts the two.

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

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

The phrase 'within a persisted run context/write scope' implies when this tool applies rather than read_artifact, but there is no explicit when-to-use/when-not guidance or named alternative condition. The reference to read_artifact is about inherited limits, not routing between the two.

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

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

Goes well beyond the read-only/idempotent annotations: pagination semantics ('Direct native page seek; at most five pages of maxMessages 10'), content exclusions (plugin user context, reasoning, tools, media, empty text), truncation behavior, the subtle meaning of hasEarlier ('unscanned raw prefix, not necessarily eligible text'), and a prompt-injection warning that historical text is untrusted data.

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

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

Front-loaded with the action and result, and nearly every clause carries distinct information (scope, pagination, exclusions, return shape, security). It is dense and somewhat packed, but there is little genuine waste.

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

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

For a complex history-read tool it covers scope, ordering, pagination limits, exclusions, truncation, and the hasEarlier edge case, and an output schema exists so return values need not be fully re-explained. An agent has everything needed to call it correctly.

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

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

With 0% schema description coverage the description must carry the load, and it does: it ties anchorSeq/throughSeq to the search result and explains maxMessageChars as the per-message character cap. It is thinner on beforeMessages (only implied by 'at most ten nearest earlier messages') and omits workspace/sessionId, so not a full 5.

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

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

States a specific verb (Read) and a precisely scoped resource: the exact user/assistant text anchor from a search result plus the nearest earlier eligible text messages. The phrase 'native history anchor' and 'from a search result' clearly distinguish it from siblings like read_session_history and search_session_history.

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

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

Gives clear context: 'Supply the original anchorSeq and fixed throughSeq' ties invocation to a prior search result, and 'No later messages or whole conversation tree' bounds scope. It does not name an explicit alternative or state when-not to use it versus read_session_history, so it stops short of a 5.

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

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

Annotations already cover readOnly/idempotent/no-destruction, but the description adds real behavioral depth beyond them: backwards cursor pins the throughSeq cut, page stability across new events, restart survival, and an explicit 512 KiB error ceiling with a remediation hint. The only gap is that it doesn't describe the shape of the returned records.

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?

Five dense sentences with the core return/pagination behavior front-loaded and no filler. Some internal jargon ('throughSeq', 'Relay') assumes prior knowledge but does not waste space.

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, no-output-schema tool, the description covers return ordering, cursor mechanics, pagination stability, and the failure mode — enough for correct invocation. It stops short of explaining the sessionId parameter or record fields.

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 whole burden. It explains cursor semantics (backwards, pins throughSeq) and refers to maxMessages (reduce on overflow), partially compensating, but ignores sessionId entirely and never states maxMessages' default of 25 or cap of 50.

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

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

States a specific verb (Return) and resource (complete native event records in native order) and scopes it to 'registered Harness workspace sessions.' However, it never names or contrasts the obvious siblings it competes with — search_session_history and read_session_context — so an agent must infer the distinction between reading full history vs. searching or reading context.

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

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

There is no explicit when-to-use guidance. The reader must infer that this is for full sequential reading while search_session_history is for searching, and read_session_context is for context. No alternatives, exclusions, or triggering conditions are named.

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, and the description reinforces this by promising no duplicate request. It adds useful context by specifying reconciliation against 'durable Harness events', which tells the agent this is an event-based check rather than a live query.

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 14-word sentence that front-loads the verb and object, then packs the crucial side-effect guarantee at the end. There is no fluff, no repetition of the title, and 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 one-parameter, annotation-rich tool, the description covers the core purpose, the source of truth, and the safety guarantee. It does not describe the return value or how to interpret the comparison result, and no output schema exists to fill that gap, so a small completeness gap remains.

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 single parameter operationId is not described in the schema (0% coverage), and the description only refers to 'an uncertain operation' without explicitly mapping it to the required parameter. It adds the qualitative notion of uncertainty, but leaves the parameter semantics largely implicit.

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 opens with a specific verb 'Compare' and identifies the resource ('uncertain operation') and the reference data ('durable Harness events'). The phrase 'without submitting a duplicate request' distinguishes it from retry or creation tools, and it is clearly differentiated from siblings like get_operation.

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

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

The phrase 'uncertain operation' signals the intended use case: when an operation's outcome is ambiguous and the agent needs to verify against durable events. It does not explicitly name alternatives such as get_operation or status_run, nor does it state when not to use it, so some inference remains.

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

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

Annotations already provide idempotentHint=true, destructiveHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds the useful fact that it restores the previous native preset rather than setting arbitrary permissions, but it does not disclose side effects such as overwriting current custom permissions or any 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 sentence with the key action and object front-loaded, and it avoids repeating the title verbatim. 'That requires attention' is somewhat vague but does not add significant bloat.

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, idempotent restoration tool, the description plus annotations give a minimally workable picture. However, with no output schema, it does not say what a successful restoration returns, what signals that attention is required, or what state the session should be in before calling this tool.

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

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

Schema description coverage is 0% and the description never explains sessionId, where to get it, or how it relates to the restore operation. The tool mentions 'session' generally, which weakly implies the parameter identifies the affected session, but the description does not compensate for the schema's lack of parameter 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 uses a specific verb ('Retry restoration') and a specific resource ('previous native permission preset for a session'), making the tool's action clear. It does not explicitly differentiate from siblings like reconcile_operation or setup_doctor, but the permission-restoration purpose is identifiable.

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

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

The phrase 'for a session that requires attention' implies this is a corrective or retry operation, but it never explicitly states when to use it versus alternatives such as reconcile_operation or setup_doctor. There is no when-not-to-use guidance or mention of 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?

Annotations already declare destructive=true and idempotent=true, so the description's real value is qualifying that destruction: it removes only the pending occurrence, does not delete history, and does not stop an active turn, and confirms the absent-case no-op. It omits any permission/auth detail despite the 'Membership-aware' label.

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

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

Three tight sentences, front-loaded with the core action followed by two scoping clarifications. Every sentence adds information; no filler.

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

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

For a low-complexity single-item removal with rich annotations and no output schema, the description covers the essential behavioral envelope (idempotency, blast radius). The gaps are the undocumented parameters and the unexplained 'Membership-aware' precondition.

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 both parameters. It only gestures at 'by ID', which loosely maps to itemId, and says nothing about sessionId or how the two combine, leaving a required identifier undocumented.

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

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

States a specific verb and resource ('removal of one pending occurrence by ID') and the title pins the target as one native Inbox item. It implies scope vs clear_session_queue via 'one pending occurrence', but never names a sibling to sharpen the 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?

Usage is only implied by the tool name and the 'one ... occurrence' scope. There is no explicit when-to-use statement and no routing to alternatives like clear_session_queue (bulk) or steer_queue_item, leaving the agent to infer the boundary.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true and idempotentHint=false, so the safety bar is lower. The description earns credit for disclosing two things annotations cannot: the session must be completed, and content read by the selected Harness model may be sent to an external model provider despite Relay's loopback address.

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 purpose sentence is well front-loaded, but well over half the description duplicates the task parameter text from the schema, which is redundant in a description. Every sentence about scope is load-bearing for the task field, yet presenting it here repeats structured data rather than adding value.

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 16-parameter mutation tool with no output schema, the description covers the task-construction semantics well, yet omits the required runId, the danger-confirmation flow (confirmedDangerousPermission) and permissionPreset inheritance. Since there is no output schema, the description could at least sketch what is returned, but an agent can still call the tool from what is given.

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 69%, and the bulk of the description is a near-verbatim copy of the task/content schema description, so it adds little beyond what the schema already states. It does enumerate the scope fields expected inside the task string, but parameters like idempotencyKey, model, provider, reasoningEffort, permissionPreset and confirmedDangerousPermission are untouched.

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 gives a specific verb, resource and scope: submit a new queued turn to the completed run session, optionally with a different model, tracked as a new run. This distinguishes it from siblings like start_run and queue_run by anchoring on an existing completed session, but it never names those 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?

There is no explicit when-to-use guidance and no routing against siblings such as queue_run, steer_run, or retry_run_with_fallback. The closest thing to a condition is 'completed run session,' which is implied pre-state rather than usage instruction.

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 say this is a non-idempotent, destructive, open-world write. The description adds substantive behavior: stale, duplicate, cross-run and cross-client replies are rejected; permission presets and permanent access are unaffected; write-vs-cancel outcomes are bounded. This is exactly the extra context the annotations cannot carry.

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

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

Front-loaded with the core action, then layered constraints in short declarative sentences with no filler. Slightly telegraphic and dense in the middle, but every sentence carries a distinct constraint that an agent needs.

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 three-parameter mutation with no output schema and 0% schema coverage, the description supplies authorization boundaries, rejection cases, and post-call continuation guidance. The remaining gap is that it never explains what runId must be or what the tool returns, minor given no output schema exists.

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 clarifies requestId semantics (must be a live id from list_run_interactions, exactly one) and the intent behind the response payload (approve-once, reject, ask the user), but says nothing about runId's role or the response oneOf discriminator shape, so the coverage is good rather than complete.

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

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

States a specific verb and resource ('Resolve exactly one live requestId') and immediately anchors the resource to a sibling tool (list_run_interactions), so the agent can distinguish it from reply_run, steer_run, or cancel_run 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?

Explicitly describes the decision procedure: grant allowed-once only within an already authorized task or after explicit user approval, otherwise reject or ask the user, never infer authority from child prompts. It also names the follow-up action (continue wait_run) and the alternatives it cannot handle (Windows UAC, policy=never), which is when-to-use guidance at the highest level.

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

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

Goes well beyond the annotations by disclosing the default-disabled gate, the one-shot semantics, the exact idempotency key (quota-fallback:<originalRunId>) that explains the idempotentHint, permission inheritance, and the 'never silently changes a model' guarantee. Refusal conditions are spelled out, which the schema and annotations cannot convey.

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

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

Three dense sentences, with the most important constraint ('Opt-in only; disabled by default') front-loaded. Every clause carries information, though the model-name strings and compound conditions make it heavy 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?

Given a high-risk, quirk-heavy mutation tool with one param and no output schema, the description covers gating, refusals, idempotency, and permissions well. It does not say what the caller receives back or what happens to the original failed run, which is the main remaining 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?

One parameter with 0% schema description coverage, so the description must carry the load. It implies runId is the original (failed) run's identifier via 'quota-fallback:<originalRunId>,' but never states the parameter relationship explicitly or the ID format expectations beyond what already exists in the schema.

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

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

States a specific verb+resource+scope: retry a quota-rejected zai/glm-5.3-flash pure-text run once with a specific fallback model. This is clearly distinguishable from siblings like start_run, cancel_run, or status_run, which do not describe a quota-fallback retry 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?

Explicitly states when it applies (quota-rejected GLM pure-text run), when it does not ('Unknown, truncated, timeout or ambiguous outcomes are refused'), and that it is 'Opt-in only; disabled by default.' Preconditions are fully enumerated rather than left to inference.

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

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

Annotations already declare read-only/idempotent/non-destructive, and the description adds substantial context beyond them: symlink/special-file skipping, default exclusion directories, encoding rules (strict UTF-8, BOM, LF/CRLF/lone CR), concrete scan caps, truncation semantics, and the critical caveat that scanComplete=false means zero matches do not establish absence. It also warns that source text/names are untrusted data, not instructions.

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?

Core purpose is front-loaded and the dense prose is largely information-bearing rather than filler. However, it is delivered as a single very long block covering caps, encoding, counting, and caveats, which is heavier than ideal even for a complex tool.

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 an output schema exists, the description needn't explain return shape, yet it still clarifies the meaning of scanComplete, matchedLines/matchedFiles as lower bounds, and separate skip categories. For a tool with hard scan caps and partial-result semantics, the agent has enough to interpret results 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?

With 0% schema coverage the description must carry the burden, and it explains query semantics (case-insensitive iu default vs case-sensitive u, no normalization), path (may explicitly select an otherwise-excluded directory as root), maxDepth 0 (direct files only), maxResults (lexical DFS selection, increase to refine), includeHidden, and caseSensitive. It omits any explanation of the required 'workspace' parameter, leaving one of seven undocumented.

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?

Opens with a precise verb+resource+scope: 'Read-only literal single-line search inside one authorized project directory.' It clearly distinguishes itself from read_project_text (named as the expansion path) and from list_project_files. An agent can identify this as the literal-text search tool without opening the schema.

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

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

Provides refinement guidance ('Narrow path/query or increase maxResults to refine') and routes to the sibling for expansion (read_project_text with expectedSha256). It also declares what the tool is not ('No cursor, regex language, subprocess or index'), effectively excluding regex use cases. It stops short of an explicit when-to-use-this-vs-alternative routing statement, so a 4.

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 cover read-only/idempotent/non-destructive safety, and the description adds substantial behavior beyond them: one match per native message, a 600-character excerpt cap, session-lexical ordering with no global recency, a per-call read bound (scanPages pages of maxMessages 10), scanComplete=false indicating incomplete results, and restart-stable cursor membership pinning. The untrusted-data warning ('never instructions') is a genuinely useful prompt-injection caveat that no annotation conveys.

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

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

Purpose is front-loaded in the first sentence and almost every sentence carries new informational content (exclusions, caps, ordering, incompleteness, cursor). Some clauses are dense jargon ('active session cut is pinned and unvisited sessions capture a cut on first visit') that costs more in parse effort than it returns, but there is 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?

An output schema exists, so return-shape explanation is unnecessary, and the description instead covers the tricky parts: bounded scanning, incomplete-result detection, cursor stability, and ordering. What is left out is parameter-level detail (limit bounds, caseSensitive, role semantics) for a tool with eight undocumented parameters, which keeps it short of fully 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%, so the description carries the full parameter burden, and it partially does: it clarifies that 'query' is literal (not regex), that 'workspace' selects exactly one workspace, and it explains cursor and scanPages behavior in depth. However, 'limit', 'caseSensitive', 'role', and 'sessionId' are never addressed, and the default-10/max-25 limit is not restated. Given the 0% coverage baseline, the partial compensation lands at 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 first sentence gives a specific verb and resource ('bounded literal keyword search of user task and assistant result text') and immediately scopes it to 'one registered workspace', which an agent can act on. It is clear and distinctive, but it never names or contrasts with the obvious siblings (read_session_history, read_session_context, search_project_text), so the agent must infer the boundary itself.

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

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

Usage is implied by scope statements ('Excludes plugin user context, reasoning, tools and media', 'Membership changes require a fresh search') rather than explicit when-to-use guidance. No alternative tool is named and no condition for choosing this over read_session_history is given. Adequate to avoid misuse, but the routing burden stays on the agent.

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, idempotentHint=true, and destructiveHint=false. The description adds a useful behavioral guarantee: it does not read or modify client configuration. It also clarifies the operational mode, 'from explicitly supplied probes', and the output style, 'machine-readable setup report', providing context beyond 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?

The description is a single, tightly written sentence that fronts the core purpose and the highest-value constraint upfront. Every word earns its place; there is no fluff or repetition 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 is a complex tool with ten parameters, seven required, and a nested facts object, yet the description gives no guidance on how to assemble or interpret those parameters. Even though output schema and annotations exist, an agent would likely struggle to call this tool correctly without understanding what 'probes' are and how the required strings relate to the diagnostic process.

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 of explaining parameters, but it only alludes to 'explicitly supplied probes' without detailing any of the ten parameters. It does not explain what 'facts' means, how the booleans should be set, or what values like relayEntry or endpointDescriptor represent, leaving the agent to infer entirely from names and enums.

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 precise verb ('Return'), a concrete resource ('a machine-readable setup report'), and a distinctive scope condition ('from explicitly supplied probes without reading or modifying client configuration'). This clearly differentiates it from sibling diagnostic or planning tools like doctor or setup_plan by emphasizing that no client configuration is read or changed.

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

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

The description implies when to use the tool: when a non-invasive, probe-based setup report is needed and no configuration access is desired. However, it does not explicitly name an alternative, state when NOT to use this tool, or explain how it contrasts with sibling tools such as setup_plan or doctor.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds 'no-write' and 'validated,' which are consistent with the annotations but do not provide rich behavioral detail such as how validation works or what the patch 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, tightly written sentence with no filler. It front-loads the core action and deliverable while naming the supported targets, making it easy to scan.

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 9 parameters, 7 required, 0% schema documentation, and many sibling tools, the description is too minimal. It explains what the tool produces but not where it fits in a setup workflow, what inputs are needed, or how to use it correctly.

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

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

Schema description coverage is 0% while there are 9 parameters, including 7 required ones. The description does not explain any parameter meaning, relationships, or expected values, so an agent cannot infer how to fill in fields like endpointDescriptor, relayEntry, or scope.

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 ('Generate'), a specific deliverable ('validated, no-write MCP configuration patch'), and the target clients (Codex, Claude Code, Cursor, OpenCode V2). This clearly distinguishes setup_plan from the sibling setup_doctor and other operational tools.

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

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

The description implies this tool is for planning a client setup without applying changes, but it gives no explicit when-to-use guidance, prerequisites, or alternatives. With sibling tools like setup_doctor and doctor present, an agent is not told how to choose between them.

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 destructive/openWorld/non-idempotent, but the description adds real context: rollback on definite failure, a JSON receipt, preservation of unknown operation IDs, and an explicit authorization requirement. This meaningfully exceeds what the annotations convey, though return/pagination details are only lightly covered.

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 dense paragraph that front-loads the core action before the caveats. Every sentence is doing work, though the phrasing is quite packed and would benefit from light 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?

For a 20-param destructive tool with no output schema, the description explains the execution/rollback flow and the receipt-based verification path, which is helpful. But it leaves most of the parameter surface unexplained, so it is only partially 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?

With 20 parameters and only 5% schema description coverage, the description carries the burden but does not compensate. It loosely gestures at backups, mapped files, and listed operations but gives no guidance on required fields like authorizationBasis, idempotencyKey, or the externalPaths/writePaths semantics.

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

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

States a specific verb and resource: 'Execute the complete deployment manifest through the EXISTING Harness native agent,' with scope (backups, files, service/remote ops, verification, rollback). It implicitly separates itself from preparation tools via 'Preparation is not proof of deployment,' though it doesn't name plan_deployment directly.

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

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

Gives a precondition ('Require task-specific user authorization') and follow-up guidance ('keep wait_run to terminal and independently read the receipt'), plus a caution ('never blindly replay'). However, it never explicitly states when to prefer this over plan_deployment or other alternatives, so usage is implied rather than spelled out.

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 annotations present the bar is disclosure beyond structure, and this description delivers: it warns that scope fields are 'task instructions, not enforced per-path filesystem isolation,' that read content may be sent to an external model provider even though Relay uses loopback, that the calling agent MUST read assistantText before claiming completion, and that still-running reviews must not be treated as finished. These are non-obvious operational facts an agent could not get from readOnlyHint/openWorldHint alone.

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 first sentence front-loads the purpose well, but the body is long and partly redundant with the input schema (the same path-reference paragraph is repeated verbatim in three schema fields). Sentences such as the authorization re-prompting note are load-bearing but buried mid-paragraph, diluting scannability.

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, 17-parameter tool with no output schema, the description covers the full lifecycle an agent must handle: required inputs, what the scope fields mean, data-egress implications, the post-start wait_run loop, the terminal states, and the assistantText verification step. Nothing essential for correct invocation and follow-through is missing.

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

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

Schema coverage is 71%, and the description adds genuine meaning for the critical required fields (provider/model/authorizationBasis exist so the named-model request is machine-identifiable and the approval can identify the processing destination), which the schema only partially conveys. Several parameters (sessionId, agentPreset, sessionMode, reasoningEffort, idempotencyKey) remain undocumented in both description and schema, so it does not fully close the 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 states a specific verb and resource with scope: 'Create or reuse a native Harness session with the permission preset fixed to read-only.' Combined with the review-focused parameters (reviewTargets, contextReadScope) the agent can tell this apart from start_run/start_deployment, though the description never explicitly contrasts itself with those 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?

It gives real routing and workflow guidance: required provider/model/authorizationBasis, the instruction not to re-ask the user for authorization, and an explicit post-start sequence ('share webUrl and keep wait_run until succeeded/failed/cancelled/needs_attention'). It also covers the review-then-fix case. It stops short of naming alternatives like start_run or validate_task_scope as the thing to use instead when the task is not a review.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true and readOnlyHint=false, but the description adds real behavioral context the annotations cannot: the scope fields are 'task instructions, not enforced per-path filesystem isolation,' and read content may be sent to the configured model provider even though Relay uses a loopback address. It also notes the returned session link is stable and that a terminal status (not webUrl) marks completion. It stops short of describing dispatch timing/blocking behavior or reuse semantics for an existing sessionId.

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 core action is front-loaded in the first sentence and the cautionary sentences are dense with operative constraints rather than filler. It loses a point because roughly half the description is a verbatim duplicate of the 'task' parameter's schema description, so an agent reading both is told the same thing twice.

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 19 parameters, no output schema, and destructive/open-world annotations, the description covers what an agent most needs: what it returns (stable session link), how completion is judged (wait_run to terminal, then assistantText), the non-enforcement of scoping, and the data-egress caveat. It leaves gaps around session reuse behavior and the interaction between externalPaths, permissionPreset, and operator policy.

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 63%, and the description meaningfully disambiguates the scope parameters beyond their schema text: reviewTargets 'identify what to assess; they are not a read whitelist' while contextReadScope 'declares where Harness may search and read,' and writeScope must be empty for read-only runs. It adds no semantics for model, provider, reasoningEffort, agentPreset, sessionMode, idempotencyKey, or content, though several of those carry their own in-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 first sentence states a specific verb and resource chain — create/reuse a Harness session, select provider/model/reasoning/presets, submit the first task, return a session link — which is far more specific than the terse title 'Dispatch a Harness run'. It does not explicitly distinguish itself from siblings like queue_run, start_review, or steer_run, so an agent must infer the boundary from the queue/review naming alone.

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 one genuinely useful routing instruction: 'Sharing webUrl is not completion: keep wait_run until a terminal status, then consume assistantText,' which names a sibling and the follow-up condition. However, it never says when to choose start_run over queue_run or steer_run, nor when sessionMode/sessionId reuse is appropriate, leaving the primary selection decision implied.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, covering non-destructive behavior. The description adds the 'never starts or modifies Harness' clarification, which reinforces but does not significantly extend those hints. 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?

Two sentences, front-loaded with the primary action and a clear exclusion. Every sentence 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 simple two-parameter tool with no output schema, the description captures core behavior and notes the prerequisite 'authorized workspace'. However, it does not mention return values, error conditions, or the impact of openBrowser beyond the schema description, leaving some operational gaps.

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

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

Schema description coverage is 50%: openBrowser has a description, but workspace does not. The tool description does not add any parameter-level detail (e.g., what constitutes a valid workspace identity). It fails to compensate for the missing workspace 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 uses a specific verb ('attach') and resource ('authorized workspace to the existing Harness Host'), and explicitly clarifies it does not start or modify Harness. This distinguishes it from siblings like start_run and start_review without ambiguity.

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 (to attach an authorized workspace to an existing host) and clarifies what it does not do (never starts or modifies Harness), but does not explicitly name alternative tools or provide conditions for choosing among related siblings. It relies on inference.

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

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

Annotations already declare readOnlyHint and idempotentHint true, and the description adds meaningful behavioral context by disclosing deprecation and the removal schedule. As a compatibility alias, failing to describe output details is acceptable since expected behavior is get_run's 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 three short clauses with no wasted words; the deprecation and replacement are front-loaded. It earns every word it uses.

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 deprecated one-parameter read-only alias, the description provides essential routing and lifecycle information, and the schema fully constrains runId. It is adequate for an agent to invoke correctly, though output shape is left to get_run.

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 description provides no parameter information, and schema description coverage is 0%. The single runId parameter is well-constrained by the schema's UUID format and pattern, reducing risk, but the description fails to compensate for the lack of schema descriptions as required at low 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 title clearly identifies the tool as 'get Harness run status' and the description explains it is a deprecated compatibility alias, so the action and resource are clear. It does not restate the behavior fully, but it differentiates itself from get_run by pointing to it as the replacement.

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 instructs 'use get_run' and warns 'Scheduled for removal in 0.3.0', giving the agent a clear directive to choose the alternative over this deprecated tool. This is a precise when-not-to-use instruction.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds genuine value beyond that: the in-process receipt guard prevents duplicate steering but is explicitly NOT a durable transaction log, and the Harness-acceptance precondition matters for a destructive mutation.

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, front-loaded with the core purpose before the cautionary notes, with little filler. The phrasing is somewhat jargon-heavy and clipped, but nothing is redundant.

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

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

For a destructive, non-idempotent mutation with no output schema, the description covers behavior (duplicate guard, non-durability, Harness precondition) reasonably well. But it leaves the parameters opaque and says nothing about the result of steering, leaving a real gap for correct invocation.

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

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

Schema description coverage is 0% and both parameters (sessionId, itemId) are undocumented in the schema, yet the description never explains what itemId/sessionId are, their format, or where to obtain the item to steer. For a 2-parameter tool with zero schema coverage, 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 verb and object: moving a pending next-turn occurrence into current-turn steering via native updateQueue, explicitly contrasted with 'queued execution' (cf. queue_run). The jargon ('next-turn occurrence', 'native updateQueue') is dense, but a concrete action is named and sibling differentiation is present.

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

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

It gives a precondition ('Native Harness must still accept steering') and cautionary guidance to inspect history/queue rather than blindly replay, implicitly pointing at read_session_history/list_session_queue. However, there is no explicit when-to-use-vs-when-not or named alternative for the steering action itself, so usage is only implied.

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

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

The description adds substantial behavioral detail beyond the annotations: task parameters are path-reference-only, no source text may be embedded, Harness reads named files itself, fields are not enforced filesystem isolation, and the model may send read content to its configured provider despite Relay's loopback address. These are meaningful privacy and execution-model disclosures that a caller needs.

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 front-loaded with the essential purpose and then provides dense, valuable warnings. Each sentence adds a distinct constraint or behavioral fact; the only redundancy is that the same text appears verbatim in the schema's parameter descriptions, but the tool description itself is not padded.

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

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

For a destructive, non-idempotent mutation on an active run, the description covers the critical safety and privacy aspects, including what must not be included in the payload and how Harness accesses files. It does not explain the return value or success/error behavior, but with no output schema and a clear purpose this is a minor gap.

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

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

Schema coverage is only 50%: runId and idempotencyKey have no schema descriptions, and the tool description does not compensate for those. However, the description does clarify the task/content parameter semantics thoroughly, explaining path-reference usage, reviewTargets, contextReadScope, and the prohibition on embedding source material, so it partially makes up for the gaps.

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 clause, 'Durably insert a correction into an active run,' uses a specific verb, resource, and state ('active run'), which clearly distinguishes it from siblings like start_run, reply_run, and cancel_run. It also names the core operation type ('correction') rather than merely restating the tool's name.

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: it is for inserting a correction into an already active run, which implies it should not be used for starting, stopping, or merely observing runs. It does not explicitly name alternatives or exclusion conditions, so it misses the top score, but the context is 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?

Annotations already cover idempotency, non-readonly, and non-destructive intent. The description adds value beyond this by scoping the mutation precisely: exactly one relay attachment is affected, and the external Harness Host's state is preserved. This boundary disclosure is genuinely useful, though it stops short of describing the observable post-forget state.

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 12-word sentence with zero waste: the action verb leads, followed by scope and the key exclusion. Every word earns its place and the critical 'does not stop the host' clarification is included without bloat.

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 is low-complexity (one parameter, no output schema), so the description covers the core semantics adequately. However, domain terms like 'relay attachment' and 'Harness Host' are unexplained, and the lifecycle relationship to siblings (how attachments are created via start_service/open_service) is missing, which could leave an agent unsure of prerequisites.

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 must compensate for the single serviceId parameter. It partially does by tying the operation to 'one relay attachment,' implying serviceId selects the attachment. However, it never explicitly states that serviceId identifies which relay attachment to forget, leaving some ambiguity given the tool name says 'service' while the description says 'attachment.'

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 ('forget') and resource ('one relay attachment') and adds a clarifying boundary ('without stopping or changing the external Harness Host'), which usefully corrects the misleading 'stop_service' name. It implicitly distinguishes itself from stop-like operations, though it does not explicitly name a sibling to differentiate from.

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

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

Usage is implied: use this when you want to detach/forget a single relay attachment while leaving the host untouched. However, no explicit when-to-use or when-not-to-use guidance is given, and no alternative tools are named (e.g., what to use if you actually need to stop the host or cancel an ongoing run).

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered structurally. The description's 'creates no run' and 'does not execute checks' largely restate that read-only profile; it adds little new behavioral context such as whether validation failures throw, what permissions the caller needs, or how policy conflicts are surfaced.

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

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

Two tight sentences with the validation scope front-loaded and the non-mutating guarantee immediately after. No filler; the only weakness is that brevity here trades away the parameter detail the low schema coverage requires.

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?

Annotations cover safety and idempotency, but with no output schema the description should explain what a validation run yields (pass/fail, policy violations, exit semantics). For a 7-parameter tool centered on path policy and admission, the description leaves the result contract and most inputs unaddressed.

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 very low at 14%, so the description carries the burden and does not meet it. It gestures at 'declared external paths' and 'configured path policy,' loosely mapping to externalPaths/writeScope, but says nothing about workspace, reviewTargets, contextReadScope, excludedPaths, or permissionPreset, leaving most of the 7 parameters unexplained.

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

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

States a specific verb (validate) applied to concrete resources (project admission, declared external paths, path policy), and the title adds the distinct framing 'preflight a task file scope without dispatch.' That separates it from run-dispatch siblings like start_run and queue_run, though no sibling is named explicitly in the description.

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

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

The phrase 'Does not execute task checks or commands and creates no run' implies a preflight/dry-run positioning, which hints that this should be called before dispatch. However, there is no explicit when-to-use statement, no stated prerequisites, and no named alternative (e.g., 'call this before start_run'), so usage must be inferred.

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 readOnly/idempotent annotations, the description reveals that a timeout is only a slice not completion, that the caller must re-invoke wait_run when hostMustCallWaitRunAgain is true, and that unrelated notifications do not authorize stopping. This is exactly the kind of behavioral context annotations cannot express.

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 a distinct requirement or correction, from avoiding temporary poll clients to the prohibition on final answers during a running job. The key purpose is front-loaded, and the length is justified by the number of critical behavioral rules.

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 polling protocol, return payload headline, and termination conditions well enough to call the tool correctly. It doesn's specify snapshot fields or hostPollContract structure, but no output schema is declared and the contract field is named, which is sufficient for a wait/loop 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 schema has no descriptions for runId or timeoutMs, so the description must compensate. It adds meaning to timeoutMs ('at most 30 seconds', 'timeout is a slice'), but says nothing about runId beyond the schema us type/format, leaving an agent to infer it identifies the run.

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 specific verb ('Poll') and resource ('durable Host history'), and names the deliverable ('latest snapshot plus hostPollContract'). This clearly differentiates wait_run from siblings like get_run or status_run, which are single-shot reads without a polling contract.

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 instructs agents to call this native MCP tool directly rather than writing temporary poll clients, and it gives concrete loop rules: if hostMustCallWaitRunAgain is true, call again immediately, and do not finalize while the run is active. It doesn't name sibling alternatives, but the polling context and stop conditions provide enough usage guidance.

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