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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds nothing beyond purpose — no note on what the explanation contains, whether it reflects a snapshot in time, or any cost/latency characteristics of a diagnostic call.

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 with no filler, and the diagnostic intent is front-loaded on the verb. It is efficient but borders on under-specified rather than optimally concise.

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?

An output schema exists, so return values need not be explained, and the read-only annotations cover safety. Still, the sole parameter's accepted values and the situations that warrant this tool over agent_get are absent, leaving an agent to guess at invocation details.

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 0% for the single required 'target' parameter, so the description must carry the burden. Saying 'an agent' weakly implies target is an agent identifier, but it never states the accepted format (name vs. ID) or whether panes/sessions are also valid, leaving the only parameter effectively undocumented.

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 specific verb ('Explain') and a specific resource (how Herdr detected an agent and why it reports its current state), which is meaningfully distinct from data-fetching siblings like agent_get or agent_list. It does not, however, name those siblings or state explicitly how it differs from them.

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

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

The use case is implied — reach for this when you need the reasoning behind an agent's detected/current state rather than the raw state itself. There is no explicit when-to-use, when-not-to-use, or named alternative among the many agent_* siblings.

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 phrase 'mark its completion as seen' usefully discloses the extra state mutation that justifies the non-idempotent, non-read-only annotations. However, nothing is said about what happens when the target agent is still running, whether the 'seen' flag is reversible, or what permissions are required.

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 primary action front-loaded and no filler. It is efficient, though the compression contributes to the missing parameter detail.

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?

An output schema exists so returns need not be explained, and the mutation is disclosed. The remaining gaps are the undefined 'target' argument and the absent routing guidance for a tool that mutates UI 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 description coverage is 0% and the required 'target' parameter is left completely undefined. The description hints that it identifies an agent, but never says whether it is an agent ID, a pane ID, or a name, so an agent cannot reliably construct the call from the text.

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: switching the user's view to an agent's pane and clearing its completion indicator. It is reasonably distinguishable from workspace_focus and tab_focus by the 'agent's pane' scoping, though it does not explicitly say how it relates to 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 rather than agent_get, agent_read, pane_read, or the workspace/tab focus tools. The agent must infer that this is for navigating the UI to a specific agent rather than inspecting its 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 readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds that the lookup key can be either a name or a pane id, which is real context, but says nothing about not-found behavior or what a retrieved agent record contains.

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; the lookup key options come after the verb resource and nothing is redundant.

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 a rich annotation set and an output schema, the description need not explain safety or return shape, and it does cover the identifier forms. Only the failure mode (target not found / ambiguous name vs pane id) is left unaddressed, which is a minor gap for a simple lookup.

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

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

Schema coverage is 0% — the lone 'target' parameter has no description in the schema — but the description compensates by specifying both accepted identifier forms (unique agent name or hosting pane id). That is the key semantic detail an agent needs to pass the argument correctly.

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

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

States a specific verb ('Get') and resource ('one agent'), and the singular 'one agent' implicitly distinguishes it from the sibling agent_list. It stops short of naming an alternative explicitly, so it is clear but not maximally differentiated.

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

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

Usage is implied by 'by unique name or hosting pane id' — an agent can infer this is a fallback/alternative to enumerating with agent_list. No explicit when-to-use, when-not, or sibling routing is 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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered and the description needn't repeat it. The one piece of added behavioral context is the word 'recognized', which implies only detected/known agents appear rather than all processes, but that qualifier is left unexplained. No ordering or scoping behavior is disclosed.

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 and resource first and the returned fields as a trailing enumeration. There is no filler and nothing an agent must read past to reach the point.

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 zero parameters, a full annotation set and an output schema, most of the burden is already carried by structured fields, so the description only needs to convey scope. The remaining gap is the undefined scope of 'recognized' — whether agents outside the current workspace or in other panes are included.

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 of 4 applies; there is no parameter semantics to document. The description does not need to compensate for any schema gap.

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

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

The description gives a specific verb ('List') and a specific resource ('recognized coding agents'), plus the attributes returned (kind, name, pane, cwd, status, terminal title). It is clear what the tool does, but it never distinguishes itself from siblings like agent_get or agent_explain, so an agent must infer that this is the enumeration counterpart to those single-agent lookups.

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

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

Usage is only implied: 'List' with no parameters signals an unfiltered enumeration, and the sibling set contains agent_get for single lookups. However, the description never says when to use this versus agent_get/agent_explain, nor whether the list spans all workspaces and panes or just the current one.

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 only declare it as a non-readonly, non-idempotent mutation; the description adds the substantive behavior the annotations can't express: blocking semantics, the default settle states, the override via 'until', and a named error condition (agent_blocked). It omits what happens when the block exceeds the timeout, which is the main remaining behavioral unknown.

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. The core action comes first, then the blocking/error semantics; every clause carries information an agent needs.

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?

An output schema exists, so return values needn't be explained. But for a 5-parameter blocking mutation, the absence of any timeout_ms guidance or timeout behavior leaves a gap in an otherwise tight definition.

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 0%, so the description must carry all parameter meaning. It explains wait, until (matching the enum values idle/done/blocked), and implies target/text, but timeout_ms (default 120000) is never mentioned — a critical omission for a call that blocks by default.

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 an agent' — which is distinct from sibling tools like agent_send_keys (keystrokes) and agent_wait (passive waiting). It never names a sibling explicitly, so the differentiation is inferred 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?

'With wait=true, block until the agent settles' tells the agent when to choose blocking behavior and how 'until' overrides the default settle set (idle, done, blocked). The rejection case 'agent_blocked if the agent is already waiting at a dialog' is a real precondition that steers the caller away from an invalid call, though it never points to an alternative tool for that situation.

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 establish that this is a safe, read-only, idempotent operation. The description adds useful behavioral context by explaining when to call it and what source=detection returns, though it does not explain default source behavior or line-limiting semantics.

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

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

