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

No annotations are provided, so the description carries the full behavioral burden. It implies a read-only discovery operation but never states it is safe/read-only, nor does it mention required runtime state or error conditions. It does enumerate the response contents, partially compensating for the missing output schema.

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 led by the verb, with the resource list following. It is long and list-heavy but each item conveys a distinct returned artifact, so little is 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?

With a zero-parameter schema and no output schema, the description does the work of describing what the call returns, which is exactly what an agent needs to decide whether to call it. It lacks only explicit safety/prerequisite notes.

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 disambiguate; baseline 4 applies. No parameter meaning is required beyond the empty 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 ('Discover') and a concrete set of resources (agent runtime, session, harnesses, logical agents, IDs, lifecycle states). It is clearly an introspection tool, distinguishing it from siblings like agent_get or capabilities, though the dense enumeration of return contents blurs focus slightly.

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

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

No guidance on when to use this versus the sibling capabilities or agent_get tools, and no prerequisites stated. The agent is left to infer that this is the broad runtime-inventory call.

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

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

No annotations are provided, so the description carries the full burden. It discloses returned content (lifecycle state, detected interactions) and disambiguates the requiresDecision field's semantics, but says nothing about whether this is a read-only operation, side effects, or permissions required.

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

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

Two compact sentences, front-loaded with the core action and followed by a targeted clarification of requiresDecision. No filler, though the second sentence is dense.

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

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

With no output schema and no annotations, the description does reasonable work by naming the returned fields and explaining the requiresDecision semantics. It is adequate for a single-parameter read tool, though it could note the read-only nature.

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?

Only one parameter (agentId) with 100% schema description coverage, so the schema already documents the ID format and its origin from agent_start. The description adds no parameter detail beyond that. Baseline 3 is appropriate.

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

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

States a specific verb (Inspect) and resource (one MCP-managed Herdr agent) plus the scope of what is returned (lifecycle state, detected interactions). It is clearly distinguishable from siblings like agent_read or agent_capabilities, though it does not explicitly name them.

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

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

The description clarifies that requiresDecision obligates the caller to apply its delegation policy, which is genuinely useful context, but it never states when to call agent_get versus agent_read or agent_capabilities. 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?

With no annotations, the description carries the full behavioral burden and does meaningfully disclose side-effect semantics: preflight/pre-spawn rejection produces no submission, while timeout/cancellation after 'Herdr starts' may leave the task submitted and is unsafe to auto-retry. That non-idempotency warning is high-value for a mutation tool, though auth requirements, blocking/wait behavior, and agent state changes are unaddressed.

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, front-loaded sentences with no filler: purpose first, then the failure/retry semantics. The unexplained term 'Herdr' is the only blemish; otherwise it is efficient.

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

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

For a 6-parameter tool with no annotations and no output schema, the description covers the risk profile well but omits the operational core — what wait/until/timeoutMs actually do to the call — and returns nothing about outcomes. Adequate on safety, thin on mechanics.

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 17% (agentId alone is documented), so the description must compensate for task, wait, until, skills, and timeoutMs. It adds nothing about these parameters — notably the until enum values (idle/working/blocked/done/unknown) and the wait/timeout interaction are left entirely to the agent's inference.

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

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

States a specific verb and resource ('Submit a task to an MCP-managed coding agent'), which an agent can distinguish from agent_send_keys, agent_start, and process_write without opening a schema. It does not explicitly name a sibling for contrast, so it falls short of a 5.

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

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

'After a positive readiness check' implies a precondition (presumably agent_start/agent_get first), and the retry caveat tells the agent when not to re-invoke. However, no alternative tool is named and the readiness-check prerequisite is never spelled out, leaving usage largely 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It implies a bounded read operation but omits permissions, side effects, blocking behavior, error modes, and what 'bounded' means beyond the lines parameter.

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

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

