attach_to_dev_server

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

No annotations are provided, so the description carries full burden for behavioral disclosure. It hints at what 'attach' means (enables status bar visibility) but doesn't explain side effects, whether the attachment is persistent, what happens on process exit, or whether there are prerequisites (e.g., must the server already be running?). The parenthetical is helpful context but insufficient for a stateful operation.

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 a single sentence, concise and to the point. It front-loads the core purpose before the parenthetical context. No wasted words, though the single-sentence format limits depth. Appropriately sized for a tool with one parameter.

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 stateful operation with no annotations, no output schema, and closely related sibling tools (start/stop/detach_dev_server, get_status), the description is thin. It doesn't explain what happens structurally, how the attachment affects get_status or get_logs behavior, or whether stopping the server auto-detaches. A stateful tool with this sibling set warrants more operational detail.

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 100%, with the logFile parameter well-described with type and example path. The description confirms the log file's role ('where dev server output is being written'). At 100% coverage and only 1 parameter, baseline 3 is appropriate - the schema already does the heavy lifting, and the description adds modest confirmation.

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 states the tool 'Attach monitoring to an existing dev server process' with a specific verb (attach) and resource (dev server process). However, it doesn't clearly distinguish it from sibling tools like detach_dev_server or get_status - the complementary relationship with detach_dev_server is implied but not explicit. The purpose is understandable but lacks sibling differentiation.

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 a hint about when to use it ('when started with Bash tool') but only vaguely. It doesn't clarify when to choose this over start_dev_server (vs creating a new one) or how it relates to detach_dev_server. No explicit when-not-to-use or alternative tools named, despite having closely related siblings.

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