Two short sentences with no wasted wording, and the primary purpose is front-loaded before the usage note.

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 existence of an output schema reduces the need to describe return values, and annotations cover the safety profile. However, for a read tool with four parameters and no schema descriptions, the description is not complete enough to guide correct use of target, lines, ansi, or the full source enum.

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 0%, so the description must carry parameter meaning, but it only explains one enum value for source. It leaves target, lines, ansi, and the other source values undocumented, which is a significant gap for four parameters.

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 an agent's terminal output." This is clear enough to identify the operation, though it does not explicitly distinguish itself from the sibling pane_read tool.

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

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

Gives explicit usage guidance: use it after agent_prompt to see the response, and use source=detection for raw bottom-of-screen text. It does not compare against alternatives like agent_wait or pane_read, so it stops short of full routing guidance.

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 only declare the generic profile (not read-only, not destructive, not idempotent); the description adds the non-obvious behavior that omitting 'name' actively clears the existing name, which is exactly the kind of surprise an agent needs flagged. It also reveals a uniqueness constraint, implying possible collision errors. It does not say what happens if 'target' does not exist.

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. The clear-on-omit rule is attached directly to the action it modifies rather than buried.

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

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

An output schema exists, so return values need not be explained, and the mutation semantics are partially covered. However, for a two-parameter mutation tool with zero schema descriptions, the missing definition of 'target' and the absence of any collision/error behavior leave an agent guessing at invocation details.

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

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

Schema coverage is 0%, so the description carries the whole burden. It gives real semantics for 'name' (unique, nullable, omit-to-clear), but leaves the required 'target' parameter completely unexplained — no hint whether it is an id, a name string, or how to obtain it.

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 ('Give... a unique name' / clear) and resource ('an agent'), which cleanly separates it from the many sibling *_rename tools (workspace_rename, pane_rename, tab_rename). It never explicitly names those siblings, but the resource scope 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 implies the two modes of use (supply a name to set, omit it to clear) but gives no guidance on when to prefer this over alternatives, nor any prerequisite such as the agent existing. Usage is inferable rather than stated.

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

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

Annotations already declare this is a non-readonly, non-idempotent, non-destructive, closed-world operation, so the safety profile is covered. The description adds the key-encoding model (logical key names in an array, e.g. ['ctrl+c']), but says nothing about whether presses are delivered sequentially, whether the agent must be focused, or whether delivery is acknowledged — notable for a non-idempotent 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?

One front-loaded sentence with the action first and illustrative values after; every clause earns its place. Slightly dense inline array literals make it marginally harder to scan than plain prose would.

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?

An output schema exists, so return values needn't be explained. But for a non-idempotent UI mutation over two required, undocumented parameters, the description leaves the meaning of 'target' and the focus/ordering behavior unaddressed — an agent could call it wrongly on a valid-looking guess.

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

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

Schema coverage is 0%, so the description carries the full burden. It does a good job on 'keys' via name examples ('esc', 'ctrl+c', 'enter', 'y'), but 'target' — a required parameter — is never explained (agent id? name? UI handle?), leaving half the inputs undocumented in both schema and prose.

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 and resource: 'Send logical key presses to an agent's UI', with concrete key examples that make the action unmistakable. It implies a scope distinction from the sibling pane_send_keys ('agent's UI'), but never names that sibling, so an agent must infer the split itself.

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

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

There is no explicit statement of when to use this versus pane_send_keys, agent_prompt, or pane_wait_output. The 'agent's UI' phrasing hints at a boundary, but no condition, exclusion, or prerequisite (agent started/focused) is 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 disclose that this is non-readonly, non-idempotent, and non-destructive, while the description adds the idle-pane precondition and notes that extra args are passed through to the agent CLI. It still does not explain failure behavior if the pane is not idle, timeout behavior, or other side effects beyond starting the process.

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

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

The description is a single, front-loaded sentence with no wasted wording. The core action and key precondition are stated immediately.

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

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

An output schema exists, so return values need not be explained, and annotations cover the safety profile. The description supplies the critical idle-pane precondition and kind examples; remaining gaps around timeout and name constraints are minor because timeout has a schema default.

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 0% across 5 parameters, so the description must carry the burden. It usefully explains kind examples and args routing, and implies pane_id must reference an idle shell pane, but it does not clarify name constraints, pane_id format, or timeout_ms semantics.

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 uses a specific verb and resource: start a coding agent, with kind examples, in an existing idle shell pane, and name it. This clearly distinguishes it from siblings such as agent_prompt, agent_list, and pane_run.

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

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

It gives an important prerequisite, that the shell pane must be existing and idle, which helps an agent avoid misuse. However, it does not explicitly say when to use this instead of pane_run, agent_prompt, or other sibling tools, nor does it describe when not to use 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 readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds the useful default-state set, but for a blocking wait it omits what happens on timeout expiry (error vs. current-state return) even though a 120s default timeout exists, which is a real behavioral gap.

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 waste, leading with the verb and the outcome. It is appropriately sized, though that brevity is part of why parameter and timeout behavior go unexplained.

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?

An output schema exists, so return values needn't be described. Still, for a three-parameter blocking tool with zero schema coverage, the definition leaves how to identify a target and what a timeout does unaddressed, which an agent needs to invoke it confidently.

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 0%, so the description must carry parameter meaning. It partially covers 'until' (settled states plus override), but 'target' is never defined (agent id? name? handle?) and 'timeout_ms' is never mentioned despite its 120000 default and the tool's blocking nature.

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 (wait) and resource (agent state), and enumerates the settled states it resolves on. It does not name or distinguish itself from waiting siblings like pane_wait_output or events_wait, so the agent must infer which wait 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?