Two short sentences, front-loaded with the core action and followed by a targeted usage hint. Every phrase adds value without 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 3-parameter read tool with no annotations and no output schema, the description leaves important context unstated. It does not explain the meaning of 'lines,' the available source modes, or expected return shape, making it incomplete for reliable 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 only 33%, and the description only clarifies one enum value, 'recent-unwrapped.' It does not explain the other source modes, how 'lines' bounds output, or the default source behavior, so it only partially compensates for the schema 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?

States a specific verb and resource: reading a bounded terminal transcript from an MCP-managed Herdr agent. It is clear what the tool does, though it does not explicitly contrast itself with siblings such as read_file, process_read, or agent_get.

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?

Offers one source-mode hint, 'Use recent-unwrapped for orchestration-oriented text inspection,' but gives no guidance on when to choose this tool over sibling transcript/read tools. No when-not conditions or alternatives 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?

With no annotations, the description carries the full burden and does disclose a meaningful side effect — creating a fresh Herdr workspace — plus the need for a 'verified native session/conversation ID' and an explicit failure mode. It stops short of covering auth/permission requirements or the lifecycle of the newly created workspace, so it is strong but not exhaustive.

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 with the core action front-loaded, followed by the alternative-usage clause and the failure note. Nothing is redundant, though the 'verified native session/conversation ID' phrasing is slightly dense and could be tightened.

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

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

For a single-parameter tool with no annotations and no output schema, the description covers purpose, alternative routing, side effect (new workspace) and failure behavior, which is sufficient for correct invocation. Only peripheral details like permissions or whether the workspace persists are left 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?

There is a single parameter (agentId) with 100% schema description coverage, so the schema already documents it as the MCP-managed ID returned by agent_start. The description references a native session ID but that is an internal mechanism, not the parameter, so it adds little beyond the schema baseline.

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

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

States a specific verb (resume) and resource (suspended logical coding-agent session) and explains the mechanism (fresh Herdr workspace + harness launch with native session ID). It also distinguishes itself from the sibling agent_start by contrasting continuation of an existing conversation with starting fresh work.

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

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

Explicitly says to use this to continue the same conversation and to 'start a new agent for independent work' otherwise, giving a clear alternative and selection condition. It also reports the failure condition (native resume unavailable), which sets expectations before invocation.

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

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

No annotations are provided, so the description carries the full burden. It discloses the authorization model (orchestrator pre-approval, runtime does not grant approval or decide escalation) and constrains the key set to bounded control/navigation keys. It does not state rate limits, whether keys can be lost, or what is returned, but the policy context is unusually rich.

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

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

Three sentences, all carrying load: the action and its authorization precondition first, then the runtime's non-decision, then the redirect to the sibling. No filler, though the middle sentence is dense enough to read as policy boilerplate.

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 2-parameter mutation tool with no annotations and no output schema, the description supplies the missing safety and routing context. It omits any statement about effects on the terminal or return behavior, but the authorization framing covers the highest-risk unknowns.

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 50%: agentId is documented in-schema as the ID returned by agent_start, while keys has no schema description. The description compensates by describing the keys parameter as bounded control/navigation keys, which explains the enum's intent. It adds meaning beyond the raw enum list without repeating 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 (send), specific resource (bounded control/navigation keys) and the target (an MCP-managed agent terminal). It explicitly distinguishes itself from the sibling agent_prompt by routing arbitrary text there. An agent can tell the two apart without opening a schema.

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

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

Gives explicit preconditions: only after the orchestrator has inspected the current interaction and determined the action is authorized. Names the alternative for the excluded case (arbitrary text must use agent_prompt). Both the when and the when-not are stated.

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

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

With no annotations, the description carries the full burden and does deliver real behavioral context: the agent is persistent, production persistence depends on the separately managed Herdr service, and startup trust/auth prompts are reported but never auto-approved. It still omits failure behavior on the timeoutMs window and the lifetime/cleanup model, so it stops short of full disclosure.

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

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

Three tight sentences: purpose first, routing second, operational caveat last. Every sentence earns its place, though the final caveat sentence is dense and could be split for scanability.

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 resource-creating tool with no output schema, the description never indicates what 'start' yields (e.g., an agent identifier for use with agent_get/agent_prompt/agent_send_keys), which the agent needs to continue the workflow. Persistence and auth caveats are covered, but the handoff-to-other-tools information is missing.

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

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

