Server Quality Checklist

Tool Scores

• herdr_agent_startA
  3.7/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the full burden. It discloses the main side effect (launching an agent), the return value, and a specific failure/retry behavior. However, it does not elaborate on what 'launch' entails (e.g., whether it blocks, if it mutates pane state) or describe the structure of the returned agent info.

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

  Conciseness5/5

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

  The description is three short sentences: purpose, return value, and retry caveat. Every sentence earns its place, with no filler, and the most important information (launch action) comes first.

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

  Completeness3/5

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

  This tool has 5 parameters, no output schema, and no annotations, so the description needs to provide context. It covers the launch action and retry behavior, but does not mention prerequisites (e.g., needing an existing pane) or what to do after launch (e.g., using herdr_agent_prompt). The description is adequate but leaves several operational questions unanswered.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the baseline is 3. The description adds no extra parameter-specific meaning; the schema already documents each parameter and its constraints (e.g., timeout_ms range, kind='opencode').

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

  Purpose5/5

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

  The description uses the specific verb 'Launch' and identifies the resource as 'an opencode agent in a pane', clearly distinguishing this from sibling agent tools like herdr_agent_prompt or herdr_agent_get. It also explicitly states the immediate outcome: 'Returns agent info.'

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

  Usage Guidelines3/5

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

  The description provides practical retry guidance when the pane is not ready, but does not explicitly state when to use this tool versus alternatives such as herdr_agent_prompt or herdr_agent_get. It implies the usage context (you need a pane and want to start an agent) but lacks explicit exclusions or contrasts.

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

• herdr_tab_getA
  3.8/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the transparency burden. It discloses the returned fields but does not mention error behavior, absence handling, or explicitly confirm that this is a read-only operation beyond the verb 'Get'.

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

  Conciseness5/5

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

  The description is a single sentence with the action and resource front-loaded. Every word earns its place; there is no redundancy or filler.

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

  Completeness4/5

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

  For a simple getter with one parameter and no output schema, the description provides sufficient context: it identifies what the tool retrieves and lists the return fields. The return field list compensates for the missing output schema, though a brief note on not-found behavior would improve completeness.

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

  Parameters3/5

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

  The schema already provides 100% coverage for tab_id with an example format (w1:t1). The description adds no additional parameter semantics beyond what the schema provides, so the baseline of 3 applies.

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

  Purpose5/5

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

  Clearly states the verb 'Get' and the resource 'single tab by id', distinguishing it from siblings like herdr_tab_list. It also enumerates the returned fields, leaving no ambiguity about scope.

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

  Usage Guidelines3/5

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

  The phrase 'by id' implies use when the tab ID is known, but there is no explicit comparison to alternatives like tab_list or pane_get. No exclusions or when-not-to-use guidance is provided.

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

• herdr_tab_listA
  3.8/5.0
  Behavior3/5

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

  With no annotations, the description must convey behavioral traits itself. It discloses the return fields and the optional workspace filter, but does not explicitly state read-only safety, no side effects, or potential ordering/pagination quirks. For a simple list operation, this is adequate but not comprehensive.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with 'List tabs', and each phrase adds essential information: optional filter and returned fields. There is zero redundancy or filler.

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

  Completeness4/5

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

  Given one optional parameter and full schema coverage, the description provides the key return fields (tab_id, label, pane_count, agent_status), making it functional for an agent. It omits the response shape and edge-case behavior (e.g., invalid workspace_id), but for a simple list tool this is largely adequate.

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

  Parameters3/5

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

  The schema describes workspace_id as 'Only list tabs of this workspace (optional).' The description mirrors this by saying 'optionally filtered to a workspace' without adding extra details like format or default behavior. Since schema coverage is 100%, the description adds no additional parameter semantics beyond the baseline.

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

  Purpose5/5

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

  The description clearly states the action ('List tabs') and the resource ('tabs'), with an optional filter by workspace. It distinguishes from sibling tools like herdr_tab_get by using 'List' and from list tools for other resources. It also previews return fields, making the purpose unambiguous.

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

  Usage Guidelines3/5

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

  The description implies usage for enumerating tabs with optional filtering but provides no explicit guidance on when to prefer this over alternatives like herdr_tab_get or herdr_pane_list. No exclusions or when-not-to-use scenarios are mentioned, leaving selection to inferred context.

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

