runpod_watch

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

With no annotations, the description fully carries the safety and behavior burden. It discloses that `watch` arms idle auto-stop and can stop a pod, `unwatch` disables auto-stop, and `troubleshoot` is read-only with a specific checklist. It even notes the ~15s refresh rate, giving the agent a clear picture of side effects and operational behavior.

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 longer than average, but every sentence earns its place by adding safety, usage, or action-specific detail. The structure is clear: a one-sentence purpose, a prominent warning, then bulletized action definitions. It is front-loaded with the most important caveat about not deploying/resuming pods.

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 multi-action nature, the absence of output schema, and the interaction with sibling tools, this description is remarkably complete. It covers prerequisites (runpod tool for deploy/resume), action-specific behavior, parameter dependencies, and what `troubleshoot` checks and returns.

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 schema already provides 100% parameter coverage and documents the `pod_id` dependency on `action`. The description adds value by giving each `action` enum value a concrete semantic meaning (e.g., watch starts broadcasting, unwatch clears the watched pod), but it does not significantly exceed the schema's structural information.

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 opens with a clear verb+resource statement: 'Watch a RunPod pod's live status in the control panel, stop watching it, or diagnose why it isn't usable.' It distinguishes itself from the sibling `runpod` tool by explicitly stating that it does not deploy or resume pods, so the agent can select this tool without confusion.

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 explicit when-to-use guidance for each action: use `watch` to monitor a pod without retargeting comfyui-mcp, use `troubleshoot` when a pod 'won't connect' or ComfyUI is unreachable, and use `runpod action:"stop"` for stopping a pod. It also warns not to watch a deliberately idle pod that must stay up, providing clear exclusions.

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