Schema description coverage is 100% and both enums (harness, effort) are documented in the schema, so the baseline is 3. The description adds no meaning beyond the schema for harness, cwd, model, effort, or timeoutMs.

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 ('Start a persistent interactive coding agent in a dedicated Herdr workspace') and immediately differentiates itself from the nearest siblings (exec, process_start). An agent can tell what this does 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 usage: 'Use this, not exec or process_start, for coding-harness work' and names the conditions that select it (long-running, parallel, cross-turn Codex/agy/Claude tasks). When-not guidance is stated, not 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?

With no annotations, the description carries the full burden and does so well: it discloses destructive terminal semantics, exactly what gets destroyed in each state (workspace vs durable logical metadata), and explicitly bounds the blast radius (never stops the shared session or other agents). This is rich behavioral context beyond anything structured fields provide.

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

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

A single dense sentence that front-loads the destructive semantics and the state-dependent outcome, then appends the scope bound. Every clause earns its place 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?

Complete enough for a one-param destructive tool: it covers what is destroyed, in which states, and the blast-radius limits. Missing only an explicit return/error behavior, which is 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 coverage is 100% and the schema fully documents agentId with a pattern and provenance note (returned by agent_start), so the baseline is 3. The description reinforces the agent-scoped nature but adds no new syntax or format detail beyond the schema.

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

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

States a specific verb (Stop) and resource (MCP-managed agent), and immediately distinguishes scope from siblings by clarifying it stops one agent, not the shared session or other agents. An agent can differentiate this from agent_suspend or process_kill from the description 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?

Explains the semantic distinction between stopping an active agent (closes workspace) and a suspended one (discards metadata), which implicitly guides when to use this versus agent_suspend. It does not explicitly name agent_suspend as an alternative or state when not to use it, so it falls 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?

With no annotations, the description carries the behavioral burden well: it says the Herdr workspace is closed, the native harness session ID is retained, and that legacy/unattributed sessions fail explicitly. It does not state permission requirements or explicitly confirm that the retained session ID makes the operation reversible (e.g. via agent_resume), so a small gap remains.

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 tightly packed sentences, front-loaded with the action and mechanism before the usage condition and the sibling distinction. Dense technical jargon ('uniquely attributed native harness session ID') costs a little readability but every sentence 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 single-parameter tool with no annotations and no output schema, the description covers mechanism, preconditions, failure modes, and sibling differentiation. The main omission is what the caller gets back or how to check the resulting state, which is minor given the low complexity.

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

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

Schema coverage is 100% and the single agentId parameter is fully documented in the schema (including its pattern and that it comes from agent_start). The description adds no syntax, format, or ID-sourcing detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb (suspend) applied to a specific resource (MCP-managed logical agent) and explains the mechanism (closing the dedicated Herdr workspace while retaining the native harness session ID). It explicitly distinguishes itself from the sibling agent_stop, so an agent can route between them without opening either 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?

Gives a concrete condition for use ('at a task/turn boundary to release runtime resources') and a precondition (agent must be idle or finished), plus an explicit exclusion ('legacy agents and sessions without verified native attribution fail clearly'). It also names the alternative tool agent_stop and the criterion that selects 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?

With no annotations present, the description carries the full burden and does well: it discloses that all hunks are validated before any mutation, that context mismatch rejects the entire patch, and that there is no fuzzy or partial fallback — a clear atomicity and failure-mode guarantee. It omits permissions requirements or what the result reports, but the core mutation semantics are unusually well specified.

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, zero filler, with the format requirement and the atomicity guarantee front-loaded. 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 mutation tool with no annotations and no output schema, the description covers the critical ground: required input format, validation-before-mutation ordering, and all-or-nothing failure behavior. It does not describe the return value or error reporting, which is the only meaningful gap.

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

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

