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

Annotations already declare this is a read-only, idempotent, non-destructive operation, so the safety profile is covered. The description adds the notion that it surfaces Herdr's internal classification logic, but says nothing about prerequisites (e.g., must the agent be live/running?) or what form the explanation takes.

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

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

A single front-loaded sentence with no filler or redundancy. It is appropriately sized, though extremely terse given the tool's diagnostic nature.

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 carries the burden of describing what is returned, yet it never indicates whether the result is a textual rationale, a state label with reasons, or structured fields. Annotations cover safety, so the gap is limited to output shape and prerequisites.

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

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

Schema description coverage is 100%, with both 'target' and 'verbose' documented in the schema itself, so the baseline is 3. The description adds no extra meaning about what 'target' accepts beyond the schema's 'live agent name or pane id' or what 'verbose' expands.

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

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

The description states a specific verb ('Explain') and resource ('an agent's current state' classification), so an agent can tell this is a diagnostic/explanation tool rather than a state-reading tool. It does not, however, distinguish itself from close siblings like herdr_agent_get or herdr_status by name.

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

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

There is no guidance on when to call this instead of herdr_agent_get, herdr_agent_read, or herdr_status, all of which touch agent state. The agent must guess the boundary between 'explain the classification' and 'get the state'.

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 declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the safety profile is partly covered. However, the description adds nothing beyond them: it doesn't say what 'focusing' changes (which pane becomes active, whether existing focus is stolen, what happens if the target is dead), which matters for a non-idempotent, non-read-only operation.

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

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

The single sentence is front-loaded and free of filler, which is good, but at four words it is under-specified rather than truly concise. There is no wasted text, yet nothing is earned by the brevity either.

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 one-parameter tool with no output schema, the description plus schema is barely sufficient to call it. It omits any note on the mutating, non-idempotent side effect and any return/confirmation behavior, which an agent would benefit from knowing.

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

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

Schema description coverage is 100% and the single 'target' parameter already documents 'Live agent name or pane id.' The description adds no additional meaning (e.g., how ambiguity between a name and a pane id is resolved), so the baseline 3 applies.

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

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

The description names a verb and a resource ('Focus an agent's pane'), which is better than a tautology, but 'focus' is ambiguous (UI focus vs. agent activation) and it does nothing to distinguish itself from siblings like herdr_pane_zoom or herdr_agent_get. An agent can guess the intent but cannot confidently route between near-neighbors.

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 indication of when to use this tool versus alternatives such as herdr_pane_zoom or herdr_agent_get, nor any prerequisite or state condition. The agent is left to infer usage entirely from the name.

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 destructiveHint=false, so the safety profile is fully covered structurally. The description adds only that the return is a 'full record', giving modest context but no detail on permissions, size, or error behavior.

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 tight sentence with the resource and accepted identifier forms front-loaded and no filler. It is efficient, though it is arguably too terse to carry routing guidance.

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 one-parameter read tool with full annotation coverage, the description is nearly sufficient; 'full record' signals the return shape even without an output schema. A brief note on record contents or errors would close the remaining gap.

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

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

Schema description coverage is 100%, with the 'target' parameter already documented as 'Live agent name or hosting pane id'. The description's parenthetical '(name or pane id)' merely restates the schema, 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's full record) and distinguishes a single-agent lookup from the list-style sibling herdr_agents. It does not, however, name or contrast with closely related read siblings like herdr_agent_read or herdr_agent_explain.

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

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

There is no explicit when-to-use guidance or mention of alternatives. The phrase 'one agent' only implicitly signals a singular lookup versus herdr_agents, leaving the agent to infer selection between this and sibling read tools.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false), so the safety burden is largely covered. The description adds the meaningful behavioral detail that it returns immediately or blocks until the agent settles, but omits whether the prompt is queued, what 'settles' means, and how this interacts with the until/timeout_ms parameters.

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

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

Two sentences, no filler, and the core action is front-loaded ahead of the return-behavior detail. Every clause carries information.

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

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

There is no output schema and five parameters, and the description never explains what 'settles' concretely means or how the until state list changes the blocking behavior described by wait=true. Adequate for the core call but leaves a real interaction gap between wait, until, and timeout_ms.

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 baseline is 3. The description usefully ties the wait parameter to the two return behaviors, but says nothing about target, text, until, or timeout_ms beyond what the schema already documents.

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

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

States a specific verb and resource ('Submit a prompt to a live agent'), which is clearly distinct from read/list siblings like herdr_agent_get or herdr_agent_read. It does not, however, differentiate itself from the closely related herdr_agent_send_keys or herdr_pane_run, 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 description explains the two return modes (wait=false submits and returns; wait=true blocks until the agent settles), which is useful context, but it never says when to choose this tool over herdr_agent_send_keys or herdr_pane_run. Usage is implied rather than stated, and no exclusions or prerequisites are given.

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 readOnly, idempotent and non-destructive, so safety is covered, but the description adds meaningful context beyond them: the returned text is untrusted terminal output and must be treated as data. This is a genuinely valuable behavioral disclosure.

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

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

