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

No annotations are provided, so the description carries the burden. It does disclose the return content (commands, their arguments, and their effects), which is genuinely useful, but it never states that the call is read-only / side-effect free, gives no sense of result size, and does not explain the relationship to the runtime state returned by siblings like herdr_app_status.

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 compact sentence that front-loads the scope ('every window command herdr_app_do can run') and then says what each entry contains. No filler, though it is arguably too short rather than too long.

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 catalogue tool the essentials are present, but with no output schema the description should more concretely frame the shape of the returned command list and how to feed those arguments into herdr_app_do. Without annotations, some statement about read-only behavior would also help.

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 to disambiguate; the baseline for a no-param tool is 4. The description correctly presents this as a global catalogue with no filtering 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 resource and intent: it enumerates every command that herdr_app_do can run, along with their arguments and behavior. Naming herdr_app_do ties it to a concrete sibling, so an agent can tell it is a discovery/introspection tool rather than an executor. Slightly ambiguous whether 'window command' means the command catalogue of the window subsystem or something narrower.

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?

Mentioning herdr_app_do implies the intended workflow (look up a command here before invoking it there), but the description never says when to call this versus just calling herdr_app_do directly, nor does it state any prerequisite. 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 burden well: it discloses that commands never open a dialog (no interactive fallback), that new spaces/tabs are immediately visible side effects, and that the call returns created IDs. It stops short of error/failure behavior or 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 dense paragraph with the verb and command examples front-loaded, followed by behavioral caveats. Every clause carries information, though the packed command list makes it slightly hard to scan and the '...' elision forces a lookup elsewhere.

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

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

For a polymorphic dispatcher with a free-form args object and no output schema, the description supplies return semantics (created IDs), side-effect visibility, and partial per-command argument contracts with a pointer to herdr_app_commands for the rest. Only the unenumerated commands and error cases are left undocumented.

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

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

Schema coverage is 100%, so baseline would be 3, but the description goes further by spelling out the concrete key sets for individual commands (space.new {name, folder, machine, argv, task}, pane.split {direction, pane}), which the free-form `args` object in the schema cannot convey on its own.

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 (run) and resource (window command), then enumerates concrete command names with their argument shapes. It also distinguishes itself from herdr_app_commands, which only lists the commands, and from herdr_exec/herdr_run by scoping to window/app commands.

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 invocation guidance: 'Supply every required argument: commands from an agent never open a dialog,' plus a clear constraint that new spaces/tabs appear immediately and should only be created when the user asks, with explicit names. It points to herdr_app_commands for discovery, though it doesn't contrast against herdr_exec or herdr_run directly.

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

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

No annotations exist, so the description bears the full disclosure burden. Listing spaces/tabs/terminals strongly implies a read-only, non-destructive operation, and the 'inspect before acting' note adds useful workflow context, but nothing states permissions, side effects, or cost.

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

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

Two short sentences, with the return content front-loaded and the usage advice second. Nothing is wasted or 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?

With no output schema, the description must describe the return value, and it does: spaces, tabs, terminals, and pane IDs. It does not explain the shape of the response (nesting, field names) or whether it reflects a snapshot, leaving 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?

The tool takes zero parameters, so there is nothing schema-side to compensate for; the baseline for a parameterless tool is 4. The description correctly adds no parameter discussion, which is appropriate.

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

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

The description names the resource precisely — spaces, their tabs and terminals, including pane IDs, in the open Herdr window — which maps cleanly onto the 'list' verb implied by the name. It does not explicitly distinguish itself from nearby siblings like herdr_list or herdr_app_status, so it stops short of a 5.

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

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

'Inspect before acting; use these IDs rather than guessing' gives a clear usage context and even a workflow recommendation. It does not name an alternative tool or state when-not to use it, so it lacks the explicit exclusions that would earn 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?

No annotations are provided, so the description carries the full behavioral burden. It discloses the key traits: captures the window's own last rendered frame even when covered, writes a PNG, returns an absolute path, and requires a running window; it does not cover overwrite behavior or failure modes in detail.

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

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

Two compact sentences, front-loaded with the action and result, and the precondition is appended without waste.

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

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