Schema description coverage is 100% with both parameters documented, so the schema already does the heavy lifting (baseline 3). The description adds only marginal meaning, clarifying that the patch is interpreted relative to cwd, but no syntax or format detail beyond the schema.

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

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

States a specific verb and resource: 'Apply a strict standard unified diff relative to cwd.' An agent immediately knows this mutates files via a patch. It does not explicitly name an alternative sibling, but no sibling overlaps this function, so disambiguation is unnecessary.

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 requirement for a 'strict standard unified diff' implies when the tool is appropriate, and the strictness constraint signals when it is a safe choice. However, it never states when to prefer this over writing files directly or what kinds of edits it should not be used for, leaving usage largely 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?

With no annotations, the description carries the disclosure burden. It reveals that this aggregates several categories (runtime, CLI capabilities, native MCP tools, bridges), which is helpful behavioral context, but does not state whether the discovery is cheap/cached, whether it reflects live or static state, or how results are structured.

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 efficient sentence that front-loads the main purpose and lists contents. No waste, though the enumerated list is dense.

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-param read-only discovery tool with no output schema, the description covers what it will return at a high level, which is adequate. However, without an output schema or annotations, it could be more complete about the shape/format of the returned information.

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?

Zero parameters, so no parameter semantics are needed. The baseline for a no-param tool is 4.

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

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

The description states a clear verb ('Discover') and resource ('VM execution environment') and enumerates the four things it returns. It is distinct from siblings, though 'agent_capabilities' nearby overlaps somewhat in naming and the distinction isn't explicitly drawn.

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 indication of when to use this versus command_info, agent_capabilities, or mcp_bridge_status, all of which plausibly overlap. The agent is left to infer usage context entirely.

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

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

With no annotations, the description must carry the behavioral burden. It usefully discloses that lookup is via PATH and that curated commands return category, summary, and version metadata, but says nothing about failure modes, non-existent commands, or response shape for uncatalogued names.

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, zero waste, with the core action front-loaded and the extra metadata behavior following. Nothing extraneous and nothing buried.

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

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

For a single-parameter read tool with no annotations, the description covers the primary action and hints at the return content (availability plus metadata for curated commands). It is nearly complete, though the exact output shape for uncurated commands remains implicit.

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

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

Schema description coverage is 100% and the single 'names' parameter is already fully documented as an array of CLI command names via PATH lookup. The description adds no syntax, constraint, or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource: 'Inspect whether named CLI commands are available on the VM.' This is clearly distinguishable from siblings like exec (which runs commands) or process_* tools. However, it does not explicitly name a sibling or contrast its role, so it stops short of full differentiation.

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

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

The description implies a pre-flight use case (checking command availability before invoking something like exec), but never states when to use it, when not to, or what the alternative is. Usage is inferable rather than 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?

With no annotations, the description carries the full burden and delivers real behavioral detail: the target is a disposable VM, oversized stdout/stderr is truncated to bounded head/tail previews with separate artifacts, and certain agent commands are prohibited. It stops short of stating state persistence between calls, auth/permission requirements, or the response shape.

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

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

Front-loads what the tool does, then stacks the routing rules in short, purposeful sentences. Slightly long at five sentences, but each one carries distinct routing or output information, so little is 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 four-parameter, unannotated, no-output-schema tool, the description covers environment nature, output truncation behavior, and the main routing decisions. Remaining gaps are persistence across calls and the exact returned payload, which are secondary for correct invocation.

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

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

Schema description coverage is 100%, so command, cwd, env, and timeoutMs are already documented in the schema (including bash -lc semantics and the timeout default/ceiling). The description adds no parameter-level detail beyond the probe exception, so the baseline 3 applies.

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

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

States a specific verb and resource ('Execute an arbitrary shell command') plus the execution target ('dedicated disposable Linux agent VM'). It also names the sibling tools it is not (process_start, agent_start), so an agent can distinguish it without opening any schema.

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

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