It explains the default settle set (idle, done, blocked) and how 'until' overrides it, which implies usage. But there is no explicit "use this when you need X instead of pane_wait_output/events_wait" guidance and no stated preconditions such as needing a live agent target.

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, so safety is covered; the description adds genuinely new behavioral facts — events are buffered, ordering is oldest-first/newest-last, and the response carries a latest_seq cursor for continuation. It does not mention buffer bounds or what happens if since_seq has fallen out of the buffer, which would be the remaining gap.

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

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

Front-loaded with the core action and ordering, then the kind vocabulary, then the return contract — a logical order with no filler. The kind enumeration is long but is the only documentation of valid filter values, so it earns its space.

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?

Output schema exists, so return shape needn't be explained, and the description correctly covers ordering and the cursor. But for a 6-parameter filterable list tool with zero schema coverage, the absence of any explanation of the filter parameters leaves an agent unable to use half the surface confidently.

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 0% across 6 parameters, so the description must carry the burden. It explains since_seq and effectively enumerates the legal values for the kinds filter, but limit, pane_id, workspace_id, and agent_status filters are documented nowhere, and the combination/AND semantics of the filters are unstated.

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: buffered Herdr events after a sequence cursor, returned newest-last. It implicitly separates polling-style retrieval from the blocking siblings events_wait and events_status, but never names them, so sibling differentiation is left to inference.

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 cursor-driven phrasing ("after since_seq", "latest_seq to use as the next cursor") implies the incremental-polling use case, which is the main thing an agent needs to know versus events_wait. However, there is no explicit when-to-use or when-not-to-use guidance and no mention of the sibling tools.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description still adds value by disclosing the payload surface and the important caveat that agent status is 'last known' — i.e. potentially stale — which annotations cannot convey.

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 listing the three things returned, with no filler. Every clause earns its place, including the parenthetical naming the seq fields.

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 an output schema documenting return values, full annotation coverage, and no parameters, the description needs only to frame what the tool reports — which it does. A small gap: it doesn't say what happens when the tap is disconnected, though 'connection' in the summary implies that is reported rather than raised.

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

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

Zero parameters, so the baseline of 4 applies. The description correctly adds no parameter detail because there is none to add.

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

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

States a specific resource — the live event tap — and enumerates exactly what it returns: connection state, buffer bounds (oldest_seq, latest_seq), and per-pane agent status. That clearly separates it from events_recent (event lists) and events_wait (blocking waits), though it does not name 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?

Usage is implied rather than stated: an agent can infer you call this to inspect tap health before consuming events, but there is no explicit when-to-use/when-not-to-use guidance and no reference to events_recent or events_wait as 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 cover the safety profile (readOnly, idempotent, non-destructive), so the description's real contribution is the blocking/timeout behavior and the explicit failure shape: 'Returns timed_out=true with no events when nothing matched.' That is exactly the kind of context an agent needs before calling a long-blocking tool. It doesn't mention the 60s default timeout or that the call occupies the agent until it fires.

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

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

Three short sentences, front-loaded with the blocking behavior, then an example, then the return caveat. No filler; the only mild redundancy is that timeout_ms in the first sentence is restated contextually.

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?

An output schema exists, so return values needn't be explained, and the description does note the timed_out case. But for a 7-param blocking tool with zero schema descriptions, the unmentioned scope filters (pane_id, workspace_id, limit) and the default timeout leave real gaps an agent must guess at.

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

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

Schema coverage is 0%, so the description must compensate, and it only partially does: it explains since_seq (a cursor), timeout_ms, and gives example values for kinds and agent_status. Three of seven params (limit, pane_id, workspace_id) get no mention at all, leaving their filtering semantics undocumented.

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 ('Block until a matching event arrives') plus the key gating condition (after since_seq, or until timeout_ms). 'Block' implicitly distinguishes it from the non-blocking siblings events_recent/events_status, but those siblings are never named.

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 'Typical: kinds=["pane_agent_status_changed"], agent_status=["done","blocked"]' example gives implied usage context for the common case. It never says when to use this instead of events_recent or events_status, nor when not to block, so 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the reported payload (version, event tap state), but says nothing about failure behavior — whether an unreachable server raises an error or returns a status field.

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; the purpose and the returned information are both stated up front, and 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?

With an output schema present, return values need no prose, and the annotations cover safety. What remains missing is only the error/unreachable contract, which matters for a reachability probe but is a minor gap given the schema-backed output.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. It also correctly implies the call is argument-free.

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 ('Check that Herdr is reachable') plus what it reports (server version, event tap state), which separates it from the many pane/agent/workspace siblings. It does not explicitly name a sibling it is not, so it falls short of the 5 bar.

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

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

Usage is only implied: an agent can infer it is a health/diagnostic probe to call before or alongside other Herdr operations. The description never says when to prefer it over events_status or session_snapshot, nor states any preconditions 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?

The annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false) already sketch the safety profile, so the bar is lower. The description does add one genuinely useful behavioral fact – that the toast renders inside the Herdr terminal UI rather than as a system notification – but says nothing about duration, stacking, whether an active UI is required, or what happens when the UI is not focused.

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 filler and the scoping detail front-loaded. Brevity here reflects under-specification rather than unnecessary padding, so it earns a good but not top 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?

