rojo_start

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

With no annotations, the description carries the load and does well: it discloses that the process is detached and survives session end, that repeat calls are idempotent per project+port, and that a port collision with another project errors. It doesn't say where the serve log/output surfaces or how the process is later terminated (rojo_stop), which are the remaining operational unknowns.

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?

Front-loaded with the action and its persistence property, then the parameter hint, then the conflict semantics — no filler. The trailing clause 'fails if another project is' is slightly elliptical but still readable.

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?

An output schema exists, so return values need not be explained, and the description covers persistence, idempotency, and conflict behavior for a two-parameter tool. It stops short of the lifecycle story (how to check or stop the served process), which is the only meaningful gap.

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. It defines `project` well (folder or .project.json path), but `port` is only alluded to via the conflict rule — its default (34872) and what it means to choose a non-default port are left to the bare 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 ('Serve a Rojo project (`rojo serve`)') and scopes it to a background process that outlives the session. That scope plus the port-conflict rule distinguishes it cleanly from rojo_stop and rojo_status.

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?

Clear about the situation it is for and spells out the no-op case (already served on that port) and the failure case (a different project on the port). It doesn't explicitly point at rojo_status or rojo_stop as the follow-up/diagnostic alternatives, so routing to siblings is left implicit.

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