Explicit when-to-use ('commands that complete on their own'), when-not ('servers, watchers, REPLs, or other long-running/interactive commands'), the named alternative for each case (process_start, agent_start), and a carve-out for harmless --help/--version probes. This is close to ideal routing guidance.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses one non-obvious trait — bytes do not pass through model context — but says nothing about overwrite behavior, destination defaults, failure modes, or what is returned for a mutating import.

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 waste; the key constraint (no model-context routing) is stated immediately.

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

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

For a mutation tool with a nested-object parameter, no annotations, and no output schema, one sentence is far too thin. The agent knows why to use it but not how to populate file, destination, or overwrite, nor what to expect on completion.

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 4 parameters, including a nested required object (download_url, file_id) plus overwrite, destination, and cwd. The description adds no parameter meaning at all, so it fails to compensate for the entirely undocumented schema.

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

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

States a specific verb and resource (import a host-provided file into the Agent VM) and adds a distinguishing scope detail — the bytes bypass model context. An agent can separate this from read_file or present_file, though the exact boundary versus those siblings is not spelled out.

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 routing file bytes through model context' implies the use case (getting a large/host file into the VM without burning context), which is useful guidance, but no explicit when-to-use or alternative tools 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?

With no annotations present, the description carries the full behavioral burden. It usefully discloses non-recursiveness, dotfile inclusion, and a deterministic name/type output shape, but says nothing about permission requirements, error behavior on a missing path, or symlink handling.

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, zero filler, with the key scoping constraint ('one directory level') front-loaded. 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?

There is no output schema and no annotations, so the description has to carry return-value and behavior disclosure. It hints at a structured name/type result and the dotfile/non-recursive behavior, but omits error cases and permissions, leaving gaps for a tool with zero structured support.

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

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

Schema description coverage is 100%, so both cwd and path are already fully documented in the schema, including relative-path resolution against cwd. The description adds no parameter-level detail beyond what the schema provides, so the baseline 3 applies.

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

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

The description gives a specific verb (list) and resource (directory contents) and pins down the scope with 'one directory level' plus 'including dotfiles'. It does not explicitly differentiate from the unrelated listing sibling workspace_list, but no sibling actually overlaps this functionality, so the purpose is unambiguous.

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

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

The phrase 'intentionally non-recursive' implies the usage context, but the description never states when to reach for this tool versus alternatives or what conditions make it the wrong choice. Usage 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?

No annotations are provided, so the description carries the full behavioral burden. It does not state that the operation is read-only, side-effect-free, or whether any permissions are required; it only lists the content being reported.

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 redundant words. Every part of it earns its place by specifying the report subject and scope.

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 parameterless status-reporting tool, the description adequately states what the report covers. It does not describe the output structure, but no output schema exists and the listed contents give an agent enough to understand 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, so the schema provides no parameter semantics to document. Per the rubric, zero parameters establishes a baseline of 4, and the description does not need to add parameter details.

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 clear verb ('Report') and names the specific resource ('configured upstream MCP bridges, their connection state, and forwarded tool-name mappings'). It is distinguishable from the listed siblings, which mostly concern agents, processes, workspaces, and file operations, though it does not explicitly name a sibling alternative.

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

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

The description implies the tool is used to inspect bridge status, but it gives no explicit when-to-use guidance, prerequisites, or alternatives to consider. This matches the minimum viable score for implied usage.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=false, so safety is covered. The description adds a real behavioral fact beyond them — that the VM filesystem path is deliberately omitted from artifact metadata — and the word 'regular' signals directories are out of scope. It does not say whether content is copied or referenced, or whether size limits apply.

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 no filler, and the core purpose is front-loaded before the metadata-privacy note.

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 correctly explains the return form (an opaque artifact resource) and the privacy behavior of the metadata. It is close to complete for a two-parameter tool, though it could clarify how the artifact relates to the source file.

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

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

