herdr_pane_split

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

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

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

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

Two short sentences, no filler, and the core action plus its default scoping are front-loaded. Every sentence earns its place.

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

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

For a five-parameter mutation with no output schema, the description is adequate but thin: it never states what the call returns (e.g. a new pane identifier), which an agent would want in order to chain follow-up calls against the split pane. The rich schema compensates for argument completeness, but the return/effect gap remains.

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

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

Schema description coverage is 100%, so the baseline is 3 and every parameter (cwd, focus, ratio, pane_id, direction) is already documented in the schema. The description repeats the pane_id default semantics without adding format or constraint detail beyond the schema.

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

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

States a specific verb and resource ('Split a pane') and adds the default target scope ('Defaults to the calling/focused pane'), which distinguishes it from siblings like herdr_pane_resize, herdr_pane_move, and herdr_pane_zoom. No sibling is named as an alternative, so it falls short of a 5.

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

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

The default-target sentence implies when the tool is appropriate (splitting the current pane without specifying an id), but there is no explicit when-to-use vs when-not guidance and no mention of alternatives such as herdr_tab_create for a new tab. Usage is inferable but not stated.

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