An output schema exists, so return values need not be described, but for a four-parameter mutation-flavored tool with zero schema descriptions the description should explain the parameters and the transient nature of the toast. It leaves the agent to guess at placement, sound, and display duration.

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 0% across four parameters, including two enums (sound: none/done/request, position: corner values). The description explains none of them, so the agent cannot tell the role of body vs. title, the default placement, or how sound affects behavior.

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 ('Show a toast') and scopes it to the Herdr terminal UI, which distinguishes it from OS-level notification tools. It is not a tautology of the name, and no sibling tool covers notifications, so the purpose is legible without opening the schema.

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

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

There is no statement of when to use this tool, when not to, or how it relates to any alternative. An agent must infer entirely from the tool name that this is for surfacing a transient user-facing message.

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 flag destructiveHint=true, but the description adds substantive context beyond them: the pane's process is killed, not just detached, which is the core risk an agent needs to weigh. Missing is what happens on failure or whether the pane must be idle/owned first.

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: purpose first, safety constraint second. No filler, nothing repeated from the schema or annotations.

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 one-parameter tool with annotations covering safety flags and an output schema covering returns, the description supplies the crux (process termination) and an ownership guard. Only the pane_id provenance/format is left unexplained.

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 0% for pane_id, and the description says nothing about the parameter — no format, no source (e.g., from pane_list), no scoping. With one undocumented required parameter, the description should compensate and does not.

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+resource ('Close a pane') and adds the key consequence ('kill its process'). The pane scope implicitly distinguishes it from tab_close and workspace_close, though that distinction is never made explicit.

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

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

Provides an explicit precondition/exclusion: 'Only close panes you created or the user named.' That is a real usage rule an agent can act on, though it does not name an alternative tool or explain what to do if the pane fails the check.

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, non-destructive, and closed-world behavior. The description adds only the example ID format and no extra behavioral context such as invalid-ID handling; with rich annotations, this is minimally adequate.

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 front-loaded sentence with zero filler. It communicates the core action and an example immediately.

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

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

For a simple read-only getter with annotations covering safety/idempotency and an output schema covering return values, the description is mostly complete. The main remaining gap is lack of guidance on obtaining the pane ID or choosing among related pane 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 0%, so the description must compensate. It gives a concrete example format ('w1:p3'), which is useful, but does not explain where to obtain the pane_id or any constraints.

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

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

States a specific verb and resource: get one pane by id. The example ID format helps, but the description does not explicitly differentiate this from siblings like pane_list or pane_read.

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 explicit when-to-use guidance, prerequisites, or alternatives. The phrase 'by id' implies the caller must already know a pane ID, but there is no routing guidance versus pane_list or 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 readOnlyHint, idempotentHint, non-destructive behavior, and a closed world. The description adds useful context by naming the returned data (rects and split tree), which goes beyond safety annotations, but it does not explain permissions, freshness, or other behavioral traits.

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

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

Two short sentences with no filler, and the primary purpose and use case are front-loaded. Every phrase contributes to understanding the tool.

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

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

For a simple read-only geometry tool with an output schema and full safety annotations, the description gives enough context to understand what is returned and why an agent would call it. It is only slightly incomplete regarding parameter semantics and sibling differentiation.

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 schema has 0% description coverage, and the description says nothing about the sole parameter, pane_id. Although the parameter name is fairly self-explanatory and required, the description does not compensate for the missing schema documentation.

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 resource and result: the geometry of the tab containing a pane, including rects and the split tree. It clearly distinguishes this as a layout-inspection tool, though it does not explicitly name sibling tools like pane_split or pane_get.

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 'Use it to pick a split direction' gives an implied use case, but there is no explicit guidance on when to choose this over pane_split, pane_get, or pane_list, nor any 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 this as a read-only, idempotent, non-destructive, closed-world operation, so the safety profile is covered. The description adds useful context by naming the fields returned and the optional workspace scoping, but it does not disclose pagination behavior, ordering, or other operational traits beyond what the annotations and output schema provide.

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

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

The description is a single front-loaded sentence with no redundant clauses. Every phrase contributes either the operation, the returned fields, or the optional scoping constraint.

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 one optional parameter, an output schema, and rich annotations, the description is nearly complete for correct invocation. It covers the operation, returned fields, and workspace scoping; only minor details such as ordering or pagination are unaddressed.

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

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

Schema description coverage is 0%, so the description must carry the burden for the single parameter. It does identify the parameter's purpose by saying 'optionally within one workspace', which maps to workspace_id and clarifies its optional nature, but it does not explain how to obtain or format a workspace ID.

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

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

The description states a specific verb and resource ('List panes') and names the returned fields (cwd, title, hosted agent, agent status), making the operation clear. It does not explicitly differentiate itself from the sibling 'pane_get', but the list-versus-single-record distinction is strongly implied.

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 within one workspace' clarifies that the tool can be used globally or scoped to a workspace, which is implied usage guidance. However, it does not explicitly say when to use this tool versus alternatives such as pane_get or workspace_list, nor does it state any 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds little beyond that, but it does not contradict the annotations and an output schema exists to cover return 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?

The description is a single front-loaded sentence with no wasted words. It is concise, though its brevity leaves gaps that belong to other dimensions rather than being a structural flaw here.

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

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

The tool is simple, read-only, and has an output schema, so the description need not explain return values. However, given 0% schema description coverage for the required pane_id and no usage guidance, the description is only minimally complete for an agent to call it correctly.

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

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

There is one required parameter, pane_id, and the schema description coverage is 0%. The description only says 'for a pane' and does not explain the pane_id format, source, or expected value, so it fails to compensate for the missing schema documentation.

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

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