Schema description coverage is 100%, so both 'path' and 'name' are fully documented in the schema, making 3 the baseline. The description adds only the implicit constraint that the path must point to a regular file, which is marginal value.

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 ('Present') plus resource ('a regular file from the Agent VM') and states the output form ('opaque MCP artifact resource'). That output form implicitly distinguishes it from read_file, which returns content, but no sibling is named 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 only implied: the agent can infer you call this when you want a VM file exposed as an artifact rather than read inline. There is no explicit when-to-use, when-not-to-use, or named alternative such as read_file or import_file.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that the target is a process *group* rather than a single PID, but it omits the destructive/irreversible nature of the operation, that SIGKILL cannot be caught, the default signal, and any permission requirements.

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 zero waste; the resource and signals come first and the scope qualifier follows. Nothing extraneous.

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 process-termination tool with no annotations, no output schema, and 0% parameter coverage, the description is too thin. It should at minimum clarify signal semantics, default behavior, and irreversibility to let an agent invoke it safely.

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 merely restates the three enum values with no added meaning (no graceful-vs-force semantics, no default explanation), and gives no detail on the processId beyond the process_start linkage.

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 pairs a specific verb ('Send') with a precise resource ('SIGTERM, SIGINT, or SIGKILL') and scopes the target to a process group 'started by process_start', which distinguishes it from a generic kill. It clearly conveys what the tool does, though sibling differentiation is implicit rather than stated.

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

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

Usage is implied: kill a process you launched via process_start. However, there is no explicit when-to-use vs. alternative, and no guidance on which signal to pick in which situation (e.g., graceful vs. forced termination), which would be the most valuable guidance for this tool.

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

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

No annotations are provided, so the description carries the burden. It discloses the relationship to process_start (only lists those sessions) which is useful behavioral context, but does not state read-only safety, return format, ordering, or whether dead sessions are included.

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

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

Single sentence, front-loaded with the verb and resource, with the purpose clause attached efficiently. No wasted words.

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

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

For a no-param, no-output-schema, no-annotation tool, the description covers the essential purpose but omits what the list contains (session identifiers? statuses?), which an agent would need to use the output 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?

Zero parameters, so there is no parameter semantics to explain; baseline 4 applies. The description correctly implies a no-argument list.

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

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

States a specific verb (List) and resource (process sessions), and explicitly scopes it to sessions created by process_start. This distinguishes it from process_read/process_write/process_kill, which operate on individual sessions rather than enumerating them.

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

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

The phrase 'so persistent processes can be rediscovered across MCP client or conversation changes' clarifies the intent and when this tool is valuable, implying use after a client restart. It does not explicitly name siblings or state when-not-to-use, but the use case is clear.

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

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

With no annotations, the description carries the full burden and does disclose the incremental offset-based behavior, which is valuable. However, it omits other behavioral traits such as error handling, blocking behavior, or permission requirements, leaving some gaps.

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

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

Two sentences, front-loaded with purpose and then usage detail, with zero wasted words. It is efficient and well-structured.

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 3-parameter tool with no output schema and no annotations, the description adequately covers what is returned (stdout/stderr/status) and how to use offsets. It could say more about return format or error states, but it is reasonably complete.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the purpose of the offset parameters (pass returned next offsets to get only new output) and implies processId identifies the process started by process_start, adding meaningful semantics beyond the bare 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 (Read) and resources (incremental stdout/stderr and status) tied to a process started by process_start. It distinguishes itself from process_list and process_write by focusing on output retrieval, though it doesn't explicitly name 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?

Clearly states the context (process started by process_start) and gives an explicit usage pattern for subsequent reads using returned offsets. It lacks explicit when-not-to-use guidance or direct alternatives, but the contextual cues are strong.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses lifecycle semantics (kept alive across MCP tool calls) and the processId handoff to process_read/write/kill, but omits permissions/auth requirements, concurrency limits, timeout or failure behavior, and interaction model details.

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, zero waste: purpose and persistence first, then the return value/handoff, then the exclusion and alternative. Front-loaded and well ordered.

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 3-param tool with no output schema, the description covers purpose, return value, and the key sibling routing, which is nearly everything an agent needs. It falls short only on permissions and failure/timeout behavior, which are not otherwise documented.

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

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

