repl_spawn

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

With no annotations provided, the description carries the full burden of disclosing behavior. It clearly states that cmd is exec'd directly (no shell by default) and lists what is NOT interpreted (env prefixes, redirections, pipes, globs). This gives the agent critical behavioral context about how the process is spawned. It does not mention return format beyond session id or error handling, but for a spawn tool this covers essential transparency.

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 compact at three sentences with the core purpose front-loaded. It efficiently communicates the through-pty nature, return value, and critical shell-vs-no-shell distinction. Minor redundancy: 'env-var prefixes' is mentioned both in the list and in the env param guidance, but this is acceptable clarity rather than waste.

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

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

Given 8 parameters (2 required, nested objects) and no output schema, the description covers the most critical gaps: how cmd execution works, shell mode, and environment handling. It does not describe the cwd, cols, rows, promptRegex parameters or what happens on error, but for a spawn tool with rich input structure, the focused coverage on the most complex behavior (shell vs no shell) is appropriate.

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 38% (3 of 8 params have descriptions in schema: id, cmd, shell; the rest like cwd, env, cols, rows, promptRegex have no schema descriptions). The description adds meaningful context beyond the schema: it explains that cmd is exec'd directly, that environment variables cannot be set via shell prefixes but should use the env param, and that shell:true routes through /bin/sh -c. This compensates significantly for the schema gaps, though it does not describe cols, rows, or promptRegex.

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 the tool's purpose: 'Start an interactive REPL or CLI process under a PTY' and that it returns a session id. It distinctly distinguishes from siblings like repl_send, repl_expect, and repl_kill by specifying that this tool spawns a new process, which is a unique action among the sibling 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?

The description includes explicit guidance on when not to use shell syntax without setting shell:true, explaining that env-var prefixes, redirections, pipes, and globs require shell:true. However, it does not explicitly mention alternatives among siblings (e.g., when to use repl_send instead for sending input).

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