The description clearly states a specific resource and information type: foreground process and shell information for a pane. It does not explicitly distinguish itself from nearby siblings like pane_get or pane_read, 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 gives no guidance on when to use this tool versus pane_get, pane_read, pane_list, or other pane-related tools. Usage is only implied by the phrase 'process and shell information', with no alternatives or exclusions named.

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 behavior, so the description only needs to add context. It adds a useful nuance that recent-unwrapped joins soft wraps, but says nothing about the 'recent' and 'detection' sources, the ansi flag's effect, or errors on a dead pane.

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 core action, with no filler. The trailing clause is dense but each phrase contributes a distinct piece of 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?

An output schema exists so return values needn't be spelled out, and the read-only profile is covered by annotations. However, with 0% schema coverage, the missing explanation of ansi, lines, and two source modes leaves real gaps for correct invocation.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, yet it explains only two of four enum values for the 'source' parameter and says nothing about 'ansi' or 'lines'. 'pane_id' and the remaining source values are left entirely undocumented.

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 terminal output from a pane') that is clearly distinct from mutation siblings like pane_run or pane_close. It does not explicitly distinguish itself from pane_wait_output or agent_read, which read similar data, 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?

Guidance is given at the parameter level ('recent-unwrapped ... suits logs; visible is the rendered viewport'), which implies when to pick a source. It does not say when to use this tool instead of pane_wait_output or agent_read, nor when not to use 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 this is a non-read-only, non-destructive, non-idempotent operation. The description adds useful behavioral context by explaining that omitting the label clears it, which is not obvious from the schema alone. However, it does not clarify whether clearing is reversible, what permissions are required, or whether the pane must already have a label.

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

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

The description is a single compact sentence with zero waste. The primary action is front-loaded, followed immediately by the important omission behavior.

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 simple two-parameter tool with an output schema and annotations covering safety. The description explains the only non-obvious behavior, clearing on omitted label, so an agent has enough context to invoke it correctly. Minor gaps like permission requirements are acceptable given the low complexity and available structured metadata.

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 0%, so the description must carry the burden. It explains the important semantics of the optional label parameter, namely that omission clears the label, but it does not describe pane_id format or meaning. Given that pane_id is a required string with an obvious name, the partial compensation is adequate for a 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?