Schema description coverage is 100%, so the schema already documents command, cwd, and env. The description adds no parameter-level syntax or defaults beyond what the schema states, so the baseline 3 applies.

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

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

The description names a specific verb and resource (start a long-running or interactive non-agent shell command) with crisp scope qualifiers. It distinguishes itself from process_read/write/kill (via the returned processId) and from agent_start (via the non-agent exclusion), so an agent can select it without opening any schema.

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

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

It gives an explicit when-not rule: do not use for Codex, Antigravity CLI (agy), or Claude Code agent work, and names the alternative (agent_start) with the reason (dedicated parallel workspaces, survives lifecycle changes). The use case 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?

No annotations are provided, so the description carries the full behavioral burden. It does not say what happens if the process is dead or stdin is closed, whether the write blocks, whether an error is returned, or whether the payload is raw text versus encoded — significant gaps for a mutation tool.

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

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

A single efficient sentence with the resource and its prerequisite front-loaded and no filler. Nothing in it is 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?

With three undocumented parameters, no annotations, and no output schema, the definition should explain parameter meaning and core behavior, but it only says what the tool does. An agent cannot call it confidently regarding newline handling or failure modes.

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 explains none of the three parameters. Critically, 'appendNewline' (default false) is never mentioned, and that default materially changes how interactive programs receive input, so the description fails to compensate for the schema 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?

States a specific verb and resource ('write to stdin of a running process') and ties the target to its sibling process_start, so an agent can tell it apart from process_read/process_kill. It is clear but does not explicitly contrast itself against 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?

The phrase 'started by process_start' implies the prerequisite (a live process created by that tool), but there is no explicit when-to-use guidance, no when-not, and no mention of alternatives such as process_read for output. 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?

No annotations are provided, so the description carries full behavioral burden. It discloses bounded reading, UTF-8, and structured line metadata, plus the binary/large-file caveat. It omits failure modes (non-existent file, encoding errors) and does not state whether output includes content plus line metadata explicitly.

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. Core behavior (bounded UTF-8 line-range read) is front-loaded, and the alternative-tool guidance follows immediately. 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 4-param read tool with full schema coverage and no output schema, the description covers the essential scope and the main exclusion. Missing only minor detail on error behavior and returned metadata shape, but adequate to invoke correctly.

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

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

Schema description coverage is 100%, so the schema already defines cwd, path, startLine, and endLine. The description adds the '1-based' nuance (also in the schema) and confirms bounded line-range semantics but introduces no parameter meaning beyond the schema. Baseline 3 applies.

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

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

Specific verb 'read' plus resource 'UTF-8 text file' and line range, distinguishing it from sibling tools like exec/list_directory. However, it does not name or explicitly contrast with the closest alternative, shell tools, only recommending them for binary/large files, so sibling differentiation is partial.

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 NOT to use it — 'Use shell tools for binary or very large files' — which gives a clear boundary condition. It lacks a positive 'use this when' framing beyond the scope of the operation, but the exclusion is practical and actionable.

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

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

No annotations, so the description must carry the behavioral burden. It correctly states 'read-only' and that no updates are installed (implying via checkLatest). However it does not disclose duration, side effects on discovery scope, or why coverage.untracked matters beyond its existence. Adequate but incomplete for a no-annotation tool.

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

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

Two tight sentences, front-loaded with the main verb+scope, followed by a useful behavioral note. No filler, though the coverage.untracked sentence assumes context not otherwise introduced.

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 audit with one boolean parameter and no output schema, most runtime detail is absent. Whether failures abort or are reported, expected output shape, and safety guarantees are all unstated. Adequate but leaves gaps for a diagnostic tool.

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

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

Schema coverage is 100%, so the schema already documents checkLatest and its default and effect. The description adds no syntax or format detail beyond what the schema provides, so baseline 3 is correct.

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 (audit) and resource (Agent VM maintenance: tools, update sources, services, APT, dependency drift). Clearly distinct from write-oriented siblings (exec, process_start, apply_patch). Lacks explicit differentiation from sibling tools but the scope is unique enough that confusion is unlikely.

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?

