kernel_start

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

With no annotations provided, the description carries the full behavioral burden. It discloses the single-kernel concurrency constraint, specifies cwd default behavior (venv project dir vs home directory), and explains the two valid kernel_name formats. It doesn't describe return value or error behavior, but the output schema exists to convey those details, so the key runtime behavioral traits are well covered.

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 tightly structured with clear paragraph breaks: intent, kernel_name semantics, cwd semantics, and concurrency constraint. Every sentence adds value — no filler, no repetition of the schema. Front-loaded with the primary purpose and written in a scannable format.

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 2-parameter tool with an output schema present, this is quite complete. It covers both parameters' semantics, the single-kernel constraint, defaults, and ties the workflow to kernel_discover/kernel_stop siblings. The only gap is the absence of error handling details (e.g., what happens when the kernel name doesn't exist), but with an output schema present, that burden is partially relieved.

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 does. It explains kernel_name's two valid formats (registered spec names with 'python3' example, and 'venv:/path/to/project' references). It also clarifies cwd's meaning and default resolution logic. Both parameters are meaningfully elaborated beyond the bare schema fields, though it stops short of describing edge cases like empty strings or valid directory formats.

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 verb ('Start') and resource ('a kernel'), and specifies that the kernel is identified by name as returned by kernel_discover. It differentiates the tool's function from siblings like kernel_stop, kernel_status, and kernel_restart. The scope is well-defined with concrete examples of valid kernel_name values.

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 explains when to use this tool: to start a kernel. It names the exact input source (kernel_discover) and gives a concrete when-not condition: 'Only one kernel can run at a time — call kernel_stop first if one is already running,' which properly excludes/precedes sibling kernel_stop. It also explains cwd semantics, removing ambiguity about the default behavior for different kernel types.

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