perch_start

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

With no annotations the description carries the full burden and does well: it discloses the browser launch side effect, automatic Cloudflare handling via a '4-step escalation ladder', idempotent re-call behavior, and the ownership prerequisite for non-collab mode. It stops short of describing failure modes or what a successful start returns.

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?

Three tight sentences, front-loaded with the core action, followed by the two operational facts an agent most needs (Cloudflare auto-handling, idempotency). Zero filler.

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 7-param, no-annotation, no-output-schema tool, the description covers launch, stealth/Cloudflare behavior, idempotency and collab prerequisites. Return value and error behavior are unspecified, which is the main remaining gap since there is no output schema.

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 baseline is 3, but the description adds real meaning beyond the schema: collabKey omission semantics ('must own the generator') and the no-op/force relationship on re-call. These go beyond the per-field schema text.

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: 'Start the Perchance editor session' plus the concrete actions (launch browser, load generator with collab key, ready to edit). It is clearly a session-bootstrap operation that contrasts implicitly with perch_navigate/perch_refresh, though no sibling is named explicitly to sharpen the distinction.

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?

Explains when re-calling is appropriate ('fast no-op' with same generator/collabKey) and the collabKey omission case for non-collab edits. It does not name an alternative tool for the already-running case, but the idempotency note largely covers the decision context.

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