Two sentences, front-loaded with the operation and immediately followed by the security caveat. No filler, every sentence 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?

With no output schema the description appropriately notes the nature of the returned text, and annotations cover the safety profile. It is nearly complete, missing only sibling differentiation and default-source behavior.

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 lines, source and target are all documented in the schema, including the enum values. The description adds no parameter semantics beyond that, which is the baseline case.

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

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

States a specific verb and resource ('Read recent output from an agent's pane'), which is clear enough for an agent to understand. It does not, however, contrast itself with the close sibling herdr_pane_read or explain whether 'recent' is bounded.

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

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

No guidance on when to use this versus herdr_pane_read, herdr_agent_get, or herdr_agent_wait, and no prerequisites or exclusions. The only implicit usage cue is the security caveat about untrusted output.

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 it is a mutation (readOnlyHint=false) that is neither idempotent nor destructive. The description adds only the 'live agent' qualifier; it does not explain name-collision behavior, whether renaming affects the running session, or why the operation is non-idempotent. Relies on annotations for safety profile with little added context.

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 short sentence covering both modes with zero filler, front-loading the primary action.

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 3-parameter mutation with full schema coverage and annotations, the description is minimally adequate but omits how 'name' and 'clear' interact (what happens if both or neither are supplied) and any effect on the live agent's state.

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

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

Schema coverage is 100%, so the schema already documents 'name', 'clear', and 'target'. The description restates the two-mode behavior but adds no format, constraints, or mutual-exclusivity rules beyond what the schema provides. Baseline 3 applies.

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

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

States a specific verb and resource ('Rename a live agent') plus the alternative action ('clear its name'), which is clear enough for an agent to distinguish it from siblings like herdr_agent_get or herdr_agent_focus. It does not explicitly name a sibling to differentiate against, keeping it 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 the two modes of use (set a name vs. clear it) but never states when to prefer this tool over alternatives or any prerequisites, such as the agent needing to be running. No exclusions or conditions are given.

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, destructiveHint=false, openWorldHint=false, so the safety profile is fully covered. The description adds that it lists 'live' agents, implying a filter on active/running agents, which is useful context. But it doesn't clarify pagination, ordering, or output format.

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

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

Single short sentence with zero waste, front-loaded with the action and resource.

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?

Given the tool has no parameters, no output schema, and rich annotations covering safety, the description is minimally adequate. It could note what 'live' means or what fields are returned, but for a simple list tool it suffices. However, it leaves ambiguity about whether it returns agent IDs, names, or statuses.

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?

No parameters, so baseline is 4. The description adds no parameter details (none exist), and schema coverage is 100%. It correctly conveys that no inputs are needed.

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?

Clear verb+resource: 'List live agents'. It's specific about scope ('live agents recognised by Herdr'), which distinguishes it from herdr_agent_get (single agent) and herdr_agents siblings like herdr_agent_read. However, it doesn't explicitly differentiate from the many other list-style siblings (herdr_panes, herdr_tabs, herdr_workspaces).

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

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

No when-to-use guidance or alternatives mentioned. It doesn't say when to call this vs herdr_agent_get for a specific agent. With 0 parameters, the use case is implied (enumerate all agents) but not 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 destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the one-word 'Destructive.' merely restates structured data without adding context. It does not say what gets destroyed, that the confirm flag gates execution, or what the effect on a live agent session is.

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, front-loaded sentences with no filler; the purpose comes first and the hazard warning follows. It is arguably too terse rather than bloated, so conciseness itself is not the problem.

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

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

For a destructive, non-idempotent mutation with three required parameters and no output schema, the description omits the mandatory confirm=true requirement, the nature of the destruction, and how it relates to sibling input tools. An agent could call this incorrectly without the extra context.

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

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

Schema description coverage is 100%, so all three parameters are documented in the schema, which sets the baseline at 3. The description adds nothing about the required confirm=true gate or the semantics of the keys array beyond the schema's own 'esc or ctrl+c' example.

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

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

States a specific verb (send) and resource (logical keys) plus the destination (interactive agent UI), so the agent knows this injects input rather than reading or prompting. It does not, however, distinguish itself from close relatives like herdr_agent_prompt or herdr_pane_run, which an agent could plausibly confuse it with.

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

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

There is no guidance on when to use this versus herdr_agent_prompt (text prompt) or herdr_pane_run (shell command), and no mention of prerequisites such as needing a live, focused agent. The agent must infer the selection rule 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.

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

Annotations declare destructiveHint=true, readOnlyHint=false, idempotentHint=false, and openWorldHint=false, so the agent knows this is a mutating, non-idempotent operation. The description adds little beyond this—it doesn't explain what makes it destructive (e.g., does it occupy the pane entirely, terminate existing processes?), whether restarting the same name is safe, or what happens on failure. Some value added but not rich.

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

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

Single, front-loaded sentence with zero waste. It states exactly what the tool does in minimal words.

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

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

For a non-idempotent, destructive tool with no output schema, the description should do more: it lacks information about return values, failure modes, what happens to the pane on agent exit, and usage relative to siblings. The schema covers parameters well, but behavioral context is thin.

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 fully documents all 5 parameters. The description adds no parameter meaning beyond what's in the schema—it doesn't clarify the relationship between name, kind, and pane_id, or how agent_args interacts with the startup process.

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?

Clear verb+resource: 'Start a coding agent in an existing available shell pane.' It specifies the action (start) and the target (coding agent), distinguishing it from siblings like herdr_agent_send_keys or herdr_open_agent. However, it doesn't explain what 'available' means or differentiate from herdr_open_agent, which likely also creates agents.

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 word 'existing available shell pane' implies a precondition (the pane must already exist and be available), but there's no explicit when-to-use guidance or comparison to alternatives like herdr_open_agent. The agent must infer that this tool requires a pre-existing pane while herdr_open_agent might handle creation.

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 cover the safety profile (readOnly, idempotent, non-destructive, non-open-world), so the description need not restate that. However, the key behavioral traits of a blocking wait tool are undisclosed: that it blocks the caller, that timeout_ms defaults to 20000 and caps at 25000, and what happens on timeout versus success.

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 sentence with no waste, but it is thin rather than tight — the brevity comes from omitting information rather than from efficient phrasing. The purpose is front-loaded, which is good.

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 blocking wait with a 20s default timeout, no output schema, and no annotations describing blocking behavior, the description should explain what is returned on success or timeout and how the caller resumes. None of that is present.

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 target, until, and timeout_ms; baseline 3 applies. The description adds nothing beyond the schema, and notably does not clarify the semantics of omitting 'until' or the timeout cap.

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

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

The description gives a specific verb and resource ('wait for an agent') plus the condition being awaited ('to reach a state'), so the core operation is unambiguous. It does not distinguish itself from siblings such as herdr_pane_wait_output or herdr_agent_get, which an agent may need to choose between.

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

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

No guidance on when to use this instead of alternatives like herdr_agent_get (polling) or herdr_pane_wait_output. There is also no mention of prerequisites such as the agent already being started or what to do when the wait times out.

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 destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds useful behavioral context by disclosing the side-effect chain (creates a worktree, opens a tab, starts an agent), but says nothing about irreversibility, what 'wait'/'focus' actually change, or permission requirements for agent_args.

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 opens with the verb and resource, then lists the optional orchestration steps in execution order. No filler, no restatement of the tool name.

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

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

For an 11-parameter, destructive, non-idempotent orchestration tool with no output schema, the agent still lacks key facts: what is returned (job handle/id?), how errors during the chain are surfaced, and how the 'wait' flag interacts with timeout_ms. Adequate as a one-line purpose but thin given the tool's complexity.

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

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

Schema description coverage is 100% across all 11 parameters, so the schema does the heavy lifting and baseline 3 applies. The description adds only the vague 'optionally create a git worktree' mapping to the worktree/cwd/base/branch group, without clarifying defaults or the HERDR_MCP_ALLOW_AGENT_ARGS gating beyond what the schema already documents.

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 ('Start') and resource ('code job') and enumerates the orchestrated steps: worktree, tab, agent, brief. This clearly differentiates it from lower-level siblings like herdr_agent_start and herdr_worktree_create, though it never names those siblings explicitly as the alternatives it composes.

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 this is the high-level composite path (it chains worktree+tab+agent+prompt), which hints at when to reach for it over its granular siblings. However, it never states when to use this versus herdr_agent_start or herdr_worktree_create, nor any prerequisites, so the guidance remains inferential.

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 convey the safety profile (non-read-only, non-destructive, non-idempotent, closed-world), so the description's only remaining job is to add context such as whether the call blocks, how long the notification persists, or whether it degrades outside a GUI session. It adds none of that.

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 short sentence with zero padding and the key noun front-loaded. It is appropriately sized, though its brevity is partly under-specification rather than discipline.

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 4-parameter notification call with a fully documented schema and no output schema, the essentials are covered. However, for a side-effecting display action with no annotations explaining runtime behavior, a sentence on blocking/async semantics or platform requirements would meaningfully close the gap.

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

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

Schema description coverage is 100%, with both enums (sound, position) and their allowed values fully specified in the schema itself. The description adds no syntax, defaults, or interaction detail beyond what the schema provides, so the baseline of 3 applies.

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

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

The description gives a specific verb ("Show") and resource ("native Herdr notification"), so the agent knows exactly what action is performed. There are no sibling notification tools to confuse it with, but it does nothing to contrast itself with the rest of the herdr_* family beyond the distinctive "notification" noun.

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

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

No guidance on when to use this tool versus alternatives, and no mention of prerequisites or context. The agent must infer that this is for surfacing user-facing alerts rather than logging or messaging.

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 destructiveHint=true, openWorldHint=false and non-idempotency, so the safety profile is partly covered. The description adds that the call opens both a tab and a pane and spawns an agent process, but does not explain the destructive/state-creating implication, focus stealing, or what happens on startup timeout, which would be useful beyond 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, action front-loaded, with the differentiator ('one-call') placed after the core verb. No wasted text.

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

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

For a nine-parameter tool with no output schema, the description covers intent but omits what is returned (presumably an agent name/id needed by herdr_agent_prompt, herdr_agent_read, herdr_agent_wait) and says nothing about failure modes such as the startup timeout. Adequate but with clear gaps.

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

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

Schema description coverage is 100%, so all nine parameters are already documented in the input schema (including the HERDR_MCP_ALLOW_AGENT_ARGS gate on agent_args). The description only echoes the optional prompt, adding no format or default detail beyond the schema, 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 compound action: open a new tab and pane and start a coding agent, optionally with a prompt. The phrase 'The one-call way to launch an agent in a fresh tab' signals it differs from herdr_tab_create + herdr_pane_split + herdr_agent_start, but never names those siblings.

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

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

'The one-call way to launch an agent in a fresh tab' implies the usage context (new tab/pane versus an existing one), but there is no explicit when-to-use/when-not, no mention of herdr_agent_start for the in-place case, and no stated prerequisites.

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 destructiveHint=true, readOnlyHint=false, idempotentHint=false, so 'Destructive' in the description merely repeats structured data with no added value. The description adds nothing about whether running processes in the pane are killed, whether the close is reversible, or what happens on failure — meaningful gaps for a destructive operation.

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

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

Two short fragments with the purpose front-loaded. Nothing wasted, but also nothing beyond the bare minimum — structure is fine within the very low information it delivers.

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?

A destructive, non-idempotent mutation tool with no output schema and no annotation beyond safety hints. The description should disclose consequences (running jobs terminated, orphaned children, irreversibility) and relationship to sibling close tools. Instead it offers two words of content.

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

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

Schema coverage is 100% and the schema itself documents both parameters ('Pane id.', 'Must be true.'). The description adds no semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

States a specific verb+resource ('Close a pane'), which clearly distinguishes it from siblings like herdr_tab_close or herdr_workspace_close that operate on different scopes. The one-line format is minimal but unambiguous.

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

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

No guidance on when to use this versus herdr_tab_close or herdr_workspace_close, no prerequisites, no mention of cascade effects. The destructive label provides a caution signal but doesn't route the agent between alternatives.

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 readOnly=false, idempotent=false, destructive=false, so the safety profile is known. The description adds nothing behavioral beyond that: it does not say what happens to the source tab if it empties, whether focus follows the pane (a parameter exists for it), or whether the operation can fail/revert. No contradiction with 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?

A single front-loaded sentence with the verb first and no filler. It is efficiently sized, though for a tool with ten parameters and three distinct modes it is arguably too terse to be maximally useful.

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 ten parameters across three modes and no output schema, the description should explain how tab_id, new_tab, new_workspace, target_pane_id, split, and ratio combine (e.g., mutual exclusivity of the destination options). None of that mode-combination logic is present, leaving the agent to infer valid parameter combinations.

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

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

Schema description coverage is 100%, so all ten parameters are self-documented and the baseline is 3. The description adds no syntax, constraints, or interaction rules beyond naming the destination modes that the tab_id/new_tab/new_workspace parameters already express.

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 ('Move') and resource ('a pane') and enumerates the three destination modes, which is enough to place it apart from siblings like herdr_pane_split or herdr_pane_close. It does not explicitly name or contrast those siblings, so it stops short of a 5.

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

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

The three destinations ('another tab, a new tab, or a new workspace') imply the cases the tool covers, but there is no statement of when to use this over herdr_pane_split, herdr_tab_create, or herdr_workspace_create, and no prerequisites or exclusions.

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 readOnly, idempotent, and non-destructive, so the safety bar is lower. The description adds genuinely useful context beyond them: the returned text is untrusted terminal output and must be treated as data with embedded instructions ignored. It does not cover truncation or how "recent" is bounded.

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, both earning their place: one states the operation, one carries the security caveat. The core purpose is front-loaded with no filler.

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

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

For a read-only tool with full schema coverage and no output schema, the description covers purpose and the key trust caveat. It could say more about what "recent" means or output limits, but nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents pane_id, lines, and source with defaults and the enum. The description adds no syntax, format, or interpretation detail beyond that, making the baseline 3 correct.

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

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

States a specific verb and resource ("Read recent output from a raw pane"), and the qualifier "raw pane" implicitly distinguishes it from agent-level siblings like herdr_agent_read. It does not explicitly name an alternative, so it stops short of a 5.

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

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

The phrase "raw pane" hints at when this is appropriate versus the agent-oriented siblings, but there is no explicit when-to-use, when-not-to-use, or named alternative such as herdr_agent_read or herdr_pane_wait_output. Usage is only implied.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false. The description adds no behavioral context beyond that — nothing about minimum/maximum size, how neighboring panes absorb the change, or why the operation is non-idempotent. It merely restates the mutation the annotations imply.

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 short, front-loaded sentence with no filler. It is efficient, though perhaps terse enough that some clarifying detail was sacrificed.

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

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

For a mutation tool with a fully documented 3-parameter schema and no output schema, the description is minimally adequate. However, it omits resize semantics (what 'amount' means in practice, e.g., lines/cells, and the effect on adjacent panes) that would help an agent call it correctly.

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

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

Schema description coverage is 100%, with each parameter (amount, pane_id, direction) documented in the schema, including the enum for direction. The description's 'focused (or given) pane' only restates the schema's 'omit for current' note, so baseline 3 is appropriate.

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

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

States a specific verb (resize) and resource (pane), plus the direction scope, so the agent knows the operation. It does not distinguish itself from adjacent pane-manipulation siblings such as herdr_pane_split, herdr_pane_move, or herdr_pane_zoom.

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

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

There is no guidance on when to use resize versus split/move/zoom, nor any stated prerequisites or constraints (e.g., whether the pane must be in a split layout). Usage is only implied by the tool name.

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 destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered without the description. The description does add real context by naming the execution principal ('as the Herdr user') and warning of arbitrary command execution, but it omits whether the call blocks/returns output, which matters given the sibling herdr_pane_wait_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, front-loaded with the action and scope, with no 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?

For a two-parameter command runner with no output schema and partial annotation coverage, the description leaves a key question unanswered: whether execution is synchronous and returns output, or fire-and-forget (paired with herdr_pane_wait_output). Otherwise it is adequate.

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

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

Schema coverage is 100%, so both pane_id and command are already documented in the schema. The description adds nothing about command syntax or pane_id format beyond what the schema states, so the baseline of 3 applies.

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

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

States a concrete verb and resource: 'Run a shell command in a pane,' plus a clarifying parenthetical about how input is submitted. An agent can distinguish it from read-oriented siblings like herdr_pane_read, but it does not explicitly differentiate from herdr_agent_send_keys or herdr_job_start, which also push input/commands.

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

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

No indication of when to use this versus herdr_agent_send_keys, herdr_job_start, or herdr_pane_wait_output. The only guidance is a parenthetical about how text and Enter are bundled, which is behavioral rather than a use-condition.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds nothing beyond restating a listing action – no pagination, scope default, or output-shape context – so it earns little credit on top of 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?

One short, front-loaded sentence with no filler. It is efficient, though arguably terse to the point of under-specification rather than maximally informative.

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 no output schema, the description conveys the essentials (lists panes, optional workspace scoping). It is adequate but leaves the default scope and return characteristics implicit.

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

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

The single parameter is fully documented in the schema (100% coverage), which sets the baseline at 3. The description's 'optionally in one workspace' merely mirrors the workspace_id schema description without adding format or default-value detail.

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

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

States a specific verb (List) and resource (panes), so an agent can distinguish it from mutation siblings like herdr_pane_close or content readers like herdr_pane_read. It does not explicitly name or contrast the closest sibling, so it stops short of a 5.

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

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

The phrase 'optionally in one workspace' implies the filtering condition, which is a form of usage guidance, but there is no when-to-use vs when-to-use-something-else instruction or mention of alternatives such as herdr_pane_read.

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 this is a non-read-only, non-destructive, non-idempotent, non-open-world operation, so the safety profile is covered. The description adds only the default-target behavior; it does not say that a brand-new pane is created, that repeated calls yield multiple panes, or what state the split leaves behind.

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, no filler, and the core action plus its default scoping are front-loaded. Every sentence 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 five-parameter mutation with no output schema, the description is adequate but thin: it never states what the call returns (e.g. a new pane identifier), which an agent would want in order to chain follow-up calls against the split pane. The rich schema compensates for argument completeness, but the return/effect gap remains.

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 baseline is 3 and every parameter (cwd, focus, ratio, pane_id, direction) is already documented in the schema. The description repeats the pane_id default semantics without adding format or constraint detail beyond the schema.

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

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

States a specific verb and resource ('Split a pane') and adds the default target scope ('Defaults to the calling/focused pane'), which distinguishes it from siblings like herdr_pane_resize, herdr_pane_move, and herdr_pane_zoom. No sibling is named as an alternative, 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 default-target sentence implies when the tool is appropriate (splitting the current pane without specifying an id), but there is no explicit when-to-use vs when-not guidance and no mention of alternatives such as herdr_tab_create for a new tab. Usage is inferable but not 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, destructiveHint=false, so the safety profile is known. The description adds little beyond that: it doesn't explain what happens on timeout (does it fail? return partial output?), whether it blocks or polls, or how the match is evaluated across the buffer. For a waiting/blocking operation, these are important behavioral details.

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

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

A single short sentence that front-loads the core action and scope. No waste, 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?

The tool has 6 parameters (1 required), no output schema, and annotations that cover safety. The description states the core purpose but omits critical operational details for a wait tool: timeout behavior, blocking vs polling, and what constitutes a match (entire buffer vs recent lines). For a tool with this complexity, it is minimally complete but leaves meaningful gaps.

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

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

Schema coverage is 100%, so the schema documents all six parameters, including enum for source and defaults. The description adds no parameter-level meaning beyond the schema. With full schema coverage, baseline 3 is appropriate.

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

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

Clear verb+resource: 'wait until a pane's output matches'. States the resource (pane output) and the trigger condition (text or regex). However, it doesn't differentiate from the sibling herdr_pane_read or herdr_agent_wait, which could also relate to waiting for output.

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

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

No when-to-use guidance, no alternatives mentioned. Given siblings like herdr_pane_read and herdr_agent_wait, an agent cannot tell from the description whether to poll with this or use another tool. The description says what it does but not when to choose it.

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

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

Annotations already declare the full behavioral profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), and the description adds no context beyond them – no note on what zooming visually does, whether it affects other panes, or any resulting state change. The bar is lower with annotations, but this description contributes nothing extra.

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 short sentence with zero waste and the action front-loaded. It is efficient, though arguably terse enough to border on under-specification for a tool with a toggle mode.

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 zero-required-parameter toggle with 100% schema coverage and no output schema, the essentials are covered by the schema. The description is the minimum viable, but adds nothing about behavior or results that would round it out.

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

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