The description states a specific action ('Set') and resource ('pane's label'), and also explains the clearing behavior when the label is omitted. It distinguishes pane_rename from tab_rename/workspace_rename/agent_rename by resource, though it does not explicitly name any sibling tool.

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

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

The description provides no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. The only conditional usage information is the clearing behavior when label is omitted, which is more of a behavioral effect than a usage guideline.

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 non-read-only, non-idempotent, non-destructive, so the safety profile is known; the description adds that input goes through an interactive shell, which implies arbitrary command execution. It omits a key behavioral fact: that the command's output is not returned here and must be collected via pane_wait_output or pane_read, and it doesn't say what happens if the pane is not at a prompt.

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 action first and the precondition second; no filler, nothing repeated from annotations.

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?

An output schema exists so return values needn't be explained, and the precondition is stated. But for a two-param tool at 0% schema coverage, the omission of pane_id format and of the follow-up step to read command output (a sibling tool exists for exactly that) 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 description coverage is 0%, so the description must carry both parameters. It clarifies that 'command' is a shell command executed with Enter, but says nothing about the pane_id form (numeric vs '%1'-style) or whether the command is a single line.

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 (type a shell command into a pane) plus the distinguishing action of pressing Enter, which differentiates it from the text/keystroke siblings like pane_send_text and pane_send_keys. It stops short of naming any sibling explicitly.

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

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

"The pane must be at an interactive shell prompt" gives a real precondition for use, which is more than a bare capability statement. However, it never says when to prefer this over pane_send_text / pane_send_keys, nor what to do if the precondition fails.

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, so the core safety profile is covered. The description adds only example key strings and does not explain delivery timing, focus requirements, or effects such as ctrl+c interrupting a running process.

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 definition is a single front-loaded sentence with no filler, and the examples are embedded efficiently. Nothing in the description 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?

For a two-parameter mutation tool with no schema descriptions, the definition is missing pane_id semantics and usage boundaries versus pane_send_text and agent_send_keys. The output schema and annotations cover return values and safety profile, but the description remains too thin for this tool's input surface.

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 0%, so the description must carry parameter meaning. It gives useful examples for the keys array, but it says nothing about pane_id or the accepted key grammar, leaving key parameter semantics incomplete.

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

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

The description states a specific verb and resource: "Send logical key presses to a pane," and gives examples of key values. It is clear what the tool does, but it does not differentiate from sibling tools such as pane_send_text or agent_send_keys.

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

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

It only says what the tool does, with no when-to-use guidance, prerequisites, or comparison to alternatives. The examples hint that this is for key sequences rather than text, but they do not route an agent between pane_send_text and agent_send_keys.

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 operation. The description adds the useful behavioral nuance that text is sent without an Enter keystroke, but it does not explain what 'raw text' means at the pane level, whether it is inserted at the cursor, or what happens on failure.

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

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

The description is a single front-loaded sentence with no wasted words. It communicates the action and the key constraint immediately.

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

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

For a simple two-parameter tool with an output schema and annotations, the description covers the core action and the no-Enter behavior. However, it omits pane_id semantics and does not explicitly route the agent away from similar tools such as pane_run or pane_send_keys.

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 0%, so the description must carry the burden for both parameters. It clarifies that 'text' is raw text sent to the pane, but it provides no meaning for 'pane_id' beyond the parameter name, leaving an important identifier undocumented.

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 ('Send') and resource ('raw text to a pane'), and adds the key qualifier 'without pressing Enter' that distinguishes it from a command-submission tool. However, it does not explicitly name sibling tools like pane_run or pane_send_keys, so sibling differentiation is only implicit.

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 'without pressing Enter' implies when this tool is appropriate versus a tool that submits commands, but there is no explicit when-to-use, when-not-to-use, or named alternative. An agent can infer the context but must consult sibling tools to be certain.

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, so the safety profile is covered. The description adds that the new pane is returned under result.pane, but discloses nothing about permission requirements, layout side-effects, or failure modes for a mutation. Adequate but thin beyond structured data.

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

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

Three short sentences, front-loaded with the core action and outcome. The 'result.pane' sentence is somewhat redundant given an output schema exists, costing a bit of tightness, but the structure is efficient.

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?

An output schema exists so return values needn't be explained, and annotations cover safety. However, for a 5-parameter mutation with 0% schema coverage, missing semantics for cwd, focus, and ratio leave the definition incomplete enough that an agent must guess.

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 0% across 5 parameters, so the description carries the full burden. It only clarifies 'direction' semantics (wide→right, tall→down) and 'beside it'; cwd, focus, and ratio are entirely undocumented in both schema and description.

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 (split) and resource (a pane) and the concrete outcome (creates a new shell pane beside it). The agent can tell exactly what the operation produces, and no sibling performs this pane-splitting action.

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 sentence 'Split wide panes right and tall panes down' gives directional guidance, but there is no explicit when-to-use vs. alternatives guidance (e.g., versus tab_create or creating a new workspace). Usage is implied rather than stated.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely useful blocking semantics and immediate-match-on-existing-output behavior. However, it omits what happens on timeout, precedence when both match and regex are supplied, and the meaning of 'source'.

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 with the blocking behavior front-loaded and the immediate-match nuance second. No wasted words, though it's too terse given the parameter gaps.

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?

An output schema exists so return values needn't be explained, but with 6 params at 0% coverage and an opaque 'source' enum plus a timeout, the description leaves too much unspecified for an agent to call this 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 coverage is 0%, so the description must compensate. It explains match (literal substring) and regex (Rust regex) well, but leaves pane_id, lines, timeout_ms, and the four-value 'source' enum entirely undocumented across 6 parameters.

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 ('Block until') and resource ('pane output contains...'), and distinguishes the two match modes (literal substring vs Rust regex). It's clear what the tool does, though it doesn't name a sibling like pane_read or agent_wait to differentiate.

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 pane_read or agent_wait/events_wait, and no prerequisites. The only contextual hint is 'Output that already exists matches immediately,' which is behavioral, not usage-routing.

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, so safety is covered. The description adds genuinely new behavioral context — that the response is large and costly, which is the key operational caveat for calling it.

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, contents front-loaded and the cost caveat second. 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?

An output schema exists, so return-value detail is unnecessary, and the description still summarizes the payload. For a zero-parameter read tool this is fully sufficient to call 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?

The tool takes zero parameters, so there is nothing to disambiguate; baseline applies. The description correctly implies no filtering or scoping arguments 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?

States exactly what the tool returns — a full live snapshot — and enumerates the resources covered (workspaces, tabs, panes, agents, layouts, focus). This makes it immediately distinguishable from the many single-resource list/get 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?

Explicitly says to prefer the list tools for routine checks, which gives the agent a clear selection rule. It does not name a specific alternative sibling, but the contrast with the list family is unambiguous.

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 flag destructiveHint=true and idempotentHint=false, but the description adds the cascading consequence ('every pane process in it'), which is the key thing an agent cannot infer from a flag. It does not restate irreversibility or confirmation behavior, which keeps it below a 5.

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

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

Two short sentences, zero padding, with the destructive scope stated before the safety constraint. 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 destructive mutation with an output schema present, the description covers blast radius and ownership limits, which is most of what an agent needs. The remaining gap is sourcing the tab_id, which nothing else documents.

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 tab_id has 0% schema description coverage, so the description carries the full burden and adds nothing: no id format, and no pointer to tab_list as the way to obtain a valid tab_id. The word 'tab' implies the resource but nothing more.

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 (close) plus resource (tab) and an explicit scope statement: 'every pane process in it'. The resource noun separates it from pane_close and workspace_close among the siblings, though those alternatives are never named.

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

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

'Only close tabs you created or the user named' is a concrete when-not-to-use rule that rules out opportunistic closing of tabs the agent doesn't own. It stops short of naming alternatives such as pane_close for closing a single pane instead of a whole tab.

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 write behavior with readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description adds that the tab starts with one shell pane and returns the new tab and root_pane ids, but it does not describe side effects such as focus behavior or workspace defaults.

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

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

The description is two short sentences with the creation purpose front-loaded and the return value noted immediately after. Every sentence adds useful information without 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 annotations cover the safety profile and an output schema exists, but the description leaves all four parameters unexplained despite 0% schema coverage. For a create tool with workspace, label, cwd, and focus options, this is incomplete.

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

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

There are four parameters (cwd, focus, label, workspace_id) with 0% schema description coverage, and the description does not mention any of them. An agent gets no explanation of what these optional inputs control beyond their bare schema titles.

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

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

The description states a specific verb and resource: create a tab, and adds the default scope that it contains one shell pane. It is clear enough to distinguish this from tab_list/tab_focus/tab_close by name, but it does not explicitly route against sibling tools such as pane_split.

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 only states what the tool does; it gives no guidance on when to use this tool versus alternatives such as pane_split or workspace_create. There are no exclusions, prerequisites, or contextual triggers.

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 the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the safety bar is lower. The description adds the useful non-obvious fact that this changes the user's visible view, but says nothing about failure when the tab id is invalid or unknown, which is the main behavioral risk.

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, front-loaded with the verb and resource, with the example folded inline. Nothing is wasted and nothing is buried.

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

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

With one parameter and an output schema present, return values need no explanation, and the id example covers the main input gap. Still missing is how to obtain valid tab ids (presumably tab_list) and what happens on an unknown id, which matters for a UI-mutating call.

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 0%, so the description carries the burden. It compensates well for a single parameter by giving a concrete identifier example ("w1:t2"), which is exactly what the bare 'tab_id: string' schema lacks.

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

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

Specific verb+resource: "Switch the user's view to a tab" tells the agent exactly what the call does, with an example identifier format. It does not distinguish itself from other focus-like siblings (workspace_focus, agent_focus), but the resource name 'tab' does most of that work implicitly.

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 workspace_focus, agent_focus, or tab_list, and no stated prerequisites (e.g., that the tab must already exist). The only contextual hint is 'the user's view', which implies a UI-facing operation.

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, and openWorldHint=false, so the safety profile is fully covered without description help. The description adds only the scoping note and does not contradict anything, but contributes no additional behavioral context such as ordering, completeness of results, or pagination.

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 clause with zero filler, with the scope qualifier front-loaded right after the verb. Nothing in it is redundant.

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 an output schema present, the description need not detail return values, and the annotations cover safety semantics. The remaining gap is minor: for a listing tool the agent still cannot tell whether omitting workspace_id returns tabs across all workspaces and in what order.

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 0% for workspace_id (only a bare title and null default), so the description is the sole source of meaning — and it does clarify that the parameter is an optional scope filter rather than a required selector. However, it says nothing about identifier format, null behavior, or what happens when it is omitted, leaving real ambiguity.

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

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

The description states a specific verb and resource ("List tabs") and adds an optional scope qualifier ("within one workspace"), which lets an agent distinguish it from mutating siblings like tab_create, tab_close, or tab_focus. It stops short of naming those siblings explicitly, so differentiation is implicit 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?

"Optionally within one workspace" implies the two usage modes (global listing vs. workspace-scoped listing) but does not say when to prefer one over the other, nor does it mention alternatives such as workspace_list for enumerating workspaces first. Guidance is inferable but not explicit.

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 safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), lowering the bar. The description adds nothing beyond that — no mention of what happens on rename, whether the label must be unique, or any 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 short sentence that is front-loaded and wastes nothing, but it is under-specified rather than genuinely concise in a helpful way.

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?

