herdr-mcp

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

Annotations already declare readOnlyHint=true, idempotentHint=true and openWorldHint=false, so the safety profile is covered. The description's contribution is naming the returned fields, which is useful but not deep behavioral context (no auth requirements, error behavior, or lookup-miss semantics).

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

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

A single, front-loaded sentence that lists the returned data with zero filler. Every clause earns its place.

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

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

No output schema exists, so the description usefully enumerates the fields the caller receives. For a simple one-parameter read tool this is nearly complete; only lookup-failure behavior is unstated.

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

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

Schema description coverage is 100%, so the single 'agent' parameter is fully documented in the schema, including the name-or-pane-ID dual form. The description adds no syntax or format detail beyond that, so the baseline 3 applies.

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

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

States a specific verb (Get) and resource (one agent) and enumerates the returned facets: status, pane location, working directory, terminal title, session info. The word 'one' cleanly distinguishes it from the sibling herdr_agent_list.

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

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

Usage is implied by 'one agent' versus the list sibling, but the description never states when to use this instead of herdr_agent_list or herdr_agent_read, nor any preconditions. Adequate but leaves routing to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and openWorldHint=false, so the safety profile is covered. The description's added value is naming the status vocabulary and pane field, but it says nothing about ordering, filtering, or freshness of the snapshot — context that matters for a monitoring tool.

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

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

Two short sentences, zero waste, with the core purpose front-loaded and the status vocabulary delivered immediately after. Nothing needs to be trimmed.

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

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

With no output schema, the description usefully previews the return shape (per-agent status and pane). That is sufficient for a zero-parameter list tool; only minor gaps remain around ordering, snapshot freshness, or what 'unknown' status implies.

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

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

The tool takes no parameters (empty object, 100% schema coverage), so there is no parameter semantics for the description to compensate for. Baseline 4 applies; nothing is required of the description here.

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

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

States a specific verb and resource ('List the coding agents herdr recognizes') and enumerates the fields returned (status values, pane), so the agent knows exactly what this yields. It does not explicitly distinguish itself from the nearest siblings (herdr_agent_get, herdr_agent_wait), but 'List' and 'primary monitoring tool' make the breadth-vs-single-agent split inferable.

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

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