Schema description coverage is 100%, so both parameters (mode with its enum and default, pane_id with its omission default) are fully documented in the schema. The description adds no syntax or semantic detail beyond the schema, 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 pair ('Zoom or unzoom') and resource ('a pane'), so the agent knows exactly what operation is performed. It does not distinguish itself from potentially confusable siblings like herdr_pane_resize or herdr_pane_move, but the action is unambiguous.

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

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

The description gives no guidance on when to use zoom versus resize or move, nor any prerequisites or exclusions. Usage must be inferred 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.

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuine value by enumerating what the snapshot contains (focused ids, counts by status, live agent locations), which is the behavioral detail an agent needs to know before calling.

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

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

One sentence of content plus a two-word directive, both front-loaded 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?

For a read-only overview tool with no output schema, the description adequately conveys what comes back and when to reach for it. It could be slightly stronger on how it relates to herdr_agents, but nothing essential is missing.

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

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

Schema description coverage is 100% and the single optional workspace_id is fully documented in the schema. The description adds no scoping detail beyond it, 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?

Specific verb-less but concrete resource: a condensed session snapshot listing focused ids, counts by status, and live agents with locations. That is far more than a restatement of the name. It does not explicitly contrast itself with the overlapping sibling herdr_agents, so it stops short of a 5.

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

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

