manage_ws_status

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

With no annotations, the description carries full burden. It discloses behavioral traits: actions that require ownership, potential side effects (restart WS, rotate events.jsonl, re-read credentials), and the ability to steal an active lock via force=true. This covers important behaviors beyond the schema, though it omits error handling or auth details beyond owner-only status.

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 with a list, front-loaded with version and purpose. Every word is functional; no fluff. The structured list of actions makes scanning easy. This is an excellent example of concise, informative documentation.

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 annotations and output schema, the description provides sufficient context for using the tool: it explains each action, flags ownership requirements, and notes side effects. However, it does not describe return values or error conditions, which would be helpful for a tool with multiple permission-sensitive actions. Still, it covers the most critical aspects.

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 has 50% coverage (force parameter described). The description compensates by explaining each action enum value: info = status dump, reconnect = restart WS, claim = try become owner, rotate = force rotation, reconfig = re-read credentials. For the force parameter, the description matches the schema. Overall, the description adds meaningful context beyond the enum listing.

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 clearly states the tool's purpose: 'Inspect or control the machine-level WS owner.' It then lists five specific actions (info, reconnect, claim, rotate, reconfig) with brief explanations. This provides a distinct and precise purpose that differentiates it from sibling tools, which are mostly CRUD for entities like messages, documents, and tasks.

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 indicates when to use each action and notes ownership restrictions ('owner-only' for reconnect, rotate, reconfig; force flag for claim). However, it does not explicitly state when to prefer this tool over alternatives. Given no obviously similar sibling tools, the guidance is adequate but could be more explicit about prerequisites and contexts.

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