herdr-mesh

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.1.0-safe.13
Disambiguation4/5
Most tools have clearly distinct purposes, especially within their domains (leases, handoffs, agent ops, workspace queries). Some overlap exists between wait variants (herdr_agent_wait, herdr_agent_wait_settled, herdr_agent_wait_any) and handoff tools (relay vs. handoff vs. batch), but each description clarifies the unique use case, reducing misselection risk.
Naming Consistency5/5
All tools follow the consistent pattern 'herdr_<domain>_<subdomain>_<action>' with snake_case throughout. Verbs like list, get, read, wait, start, close, renew, release appear in predictable positions, making the API easy to navigate and guess.
Tool Count2/5
With 44 tools, the server exceeds the typical well-scoped range. While the domain is complex, the surface is bloated with many near-duplicate read-only list/get/read tools for every entity (agent, pane, tab, workspace, lease types). This will likely overwhelm agents and increase selection errors, even if each tool individually is justified.
Completeness4/5
The surface covers the core lifecycle comprehensively: controller leases (acquire/resume/takeover/renew/release), worker/reviewer management, handoff workflows, verification, and pane adoption/cleanup. Minor gaps exist (e.g., no API to update or modify workspace entities), but these are peripheral and do not block primary coordination workflows.
Average 3.3/5 across 44 of 44 tools scored. Lowest: 2/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 4 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. 'Get' implies a read operation, but it does not explicitly state side-effect-free behavior, permissions, or response format. The description is too minimal to inform an agent about runtime behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
It is a single, short sentence with no fluff, but it is under-specified. It is concise but not informative enough to be useful, so it earns a neutral score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/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 annotations or output schema, the description still leaves critical gaps: what fields are returned, any filtering or pagination, and how it differs from tab_list. It is too minimal for an agent to call successfully without guessing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter tab_id has 0% schema description coverage, and the description never explains what tab_id represents or how it should be formatted. The schema only says it's a string, so the description adds no value beyond that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a clear verb ('Get') and resource ('a tab'), but 'details' is vague and does not distinguish from sibling tools like herdr_tab_list or herdr_pane_get. It communicates the basic action but lacks specificity about what details are included.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. There is no mention of context, exclusions, or trade-offs. An agent has no help deciding between this and herdr_tab_list or other similar getters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full burden of behavioral disclosure. It only mentions renewing a lease without explaining side effects, constraints (e.g., ttl_seconds bounds), failure conditions, or whether it requires the caller to be the current holder. This is minimal and insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words, but it is under-specified rather than concise. It omits essential usage and parameter information, so it is not appropriately sized for the complexity of the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 parameters, no output schema, and no annotations, this description is grossly incomplete. It lacks parameter semantics, behavioral details, and usage context. An agent cannot correctly invoke this tool based on the provided information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain the parameters. It does not define controller_id, controller_lease_id, controller_fence_token, or ttl_seconds. The vague phrase 'exact Herdr pane and identity' does not map to these parameters, leaving the agent without meaning beyond raw property names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('renew') and resource ('active controller lease'), and hints at the requirement of an exact pane and identity. It distinguishes itself from controller_acquire/release/takeover by its unique verb, but does not explicitly name alternatives or contrast with them. Clear but not fully differentiated from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus sibling tools like controller_resume, controller_takeover, or controller_release. There is no context about the lifecycle of leases or selection criteria. The description only states what the tool does, not when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavior. It simply says 'Get details' without stating whether this is a read-only operation, what the response format is, or any error conditions. While 'get' implies non-mutation, it does not provide meaningful behavioral transparency beyond the operation name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence with no unnecessary words. It is front-loaded and easy to parse. However, it is under-specified, so while it is concise, it sacrifices clarity for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a simple getter with one parameter and no output schema, the description should at least explain what 'details' means and how to use pane_id. It does neither. It also lacks any differentiation from sibling tools, making it incomplete for an agent to confidently select and invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only a required string pane_id with no description. The description says 'for a pane', which minimally suggests pane_id identifies the pane, but it does not explain how to obtain a valid ID, what format it should be in, or any additional semantics. With 0% schema description coverage, the description should compensate more substantially.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get details for a pane' provides a verb and resource, but 'details' is vague and does not specify what details are included. It also does not distinguish from sibling tools like herdr_pane_read, which could also be interpreted as retrieving pane information. The purpose is somewhat unclear without additional context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives such as herdr_pane_list or herdr_pane_read. There is no mention of context, preconditions, or exclusions. An agent is left to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/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 implies a read-only operation via 'list' but does not explicitly confirm non-destructive behavior, nor does it explain what 'collection state' entails or whether any side effects occur. The description is too terse to be transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is technically concise, but it is under-specified. The instruction warns that under-specification is not the same as conciseness; here, the brevity sacrifices crucial information, earning a low score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's place among many similar handoff and collection tools, the description offers no context about its role, return format, or expected use cases. There is no output schema, and the description fails to clarify key terms like 'content-free' and 'collection state', making it incomplete for correct agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, controller_id, is optional and undocumented in both the schema and the description. With 0% schema description coverage, the description is expected to compensate, but it does not mention the parameter at all, leaving the agent without any semantic context for this value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('List') and a specific resource ('handoff receipts'), and adds the qualifiers 'content-free' and 'collection state', which help distinguish it from other handoff-related tools. However, it does not explicitly name sibling tools or explain what 'content-free' means, so it is not a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus its many siblings such as herdr_handoff, herdr_collect_handoffs, or herdr_handoff_receipt_abandon. The description does not state any conditions, prerequisites, or alternative routing, leaving the agent to infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/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 says 'collect' but does not explain what happens to the receipts—whether they are removed, acknowledged, returned in the response, or if the operation is idempotent. It also omits any mention of side effects, required permissions, or the meaning of the controller tokens. For a mutation-like operation, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the core purpose and the count constraint. It is efficiently worded, but given the complexity of the tool (7 parameters), the brevity may be under-specification rather than conciseness. However, it presents the key differentiator ('without submitting another prompt') clearly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 parameters, no annotations, and no output schema, the description is profoundly incomplete. It does not explain what a handoff receipt is, what 'collecting' entails, what the response format is, or why controller tokens are required. An agent cannot correctly invoke this tool with full confidence based on the description and schema alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description provides virtually no parameter semantics. It implies the receipts array holds the items to collect (via the 'one to eight' range), but it does not explain the roles of controller_id, controller_lease_id, controller_fence_token, mode, read_lines, or timeout_ms. The description does not compensate for the schema's lack of explanatory text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action ('collect') and the target resource ('pending handoff receipts') with a specific count range (one to eight) and a distinguishing nuance: it happens without submitting another prompt. This is clear, but it does not explicitly contrast with sibling tools like herdr_handoff_receipt_list or herdr_batch_handoff, 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.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus its siblings. The phrase 'without submitting another prompt' hints at a context, but it does not name alternatives or conditions that would select this tool over herdr_handoff_receipt_list or herdr_batch_handoff. No exclusions or prerequisites are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose side effects. 'Release' implies a mutation, but the description does not state what happens to the barrier, whether the action is idempotent, or what occurs if the precondition isn't met. The 'explicitly' modifier suggests caution but adds no concrete behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that front-loads the core action. It avoids verbosity, but the brevity comes at the cost of important detail. Still, it is efficiently structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with four required parameters, no annotations, and no output schema, this description is far too sparse. It fails to explain the meaning of the parameters, the intended use adjacent to sibling tools, or the operational effect, making it inadequate for correct invocation by an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the four required parameters (receipt, controller_id, controller_lease_id, controller_fence_token). The agent must rely solely on the schema, which only provides types and patterns, leaving semantics completely unaddressed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action (release) and the resource (an outstanding handoff barrier), and adds a precondition (after its exact leased agent is settled). It distinguishes from listing and creation tools by the verb 'release', though it doesn't explicitly name sibling alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus the many handoff-related siblings (e.g., herdr_handoff, herdr_handoff_receipt_list). The only usage hint is the precondition 'only after its exact leased agent is settled,' which is a condition rather than guidance about selecting this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure, but it only says it prompts an agent and collects a result. It doesn't disclose whether the operation blocks, how long it waits, what happens on timeout, whether the agent's lease is affected, or what 'receipt-bound settled result' means in practice. This is a significant gap for an 8-parameter tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the core action. It wastes no words and is easy to scan. However, it is so brief that it omits critical information, so it earns a 4 rather than 5 for being efficient but not complete.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 8 parameters, 5 required, no output schema, and no annotations, the description is far from sufficient. It doesn't explain the receipt concept, result format, error conditions, or how the 'settled result' is obtained. An agent would lack critical context to call the tool correctly without additional external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no parameter-level meaning. Schema coverage is only 38%, with descriptions only for target, message, and wait_status (deprecated). The controller parameters (controller_id, controller_lease_id, controller_fence_token) are not explained in the schema or the description, so the agent must infer their purpose. The description does not compensate for the low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('Prompt one active leased agent') and outcome ('collect the exact receipt-bound settled result'). It uses a specific verb and resource, and the singular 'one' distinguishes it from batch operations like herdr_batch_handoff. However, it doesn't explicitly contrast with other single-agent tools such as herdr_relay or herdr_agent_wait, so it's clear but not fully differentiating.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. It doesn't mention conditions like 'use for a single agent handoff requiring a receipt-bound result' or exclude batch cases. Siblings like herdr_batch_handoff and herdr_collect_handoffs exist, but the description doesn't point the agent to choose this tool based on any criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 cleanup-only scope, the absence of ownership/authority transfer, and the checks performed. However, it doesn't describe side effects on the existing agent, reversibility, or required permissions, leaving significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense sentence that leads with the purpose and includes a key limitation. It is efficient with no filler, though it could be structured to highlight critical prerequisites more prominently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 14 parameters (13 required), no annotations, and no output schema, the description is far from complete. It doesn't explain how the parameters interact, what success looks like, or what preconditions must be verified. The concise description covers the high-level intent but not the execution context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 7% (only 'target' has a description), and the tool description adds no parameter-specific guidance. It references categories like identity, authority, state cursor, and protected-pane checks but does not explain any of the 14 parameters or how to construct them correctly. The agent is left to guess from names and patterns alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/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 cleanup-only lease) on a specific resource (an existing idle/done named agent), and adds the restriction that adoption grants no Git ownership or implementation authority. This is clear and not a tautology, though it doesn't explicitly differentiate from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 like herdr_owned_pane_close, herdr_controller_takeover, or herdr_owned_worker_start. It mentions preconditions (exact identity, authority checks) but not when a caller should choose 'adopt' over other operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry full behavioral disclosure. It hints at a non-destructive read and warns about context flooding with large `lines`, but it doesn't describe the return format, default behavior when `lines` or `source` are omitted, pagination, or any side effects. The caution about context flooding is a minor transparency element, but overall the behavioral surface is underexplained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: a single imperative sentence followed by a targeted caution. It's front-loaded with the core purpose and the caution is immediately relevant and useful. No redundant or verbose language.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with three parameters (one required) and no output schema, the description should explain what the tool returns, parameter defaults, and the meaning of non-obvious inputs. It only covers the action and a caution. Missing information includes what the terminal output looks like, the default of `lines` (likely all), and what `source` variations mean in practice. This is insufficient for an agent to make informed calls without additional inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (only `source` has a description). The tool description mentions `lines` but only as a caution, not its meaning or default. It does not explain `pane_id` or the semantics of the `source` enum values. With low schema coverage, the description fails to compensate for the undocumented parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Read a pane's terminal output') with a specific verb and resource. It distinguishes itself from siblings like herdr_pane_get (likely metadata) and herdr_agent_read, but doesn't explicitly name alternatives. The purpose is unambiguous but could be slightly more specific about what a 'pane' is.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The only usage guidance is 'Keep `lines` small to avoid flooding context,' which is a parameter-level caution rather than tool-selection guidance. There's no mention of when to use this tool versus sibling read tools (e.g., herdr_agent_read, herdr_pane_get) or when not to use it. No exclusions or alternative conditions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/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. 'Get' indicates a read operation, but the description does not disclose response format, error or not-found behavior, permissions, or side effects. This leaves the tool's behavior largely to inference.
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 one short, front-loaded sentence with no filler. For a one-parameter getter, this is an appropriately concise size and structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema and no annotations, the description leaves the return shape and selection criteria unspecified. It also does not clarify how to obtain the workspace ID or how this differs from workspace_list. The tool is simple, but the description remains too minimal for an agent to invoke it with full confidence.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description adds no meaning to workspace_id beyond its self-explanatory name. It does not specify that workspace_id is the unique identifier of the workspace or describe how to obtain it. With only one parameter, the gap is modest, but the description still fails to compensate for the missing schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and a clear resource ('a workspace'), so an agent can tell this is a singleton lookup rather than a list operation. It differentiates from the sibling herdr_workspace_list, though it does not explicitly name it. 'Details' is somewhat generic, 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.
Usage Guidelines2/5
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 workspace_list or other getter tools such as agent_get or pane_get. The only usage cue is the workspace_id parameter in the schema, but the description never mentions it. No when-not conditions or alternative routing are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry behavioral disclosure, and it does convey several traits: it batches up to eight independent tasks, requires active leased agents, and returns exact receipt-bound results rather than inline output. It omits failure semantics, partial-success behavior, and effects of mode/timeout, so it is adequate but not complete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The single sentence is compact, front-loaded with the action, and contains no fluff. It earns its place, though it is short given the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter tool with no annotations and no output schema, this one-liner is not enough. It omits controller lease/fencing requirements, mode semantics, timeouts, read_lines, and result routing, leaving an agent to guess at essential invocation context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description adds almost no per-parameter meaning. 'Up to eight tasks' hints at requests, but the critical controller_id, controller_lease_id, controller_fence_token, mode, read_lines, and timeout_ms parameters are left entirely unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a clear action (deliver and collect) with a specific resource (up to eight independent tasks to active leased agents) and a concrete result (exact receipt-bound results). It is distinctive enough against siblings like herdr_handoff, though it doesn't explicitly name the alternative or scope boundary.
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: this is for batch-delivering independent tasks to already leased/active agents and retrieving receipt-bound results. However, there is no explicit when-to-use vs. herdr_handoff, herdr_collect_handoffs, or the wait tools, and no exclusions or prerequisites beyond 'active leased agents.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 of behavioral disclosure. It does reveal one significant behavior: rotating the lease id and fence token, and states that conversational history is unnecessary. However, it does not mention side effects such as invalidating prior tokens, prerequisites like having an existing lease, or error conditions. This partial disclosure earns a 3.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the purpose and condition. Each sentence adds distinct information: the trigger/precondition and the mechanism/benefit. It avoids redundancy but could be slightly more explicit about parameters, though as a standalone it is well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 parameters (3 required), no output schema, and no annotations, the description is insufficient. It does not explain parameter meanings, expected return values, failure modes, or any side effects. Even with the context that this is a resume operation, an agent cannot confidently call it without understanding what authority_ref and authority_sha256 are. The description leaves significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description is the only source for parameter meaning. The description mentions 'same named Herdr agent identity' which likely relates to controller_id, but it never explicitly explains controller_id, authority_ref, authority_sha256, or ttl_seconds. There is no mapping between the description and the parameters, leaving the agent without needed semantic information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (resume coordination), the trigger condition (after clear or MCP restart), and a constraint (same named Herdr agent identity). It also mentions the core behavior of rotating lease id and fence token. However, the term 'coordination' is somewhat vague and could be more specific about what exactly is being resumed, which prevents a 5.
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 gives context about when to use this tool (after clear or MCP restart) and a precondition (same agent identity). However, it does not explicitly contrast it with sibling tools like herdr_controller_acquire or herdr_controller_renew, nor does it state when not to use it. The guidance is implied rather than explicit, so a 3 is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 of behavioral disclosure. It mentions the checks performed (identity, state, cursor, controller, checkpoint) and explicitly states that files, worktrees, and branches are preserved, which is valuable. However, it does not disclose what happens to the pane itself beyond 'close' (e.g., whether it is deleted, returned as a result), nor any side effects or error conditions. It adds some context beyond the schema but lacks critical details for a destructive-looking operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is relatively concise and front-loads the primary action ('Capture and close'). It uses dense technical jargon but does not waste words. The structure is straightforward, though the list of checks is compressed into a stream of terms that could be parsed more cleanly. Overall, it is appropriately short for the information it conveys.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 8 parameters (7 required), no annotations, no output schema, and a complex domain, the description is insufficiently complete. It does not explain the return value, error handling, or the meaning of 'capture.' It mentions preservation of files/worktrees/branches but not what happens to the pane itself. Given the complexity of the operation, an agent would need additional documentation or schema descriptions to use it safely and correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero description coverage for its 8 parameters, so the description must compensate by explaining their meanings. The description mentions vague groupings like 'exact identity, idle/done state, fresh state cursor, controller, and durable checkpoint checks' which may correspond to parameters but does not map them explicitly. It fails to clarify what lease_id, controller_id, checkpoint_ref, etc. actually represent or how they should be filled. An agent reading the description would not know what each parameter needs or why, making correct invocation difficult.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/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: close a pane, specifically a cleanup-only adopted pane, and mentions preservation of files/worktrees/branches. It distinguishes itself from siblings by specifying 'cleanup-only adopted pane' and the checks performed. The verb 'capture' is somewhat ambiguous, and it doesn't explicitly name the resource type in the same way a simpler definition would, but the core purpose is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. It mentions 'cleanup-only adopted pane' which hints at a use case, but there is no comparison to sibling tools like herdr_owned_reviewer_close or herdr_owned_worker_release, and no conditions for when this is the right choice. The agent must infer from the name and the 'cleanup-only' phrase, which is insufficient for a tool with many siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 and does add meaningful safety disclosure: 'This is read-only and executes no repository code.' This is genuinely useful beyond what the name conveys. However, it stops there — it doesn't disclose outcomes on digest mismatch, whether prior settlement is required, or whether holding a lease is a precondition.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler; the primary return payload is front-loaded in the first sentence and the safety qualifier is tucked efficiently into the second. Nothing extraneous, though the structure is entirely adequate rather than exemplary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite moderate complexity (5 required params, 0% schema coverage, no output schema, no annotations), the description explains neither the parameters' roles nor the expected output shape. An agent cannot independently construct correct values for expected_head/expected_status_sha256 or understand the verification context. Sufficient for a caller who already knows the values, but too thin for autonomous selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so all 5 required parameters are undocumented in both the schema and the description. The prose mentions 'Git status digest' (maps weakly to expected_status_sha256) and settled identity, but never clarifies what lease_id, controller_id, base_commit, or expected_head mean, nor that the expected_* fields are the values the caller asserts. At 0% coverage, the description must compensate and does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Return') and a precise resource ('exact settled writer identity, Git status digest, and content digest used to authorize a host verification'). This clearly distinguishes a snapshot/inspection tool from its siblings herdr_owned_worker_verify (performs verification) and herdr_owned_worker_verification_list (lists records). Slightly docked because it doesn't name the sibling it is not, but 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the tool returns but gives no explicit when/when-not guidance or named alternatives. An agent must infer that this is the inspection counterpart to herdr_owned_worker_verify and herdr_owned_worker_verification_list from the sibling list alone. No prerequisites (e.g., must a lease/verification already exist?) or routing conditions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must carry the burden of behavioral disclosure. 'List workspaces' provides no information about side effects, scope of results, performance implications, or whether it is a pure read operation. It only restates the action.
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, direct sentence with no redundant words. It is perfectly concise for a tool with no parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should clarify the returned data format (e.g., a list of workspace names, IDs, or full objects). It does not, leaving the agent uncertain about the result. The minimalism is a gap for a list tool.
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, and the schema fully covers this (coverage 100%). The description adds no parameter-related information, which aligns with the baseline of 4 for parameter-less tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a clear action on a resource: 'List workspaces.' It is specific and not a tautology, but lacks differentiation from many sibling list tools like herdr_owned_pane_list or herdr_agent_list, which could confuse an agent selecting among them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The description does not mention scope, exclusions, or alternative tools, leaving the choice to the agent's inference. There is no explicit when/when-not condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral burden. It discloses that losing waits are cancelled and that per-target after_seq cursors prevent stale terminal states, which adds meaningful behavior beyond the name. However, it omits side effects (e.g., whether waits are non-destructive), timeout behavior, and the meaning of 'idle, done, or blocked' in practice. Some behavioral transparency is present 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?
Two dense sentences, each adding unique information: the concurrency and terminal states, the cancellation behavior, and the cursor mechanism. No filler or redundancy. The most important fact (concurrent wait-for-first) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has three parameters, no output schema, and no annotations, yet the description is minimal. It fails to explain return values, error conditions, timeout semantics, or what the awaited states mean in practice. Critical usage context is missing for a tool that coordinates multiple agents, making successful invocation risky without prior knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It mentions 'after_seq cursors' but does not explain the after_seq parameter, and it entirely omits read_lines and timeout_ms, leaving their purpose and accepted values unexplained. The target parameter's meaning is only hinted at via 'agents' and the description of target types in the schema, but the description does not reinforce it. The compensation is insufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('wait') and resource ('several agents') with the condition 'first ... to become idle, done, or blocked'. It clearly distinguishes from sibling tools by the 'concurrently' and 'any' semantics, though it does not explicitly name an alternative. 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus its siblings (e.g., herdr_agent_wait, herdr_agent_wait_settled). The description explains what it does but not the conditions that would lead an agent to choose it over alternatives. No exclusions or contextual triggers are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full behavioral burden. It discloses that the tool verifies branch/base/HEAD/status digest and ownership leases, reserves a lane, and starts a worker in a no-focus tab without splitting the controller. It does not mention side effects on failure, return values, or whether it's idempotent. The information is helpful but incomplete for a complex operation with 18 required parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, efficient, and front-loads the primary action. It avoids unnecessary fluff and packs a lot of information into a compact structure. No redundancy or waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the description's detail, it is not complete for a tool with 19 parameters, no output schema, and no annotations. It lacks explanation of parameter relationships, required values, error handling, and return format. The prerequisite is mentioned but not described in depth. An agent would struggle to correctly invoke this tool without additional documentation or schema hints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description needs to compensate. It mentions key concepts like 'branch/base/HEAD/status digest' and 'control tab' but does not map these to the 19 parameters explicitly. For example, it doesn't explain the purpose of controller_id, controller_lease_id, fence token, or owned_scopes. The description provides high-level workflow context but fails to clarify individual parameter semantics, making it insufficient for an agent to construct correct arguments.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/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: reserve a Git lane, verify its state, then start a leased writer in a dedicated tab. It includes specific verbs and resources, and distinguishes it from list/verify/release siblings by focusing on the start workflow. However, it doesn't explicitly name sibling tools to differentiate, which prevents a 5.
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 gives a prerequisite ('Durable ticket/spec authority must already have been validated by the coordinator') but does not explicitly explain when to use this tool versus alternatives like herdr_owned_worker_release or herdr_owned_worker_verify. The usage context is implied by the action, but no exclusions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 full burden. It discloses that the tool revalidates several conditions and preserves the worktree/bytes, which is useful. However, it omits failure behavior (e.g., whether release aborts if validation fails), any side effects on the lease, or reversibility, leaving significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that leads with the action and immediately states constraints and key properties. It is concise with no filler, though it could be split for readability. It earns a high score for efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (10 parameters, 9 required, no annotations, no output schema), the description is far from complete. It lacks parameter-level explanations, failure semantics, and usage context, so an agent cannot reliably determine how to call it correctly or interpret outcomes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate, but it only references a few parameters indirectly (expected_head, expected_status_sha256, checkpoint_ref/sha256). It does not explain the purpose of lease_id, controller_id, controller_fence_token, expected_state_change_seq, or how they interrelate, making correct invocation difficult.
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 'Release' and the resource 'idle/done identity-matched writer', distinguishing it from worker start/verify/list siblings. It also specifies the exact preconditions (revalidating branch, HEAD, Git status digest, checkpoint) and the preservation guarantee, making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no explicit guidance on when to use this tool versus alternates like herdr_controller_release. It implies usage only for idle/done writers, but does not name alternatives or provide exclusion conditions, leaving the agent to infer selection among many release-like siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states that it returns a 'durable receipt' and implies submission, but it does not disclose whether the action is synchronous or asynchronous, any side effects on the agent lease, permission requirements, or how the receipt is stored or retrieved. This is minimal disclosure for a tool with no safety annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler words. It states the action and outcome efficiently. It could have added more details, but as far as conciseness, it is well-structured and does not bury key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 6 parameters, no output schema, and no annotations, the description is severely incomplete. It does not explain the purpose of the controller_* parameters, the conditions required to use the tool (e.g., must have an active lease), what a 'durable receipt' means, or how to later collect the result. An agent would need to infer too much about prerequisites and expected behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (only text, submit, and target have descriptions). The description does not add any parameter-specific meaning beyond what the schema provides, and it especially fails to clarify the controller_* parameters (controller_id, controller_lease_id, controller_fence_token) that lack schema descriptions. Given the low coverage, the description should have compensated but does not.
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 (submit a prompt), the target (one active leased agent), and the outcome (return a durable receipt for later collection). It is specific and unambiguous, and it differentiates from sibling tools like herdr_agent_read (reading) and herdr_handoff (handoffs) by focusing on submission with a receipt.
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 the primary use case: when you want to submit a prompt and get a receipt. However, it does not explicitly mention when not to use this tool or contrast it with alternatives like herdr_agent_wait or herdr_handoff. The context makes it clear for submission, but there is no explicit routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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. It discloses that the tool waits for specific states and returns state plus visible output, and mentions stale-state handling via after_seq. However, it does not describe timeout behavior, potential blocking duration, error handling, or any side effects. This is adequate but not comprehensive for a waiting tool with timeout_ms available.
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 and every word earns its place. The core action and state conditions are front-loaded, and the after_seq note adds critical behavioral context without redundancy. It is concise, well-structured, and immediately scannable.
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?
For a tool with no output schema, the description hints at return values ('state and visible output') but does not detail the structure. It also omits timeout behavior, even though timeout_ms is a parameter, and does not explain read_lines. Given the complexity of a waiting operation, more context would be needed for a complete picture, but the description covers the essential purpose and a key parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25%, so the description must compensate for the undocumented parameters. It only explains after_seq (useful for avoiding stale states) but provides no explanation for read_lines or timeout_ms. Since two of the four parameters lack semantic context in both schema and description, the description is insufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'wait' and the resource 'agent', and specifies the exact states it waits for (idle, done, or blocked) and what it returns (state and visible output). This distinguishes it from generic wait tools, though it does not explicitly contrast with sibling wait tools like herdr_agent_wait, which is a minor gap.
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 guidance on using the after_seq parameter to avoid stale terminal states, which is helpful. However, it does not explicitly state when to prefer this tool over alternatives such as herdr_agent_wait or herdr_wait_output, nor does it mention conditions when this tool should not be used. Usage context is implied but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 of behavioral disclosure. The explicit 'This is read-only' statement is a genuine, valuable disclosure confirming the operation does not mutate state, and 'persistent' adds lease-lifetime context. However, it stops there — no mention of pagination, return shape, or any operational caveats. It covers the core safety trait but little else.
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 with zero waste: verb and resource first, scope qualifier second, read-only disclosure last. Every clause earns its place, and the key information is front-loaded for an agent scanning the description.
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 is simple (one optional param, no required fields, no enums), and the description covers its purpose and parameter meaning adequately. However, there is no output schema and the description gives no hint about return format, which leaves the agent blind to what the response looks like for what is fundamentally a listing operation. Adequate but with identifiable gaps for a read 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?
Schema description coverage is 0%, so the description must compensate. It does meaningfully explain the sole parameter by noting the list is 'optionally limited to one controller,' mapping to controller_id. This adds real meaning beyond the bare 'controller_id: string' in the schema. However, it doesn't define what a controller is or what omitting the parameter returns, leaving partial compensation for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List') and resource ('persistent reviewer leases'), with an optional scope ('limited to one controller'). The resource name clearly differentiates this from the action-style siblings (herdr_owned_reviewer_start/close/cleanup) and from worker-focused tools via the 'reviewer' qualifier. It doesn't explicitly name a sibling contrast, but the verb+resource pairing 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 Guidelines2/5
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 is provided. With dozens of siblings including herdr_lease_inventory and herdr_owned_worker_list, the description does not help an agent select between this and similar list tools. The 'read-only' note is behavioral, not usage routing, so an agent gets no context about when to prefer this over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 — and it does state 'This is read-only', which discloses the primary safety trait. However, it adds little behavioral context beyond that: no mention of what 'persistent' implies about data freshness, whether an acquired controller is required for the filter, or what empty results look like. Adequate but thin.
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, no wasted words. Purpose is front-loaded and the read-only safety note follows immediately. Every element earns its place.
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?
For a simple one-parameter read-only list tool, the essentials are covered. Gaps remain: no output description (no output schema exists), no differentiation from herdr_lease_inventory, and the unresolved worker-versus-lease terminology. Adequate but not fully self-sufficient given the large sibling set.
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 0%, so the description must compensate for the lone controller_id parameter. It does clarify the core meaning via 'optionally limited to one controller'. But it omits how to obtain a valid controller_id, what format is expected, and behavior for invalid or nonexistent controller IDs. Partial compensation for a low-coverage schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List persistent writer leases') plus an optional controller filter. However, the tool name says 'owned_worker' while the description says 'persistent writer leases' — a terminology mismatch that leaves the relationship to the similarly-named herdr_lease_inventory and herdr_owned_worker_verification_list unclear. Slightly ambiguous but fundamentally clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains one usage dimension ('optionally limited to one controller') but gives no guidance amid 43 siblings about when to call this versus herdr_lease_inventory, which appears to overlap in domain, or herdr_owned_worker_verification_list. No exclusions or alternative routing are given despite strong overlap potential.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does disclose that the operation is read-only and never returns command output. However, it leaves other behavioral aspects unclear, such as whether results are paginated, ordered, scoped globally, or what a 'content-free host verification record' actually contains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler; the core action is front-loaded and the behavioral caveat is concise. Every clause earns its place.
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?
For a read-only list tool with no output schema, no annotations, and 0% schema coverage, this is serviceable but incomplete. It does not describe the return shape, record contents, filter interaction, or failure behavior, leaving an agent to infer several important details.
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 0%, so the description must compensate. It partially does by indicating records can be listed 'optionally for one controller or writer lease', which loosely maps to controller_id and lease_id. It does not explain whether the filters can be combined, which parameter corresponds to which role, or any constraints beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific operation: listing host verification records, with optional filtering by controller or writer lease. It distinguishes the tool from verification/verify siblings by emphasizing 'content-free' records and 'never returns command output', though it doesn't name any sibling explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 related tools like herdr_owned_worker_verification_snapshot or herdr_owned_worker_verify. No alternatives, exclusions, or contextual cues for selection are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden but only states a 'List' operation and an optional filter. It does not explicitly note read-only behavior, whether the list is scoped to the caller, or whether any state changes occur. This is minimal but not misleading.
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?
One short sentence communicates the operation and the only option. Every word is useful, and it is front-loaded and direct.
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?
For a simple 1-parameter list tool the core behavior is stated, but there is no mention of the return shape and no distinction from the similarly named herdr_owned_pane_list. Without an output schema or annotations, that leaves an agent to guess what 'panes' resolves to and which list variant is appropriate.
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 already documents the single 'workspace' parameter as a filter (100% coverage). The description's 'optionally filtered' adds no new semantic detail beyond 'optional'; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a clear verb ('List') and resource ('panes') plus the optional workspace filter. However, it doesn't differentiate from the sibling herdr_owned_pane_list, so the agent cannot tell the difference between the two list tools from this description alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit when-to-use guidance compared to sibling tools such as herdr_owned_pane_list, herdr_pane_get, or herdr_pane_read. The only usage signal is the optional workspace filter, which is parameter-level rather than tool-selection guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It discloses that the fence becomes invalid immediately and that worker/reviewer leases are preserved, which is valuable. However, it does not mention what happens to the controller state or any prerequisites beyond checkpointing.
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 with no filler. The purpose and key side effects are front-loaded, making it easy to read quickly. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 required parameters, no annotations, no output schema, and zero schema descriptions, this sparse description is inadequate. It fails to explain the parameters, success/failure behavior, or how checkpointing relates to the release. An agent would struggle to invoke this correctly without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate, but it provides no explanation of the five required parameters. While names like controller_id and controller_lease_id are self-explanatory, the roles of checkpoint_ref and checkpoint_sha256 are not clarified, leaving the agent guessing about their format or purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool releases a controller generation after durable checkpointing, with a specific verb and resource. It distinguishes itself from other controller tools (acquire, renew, etc.) by implying a final release operation, though it does not explicitly name siblings.
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 'after durable checkpointing' provides context for when to call, but it does not explicitly state when not to use it or mention alternative controller operations. The agent must infer that this is the terminal release step.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 key behaviors (dedicated no-focus tab, lease persistence, identity verification, no split, no arbitrary commands), but doesn't mention side effects, error behavior, or prerequisites beyond the listed parameters. It adds some transparency but lacks depth 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words, and it front-loads the primary action and key constraints. It could be slightly more structured but is concise and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (11 parameters, no output schema, no annotations), the description is insufficient. It doesn't explain parameter meanings, the lease lifecycle, what 'verify identity' entails, or expected results. An agent would struggle to correctly supply all parameters and anticipate side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate by explaining parameters. It does not explain any of the 11 parameters (e.g., controller_id, lease, fence token, purpose, parent_pane_id, cwd, name, kind). The description only says 'start one supported reviewer' without mapping 'kind' or clarifying others, leaving agents to guess from names.
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 specific action (create a dedicated no-focus tab and start a reviewer), names the resource (reviewer), and differentiates itself from sibling tools by specifying it never splits the controller tab and rejects arbitrary shell commands. It effectively distinguishes from worker_start and other tools.
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 when to use it (when starting a reviewer) and provides exclusions (no shell commands, no splitting). However, it doesn't explicitly name alternative tools like herdr_owned_worker_start or state conditions for choosing between them, so some inference is required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. It says 'Get details' which suggests a read-only operation, but it does not explicitly state that it has no side effects, requires no special permissions, or what error conditions might occur. There is no disclosure of safety profile or any caveats beyond the basic purpose.
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 is front-loaded with the core action and includes a parenthetical list of returned details. It is concise with no filler or redundant information.
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?
With one parameter, no output schema, and no annotations, the description should hint at the return format. It does by listing 'state, pane id, workspace, agent session,' but it does not explain the structure (e.g., object, array) or any possible failure modes. It is adequate for a simple getter but could be more explicit about what the caller receives.
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 'target' parameter is well-described in the schema as accepting terminal IDs, agent names, labels, or pane IDs. The tool description itself adds no additional meaning beyond the schema, so it meets the baseline but does not elevate it.
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 purpose: 'Get details for a single agent' and lists specific types of details (state, pane id, workspace, agent session). This is a specific verb+resource that distinguishes it from list tools like herdr_agent_list, and the word 'single' disambiguates from batch operations.
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 fetching a single agent's details, but does not explicitly mention alternatives or when not to use it. Sibling tools like herdr_agent_list and herdr_agent_read exist, but no routing guidance is provided. The 'single agent' wording gives some implied context, but there is no explicit when/when-not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It usefully reveals that the tool returns an ephemeral fence token and that the lease is exclusive. However, it does not disclose failure conditions, whether acquiring can invalidate an existing lease, TTL behavior, or permission requirements, which are significant for a lease-acquisition operation.
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 filler. It front-loads the action and resource, then immediately adds the most important behavioral detail—the ephemeral fence token. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations, no output schema, and four parameters with zero schema-description coverage, the description is not complete enough. It explains what the tool returns and why it matters, but omits parameter meanings, failure semantics, exclusivity conflicts, and lease lifecycle considerations, leaving an agent to guess at critical invocation details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no explanation of the required parameters. The phrase 'named project' loosely hints at controller_id, but authority_ref and authority_sha256 remain completely unexplained, and ttl_seconds behavior is left entirely to the schema. The description does not compensate for the missing parameter documentation.
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 ('Acquire'), a precise resource ('the first exclusive controller lease for the named project'), and a distinguishing trait ('first') that separates it from sibling tools like resume, takeover, renew, and release. It clearly identifies what the tool accomplishes and its return value.
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: this is the initial acquisition of an exclusive controller lease, and the returned fence token is required for every coordination mutation. It does not explicitly enumerate alternatives or when not to use it, but 'first exclusive' strongly implies this is for initial acquisition rather than renewal or takeover.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 of behavioral disclosure. It does disclose a key behavior: it refuses blocked/working reviewers and requires condition matching. However, it doesn't mention any side effects like lease release, return values, or error handling, leaving some behavioral aspects opaque.
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?
A single, dense sentence conveys the core operation, conditions, and refusal behavior with no filler. Every clause adds value, and the key scoping constraint ('only an idle or done reviewer') is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 6 parameters with no schema coverage, no annotations, and no output schema. The description explains the general use case and refusal condition but omits necessary details like what each parameter means (especially expected_state_change_seq, controller_fence_token), what 'capture' implies, or what success/failure looks like. It leaves the agent undersupplied for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description mentions nothing about the six parameters. It refers to 'lease' and matching conditions, but doesn't explain any parameter's purpose, syntax, or relationship. With zero compensation from the description, parameter semantics are entirely absent.
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 combination ('capture and close') with a clear resource ('reviewer') and constraints (idle or done, with matching pane/agent/name/cwd/controller/lease). It distinguishes this from other reviewer tools like start, list, and cleanup by specifying the condition for operation.
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 states the condition for use ('only an idle or done reviewer') and the refusal condition ('Blocked or working reviewers are refused'). This gives clear when-to-use/when-not-to-use guidance, though it doesn't name alternative sibling tools for other states.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosure. It implies a read-only operation via 'List', but it does not state whether there are side effects, authentication requirements, pagination, or ordering. For a simple list tool this is acceptable, but additional context like return format or default scope 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?
A single, front-loaded sentence that conveys the core action and the optional filter. There is no wasted language, and the description is appropriately brief for a simple tool.
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 low complexity (one optional parameter, no nested objects, no output schema). The description covers the essential purpose and the parameter's role. While it does not describe the output format, the list action is straightforward, and naming conventions align with sibling tools. It is nearly complete for an agent to call it correctly.
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 schema only defines a 'workspace' string with no description, and schema coverage is 0%. The description compensates by explicitly stating 'optionally filtered to a workspace', clarifying the parameter's purpose. This adds meaning beyond the schema, so the score is above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists tabs and optionally filters by workspace. It distinguishes from herdr_tab_get (which presumably gets a single tab) and other list tools by naming the resource and the optional filter. It could explicitly name sibling alternatives, but 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is the tool for listing tabs, but it provides no explicit guidance on when to use it versus alternatives like herdr_tab_get or other list tools. There is no mention of conditions, exclusions, or prerequisites. The usage context is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility. It reveals the blocking behavior and gives a use case, but does not disclose timeout handling, error conditions, or return values. The schema documents timeout_ms, but the description does not emphasize its importance, leaving gaps 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, concise, and front-loaded with the core purpose. It avoids redundancy and directly states the use case, making it efficient. Slightly more structure could be added, but it is well-suited for quick scanning.
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?
For a simple blocking tool, the description is adequate but omits key behavioral details such as timeout consequences and what happens if the target is not found. It also does not clarify how it differs from sibling wait tools, which is important given the many related options. The lack of an output schema further necessitates a more comprehensive description.
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%, providing descriptions for all parameters (especially status enum and timeout_ms). The description adds minimal extra meaning by mentioning 'idle/done' statuses, which are already in the enum. It does not compensate for any missing schema information, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool blocks until an agent reaches a specified status, specifying the verb 'block' and the resource 'agent'. However, it does not distinguish this from sibling tools like herdr_agent_wait_settled or herdr_agent_wait_any, so it lacks explicit sibling differentiation.
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 a clear usage context—synchronizing a handoff by waiting for an agent to become idle or done—which helps the agent understand when to apply it. It does not mention alternatives or exclusions, but the context is specific enough to guide usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for behavioral disclosure. It explicitly states 'This is read-only', which signals no side effects, and it describes the comparison-and-report behavior. This is strong transparency for a read-only list tool, though it omits any auth requirements or rate limits.
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 the primary action, and ends with a clear read-only note. Every word earns its place with no filler or redundant detail.
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?
For a read-only inventory tool with one optional parameter and no output schema, the description covers the core behavior and safety. However, it fails to explain the controller_id parameter or any output structure, leaving an agent without enough information to fully use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has a single optional parameter, controller_id, with no description (0% coverage). The description completely ignores this parameter, giving an agent no clue about its purpose, format, or impact on results. This is a significant gap.
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 specifies the action ('List live Herdr agents with matching reviewer, writer, or adopted-pane leases') and the additional reporting behavior ('report retained leases whose live identity is missing or changed'). It names the resource and distinguishes this tool from siblings that handle owned workers, panes, or general reconciliation.
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 a clear picture of what the tool does, so an agent can infer when it might be useful (inventory and discrepancy checking). However, it does not explicitly state when to use this tool over alternatives like herdr_lease_reconcile or herdr_owned_worker_list, nor does it mention any exclusions or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosing behavioral traits. It only says 'Block until', which is verbose and could be interpreted as a synchronous wait, but it does not explain timeout behavior, error handling, whether the operation is read-only, or what the return value is (since there is no output schema). It also does not clarify if it polls or uses events. These gaps are significant for a blocking tool, so a 2 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, with the primary action and use case front-loaded. There is no redundant text, and every word adds value. It is appropriately sized for the tool's complexity, so it earns a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, blocking behavior, no output schema), the description is incomplete. It does not specify what happens on timeout, whether the operation is side-effect free, or the return value. It also does not differentiate from sibling wait tools. An agent cannot fully understand the tool's behavior from this description alone, making a 2 appropriate.
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 descriptions for all parameters (match, regex, source, pane_id, timeout_ms), giving high coverage. The description adds minimal extra meaning beyond the purpose ('wait for a build/command to finish'), which does not clarify parameter-specific semantics like how timeout_ms behaves or how source options differ. Since schema coverage is high, the baseline is 3, and the description does not meaningfully improve it.
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 clear action ('Block until'), a specific resource ('a pane's output'), and the condition ('matches given text or regex'). It also gives a concrete use case ('wait for a build/command to finish in another agent's pane'). This is specific and distinguishes the tool from simple read operations, though it does not explicitly name sibling wait tools.
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 a clear context for when to use the tool: waiting for a build/command to finish in another agent's pane. It implies the tool is for cross-agent waits, but it does not explicitly contrast with other wait tools like herdr_agent_wait, herdr_agent_wait_any, or herdr_agent_wait_settled, nor does it state when not to use it. Thus it has clear context but no exclusions or alternatives, fitting a 4.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden, and it does convey that this is a conditional transfer of an expired lease and that a durable authority plus predecessor lease are required. It does not disclose the side effects on the previous identity/lease, error behavior, or whether the operation is reversible, which matters for a takeover-style mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense sentence with the core action and guardrails front-loaded; no filler. The word 'done' is terse and the sentence is long, but it remains economical.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
A takeover operation with five parameters, four required, no annotations, and no output schema needs more lifecycle context: when to prefer it over controller_resume/renew, what response confirms takeover, and what happens to the predecessor lease. The description gives preconditions but leaves these gaps.
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 description maps expected_predecessor_lease_id ('expected predecessor lease'), controller_id ('expired controller lease'), and the authority parameters ('durable authority'). With 0% schema coverage it still leaves ttl_seconds unexplained and does not clarify the relationship between authority_ref and authority_sha256.
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 names a specific action ('transfer'), a specific resource ('expired controller lease'), and a target ('this Herdr pane'), then narrows it with explicit conditions ('only when previous identity is missing, done, or blocked'). This makes the tool distinct from typical acquire/renew/release controller operations even without reading the schema.
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 gives an explicit condition of applicability: only when the predecessor identity is missing/done/blocked and the lease has expired. It implies not to use when a healthy/active predecessor exists, but it does not name alternatives such as herdr_controller_resume or herdr_controller_renew.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 of behavioral disclosure. It does disclose the dry-run default and the preservation guarantees, which is valuable. However, it never states what actually happens when dry_run is false—whether the retained failed lease is deleted, released, or otherwise altered—leaving a core side-effect gap.
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 with no filler. The primary purpose is front-loaded, the safety condition comes second, and the operational default is stated last. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a six-parameter tool with no annotations and no output schema, this description is not complete enough. It omits what the reconciliation actually does, how the required controller/fence parameters are used, and what the caller should expect in response. The safety framing is helpful but insufficient for confident invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it only adds meaning to dry_run by noting the default behavior. The five required parameters (controller_id, controller_lease_id, controller_fence_token, lease_type, lease_id) are left entirely unexplained beyond their names and formats, which is a major gap for a reconciliation 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 a specific verb ('Reconcile') and a specific resource ('retained failed lifecycle lease'), and adds a precise precondition ('only when the exact leased pane is confirmed absent'). This clearly distinguishes the tool from the many sibling tools, especially from lease_inventory and controller_release.
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 an explicit condition for use: only when the exact leased pane is confirmed absent. It also states a safety boundary: live panes and ambiguous writers are always preserved. It does not name alternative sibling tools, but the when-to-use guidance is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so richly: commands are 'fixed, controller-fenced, digest-pinned, time-bounded, and recorded'. It also specifies exactly what bootstrap inputs are allowed, which tells the agent about validation and rejection behavior. This goes well beyond what the schema alone conveys.
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 only two sentences, with the core action and resource front-loaded, and every phrase contributes meaning. The dense, technical language is not padding; it conveys fixed commands, fencing, digest pinning, time bounds, recording, and bootstrap constraints economically.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-parameter tool with no output schema and no annotations, this description is too high-level to let an agent construct a correct call. It never explains what 'expected_status_sha256' and 'expected_worktree_sha256' represent, how timeout_seconds is applied, what 'settled leased writer' means, or what the verification result looks like. The behavioral summary is strong but operational detail is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it only adds meaning for the bootstrap-related parameters ('npm ci' or hash-pinned requirements.lock manifests). The many required parameters — controller_id, controller_lease_id, controller_fence_token, lease_id, expected_head, expected_status_sha256, expected_worktree_sha256 — are not explained or mapped to the behavioral concepts like 'controller-fenced' or 'digest-pinned'.
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 opens with a specific action verb, 'Run', on a clear resource: 'the repository-selected verification gate' for 'one settled leased writer'. It also describes scope ('on the host') and contrasts clearly with sibling tools like verification_list and verification_snapshot, which are list/snapshot operations, not execution.
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 tells the agent this is for running verification on a settled leased writer and imposes strict constraints on dependency bootstraps, which is useful context. However, it never explicitly says when not to use this tool or points to alternatives, leaving the agent to infer the appropriate usage from the context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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. 'Show' implies a read-only, non-destructive operation, and the discovery framing conveys a status-query semantic. However, it doesn't explicitly state it has no side effects or how output is structured, leaving some behavior implicit rather than disclosed.
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 tight sentences with no filler. The core purpose and the useful example list are front-loaded, followed by a single concise usage directive. 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?
For a simple single-parameter, optional-parameter status tool with no output schema, the description covers purpose and usage adequately. Return-value structure isn't described, but the absence of an output schema and the straightforward listing semantic make this a minor gap.
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 single outdated_only parameter is already documented in the schema as 'Only list integrations whose hook/extension is outdated.' The description adds nothing about parameters, but the schema does the heavy lifting, warranting the baseline score.
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 (show), resource (agent integrations), and scope (install status), and enumerates concrete examples (pi, omp, claude, codex, opencode, hermes, qodercli). It is clearly distinguishable from sibling tools like herdr_bridge_status since it addresses integration installs, not bridge or worker state.
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 an explicit directive: 'Use this to discover what agent types are available in this herdr install.' This gives clear intended context. It doesn't explicitly name alternatives to exclude, but the discovery/status framing makes the intended scenario evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description properly carries the safety burden: it states that dry-run is the default, that only identity-matched idle/done reviewers may be closed, and that blocked, working, and ambiguous leases are preserved. It could also reveal what actually happens during closure or on auth/fencing failures, but the core behavioral profile is well covered.
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 dense sentence that front-loads the primary behavior, includes the critical dry-run default, and adds safety constraints without filler. Every clause adds useful information.
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 description is adequate for selecting and safely invoking the tool, and it covers key behavioral safeguards. However, there is no output schema and the description does not say what the inspect/close result looks like, nor what read_lines controls; ambiguous lease handling is also implicit. These gaps make it minimally viable rather than fully 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?
Since schema description coverage is 0%, the description must compensate for parameter meaning. It partially does: 'dry-run is the default' explains dry_run, and 'for one controller' plus 'identity-matched' clarify the role of the controller identifiers. However, read_lines is entirely unexplained, and controller_lease_id/controller_fence_token rely on inference rather than explicit description.
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 (inspect and optionally close), the resource (reviewer leases), the scope (one controller), and precise eligibility criteria (identity-matched idle/done). This distinguishes it from sibling tools like herdr_owned_reviewer_list and herdr_owned_reviewer_close.
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 clearly communicates when to use the tool: to inspect or safely clean idle/done reviewer leases for a controller. The dry-run default and preservation guarantees also tell the agent when the tool is conservative. It does not explicitly name alternatives or give an explicit when-not-to-use condition, 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.
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 of behavioral disclosure. It clearly states the operation is read-only and explicitly notes that fence tokens are not exposed, which is valuable security-relevant behavior. It does not describe output structure or edge cases, but for a simple list operation this is largely sufficient.
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 short sentences with no filler. It front-loads the action and resource, then adds a concise safety qualifier. Every word earns its place, making it an efficiently structured description.
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 read-only list tool, the description adequately specifies what is returned (identities and expiry), the safety behavior (no fence tokens), and the read-only nature. It could be slightly more complete by clarifying how 'controller leases' relate to the broader 'lease_inventory' tool, but overall the definition is sufficient for an agent to invoke it correctly.
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 and an empty input schema, so there are no parameter semantics to document. Per the baseline for zero-parameter tools, a score of 4 is appropriate; the description does not need to compensate for missing parameter information.
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 a specific resource ('controller lease identities and expiry'), making the tool's function immediately clear. It also distinguishes itself from lease-management siblings by scoping to the controller lease aspect, and the 'without exposing fence tokens' qualifier adds clarity about what is not included.
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 the tool is for retrieving controller lease identity and expiry information, but it does not explicitly state when to prefer this tool over alternatives like herdr_lease_inventory or other controller actions. No exclusions or alternative routing are provided, leaving usage context mostly inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 explicitly states 'This is read-only,' which is a key behavioral trait for a listing tool. However, it does not mention other behaviors like pagination, ordering, or side effects, but for a simple read-only list, the read-only disclosure is sufficient to prevent misuse.
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 zero fluff. The primary action and object are front-loaded, and the secondary detail (optional filter) follows logically. The read-only note is a concise, valuable addition. 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?
Given the tool has one optional parameter, no output schema, and no annotations, the description covers the essential facts: what is listed, the optional filter, and read-only nature. It does not state the return format or any pagination details, but for a focused list tool, the description is reasonably complete for correct invocation.
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 schema defines controller_id as optional but provides no description (0% coverage). The description explains that the list can be 'optionally limited to one controller,' directly assigning functional meaning to the parameter. This goes beyond the raw schema and helps the agent understand how to use the optional filter.
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 ('List cleanup-only leases for adopted legacy panes') with a clear resource and optional filter. This is distinct from sibling list tools like herdr_owned_worker_list or herdr_pane_list, as it explicitly scopes to cleanup-only leases for adopted legacy panes.
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 clarifies the tool is read-only and optionally limited to one controller, but it does not explicitly tell when to prefer this tool over alternatives (e.g., herdr_lease_inventory or herdr_pane_list). No exclusions or comparisons are given, so the agent must infer usage from the name and context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosing behavior. It clearly states the operation is a read (non-destructive), highlights the most reliable source (visible screen), and warns about context flooding. It does not discuss error handling or rate limits, but for a read tool this is acceptable. It adds meaningful context beyond the schema by explaining the rationale for defaults and the target lookup step.
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 (two sentences) and front-loads the primary purpose. Every sentence adds value: stating what it does, the recommended source, a usage caution, and a pointer to find targets. No redundancy or 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?
For a tool with 3 simple parameters and no output schema, the description covers essential context: how to identify the target (via herdr_agent_list), what source to use, and how to control output volume. It doesn't explain return format, but that's not required. It is complete enough for an agent to invoke correctly.
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 enhances parameter meaning by advising on 'lines' (keep small) and explaining the 'source' default preference for visible screen as most reliable. It guides usage without repeating schema details, adding value beyond the structured field 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 verb ('read'), resource ('another agent's terminal output'), and purpose ('gather context' for 'contextual handoff'). It clearly distinguishes from sibling tools by specifying 'another agent's' output and the handoff context, making its role 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 provides explicit when-to-use guidance: 'to gather context (contextual handoff)'. It also gives practical usage tips: defaults to the visible screen as the most reliable source, advises keeping 'lines' small to avoid context flooding, and directs users to call 'herdr_agent_list' to find valid targets. While it doesn't explicitly state when not to use it compared to all siblings, the guidance is sufficient for correct selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full behavioral burden. It clearly conveys the read-only listing behavior and discloses the returned fields: semantic state, cwd, and pane/tab/workspace ids. There is no contradiction, though it does not mention error cases or system-level caveats.
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: two sentences, no filler, with scope and output detail front-loaded. The second sentence earns its place by adding direct usage guidance.
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, no-output-schema listing tool, the description fully covers what the tool returns, its scope, and how it should be used. Nothing essential is missing for an agent to select and invoke it correctly.
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 and the schema coverage is 100%, so there is no parameter semantics burden on the description. The baseline for a no-parameter tool is 4, and the description does not need to add parameter-level detail.
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 ('List'), a clear resource ('all agents herdr currently recognizes'), and enumerates supported agent types. It also distinguishes itself from narrower sibling tools by covering any supported agent type rather than a specific owned/controller subset.
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 'Use this first to discover targets for other agent tools,' giving clear entry-point guidance. It does not explicitly name alternatives or exclusions, but the context and scope make the intended usage clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 explicitly states 'This is read-only', which is the key behavioral trait. It also implies it is safe to call at startup. However, it doesn't disclose any potential side effects, authentication requirements, or expected output format. For a read-only status tool, this is adequate but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, tightly packed with relevant information. The purpose is stated first, followed by the handshake context. 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.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the bridge status tool has no parameters and no output schema, the description is sufficient. It specifies exactly what the tool reports (safety profile, protocol version, stable capabilities) and when it should be used (startup handshake). An agent can call it correctly without further information.
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 for parameter semantics is 4. The description adds no parameter information because there are none, which 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 ('Report') and resource ('bridge') with clear details on what is reported: safety profile, protocol version, and stable capabilities. It also identifies itself as a startup handshake, which clearly distinguishes it from sibling tools that deal with workers, panes, controllers, and agents.
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 specifies that this is the startup handshake for coordinators, giving clear situational context. It doesn't explicitly list alternatives or when not to use it, but the context is strong enough that an agent would know this is the initial status check for the bridge.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral burden. It discloses that sessions are persistent, survive disconnects, and support sharing/reattachment—useful behavioral traits beyond the name alone. It doesn't mention any side effects, but as a list operation, none are expected, and the disclosed behaviors are sufficient.
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, focused sentence that states the core purpose and then adds valuable context about session characteristics. It is front-loaded with the action and resource, and every clause 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 list tool with no output schema, the description is complete. It tells exactly what the tool lists and the nature of those sessions, which is enough for an agent to decide whether to invoke it. There is no missing information that would hinder correct usage.
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?
There are zero parameters, and the schema has 100% coverage (vacuous). The baseline for zero parameters is 4, and the description need not add parameter semantics. No gaps exist here.
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 herdr persistent sessions' with a specific verb and resource. The qualifier 'persistent' distinguishes this from other list tools in the sibling set (e.g., controller_list, agent_list), making its 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?
It provides clear context on when to use this tool by explaining that sessions survive disconnects and can be shared/reattached locally or over SSH. This implies usage when the agent needs to interact with persistent, reattachable sessions. However, it does not explicitly state when not to use it or name alternatives, so it misses an exclusion clause.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![herdr-mesh-safe MCP server](https://glama.ai/mcp/servers/nativestrider/herdr-mesh-safe/badges/card.svg)](https://glama.ai/mcp/servers/nativestrider/herdr-mesh-safe)

Score Badge

Copy to your README.md:

[![herdr-mesh-safe MCP server](https://glama.ai/mcp/servers/nativestrider/herdr-mesh-safe/badges/score.svg)](https://glama.ai/mcp/servers/nativestrider/herdr-mesh-safe)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/nativestrider/herdr-mesh-safe'

If you have feedback or need assistance with the MCP directory API, please join our Discord server