"Start here" is an explicit directive telling the agent this is the orientation call before drilling into specific agents, panes, or workspaces. It gives clear usage context but names no exclusions or alternative tool for the same information.

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?

The annotations already declare destructiveHint=true, so the trailing 'Destructive.' merely restates structured data and earns no credit. The description does add one useful behavioral detail beyond the annotations: that the tab's panes are destroyed along with the tab, which is meaningful scope-of-destruction context.

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 very short sentences with the scope statement front-loaded. The 'Destructive.' fragment is redundant against the annotations, which costs it the top score, but nothing else is wasted.

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

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

Adequate for a simple destructive action whose safety profile is fully covered by annotations and whose parameters are fully documented by the schema. It is missing, however, any note on consequences (killed pane processes, irreversibility) or routing to sibling close tools.

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

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

Schema description coverage is 100% with only two parameters, so the schema already documents tab_id and the confirm guard. The description adds nothing about identifier format or why confirmation is mandatory, making this the baseline 3.

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 ('Close a tab') and clarifies scope by noting it also closes the tab's panes, which is what separates it from herdr_pane_close. It stops short of naming those sibling tools explicitly, so differentiation is implied rather than stated.

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

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

There is no guidance on when to use this versus herdr_pane_close or herdr_workspace_close, and no prerequisites or warnings about what happens to running processes in the closed panes. The agent must 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.

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

