use_harness

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

With no annotations, the description carries the full burden. It does disclose a key security constraint (HARNESS_ALLOW_HOSTS) and explains the capability of driving local agents. But it omits important behavioral traits: it doesn't state that the prompt executes arbitrary commands (potential side effects), what the return value contains (stdout/stderr), or whether the call blocks until completion. This is a risky execution tool, and the description should be more candid about its effects and result format.

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

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

The description is three sentences, each earning its place: the first defines the action, the second expands on capabilities, and the third provides a crucial security constraint. It is front-loaded with the main verb and avoids redundancy or filler. This is a model of concise, informative writing.

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

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

For an execution tool of moderate complexity (4 params, no output schema), the description covers the primary purpose and a necessary prerequisite but leaves gaps: it doesn't describe the response format or error behavior, which is essential when no output schema exists. It also doesn't point to list_harnesses as a way to discover allowed hosts. Thus, while useful, it falls short of being fully self-sufficient for an agent to invoke it correctly without additional context.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal extra meaning: it ties the 'host' param to the HARNESS_ALLOW_HOSTS allowlist and clarifies that 'prompt' is the task for the harness. It does not elaborate on 'cwd' or 'timeout_ms' beyond what the schema already states, so no significant enhancement is provided.

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 opens with a specific verb and resource: 'Run a prompt in a headless host CLI' with concrete examples (claude -p, codex exec, opencode run). It also clarifies its scope by stating it lets the model drive local agents, skills, plugins, and MCP tools, which distinguishes it from siblings like chat (interactive) and list_harnesses (listing). No ambiguity remains about the tool's core function.

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 clear context for when to use this tool: whenever the model needs to execute a prompt in a headless CLI harness. It also provides a prerequisite (host must be in HARNESS_ALLOW_HOSTS), which implicitly guides the agent to verify host legitimacy. However, it does not explicitly contrast with sibling tools like chat or list_harnesses, nor state when not to use it, so it misses the 'when-not' element for a 5.

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