The tool is simple, has a fully documented single optional parameter, and no output schema. The description supplies the return path and running-window requirement, leaving no material 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?

The only parameter, file, is fully documented in the schema (100% coverage), including the default. The description does not add file-path semantics beyond the schema, so it meets the baseline for high schema coverage.

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

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

States a specific verb ('Save') and resource ('window's last rendered frame as a PNG'), including the return value (absolute path). The 'even when covered' detail further clarifies what is captured, making it unmistakable versus other window/app 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?

Provides a precondition ('Needs a running window') but gives no explicit when-to-use guidance or alternatives among the many herdr_app_* siblings. The context is implied for visual capture, but selection guidance is thin.

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 usefully enumerates the state categories returned (layout, selected space/tab, focused pane, overlays, zoom, errors), which is real behavioral context, but it does not explicitly state that the operation is read-only or non-mutating.

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

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

The description is a single compact sentence listing the relevant state categories with no filler. It is appropriately sized, though the fragment structure makes it read more like a caption than a front-loaded instruction.

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, low-complexity tool with no output schema, the description gives an adequate inventory of returned state. However, it omits the query's read-only nature and any routing relative to closely named siblings, leaving some context incomplete.

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

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

The tool has zero parameters, so the baseline is 4. There are no parameter semantics for the description to compensate for, and the schema imposes no inputs.

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

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

The description implies an observational state query by saying 'What the window shows' and enumerating the aspects reported, but it uses no clear verb such as 'returns' or 'inspect' and never distinguishes this tool from siblings like herdr_status or herdr_app_shot. The purpose is inferable but vague.

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

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

There is no guidance on when to use this tool versus alternatives. With siblings such as herdr_app_shot and herdr_status present, the description leaves the agent to infer that this returns textual window state rather than a screenshot or global status.

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

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

No annotations are provided, so the description carries the behavioral burden; it discloses non-interactive single-command execution, local/remote scope, exit-code and exact-output return, and termination at exit or timeout. It does not discuss permissions, authorization, or side-effect risk, which is a meaningful gap for an arbitrary command-execution 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?

Three tight sentences, front-loaded with the core action and return contract, followed by usage constraints and the sibling alternative. There is no wasted text.

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, but the description explains the return contract (exit code and exact output) and timeout termination. With 86% schema coverage, parameters are largely self-documenting; remaining gaps are remote-machine prerequisites and safety/permission context.

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

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

Schema description coverage is 86%, so the baseline is 3 even with no parameter details in the description. The description only loosely reinforces the `on` parameter via 'here or on another machine'; argv, line, env, cwd, input, and timeout semantics are left to 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 (run one command), scope (here or another machine, without a terminal), and return contract (exit code and exactly what it wrote). It explicitly names herdr_run as the alternative, making it clearly distinguishable from 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?

Gives concrete when-to-use examples (git diff, ls, cat) and an explicit when-not/alternative rule: use herdr_run for anything long or interactive. This is a clear routing decision for an 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?

With no annotations, the description carries the full burden and does so well: it discloses the uniqueness constraint on each `old`, non-overlap of edits, and the all-or-nothing atomicity guarantee. Gaps remain around what happens if the file is missing, encoding assumptions, and whether `new` may be empty to delete text.

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 short sentences with zero filler. Scope comes first, then the matching and atomicity constraints, then the failure remedy, which is the order an agent needs them.

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?

Covers the remote/local scope, the matching constraint, atomicity and error recovery, and there is no output schema to explain. Missing only edge-case behavior such as a nonexistent path, creating a file, or empty `new` for deletion, which an agent editing files will likely wonder about.

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 75%, and the description still adds real meaning beyond the schema: the `old`/`new` pair must match exactly once within the file, edits cannot overlap, and the failure remedy is to widen the `old` context. That is semantics the schema's bare string types do not convey.

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

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

States a specific verb and resource: 'Replace exact text in a file here or on another machine.' That is concretely different from herdr_file_write, though the description never names the sibling to make the contrast explicit for an agent choosing between 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 implies when this is the right tool (surgical replacement rather than whole-file write), and gives recovery guidance on edit_failed. But it never states when to prefer herdr_file_write or herdr_put, nor any preconditions such as the file needing to already exist.

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 behavior: partial reads via offset/limit and a return value that includes total line count, which implies the file may be longer than what is returned. It says nothing about encoding, binary files, permission errors, or whether the operation is side-effect free.

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

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

One compact sentence with the read scope front-loaded, followed by the pagination contract and return shape. No filler and no repetition of the title.

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 compensates by stating the return values (text plus total line count). Remote-machine and cwd behavior are covered by the schema. Only minor gaps remain around failure modes and file-type limits.

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

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

Schema description coverage is 100%, so all five parameters including `on`, `cwd`, `offset`, and `limit` are already documented in the schema. The description restates the offset/limit behavior ('lines from offset, at most limit') without adding syntax or edge-case meaning beyond it. Baseline 3 applies when the schema does the heavy lifting.

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+resource ('Read a text file') with the important scope qualifier 'here or on another machine'. It is clearly distinguishable from herdr_file_write and herdr_file_edit by the read verb, though it never names those siblings explicitly.

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

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

The use case is implied by the name and the 'here or on another machine' hint, which points at the `on` parameter and herdr_machines. There is no explicit guidance on when to prefer this over shelling out via herdr_exec, nor any exclusions (binary files, size limits).

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that missing folders are created and that writes are atomic, but it does not explicitly say whether an existing file is overwritten or what happens to prior content, which is important for a write operation.

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

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

The description is two short sentences with the core behavior front-loaded. Every phrase earns its place by conveying scope, folder creation, and atomicity without waste.

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

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

For a simple write tool with 100% schema coverage and no output schema, the description covers the key non-obvious behaviors: remote targeting, folder creation, and atomicity. It is slightly incomplete because it does not explicitly state overwrite semantics, which matters for a full-file write.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema. The description adds only broad context ('here or on another machine') and does not add parameter-level semantics beyond what the schema provides, making the baseline 3 appropriate.

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

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

The description states a specific verb and resource ('Write a whole file') and explicitly distinguishes whole-file writing from partial editing. It also states the scope ('here or on another machine'), letting an agent differentiate it from siblings such as herdr_file_edit.

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 'whole file' implies this should be used when replacing full content rather than editing part of a file, but it does not explicitly name herdr_file_edit or state when to choose one over the other. Usage is inferable but not directly 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?

No annotations are provided, so the description carries the full burden. It does useful work by disclosing the returned field set and that finished terminals are also retrievable, but it says nothing about what happens when the identifier is unknown (error vs. null), whether data is cached, or any access constraints. Adequate but with clear gaps 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?

A single front-loaded sentence with zero filler. Every clause enumerates a concrete returned field, so nothing 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 no output schema, the enumeration of return fields is exactly the compensating detail an agent needs, and it is present. The remaining gap is failure behavior for a missing or invalid terminal id, which matters for a lookup tool but is a modest omission given the schema fully documents the sole input.

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 and schema description coverage is 100%, with the schema already documenting the accepted forms (`t7`, a name, `machine/t7`). The description adds nothing about the identifier format or resolution rules, 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 ("Get a terminal") and enumerates exactly what comes back: argv, cwd, state, status, exit code, labels, foreground process. It implicitly contrasts with herdr_list by scoping to "One terminal," but never names that sibling, so the differentiation is suggestive rather than explicit.

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

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

No when-to-use or when-not-to-use guidance and no alternative named, even though herdr_list is the obvious sibling for enumerating terminals. "live or finished" hints that it works for terminated terminals too, but the agent must infer that retrieval-by-identifier is the intended call pattern.

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

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

With no annotations, the description carries the burden and does disclose the actual input sent by target type, the effect scope, and that it reports the outcome. It omits details about permissions, failure behavior, and reversibility.

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 action and effect. Every phrase contributes useful information without repetition.

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

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

For a two-parameter tool with complete schema coverage and no annotations or output schema, the description covers the action, target-specific key, scope, and rough return behavior. It could be more explicit about the report format, but it is adequate.

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

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

Schema description coverage is 100%, so terminal and timeout are already documented by the schema. The description adds useful key-choice context but does not add parameter syntax or format details beyond what the schema provides.

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

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

The description states a specific action, the exact key behavior for agents versus programs, and the scope: it stops the current turn, not the process. This clearly distinguishes it from the process-killing sibling herdr_kill.

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

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

It gives clear situational context by explaining esc for agents and ctrl+c for programs, plus an exclusion that it does not stop the process. However, it does not explicitly name alternatives such as herdr_kill for process termination or herdr_keys for arbitrary key sends.

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 exist, so the description carries the full disclosure burden. It reveals the accepted key-name grammar (ctrl+c, alt+x, f5) but says nothing about whether the press is synchronous, whether it targets the foreground process, what happens on an unrecognized key name, or whether the terminal must already be attached.

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 the core operation first and the illustrative example trailing; nothing is redundant. The trailing '...' after 'a' is slightly loose but conveys the open-ended key set efficiently.

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

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

For a simple two-parameter input tool with no output schema and no annotations, the description covers what to pass and roughly why. It stops short of covering failure modes, return behavior, or any prerequisite state, which leaves an agent guessing at edge cases.

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

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

Schema coverage is 50%: `terminal` is documented in the schema, but `keys` is a bare string array with no item documentation. The description compensates well by enumerating the valid key tokens and showing that modifier combinations are expressed as 'ctrl+c'/'alt+x', which is exactly the missing semantics for the undocumented 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?

States a specific verb and resource ('Press named keys in a terminal') plus the accepted key vocabulary, so the operation is unambiguous. It never distinguishes itself from siblings like herdr_send or herdr_interrupt, leaving the agent to infer that this is key-level input rather than text or a signal.

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 parenthetical example ('to answer a dialog with down, enter') implies the intended usage pattern but gives no explicit when-to-use/when-not guidance. Nothing says whether to prefer this over herdr_send for typing text or over herdr_interrupt for breaking out of a process.

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

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

With no annotations, the description carries the full burden; it does disclose the escalation sequence (hangup, then terminate, then kill), which is meaningful behavioral detail. However, it never says the operation is destructive/irreversible, what happens if the terminal is already gone, or what is returned, leaving key traits unstated.

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

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

Two short sentences with zero waste, and the core action is front-loaded before the safety caution.

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

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

For a simple one-parameter tool this is nearly sufficient, but the crowded sibling set (herdr_interrupt, herdr_rm, herdr_send) makes the absence of explicit routing between them a real gap. The lack of any destructive/irreversibility statement is also notable given no annotations.

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 'terminal' parameter already documents its accepted forms (`t7`, a name, or `machine/t7`). The description adds nothing about the parameter, 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 object: it ends the program in a terminal, and names the escalation mechanism. Combined with the title it is unambiguous what the tool does, though it does not explicitly distinguish itself from sibling tools like herdr_interrupt or herdr_rm.

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?

'Only clean up terminals you started' is a real guardrail about when to use it, but there is no guidance on when to prefer this over herdr_interrupt (soft signal) or herdr_rm (remove terminal). The alternative-selection guidance an agent needs 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 discloses removal via empty string but does not explain whether labels merge with or replace existing labels, what permissions are required, or what the response looks like — critical 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?

Two short sentences with zero waste. The core operation and the notable removal rule are front-loaded and easy to parse.

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

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

No annotations, no output schema, and a nested labels object create a high burden. The description omits whether existing labels are preserved when setting new ones, which is essential 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 coverage is only 50%, with the labels parameter lacking a schema description. The description partially compensates by explaining free-form key=value labels and empty-string removal, but it still leaves ambiguity about merge/replace semantics for the labels object.

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 specific verb and resource: set or remove labels on a terminal, with free-form key=value syntax. It is understandable without opening the schema, though it does not explicitly distinguish itself from the generic sibling herdr_put.

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 provides one useful usage rule — an empty string removes a label — but offers no guidance on when to use this instead of herdr_put or other mutation tools, and no prerequisites or exclusions 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 must carry the full burden. It does disclose scope (all machines, not just the caller's own work) and the shape of results (status, cwd, labels, parent), but never states that it is read-only, nor mentions result volume, pagination, or what 'connected machine' failures look like.

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 tightly written sentences with zero filler. The resource and scope come first, and the clarifying note about scope breadth 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?

Because there is no output schema, the description's enumeration of returned fields is genuinely necessary and present, and the cross-machine scope is spelled out. What is missing is any note on the read-only nature or on result size, which matters for a fleet-wide listing.

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 'all' and 'labels' are already documented in the schema. The description does not reference either parameter, offering no extra detail such as label-matching semantics beyond what the schema provides; 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 concrete verb and resource ('Live terminals') plus explicit scope: this machine and every connected machine, with the fields returned (status, cwd, labels, parent). It does not name a sibling such as herdr_get or herdr_status to differentiate itself, so it falls just 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?

Usage is only implied — an agent can infer it is the discovery/enumeration entry point, and 'Includes the user's other work, not just yours' hints at why it is broad. There is no explicit when-to-use, no exclusion, and no pointer to herdr_get or herdr_status for narrower lookups.

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 carries the full burden. It discloses the return content ('with their connection state'), implying a read-only listing, but never states that it is read-only, what a disconnected entry looks like, or what happens if the core has no machines. Useful but thin for an unannotated 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 short sentences, zero filler, with the identification of the returned set front-loaded before the follow-up usage hint.

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 must convey return shape itself. It says the result includes names and a connection state but gives no field names, ordering, or format for 'connection state', leaving an agent to discover the payload by calling it.

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

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

Zero parameters, so the baseline of 4 applies. The mention of `on` and `machine/t7` is argument syntax for other tools rather than a parameter of this one, but it does add relevant meaning for how the output is consumed.

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 the specific resource (machines added to this core over ssh or via a command) and what makes it distinct: 'the other machines'. The listing verb is only in the title, so the description itself is a noun phrase, but purpose is unmistakable and separated from siblings like herdr_status/herdr_app_ls.

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?

'Use their names in `on` and `machine/t7`' gives concrete downstream usage, which implies when to call it (before targeting a machine). However, no explicit when-not or named alternative is given among the many herdr_* siblings, so guidance 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?

No annotations are provided, so the description carries the behavioral burden alone. It usefully discloses that the write lands on the remote machine and that it returns the path, but says nothing about overwrite/collision behavior, permission requirements, or error conditions 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 front-loaded sentence with the location and return value packed in and zero filler. Nothing should be trimmed.

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?

All four parameters are schema-documented, and although there is no output schema, the description covers the return value ('where it landed'). Complete enough to invoke correctly, though it could say more about remote-write side effects.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters, and the baseline is 3. The description implies the text-vs-base64 split via 'image to paste, a patch' but adds no format or exclusivity detail beyond what the schema states.

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

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

States a specific verb (Write) and resource (a file beside a live terminal, on its machine), plus concrete use cases (image to paste, a patch). It distinguishes itself from the read/inspect siblings but never explains how it differs from the closely-named herdr_file_write, leaving genuine 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 parenthetical use cases imply when to reach for it (delivering a payload for a program to read), but there is no explicit when-to-use/when-not and no named alternative. With herdr_file_write sitting right beside it, the omission matters.

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 states the return content is plain text including screen and history, and that it works for live or finished terminals, but it does not explicitly confirm read-only behavior, error handling, or whether live reads block or stream.

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

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

The description is a single focused sentence with no wasted words, and the key return content is front-loaded. It is appropriately sized for a simple read 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?

For a low-complexity read tool with full parameter schema coverage, the description adequately explains what is returned. However, it lacks usage context and does not help an agent distinguish this tool from the many sibling terminal tools.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description mentions `lines` of history but adds no syntax or format details beyond what the schema provides, making 3 the appropriate 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?

The description clearly identifies the resource and output: the terminal's screen plus `lines` of history, as plain text. It is more specific than the title alone, but it does not differentiate this tool from siblings such as `herdr_get` or `herdr_app_shot`.

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

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

The description provides no guidance on when to use this tool versus alternatives. It mentions that the terminal may be live or finished, but gives no conditions or exclusions for selecting this read tool over sibling 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?

No annotations are provided, so the description carries the full disclosure burden and does not meet it. It does not say whether removal only detaches the list entry or also tears down the underlying process, whether the operation is reversible, whether the terminal must be in a finished state, or what happens on failure.

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

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

One short, front-loaded sentence with no waste. It is efficient, though its terseness is part of why behavioral gaps remain.

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 zero annotations and no output schema, the description leaves out the failure semantics, the precondition implied by "finished", and any hint of the result. An agent knows what it removes but not what the call actually does.

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 already documents the single `terminal` parameter with concrete formats (`t7`, a name, `machine/t7`). The description adds no format or resolution detail beyond what the schema supplies, 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 ("Remove a finished terminal from the list"), and "from the list" implicitly separates it from process-killing siblings like herdr_kill and herdr_interrupt. Sibling differentiation is only implied, though — it never names the alternatives it is not.

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

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

No when-to-use or when-not-to-use guidance. The adjective "finished" hints at a precondition but the description never states what to do if the terminal is still running, nor steers the agent to herdr_kill/herdr_interrupt in that case.

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 states that server.stop and server.restart are refused because they affect every terminal, but it does not warn that other listed methods such as doc.set or machine.rm may mutate state, nor does it mention auth, errors, or side effects for arbitrary methods.

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 the capability and selection rule. Each sentence adds routing guidance, concrete examples, or a safety constraint without repetition.

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

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

For a generic RPC escape hatch with no annotations or output schema, the description covers selection, example methods, discovery via rpc.discover, and a key refusal. It still leaves auth/error behavior and mutation risk for non-refused methods unstated, so it is strong but not 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 coverage is 0%, and neither parameter is described in detail. The method examples add some meaning by showing the JSON-RPC name format, and rpc.discover is cited for per-method schemas, but the params object and method-specific parameter structure are left for the agent to discover.

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: 'Call any herdr-core JSON-RPC method directly.' It distinguishes itself from dedicated sibling tools by saying it is for methods without a dedicated tool, and the examples make the scope concrete.

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 defines when to use it ('For methods without a dedicated tool'), names example methods, points to rpc.discover for schemas, and states that server.stop and server.restart are refused. This covers alternatives and exclusions clearly.

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: lifecycle ('stays alive'), execution semantics ('argv runs as given; line runs in the shell; neither opens that machine's shell'), template task timing ('sent as the first message once the agent is ready'), default wait/timeout behavior, and what is returned (terminal address, first_message.sent, output/wait for background=false).

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 nearly every clause carries distinct information — the agents/programs split and the return-value note are well placed at the end. Phrasing is telegraphic in spots ('argv runs as given', 'neither opens that machine's shell'), which trades a little clarity for density.

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 13-parameter, zero-required, mutation-style tool with no output schema and no annotations, the description supplies the launch model, the agent-vs-program decision, default timeout/wait behavior, and the return shape. Nothing needed to call 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?

Schema coverage is 100%, so baseline is 3; the description adds real meaning beyond it by contrasting argv and line execution, tying background to the timeout wait, and explaining when task is delivered. It does not cover the less obvious flags (rm, keep, outlive_parent, labels), which are left entirely to 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 ('Start a program in a new terminal that stays alive') and immediately distinguishes the two launch modes (argv vs line) plus the template case referencing herdr_templates. An agent can tell this apart from herdr_exec or herdr_send without opening another 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 per-case guidance: 'Agents: always background=true, a name, and the whole task up front' versus 'Programs: background=false waits for exit'. It also routes to herdr_templates and herdr_machines. It stops short of naming an explicit alternative tool (e.g. herdr_exec) or a when-not-to-use condition, so not 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 full load and does so well: it discloses the idle debounce (~3 s), that blocked programs are refused, the force caveat, and that wait=true waits for and reports the resulting turn. It is silent on what a wait=false call returns, which matters since there is no 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?

Four short sentences, front-loaded with the core action, then constraints, then the anti-pattern warning. No sentence is redundant and nothing is repeated from the schema verbatim.

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 six parameters and no annotations or output schema, the description covers the risky behaviors (debounce, blocked refusal, force semantics, wait reporting) and adds a recovery instruction. Gaps remain around the return value on wait=false and what happens when the 'if' precondition fails.

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

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

Schema coverage is 100%, so baseline is 3; the description still adds meaning by linking force to the blocked-program refusal and explaining that wait=true returns how the turn ended, plus the idle timing that underpins the 'if' enum. It does not clarify the conditional behavior when 'if' is not satisfied.

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 mechanism: paste text into a terminal and press Enter. That mechanism-level phrasing distinguishes it implicitly from sibling writers like herdr_put and herdr_keys without the agent needing to open their 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?

Gives concrete context for conditional behavior (only after ~3 s of no typing), the force escape hatch, and when to use wait=true. The closing instruction 'do not resend after an unclear result: read first' routes the agent to a read-first workflow, though it does not name the sibling tool explicitly.

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 exist, so the description carries the full load; it implicitly signals a side-effect-free read by describing only informational outputs, but never states read-only or idempotent behavior explicitly. It does add value by naming the specific data surfaced (uptime, pid, terminal counts, connection details), which compensates somewhat 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 compact sentence with no filler, front-loaded on the owning component ('herdr-core's ...') before the field list. It is appropriately sized, though the field enumeration is slightly dense and would read better split.

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 must convey return contents, and it does list the main fields. For a zero-argument, zero-annotation status tool this is close to sufficient, though it omits error/health semantics (e.g., what an unreachable core looks like).

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 the baseline of 4 applies. Nothing in the description contradicts or complicates the no-argument call signature.

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 is a noun phrase enumerating returned fields (identity, version, pid, uptime, terminal counts, connection details) rather than stating an action, but it does convey that this is a core/server status read. It never explicitly contrasts itself with the adjacent herdr_app_status sibling, so the agent must infer that one is core-level and the other app-level.

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

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

There is no guidance on when to call this tool, no prerequisites, and no mention of alternatives such as herdr_app_status or herdr_list. The agent is left to infer usage purely from the noun phrase.

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

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

No annotations are present, so the description carries full behavioral burden. It implies a read-only list returning names and descriptions, but it doesn't explicitly confirm read-only nature, mention any rate limits, caching, or whether it returns all templates or a filtered 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?

Two short sentences with no waste. The core purpose is front-loaded, and the follow-up action is clearly stated.

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 list tool with no output schema, the description adequately conveys what it returns (names and descriptions) and how to use the result. Minor gap: it doesn't explicitly say these are all available templates or mention any caveats.

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 is empty and requires no documentation. The description adds no param info because none exist; baseline 4 is appropriate.

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

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

The description identifies the resource as ready-made agent roles (e.g., reviewer, implementer) and implies listing them by name and description. It also mentions the sibling herdr_run for the follow-up action, helping distinguish this discovery step from execution.

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 provides a clear next step: 'Run one with herdr_run argv=[name] and a task.' That implies this tool is for discovering templates, but it does not state when not to use it or contrast with siblings like herdr_list or herdr_get.

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

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

With no annotations, the description carries the full burden and does well on the surprising part: a timeout does not fail, it returns ended=false and the caller should wait again. It also discloses children=all vs any semantics. It says nothing about permissions, whether concurrent waits or nested waits are safe, or what a returned payload otherwise contains beyond the ended flag.

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?

Tight and front-loaded: the primary completion condition comes first, then modes, then the timeout contract, then children. A few phrases are dense to the point of obscurity, e.g. "returns on the next child's news", which costs a bit of clarity.

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

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

Four optional params, no output schema, no annotations — the description covers the wait conditions, timeout contract, output matching, and children scope, which is nearly everything needed to call it. Minor gaps remain on error cases (invalid terminal) and on what else the result contains besides ended.

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?

At 75% schema coverage the baseline would be 3, but the description adds real meaning for the undocumented `children` enum (all = wait for every child to stop working, any = return on the next child event) and clarifies whose children are waited on by default. That fills the schema's one genuine 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 precise completion conditions: agent reports idle/done/blocked/error, program exit, or (with `output`) text appearing. The two wait modes are clearly delineated. It does not name a sibling such as herdr_status or herdr_get to contrast with, so an 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?

"Use it instead of sleeping or polling" plus the explicit note that a timeout is a check-in (ended=false) and that you should wait again gives strong operational guidance, including the retry loop. What's missing is when not to use it or which sibling to choose instead.

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