Annotations already declare the full safety profile (not read-only, non-idempotent, non-destructive, closed-world), so the description is not the sole carrier of behavior. It adds only the implicit fact that workspace targeting is optional, and says nothing about defaults, auth, or side effects — acceptable but thin with annotations present.

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 short sentence with the core action front-loaded and the optional scoping tacked on. Zero wasted words.

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

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

For a simple create tool with a fully documented schema and annotations covering safety, the description covers purpose and scoping adequately. The only real gap is not stating the default workspace behavior when workspace_id is omitted.

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

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

Schema description coverage is 100%, so all four parameters (cwd, focus, label, workspace_id) are already documented in the schema. The description only restates workspace_id as optional, adding no syntax or format meaning beyond the structured fields.

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

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

Specific verb (Create) + resource (a tab) with a stated scope modifier (optionally in a specific workspace). It is clearly distinguishable from herdr_tab_close and herdr_tabs by the create verb, but it never names or contrasts those siblings.

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

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

No guidance on when to use this versus alternatives such as herdr_open_agent or herdr_workspace_create, no prerequisites, and no statement about what happens when workspace_id is omitted. The agent must infer all usage context.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, covering the safety profile. The description adds the scoping constraint that the list can be restricted to one workspace, which is useful operational context, but discloses no additional behavioral traits such as pagination, return format, or auth requirements.

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

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