An output schema exists so return values needn't be explained, but with zero parameter documentation and no usage context, the definition leaves significant gaps for invoking a two-parameter mutation 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 0%, so both parameters (tab_id, label) are undocumented in the schema. The description only implies that a tab is identified and given a new label; it does not clarify tab_id format or label constraints.

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 clear verb ('rename') and resource ('tab'), which distinguishes it from unrelated siblings, but gives no differentiation from the closely related pane_rename, workspace_rename, and agent_rename 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 guidance on when to use this tool versus alternatives such as workspace_rename or pane_rename, and no prerequisites or context 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 destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is covered. The description adds meaningfully by disclosing the cascade — closing terminates every pane process in the workspace — and the ownership constraint, both of which go 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 and scope front-loaded, with the constraint second. Nothing wasted and nothing buried.

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

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

An output schema exists, so return values need no explanation, and the mutation's scope and ownership rule are both stated. Minor gaps remain around irreversibility and what happens to running agents, but the essentials for safe invocation are 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?

There is a single required parameter with 0% schema description coverage, and the description never addresses it. The name workspace_id is largely self-explanatory and the surface area is minimal, but the description offers no hint about where the ID comes from (e.g. workspace_list).

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 workspace") plus the blast radius ("every pane process in it"), which implicitly separates it from pane_close and tab_close. It does not name those siblings explicitly, so differentiation is inferred from scope 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?

"Only close workspaces you created or the user named" gives a real precondition, but it is a safety restriction rather than routing guidance. There is no mention of when to prefer tab_close/pane_close for narrower shutdowns.

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 non-read-only, non-destructive, non-idempotent, and closed-world, so the safety profile is covered. The description adds genuine value by disclosing the concrete side effects (a tab and a shell pane are created) and the returned ids. It does not warn that focus=true may steal UI focus, which is the one notable omission.

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, zero filler, and the side-effect statement is front-loaded ahead of the return-value note. 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?

Return values are covered (and an output schema exists anyway), and the creation side effects are stated. But for a zero-required-param creation tool whose optional arguments are fully undocumented, an agent still lacks enough to call it correctly with cwd/label/focus.

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 0% across all three parameters (cwd, focus, label), and the description never mentions any of them. The reader must guess whether label names the workspace or the tab, and what cwd defaults to for the shell pane.

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

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

Specific verb + resource ('Create a workspace') plus the exact composition it produces (one tab, one shell pane) and the identifiers returned. An agent can distinguish this from tab_create or worktree_create without opening any schema.

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

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

Usage is only implied: the reader infers this is the entry point before splitting panes or creating extra tabs, but the description never states when to use this versus tab_create or workspace_get. No prerequisites or exclusions 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 declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=false, and the description adds nothing on top: it doesn't say whether the switch changes persistent UI state, affects subsequent agent commands, or what happens to the previously focused workspace. It does not contradict the annotations, but it contributes no behavioral context of its own.

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 filler and the action front-loaded. Its brevity borders on under-specification, but nothing is wasted.

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

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

An output schema exists so return values need not be explained, but the description leaves key gaps for a state-changing focus tool: the source/format of workspace_id and the effect the switch has on subsequent tool calls. For a 1-param mutation sibling to several *_focus tools, this is too 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 coverage is 0% for the single required workspace_id, and the description never says what form the identifier takes or where to obtain it (e.g., from workspace_list). With one undocumented parameter, the description should compensate and does not.

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?

"Switch the user's view to a workspace" gives a specific verb and resource, and the word "view" distinguishes it from tab_focus and agent_focus, which act on tabs and agents. It never names a sibling explicitly, so the differentiation is implicit 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?

