platform_workspaces

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

With no annotations, the description carries the full burden for behavioral disclosure. It reveals that switch atomically authorizes and changes the authenticated socket, credentials, and subsequent calls, and that current decodes from a JWT. It also discloses that responses include activeTarget and contextVersion, which is beyond the schema. These details give the agent a clear picture of side effects without needing additional hints.

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 reasonably concise but opens with an extraneous sentence about Arch's general capabilities ('Arch creates and changes projects, agents, tools, configuration, versions, and deployments') that is not specific to this tool. While the core content is well-structured with 'Manage workspaces' and an action list, this preamble adds noise and could be trimmed. The description remains clear but not optimally front-loaded.

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 tool with three actions, two parameters, and no output schema, the description covers the essential context: what each action does, the required input for switch, and key response fields (activeTarget, contextVersion). It mentions the workflow of surfacing the active environment after a switch, which is useful for an agent. It does not detail error conditions or exhaustive response structures, but given the tool's complexity, this is sufficient.

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 only 50% (only tenantId has a description), but the tool description compensates by explaining the action enum values in detail and clarifying that tenantId is required for switch. This adds meaning beyond the schema, such as that list returns workspaces with an active flag. The description effectively documents both parameters without leaving gaps.

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 manages workspaces (tenants) and enumerates three specific actions (list, switch, current) with brief explanations. This explicitly differentiates it from sibling tools like platform_projects or platform_config, which handle other resources. The verb 'manage' plus the action list leaves no ambiguity about what the tool does.

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 explains when to use each action (e.g., list to see all workspaces, switch to change active, current to inspect the active one) and even suggests surfacing the active environment after a switch. However, it does not explicitly mention when not to use this tool or point to alternative tools, leaving some inference to the agent. Siblings like platform_projects exist but are not compared, so guidance on choosing between them is implicit rather than explicit.

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