One short sentence with zero waste, front-loading the action ('List tabs') and then the optional scope. Every word earns its place for a tool of this simplicity.

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 operation with rich annotations and full schema coverage, the definition is nearly complete. It omits return-value details, but with no output schema and an obvious list semantic, that is a minor gap rather than a blocking one.

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

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

Schema description coverage is 100%, and the single optional parameter workspace_id is fully described in the schema as 'Restrict to this workspace id.' The description's 'optionally in one workspace' mirrors this without adding syntax, format, or edge-case details beyond what the schema already provides.

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

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

States a specific verb and resource ('List tabs') and scopes it with 'optionally in one workspace.' This clearly distinguishes it from sibling tools like herdr_tab_create and herdr_tab_close. It does not explicitly name those alternatives, 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.

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

Provides no when-to-use guidance or comparison to alternatives. The phrase 'optionally in one workspace' implies you can filter, but it does not say when to prefer this tool over herdr_workspaces, herdr_panes, or other list tools, nor does it state any exclusion conditions.

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 destructiveHint=true, readOnlyHint=false and idempotentHint=false, so 'Destructive.' merely restates structured data and earns no credit. Nothing is added about the group-close side effect on linked worktrees, whether closed panes lose state, or whether the operation can be undone.

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

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

Two short sentences with the operation front-loaded and the risk flag second. No waste, though the extreme brevity is under-specification rather than elegance.

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

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

