ipython_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 useful traits: sessions are named, multiple can run concurrently, and they are fully independent. But it does not describe the session lifecycle, whether a background process is spawned, what happens on startup failure, or cleanup behavior, which are important for a process-starting tool.

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 only two sentences with no filler. The core action is front-loaded, and the critical python_path constraint and session-independence semantics are stated efficiently. 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?

The description covers important preconditions and session independence, but there is no output schema and no annotations, so the description must also explain invocation outcomes and side effects. It does not mention what the caller receives after starting, how a session is later referenced, or how this relates to ipython_install_deps and ipython_stop. This is adequate but has clear gaps for a process-management tool.

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 100%, so the baseline is 3. The description adds value beyond the schema by clarifying that python_path must be absolute, must point to a Python 2.7 interpreter with project requirements installed, and that a virtualenv interpreter can be used. This gives the agent actionable selection guidance not present in the schema alone.

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 action ('Start a named Python 2 IPython session') and a resource. It implies a persistent session, and the mention of multiple independent named sessions adds useful scope. However, it does not explicitly distinguish itself from sibling ipython_run, which could be ambiguously similar in an agent's view.

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 important usage context: the python_path must be an absolute path to a Python 2.7 interpreter with project requirements installed, and virtualenv interpreters are supported. It does not, however, explicitly say when to prefer this over ipython_run, ipython_stop, or ipython_status, nor does it name alternatives or exclusion conditions.

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