'The primary monitoring tool' implies the context in which to reach for this rather than another tool, but it names no alternatives and gives no when-not conditions (e.g. use herdr_agent_get for a single agent's detail, herdr_agent_wait to block until state changes). Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds the useful detail that output is plain text rather than structured, but says nothing about truncation, pagination, or behavior when the agent has no output.

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

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

Two tight sentences, no filler. The core action is front-loaded, followed immediately by the practical purpose, which is the right ordering for an agent skimming tool lists.

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

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

There is no output schema, but the description disambiguates the return format as plain text, which is the key thing an agent needs to know about the result. For a read-only, three-parameter tool with full schema coverage, this is nearly complete; only edge-case output behavior is unaddressed.

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

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

Schema description coverage is 100%, so the agent/name pattern, the lines range (1-500, default 60), and each source enum value are already fully documented in the schema. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource: 'Read recent terminal output from an agent's pane as plain text.' An agent can distinguish it from metadata-oriented siblings like herdr_agent_get. However, it does not explicitly name or contrast against those siblings, so it lands at clear-but-undifferentiated.

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

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

'Use it to see what an agent did, what it is asking, or why it failed' gives clear scenario-based context for when to reach for this tool. It stops short of naming alternatives or exclusions (e.g. vs herdr_agent_wait for blocking on state), which is what a 5 would require.

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

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

Annotations already mark this readOnly, idempotent, and non-open-world, so safety is covered. The description adds real behavioral value beyond that: the default settled-status set (idle/done/blocked) and the immediate-return short-circuit when the agent already matches. It omits what happens on timeout or how the wait terminates, which keeps it from a 5.

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

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

Three compact sentences, front-loaded with the core action, and no filler. The second sentence partially duplicates the schema's 'until' description, which is the only wasted effort.

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

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

No output schema exists, so the description ideally would say what a wait returns (final status? timeout signal?) and whether a timeout is an error or a normal result. For a blocking tool with a bounded timeout, that gap matters, though the annotations and full schema coverage keep this adequate.

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

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

Schema description coverage is 100%, so the schema already documents the agent identifier, the 'until' enum, and the timeout default/max. The description's note about omitting 'until' restates the schema's own 'Omit to wait for any settled status' text, adding no new syntax or format detail. Baseline 3 applies.

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

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

States a specific verb and resource: waiting for an agent to reach a status, which cleanly separates it from read-style siblings like herdr_agent_get and herdr_agent_list. The distinction from those siblings is semantic rather than explicit, so it falls just short of a 5.

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

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

The description implies when to reach for this tool via its blocking nature, and explains the default behavior when 'until' is omitted. However, it never explicitly says to use this over herdr_agent_get for polling, nor states any preconditions (e.g., the agent must exist).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and openWorldHint=false, so the safety profile is covered. The description adds meaningful domain context that panes survive client detach and may hold a shell, process, or agent, which helps interpret results, but says nothing about ordering, pagination, or result shape.

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

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

Two short sentences, front-loaded with the action and followed by the entity definition. No filler, no redundancy.

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

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

For a simple read-only list tool with full schema coverage and annotations covering safety, the description is nearly sufficient. It only lacks minor operational details such as ordering or whether results are paginated, which are low-stakes here.

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

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

With a single parameter at 100% schema coverage, the schema fully documents workspace_id including its format and the omit-to-list-all behavior. The description adds no parameter meaning beyond that, which is the expected baseline.

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

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

The description gives a specific verb+resource ('List panes') and adds a definition of what a pane is, which is genuinely useful domain vocabulary. It does not explicitly differentiate itself from siblings like herdr_tab_list or herdr_workspace_list, so an agent must infer the hierarchy.

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

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

There is no when-to-use guidance and no mention of alternatives. The only conditional behavior ('omit workspace_id to list all workspaces') is already stated in the schema, so the description contributes nothing about tool selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety and repeatability profile is fully covered. The description adds the diagnostic-role context and mentions the version report, but does not describe failure behavior (e.g., what a non-running server returns), so added value beyond the structured fields is modest.

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

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

Two short sentences with zero filler, and the primary purpose is front-loaded before the troubleshooting hint. Every clause earns its place.

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

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

For a 0-parameter, no-output-schema health check with annotations covering safety, the description is nearly sufficient: purpose plus invocation trigger are present. The only gap is not stating what a failed check looks like, which is minor given the tool's simplicity.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain; the baseline of 4 applies. The description correctly implies a no-argument invocation.

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

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

States a specific verb+resource ('Check that the herdr server is running') plus an output ('report its version'), which cleanly distinguishes it from the sibling listing tools (workspace_list, tab_list, pane_list, agent_list). An agent can identify this as the health/diagnostic probe without opening any schema.

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

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

Gives an explicit triggering condition: 'Call this first if other herdr tools fail,' which tells the agent exactly when to reach for it versus continuing with a listing/agent tool. It stops short of a full when-not statement (e.g., don't call it for routine data retrieval), so it is clear but not exhaustive.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and openWorldHint=false, so the safety and repeatability profile is covered structurally. The description contributes only the domain model of what a tab is, adding no extra behavioral context such as result size, ordering, or scoping behavior beyond what the schema already states.

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

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

Two short sentences, the action front-loaded, and the second sentence earning its place by defining the resource. No filler or redundancy.

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

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

For a simple, fully annotated, single-parameter read tool, the description plus schema covers what an agent needs to invoke it. The main residual gap is that no output schema exists and the description says nothing about the shape or size of the returned tab list.

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

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

Only one parameter, and the schema documents it at 100% coverage including the 'omit to list tabs in all workspaces' behavior. The description adds nothing about parameters, so the schema does all the work — the baseline of 3 applies.

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

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

States a specific verb and resource ('List tabs') and then defines the resource itself, distinguishing a tab from a workspace or pane. It does not name any sibling tool (e.g. herdr_pane_list) explicitly, but the hierarchy explanation gives an agent enough to tell what this enumerates.

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

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

There is no explicit when-to-use/when-not guidance and no reference to alternatives such as herdr_pane_list. The hierarchy note ('tabs are layouts inside a workspace; each contains one or more panes') only implicitly signals that this is the middle layer of the workspace/tab/pane model.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds domain semantics about workspace composition, but says nothing about pagination, ordering, or the scope of what is returned, so it adds modest value over the annotations.

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

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

Two short sentences, zero filler. The purpose is front-loaded and the definition sentence immediately follows to disambiguate the domain term.

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

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

For a no-parameter, read-only list tool with no output schema, the description is nearly complete: it says what is listed and what a workspace is. It stops short of indicating what each listed workspace contains or how results are ordered, which would help an agent consume the output.

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

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

The tool takes zero parameters, so there are no parameter semantics to explain; the baseline for a parameterless schema is 4. Nothing in the description contradicts or misrepresents the empty input schema.

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

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

States a specific verb and resource ('List herdr workspaces') and defines what a workspace is as a project-level container owning tabs and panes. That definition implicitly distinguishes it from herdr_tab_list and herdr_pane_list, but no sibling is named explicitly, so it falls short of a 5.

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

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

The hierarchy note ('owns tabs and panes and rolls up agent states') gives implicit context for where this tool sits relative to the tab/pane/agent list tools, but there is no explicit when-to-use, when-not-to-use, or named alternative. Usage is inferable rather than stated.

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