For a destructive mutation with full annotation coverage and a fully documented schema, the minimum is met: safety profile from annotations, parameter meaning from the schema. Gaps remain around the group/linked-worktree cascade and confirmation semantics, which the description should surface given the destructive nature.

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

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

Schema description coverage is 100%, so each parameter (workspace_id, confirm, group) is already documented in the schema. The description adds no formatting, ordering, or semantic 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 and resource: closing a workspace, explicitly including its panes. This scope ('and its panes') distinguishes it from herdr_pane_close and herdr_tab_close, though the description never names those alternatives.

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

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

There is no when-to-use or when-not-to-use guidance, and no mention of the required confirm flag as a precondition. 'Destructive.' is a warning label, not usage routing; an agent gets no instruction on choosing this over herdr_pane_close or herdr_worktree_remove.

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 disclose the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the description is not the sole source of behavioral information. Still, it contributes nothing beyond that: no indication of what a workspace is, whether creation has side effects, or that all parameters are optional. It neither contradicts nor enriches 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?

A single short sentence with no wasted words and the key verb front-loaded. That said, the brevity is under-specification rather than disciplined economy, so it earns only a middling score.

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?

This is a creation/mutation tool with no output schema and three optional parameters, yet the description explains nothing about what is created, what happens if cwd is omitted, or what the caller receives back. For a state-changing operation it leaves significant gaps.

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 cwd, focus, and label are fully documented in the schema itself. The description adds no additional meaning such as defaults or interaction between parameters, which is the expected baseline-3 outcome when the schema does the heavy lifting.

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

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

