start_grab_session

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

Annotations already mark the tool as destructive and non-idempotent, and the description adds useful behavior: overlay injection, loopback serving, and proxy-mode behavior. However, it does not disclose lifecycle implications beyond starting — such as how long the background bridge runs, whether it is persistent, or that a running server session is created.

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 short — two sentences with strong front-loading of the primary action. The phrasing is economical, though terms like 'capability-keyed', 'Raven', and 'zero-paste' add flavor without substantial precision.

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?

Given the lack of an output schema and the operational nature of this tool, the description misses some contextual grounding: what a grab bridge concretely does, what start/stop lifecycle expectations are, and whether the bridge runs in a foreground process, background session, or as a service. The proxy mode and manual script alternative are covered, but the tool's operational footprint is not fully surfaced.

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?

The input schema is fully documented at 100% coverage, so parameters like path, port, mode, and proxy_target already carry clear meaning. The description does not add meaningful parameter-level guidance beyond echoing the proxy/manual mode distinction found in the 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?

The description names a specific action and resource — 'Start a capability-keyed Raven grab bridge on loopback' — and explains the two main modes (proxy and manual script tag). However, 'Raven grab bridge' and 'capability-keyed' are unexplained jargon, and the description does not explicitly contrast with stop_grab_session or other grab-related siblings.

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 explicitly recommends proxy mode as the 'preferred zero-paste path' and notes the manual script tag remains available when needed. This gives clear within-tool routing guidance, though it does not state when proxy mode is not appropriate or explicitly point to stop_grab_session for teardown.

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