• herdr_worktree_createA
  3.8/5.0
  Behavior3/5

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

  With no annotations, the description carries the burden of behavioral disclosure. It adds useful context: return values (workspace_id, root_pane.pane_id) and a potential retry condition for agent.start. However, it does not discuss side effects such as repository mutation, permissions, or reversibility, which are important for a creation tool.

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

  Conciseness5/5

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

  The description is three sentences, front-loaded with the main purpose, followed by return values and a practical caveat. Every sentence contributes unique information with no redundancy or filler.

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

  Completeness4/5

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

  The tool is moderately complex (6 parameters, no output schema, no annotations). The description covers the core action, return values, and a specific edge case. However, it lacks details on how the workspace/agent integration works and does not explicitly explain the role of optional parameters like base or focus, though these are documented in the schema.

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

  Parameters3/5

  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 each parameter. The description adds no additional parameter-level meaning beyond what the schema provides, only referencing the overall purpose. This matches the baseline of 3 for full schema coverage.

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

  Purpose5/5

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

  The description states a specific action: 'Create a git worktree and open it as a herdr workspace.' It clearly identifies the resource (git worktree) and the effect (opening it as a workspace). This distinguishes it from sibling tools like herdr_worktree_list and herdr_worktree_remove.

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

  Usage Guidelines3/5

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

  The description implies when to use this tool (when a new worktree and workspace are needed) but does not explicitly mention alternatives or exclusions relative to sibling tools. No guidance is given on when not to use it or what other tools might be more appropriate.

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

• herdr_worktree_listA
  3.8/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the burden of behavioral disclosure. It indicates a read-only listing operation through the verb 'List' and lists return fields, but does not disclose edge-case behavior, scoping effects of workspace_id, or potential side effects. This is adequate but not rich.

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

  Conciseness5/5

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

  The description is a single sentence that front-loads the action and resource, then concisely lists the return fields. Every word adds value and there is no redundant or filler content.

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

  Completeness4/5

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

  For a simple listing tool with two optional parameters and no output schema, the description covers purpose and return shape sufficiently. It does not explain pagination, ordering, or behavior with no worktrees, but these are not critical for basic use. The absence of annotations is partly mitigated by the clear read-only verb.

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

  Parameters3/5

  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 tool description adds no extra semantic detail about cwd or workspace_id beyond what the schema provides, landing at the baseline.

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

  Purpose5/5

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

  The description uses a specific verb ('List') and resource ('git worktrees for a repository'), clearly distinguishing it from sibling tools like herdr_worktree_create and herdr_worktree_remove. It also enumerates the returned fields, removing ambiguity about what the tool does.

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

  Usage Guidelines3/5

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

  Usage is implied by the phrase 'for a repository' and the optional cwd parameter, but the description does not explicitly state when to use this tool over alternatives, nor does it mention when not to use it. No exclusions or alternative tool references are provided.

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

• herdr_pane_wait_for_outputA
  3.9/5.0
  Behavior3/5

  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 discloses the blocking nature ('Block until') and return type ('Returns the matched output lines'), but does not explain timeout behavior (e.g., what happens if timeout_ms is exceeded), error conditions, or whether the tool consumes or clears output. This is moderate but incomplete.

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

  Conciseness5/5

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

  The description is two sentences long, front-loads the core action, and contains no filler. Every phrase adds value: the blocking behavior, the match criterion, the efficiency note, and the return outcome. It is ideal in size and structure.

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

  Completeness3/5

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

  The tool has 6 parameters (including a nested match object) and no output schema, so the description must explain both usage and return. It covers the basic flow (block until match, return lines) but omits important context such as timeout behavior, how 'source' affects which buffer is watched, and what counts as 'matched output lines' across buffer types. This leaves gaps for an agent trying to invoke it correctly in edge cases.

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

  Parameters3/5

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

  Schema description coverage is 100%, and the schema already explains each parameter (e.g., match type, source, lines, timeout_ms). The description adds minimal semantic value beyond that, mainly reaffirming the matching concept ('substring or regex') and the return. Given the high coverage, a baseline 3 is appropriate.

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

  Purpose5/5

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

  The description states a specific verb ('Block until') and resource ('pane output'), and clearly identifies the triggering condition ('matches a substring or regex'). This distinguishes it from sibling tools like herdr_pane_get, which return output immediately, and herdr_pane_send_input, which writes. 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.

  Usage Guidelines4/5

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

  The description explicitly says 'More efficient than polling,' which tells the agent to use this tool instead of repeatedly calling a read tool. However, it does not name the alternative tool (e.g., herdr_pane_get) or provide an explicit 'when not to use' exclusion, 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.