The description states a verb and resource ('Create a workspace'), so the basic operation is unambiguous. However, it adds nothing beyond what the tool name herdr_workspace_create already conveys and offers no differentiation from siblings like herdr_workspaces or herdr_workspace_close. It is minimally viable rather than genuinely informative.

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

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

There is no guidance on when to create a workspace versus using an existing one, no mention of prerequisites (e.g., a valid cwd), and no reference to related tools. The agent must infer all usage context 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.

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds nothing beyond that, but it is consistent with the annotations rather than contradicting them.

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 words, fully front-loaded and waste-free. It is minimal, but for a no-argument list tool there is little to trim or restructure.

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 gives no hint of what a workspace record contains or how results are ordered/paginated, and it doesn't route the agent among the many sibling list tools. Adequate but with clear gaps for a trivial tool.

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

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

The tool takes zero parameters, so the baseline is 4. There is no parameter semantics to document, and the empty schema is self-explanatory.

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?

Clear verb+resource ('List workspaces'), so an agent knows exactly what it retrieves. However, it offers no differentiation from siblings like herdr_tabs, herdr_panes, or herdr_agents, which are structurally similar list tools.

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 statement of when to use this versus the sibling list tools, nor any prerequisites or exclusions. The agent must infer usage purely from the name.

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=false, destructiveHint=false, and idempotentHint=false, so the safety profile is covered. The description adds the '(or open)' nuance and states it returns a workspace, but discloses nothing about path constraints, permissions, or side effects.

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

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

A single front-loaded sentence with no wasted words. However, the brevity borders on under-specification for a 7-parameter mutation tool, and the '(or open)' phrasing is slightly ambiguous.

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 7-parameter, zero-required mutation tool with no output schema and no annotations covering behavior, the description is far too thin. It does not explain how the parameters relate, what happens on partial input, or the resulting workspace.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters including the HERDR_MCP_CWD_ALLOW constraint on 'path'. The description adds no parameter meaning beyond what the schema provides, making the baseline 3 correct.

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

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

States a specific verb (create/open) and resource (git worktree), and notes the return value (its workspace). It implicitly separates itself from herdr_worktree_remove and herdr_worktree_list, though it never names those siblings explicitly.

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

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

The '(or open)' parenthetical hints at reuse of an existing worktree, but there is no when-to-use guidance, no prerequisites, and no reference to the sibling worktree tools or herdr_workspace_create.

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, destructiveHint=false, so the safety profile is fully covered by structured data. The description contributes one useful nuance — that the result is Herdr's registry of worktrees rather than a raw git query — but says nothing about pagination, ordering, or output 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?

A single front-loaded sentence with zero filler. Every word earns its place and the resource is stated before any qualification.

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 minimally adequate. It is missing only minor clarification about filter behavior and result contents, which keeps it at the minimum-viable level rather than deficient.

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

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

Schema coverage is 100%, so both optional parameters (cwd, workspace_id) are already documented in the schema. The description adds no information about how these act as filters or what happens when both/neither are supplied, so the baseline of 3 applies.

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

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

States a specific verb and resource ('List git worktrees') with a scoping qualifier ('known to Herdr'), which distinguishes it from Herdr's own 'git worktree list'. Siblings like herdr_worktree_create/remove make the list-vs-mutate split inferable, but the description never names or contrasts them explicitly.

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

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

There is no statement of when to use this tool, when not to, or what alternative exists. The only usage signal is the implicit read-only nature of the verb. An agent must infer the context entirely.

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

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

The annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so 'Destructive.' merely restates structured data rather than adding context. The description does not say what is lost (e.g. uncommitted changes, agent state) or whether the operation can be undone, which would be the valuable addition for a destructive mutation.

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

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

Two short sentences with the destructive warning front-loaded; nothing is wasted and the key signal is immediately visible.

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

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

For a destructive mutation with full annotation and schema coverage, the description is minimally adequate: safety is covered by annotations and parameters by the schema. It still omits when to prefer this over herdr_workspace_close and what exactly gets destroyed, which an agent would benefit from.

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

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

Schema description coverage is 100%, so all three parameters (workspace_id, confirm, force) are already documented in the schema. The description adds no syntax, formatting, or interaction detail beyond that, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Remove a worktree workspace'), which clearly separates it from herdr_worktree_create and herdr_worktree_list. However, it does not differentiate itself from the similar herdr_workspace_close sibling, leaving some ambiguity about which removal tool applies.

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

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

There is no guidance on when to use this tool versus alternatives such as herdr_workspace_close, nor any stated prerequisites. The only implied usage comes from the word 'Remove', which is not enough to route an agent among closely related siblings.

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