The description offers no when-to-use guidance, no prerequisites, and no mention of the near-identical siblings (tab_focus, agent_focus) that an agent could easily confuse it with. The agent must infer everything 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, idempotentHint, non-destructive, and closed-world, so the safety profile is fully covered elsewhere. The description adds nothing behavioral on top - no statement about error/not-found handling or what a successful lookup returns - beyond the id example.

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; the example is tucked in parenthetically where it does least harm. Slightly terse for a tool definition but never wasteful.

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 one required parameter, no enums, and an output schema already defined, the description needs only to convey lookup semantics and the id format. It covers purpose and a sample id but leaves the id's origin and failure behavior unstated, making it minimally adequate.

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

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

Schema description coverage is 0%, so the description must compensate, and it only partially does by giving an example id value ("w1") that hints at the expected string shape. It still doesn't say whether the id is the workspace name, slug, or opaque handle, nor how it is obtained.

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

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

States a specific verb and resource ("Get one workspace by id") and the singular framing clearly contrasts with a bulk retrieve. It does not explicitly name workspace_list as the alternative, so it stops short of the top score.

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?

"Get one workspace" implies a targeted lookup as opposed to workspace_list's enumeration, but the description never states when to use this versus workspace_list or what to do if the id is unknown. Usage is only inferable from the numbering.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is fully covered. The description adds that counts and agent status are aggregated, which hints at the cost and shape of the scan, but says nothing about ordering, filtering, or whether all workspaces are returned.

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 the verb and resource front-loaded and no filler. Every clause (labels, counts, aggregate status) conveys distinct information about the result.

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 an output schema present, return-value detail is not the description's job, and annotations cover the safety profile. What remains missing is scope — whether this lists every workspace unconditionally — which matters for an agent deciding between it and workspace_get.

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

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

Zero parameters, so there is no parameter semantics to explain and the baseline applies. Nothing in the description misleads about inputs.

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

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

Specific verb ('List') plus resource ('workspaces') and an enumeration of what each entry carries (labels, tab/pane counts, aggregate agent status). It is clearly distinct from workspace_get in spirit, but never names the sibling or states the enumeration-vs-single-item distinction 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?

No statement of when to use this versus workspace_get, tab_list, or pane_list — tools whose names imply overlapping enumeration. The agent must infer that this is the top-level discovery call.

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, openWorldHint=false, and idempotentHint=false, so the safety profile is covered. The description adds nothing beyond that — no note on what happens to the previous label, whether focus/state changes, or whether other sessions are affected by a rename.

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 four-word sentence is maximally front-loaded and wastes nothing. However, the brevity here reflects under-specification rather than disciplined conciseness, so it only reaches the minimum-viable level.

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?

An output schema exists, so return values need not be explained. But for a mutation tool with two fully undocumented parameters and zero behavioral context beyond the annotations, the description is too thin for an agent to call it confidently.

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

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

Schema coverage is 0%: neither 'workspace_id' nor 'label' has a description or format hint in the schema. The description only weakly implies that 'label' is the new name and never mentions workspace_id's expected identifier form, so it does not compensate for the coverage gap.

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

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

States a specific verb and resource ('Rename a workspace'), so an agent can immediately tell this mutates a workspace's name. It does not distinguish itself from the many sibling rename/close/create tools (pane_rename, tab_rename, agent_rename, workspace_close), leaving the reader to infer this is the workspace-level variant.

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 workspace_create, workspace_close, or the sibling rename tools, and no prerequisites (permissions, workspace state) are stated. The agent must infer usage entirely from 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 the write/idempotency/safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description adds one real behavioral fact beyond them — that a linked workspace is opened as a side effect — but says nothing about failure modes, existing-path/branch collisions, or whether a branch is created.

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 front-loaded sentence with no filler and the primary action stated first. It is efficient, but the brevity is partly under-specification rather than disciplined economy.

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?

An output schema exists so return values need not be explained, and annotations cover safety. However, for a 7-parameter mutation tool with zero schema coverage, the description omits the git-repo precondition, default behaviors for unset params, and conflict handling — not enough for correct invocation.

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

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

Seven parameters with 0% schema description coverage and none of them explained in the description. The words 'worktree' and 'linked workspace' hint that path/branch/base/workspace_id exist, but an agent gets no semantics for cwd, base, focus, or label.

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 ('Create a git worktree') plus a meaningful secondary effect ('open it as a linked workspace'). It is distinguishable from workspace_create and worktree_list by naming the git-worktree concept, though it never explicitly contrasts with workspace_create.

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 choose this over workspace_create or worktree_list, and no prerequisites stated (e.g. that the cwd must be inside a git repository). The agent must infer the usage 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds the scoping context ('known to a workspace or repository') but nothing about ordering, pagination, or what a 'known' worktree means.

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. Appropriately sized for a simple read-only list tool, though it leaves little room for the missing parameter 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?

The output schema will describe return values and annotations cover safety, so the main gap is parameter meaning. For a tool whose two optional params are entirely undocumented, the description should do more to explain cwd vs workspace_id.

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 0%, so both optional parameters (cwd, workspace_id) are undocumented anywhere. The phrase 'workspace or repository' loosely hints at workspace_id and perhaps a repo path via cwd, but it does not explain the semantics of either parameter or whether they are alternatives or combinable.

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') and scopes it to a workspace or repository, which separates it from worktree_create. It does not explicitly name the sibling, but the read vs create distinction is clear.

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 scope phrase implies when to use it (inspecting worktrees in a workspace/repo context), but it gives no explicit when-to-use, exclusions, or guidance about picking between cwd and workspace_id. The agent must infer that worktree_create is the alternative for creating.

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