Implies usage when a proactive read-only health check is needed, but never states when to use it vs alternatives or prerequisites. No exclusions or alternatives named, so the agent must infer context.

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

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

No annotations are provided, so the description carries the full burden. It does disclose useful traits: isolation, shared repository backing, and the immutability of the returned workspace ID. It omits auth requirements, failure/timeout behavior, idempotency, and lifecycle/cleanup expectations — meaningful gaps for a tool that provisions remote-backed 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?

Two tight sentences with zero filler. The core action is front-loaded and the return-value/usage note follows immediately.

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 creation tool with complete schema coverage, no annotations, and no output schema, the description covers purpose and output shape adequately. It is slightly thin on lifecycle context (the workspace_delete sibling implies teardown responsibility) and on operational constraints like timeouts and auth, but nothing critical to a correct call is missing.

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

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

Schema description coverage is 100%, so revision, timeoutMs, and repository are already documented including format constraints and defaults. The description adds no parameter-level detail beyond what the schema provides, which is the baseline-3 case.

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?

Names a specific verb ("Create") and a specific resource ("isolated managed Git worktree backed by shared repository storage"), plus what it produces ("immutable workspace ID and path"). This is unmistakably distinct from siblings such as workspace_list and workspace_delete, so an agent needs no schema inspection to route correctly.

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 use as cwd with existing tools" tells the agent what to do with the returned ID/path, which is genuine invocation context. However, there is no statement of when to prefer this tool over alternatives, when not to use it, or any prerequisite (e.g. required credentials, cleanup via workspace_delete). Usage is implied rather than 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?

With no annotations, the description carries the full behavioral burden. It helpfully discloses that dirty workspaces are refused unless force is explicitly true, which is a real guardrail beyond the field names. It says nothing about whether deletion is permanent/irreversible, what permissions are needed, or what happens to in-flight agent/process sessions attached to the workspace.

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 destructive action and its ID-based scope front-loaded, followed by the one behavioral caveat. 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 two-parameter delete tool with no output schema and no annotations, the description covers purpose, the key safety gate, and the required identifier. Completeness would improve with a statement about permanence/reversibility or error behavior, but there is no output schema demanding return-value explanation.

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%: 'force' is documented in the schema, while 'workspaceId' is only constrained by a regex pattern. The description reinforces the force semantics ('unless force is explicitly true') and characterizes the ID as immutable, but adds no format or constraint detail beyond the schema.

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

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

The description gives a specific verb and resource ('Remove a managed Git worktree') and scopes it by 'immutable workspace ID', which cleanly separates it from siblings like workspace_create and workspace_list. An agent can select it 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?

Usage is implied by the verb 'Remove' and the workspace-ID scoping, and the dirty-workspace condition hints at when the call will fail. However, there is no explicit guidance on when to use this versus alternatives (e.g. workspace_create's inverse, or cleanup workflows), nor any stated prerequisites or irreversibility warning.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose a meaningful trait: state is reconstructed from durable filesystem and Git worktree state rather than an in-memory registry. However, it never states that this is a side-effect-free read or anything about cost/latency on large trees.

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

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

A single front-loaded sentence that names the resource first and then the fields returned. No filler, no restatement of the tool name.

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

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

With no output schema, the description usefully enumerates the returned fields (repository, HEAD/branch, dirty status), which is exactly what an agent needs. It is close to complete; a note on read-only semantics or empty-state behavior would close the 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies for a parameterless 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?

States a specific resource (managed Git workspaces) and the details surfaced (repository, HEAD/branch, dirty status), which clearly separates it from the write-oriented workspace_create/workspace_delete siblings. The verb 'Rediscover' is slightly unusual for what is effectively a list operation, but the resource and scope are unambiguous.

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

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

There is no explicit when-to-use guidance, no mention of prerequisites, and no reference to the sibling tools it complements. An agent must infer that this is the read counterpart to workspace_create/workspace_delete. The 'rediscover' framing hints at re-scanning state but never says when that is appropriate.

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