• herdr_agent_getA
  4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the burden of behavioral disclosure. It usefully lists the returned fields (agent_status, terminal_title, interactive_ready) and notes the nested location of agent_status, adding value. However, it does not explicitly state that the operation is read-only or describe side effects, though the 'get' verb strongly implies safety.

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

  Conciseness5/5

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

  The description is two sentences long, with the main purpose in the first sentence and supplementary details in the second. It is front-loaded and contains no filler, making it highly concise and easy to parse.

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

  Completeness4/5

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

  For a simple one-parameter getter without an output schema, the description adequately explains the return payload and the nesting of agent_status. It could optionally mention error scenarios, but the essential information is present for an agent to decide whether to invoke this tool.

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

  Parameters3/5

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

  The input schema already fully describes the 'target' parameter with 100% coverage, including the same valid target types. The description merely repeats this information without adding new semantic context, matching the baseline for schema-covered parameters.

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

  Purpose5/5

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

  The description clearly states the tool's function with the verb 'Get' and resource 'agent info', and specifies the target types (pane id, session id, path). It distinguishes itself from sibling tools like herdr_agent_start, herdr_agent_prompt, and herdr_agent_wait by focusing on retrieving current state rather than initiating actions.

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

  Usage Guidelines3/5

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

  The description implies usage for checking agent status, but it does not explicitly state when to use this tool versus alternatives such as herdr_agent_wait or herdr_agent_read. No exclusions or alternative tools are mentioned, so the guidance relies on inference from the name and description.

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

• herdr_agent_promptA
  4/5.0
  Behavior3/5

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

  No annotations are present, so the description carries the full burden. It discloses a key behavior: the tool may block until the agent reaches a status. However, it does not mention potential errors, timeouts, side effects, or return values. The write nature is evident from 'Send a prompt', but disclosure of consequences is limited.

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

  Conciseness5/5

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

  The description is a single, well-structured sentence that front-loads the primary action and follows with the optional blocking behavior. Every word earns its place; it is concise without being under-specified.

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

  Completeness4/5

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

  The description covers the core functionality (send prompt, optionally wait for statuses) and the parameter schema is thorough. Minor gaps exist around error handling and return value, but for a 3-parameter tool with no output schema, the description provides sufficient context.

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

  Parameters3/5

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

  The input schema already provides complete descriptions for all three parameters (target, text, wait) with 100% coverage. The description adds no new parameter-level meaning beyond repeating the wait behavior. Thus, the baseline of 3 applies.

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

  Purpose5/5

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

  The description clearly states the primary action: 'Send a prompt to an agent running in a pane.' This distinguishes it from siblings like herdr_agent_send_keys (sends keys) and herdr_pane_send_input (sends generic input) by focusing on 'prompt' to an 'agent'. The optional blocking on statuses adds specific scope.

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

  Usage Guidelines4/5

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

  The description implies the use case: when you need to send a textual prompt to an agent and optionally wait for a status. It provides clear context (agent in a pane, statuses to wait for) but does not explicitly name alternatives or exclusions, so an agent must infer when to prefer this over related tools.

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

• herdr_agent_send_keysA
  4/5.0
  Behavior3/5

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

  With no annotations, the description carries the full burden. It mentions the effect of sending CtrlC to interrupt a stuck agent, which implies the tool can affect running processes. However, it does not disclose potential side effects, error conditions, or whether the operation is asynchronous. More detail would improve transparency.

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

  Conciseness5/5

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

  The description is two sentences long, front-loads the action, and includes concrete examples (CtrlC, Enter, Escape). Every sentence adds value without unnecessary elaboration.

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

  Completeness4/5

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

  For a simple tool with two fully described parameters and no output schema, the description effectively communicates purpose and common use cases. It could mention expected response behavior, but this is not critical given the simplicity.

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

  Parameters3/5

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

  The schema already provides descriptions for both parameters (keys and target) with examples. The tool description does not add additional meaning beyond what the schema offers, so the baseline of 3 for high schema coverage applies.

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

  Purpose5/5

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

  The description clearly states the action ('Send key presses') and the target ('an agent's terminal'). It also specifies key use cases (recovery, TUI navigation) which helps differentiate it from sibling tools like herdr_pane_send_input.

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

  Usage Guidelines4/5

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

  The description provides when-to-use context by mentioning recovery and TUI navigation, but it does not explicitly mention alternatives or when not to use the tool. This is clear enough for an experienced agent to decide.

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

• herdr_agent_waitA
  4/5.0
  Behavior3/5

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

  With no annotations, the description is responsible for behavioral disclosure. It does communicate the blocking nature and the statuses being waited on, but it omits important behavioral details such as timeout behavior, whether it returns immediately if already in the target status, or what the return value looks like.

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

  Conciseness5/5

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

  The description is two sentences with no wasted words. The first sentence defines the behavior and lists statuses; the second sentence gives practical usage context. It is front-loaded and every sentence earns its place.

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

  Completeness4/5

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

  The tool is simple, all three parameters are fully documented in the schema, and the description covers the core behavior and usage alternative. The only notable gap is the lack of timeout/return-value detail, but this is a minor omission for a blocking wait primitive without an output schema.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the baseline is 3. The description does not add any parameter meaning beyond what the schema already provides; it mentions statuses inline but does not explain timeout defaults or the target/pane id format.

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

  Purpose5/5

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

  The description uses a specific verb ('Block') plus a resource ('agent') and explicitly enumerates the target statuses. It also distinguishes itself from the polling alternative by name, making its purpose clear and distinct from sibling tools like herdr_agent_get.

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

  Usage Guidelines4/5

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

  The description clearly positions this as an 'Alternative to polling agent.get in a loop,' giving explicit context for when to use it instead of a polling loop. It does not list exclusions or when-not-to-use scenarios, but the alternative reference provides strong practical guidance.

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

• herdr_pane_listA
  4/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the full burden. The verb 'List' implies a read-only operation, and the description discloses the output fields. However, it doesn't explicitly state that it has no side effects, or mention any access/privacy considerations. For a simple list operation, this is adequate but could be more explicit.

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

  Conciseness5/5

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

  Two concise sentences: the first states the action and optional filter, the second specifies the returned fields. No unnecessary words, and the structure is well-organized for quick scanning.

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

  Completeness4/5

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

  For a low-complexity list tool with one optional parameter and no output schema, the description is sufficiently complete. It covers purpose, scope, and return contents. It omits details like ordering or pagination, but these are not critical for a fundamental list operation, so the description meets the needs.

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

  Parameters3/5

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

  The input schema covers the only parameter (workspace_id) with a clear description, achieving 100% coverage. The tool description repeats this information without adding new meaning or format details. Since the schema does the heavy lifting, the baseline score of 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states 'List all panes' with an optional workspace filter, using a specific verb and resource. It distinguishes from sibling pane_get by indicating this returns all panes, not a single one. Including the fields (pane_id, cwd, agent_status) further clarifies scope.

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

  Usage Guidelines4/5

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

  The description conveys a clear use case: when you need an overview of panes, optionally scoped to a workspace. It doesn't explicitly mention alternatives or when not to use it, but among sibling tools like pane_get or pane_split, the listing purpose is self-evident, so context is clear.

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

• herdr_pane_send_inputA
  4/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the burden of disclosing behavior. It explains the key naming convention ('like Enter, CtrlC, Backspace') and mentions the combined text/keys capability. However, it does not disclose side effects, whether input appends or replaces, or what the return value is. The added context is helpful but not comprehensive.

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

  Conciseness5/5

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

  The description is compact and front-loaded: the main action appears in the first sentence, followed by use cases and key-name examples. Every sentence provides useful information without unnecessary fluff. This is appropriately sized for the tool's simplicity.

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

  Completeness4/5

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

  For a simple send-input tool with no output schema and no annotations, the description covers the core purpose, usage context, and key format. It does not explain return values or prerequisites explicitly, but the tool's operation is straightforward and the description offers enough to invoke it correctly. Sibling tools like herdr_pane_wait_for_output complement it, so the boundary is clear.

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

  Parameters3/5

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

  The input schema already has 100% description coverage for all three parameters, so the baseline for this dimension is 3. The tool description adds marginal value by clarifying that text and keys can be sent together ('and/or'), but it largely restates what the schema already conveys. No additional semantic detail is required.

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

  Purpose5/5

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

  The description clearly states the tool's action: 'Send text and/or key presses to a pane in one call.' It specifies the resource (pane) and the verb (send), and distinguishes it from sibling tools like herdr_agent_send_keys by targeting panes. The mention of warm-up (PING_REPLY_WITH_PONG) and sending commands further clarifies its scope.

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

  Usage Guidelines4/5

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

  The description gives clear usage context: 'Used for warm-up (PING_REPLY_WITH_PONG) and sending commands.' This implies when to use it, but it does not explicitly name alternative tools or conditions for NOT using it. Thus, it meets the 'clear context, no exclusions' level.

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

• herdr_pane_splitA
  4/5.0
  Behavior3/5

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

  No annotations are provided, so the description must carry the transparency burden. It discloses the primary action and return value, but does not mention side effects such as resizing the original pane or focus change behavior, which would be useful for an agent.

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

  Conciseness5/5

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

  Two sentences, both informative and front-loaded: the first states the action and result, the second gives a practical use case. No wasted words.

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

  Completeness4/5

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

  With the schema covering all parameters, the description adequately provides the return value and typical usage scenario. It could include edge cases or failure modes, but the tool is moderate in complexity and the essentials are present.

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

  Parameters3/5

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

  The input schema already describes all five parameters with 100% coverage. The description adds no extra parameter details beyond reiterating the 'direction' options already present in the schema.

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

  Purpose5/5

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

  The description clearly states the verb 'Split' and the resource 'a pane', explaining the outcome as 'creating a new pane to the right or below'. This distinguishes it from sibling pane tools like list/get/send_input/wait_for_output.

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

  Usage Guidelines4/5

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

  The phrase 'Essential for launching reviewers in a clean pane' provides a clear use case, suggesting when to choose this tool. However, it does not explicitly say when not to use it or recommend alternative tools.

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

• herdr_workspace_listA
  4/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the full burden. It states the read-only nature implicitly via 'list', but does not disclose details such as whether the result is ordered, paginated, or what 'open' means. For a simple list tool this is acceptable but lacks richer behavioral context.

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

  Conciseness5/5

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

  The description is a single, front-loaded sentence that efficiently conveys the operation with zero wasted words. It is concise and well-structured.

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

  Completeness4/5

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

  Given the tool's simplicity (no parameters, no output schema), the description is reasonably complete. It states the primary behavior clearly. However, it does not describe the return format or any edge cases, which would make it fully complete.

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

  Parameters4/5

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

  The input schema has zero parameters, and the 100% schema coverage baseline gives a score of 4. The description does not need to add parameter semantics since there are none, and no gaps exist.

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

  Purpose5/5

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

  The description 'List all open workspaces in herdr' clearly states the action (list) and the resource (workspaces), with an explicit scope ('all open'). This distinguishes it from sibling tools like herdr_workspace_get, which presumably retrieves a single workspace.

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

  Usage Guidelines3/5

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

  The description implies usage for listing all workspaces but does not explicitly contrast with alternatives like herdr_workspace_get or state when to choose this tool over others. Sibling names give context, but no direct guidance is provided.

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

• herdr_agent_readA
  4.2/5.0
  Behavior3/5

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

  With no annotations, the description carries the full burden. It discloses that the tool reads output and gives a concrete scenario, but does not explain behavior like default line count, whether it waits, or how 'recent' is defined, leaving some ambiguity.

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

  Conciseness5/5

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

  Three sentences, front-loaded with the core action, then purpose, then an example. No wasted words.

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

  Completeness4/5

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

  The schema is rich with descriptions, and the description covers the tool's main use cases. It could mention more about the source options or return structure, but for a read tool with no output schema, it is sufficient for basic use.

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

  Parameters4/5

  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 value by suggesting specific parameter values ('~400 lines', 'recent') for warm-up, which gives practical meaning beyond the schema's generic descriptions.

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

  Purpose5/5

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

  The description states a specific action ('Read recent output from an agent's terminal') and explains its purpose (checking for TASK_COMPLETE, blocked questions, or any output). It clearly differentiates from sibling tools like herdr_pane_wait_for_output by focusing on reading output directly.

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

  Usage Guidelines4/5

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

  It explicitly identifies when to use the tool—to check for TASK_COMPLETE, blocked questions, or agent output—and provides a concrete warm-up example with ~400 lines from 'recent'. However, it does not mention when not to use it or name alternative tools explicitly, so it lacks exclusions.

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

• herdr_pane_getA
  4.2/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden. It discloses the exact data fields returned, establishing the tool as a read-only getter. It does not mention error conditions or side effects, but for this simple get operation the return-field list provides adequate transparency.

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

  Conciseness5/5

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

  The description is a single concise sentence that front-loads the purpose and lists return fields without unnecessary words. It is well-structured and efficient.

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

  Completeness4/5

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

  For a tool with one parameter and no output schema, the description adequately covers what the tool does, the input, and the output fields. It lacks some context about error handling or prerequisites, but given the simplicity of the tool, it is sufficiently complete.

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

  Parameters3/5

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

  The schema description for pane_id is already complete with a format example (w1:p1), and the description does not add additional parameter-level details. Since schema coverage is 100%, a baseline of 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the tool gets pane info by ID and lists the specific fields returned (cwd, terminal_id, etc.), making its purpose unambiguous. It distinguishes itself from sibling tools like herdr_pane_list (which presumably lists panes) and herdr_pane_split (which modifies panes).

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

  Usage Guidelines4/5

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

  The description implies usage for retrieving details of a specific pane by its ID, which is evident from the tool name and description. However, it does not explicitly mention when NOT to use it or name alternatives, though the sibling set makes the distinction clear.

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

• herdr_session_snapshotA
  4.2/5.0
  Behavior3/5

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

  With no annotations, the description carries the transparency burden. 'Dump' suggests a read-only operation, but it does not explicitly state non-destructiveness or describe the output shape/size. It adds context about intended use (debugging) and components, but lacks deeper behavioral disclosure.

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

  Conciseness5/5

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

  Two short sentences, front-loaded with the core action and followed by a concise list of contents. Every word is informative with no redundancy.

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

  Completeness4/5

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

  For a zero-parameter tool with no output schema, the description adequately explains what the tool does and when to use it. It could optionally mention return format or volume, but the component list provides sufficient context for a debugging snapshot.

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

  Parameters4/5

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

  The tool has zero parameters, so the baseline of 4 applies. There is no parameter information needed, and the description correctly focuses on behavior rather than inputs.

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

  Purpose5/5

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

  Clear verb+resource: 'Dump the full herdr session' with an explicit enumeration of contents (workspaces, tabs, panes, layouts, agents). This distinguishes it from sibling per-entity getters by emphasizing a complete snapshot.

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

  Usage Guidelines4/5

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

  States it is 'useful for debugging the entire state at once,' which implies a when-to-use scenario. It does not explicitly mention alternatives, but the contrast with sibling list/get tools is reasonably clear.

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

• herdr_workspace_getA
  4.2/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden. It discloses what is returned, including the conditional 'worktree info if linked', which is useful. The verb 'Get' strongly implies a read-only operation, but error behavior is not mentioned, so it misses a perfect score.

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

  Conciseness5/5

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

  The description is a single, front-loaded sentence that conveys action, target, and return value with zero filler. Every word earns its place.

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

  Completeness4/5

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

  For a simple getter with one parameter and no output schema, the description adequately conveys what the tool does and returns. It could mention behavior on invalid IDs, but given the low complexity, it is sufficiently complete for an agent to select and invoke it.

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

  Parameters3/5

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

  The input schema already provides full description of the sole parameter (workspace_id with format example), and the tool description adds no additional parameter semantics. With schema coverage at 100%, the baseline of 3 is appropriate.

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

  Purpose5/5

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

  The description states 'Get a single workspace by id' with a specific verb and resource, clearly distinguishing it from herdr_workspace_list. It also lists the return contents (label, tab/pane count, worktree info if linked), making the tool's purpose unambiguous.

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

  Usage Guidelines4/5

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

  The description clearly implies usage when you have a specific workspace id, and the contrast with the sibling 'workspace_list' is evident. However, it does not explicitly state when not to use it or name alternatives, so it falls short of a full 5.

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

• herdr_pingA
  4.3/5.0
  Behavior3/5

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

  The description discloses that the tool returns server version and protocol, giving insight into its output. However, it does not explicitly state that it is a read-only, non-destructive operation, which would be helpful given the absence of annotations.

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

  Conciseness5/5

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

  The description consists of two short sentences, front-loaded with the action verb, and contains no unnecessary information. Every word earns its place.

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

  Completeness5/5

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

  For a zero-parameter, simple ping tool with no output schema or annotations, the description covers the essential purpose and return values, making it complete in context.

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

  Parameters4/5

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

  The tool takes no parameters, so the description does not need to explain parameter semantics. The baseline score of 4 is appropriate for a zero-parameter tool.

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

  Purpose5/5

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

  The description uses the specific verb 'Ping' and identifies the resource 'herdr server', making its purpose unmistakable. It also distinguishes itself from sibling tools that handle sessions, workspaces, tabs, etc., which are all different actions.

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

  Usage Guidelines4/5

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

  The description implies the tool is used to check server connectivity and retrieve version/protocol info, which is clear from the context. However, it does not explicitly provide when-to-use guidance or compare with alternatives, though no direct alternatives exist for a ping operation.

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

• herdr_worktree_removeA
  4.5/5.0
  Behavior5/5

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

  With no annotations, the description carries the full burden and does exceptionally well. It immediately warns 'Destructive', states exactly what is deleted (worktree checkout), what else happens (closes its workspace), and what is NOT deleted (git branch). This exceeds typical transparency for destructive tools.

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

  Conciseness5/5

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

  Two sentences, front-loaded with a warning, and every word earns its place. Efficient and clear.

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

  Completeness5/5

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

  For a destructive tool with no annotations and no output schema, this description is remarkably complete. It communicates the primary behavior, the secondary effect (closing workspace), and an explicit non-goal (branch deletion), making it a reliable basis for agent invocation.

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

  Parameters3/5

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

  Schema coverage is 100%, so the description need not explain parameters. The description does add context around workspace_id by saying it 'closes its workspace', but this is largely redundant with the schema's 'Workspace of the worktree to remove.' No significant extra value is added for force, though the destructive warning hints at its relevance.

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

  Purpose5/5

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

  The description uses a specific verb ('deletes') and resource ('worktree checkout') and adds key specificity by noting it also closes the workspace. It clearly distinguishes from siblings like herdr_worktree_create and herdr_worktree_list, and explicitly separates branch deletion via 'Does NOT delete the git branch'.

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

  Usage Guidelines4/5

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

  Provides clear context on what the tool does and indirectly when to use it (when removing a worktree). It explicitly names the alternative for branch deletion ('use git branch -D separately'), giving an exclusion. However, it doesn't explicitly compare to other herdr tools or state prerequisites like needing to list worktrees first.

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