workspace_create

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

Annotations already indicate a non-read-only, destructive operation. The description adds useful context beyond annotations: it requires environment and OAuth privileges, and it reveals that the operation creates a new local folder or git repo. It does not discuss collision behavior or side effects of setDefault, but there is no contradiction with the annotations.

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?

Three sentences with no filler. The primary purpose is front-loaded, the excluded use case is stated immediately, and the permission requirements are concise and actionable.

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 mutating creation tool with no output schema, the description covers purpose, prerequisites, exclusions, and what gets created. It stops short of a 5 because it does not address what happens if the alias already exists or what setDefault=true actually does at the workspace level.

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 documents root, slug, and alias reasonably well. The description reinforces that creation happens 'under a configured allowed root' and distinguishes remote HTTP/OAuth aliases from local paths, but it adds no new meaning for kind or setDefault. At 60% schema coverage, the description helps but does not fully compensate for the undocumented parameters.

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 a specific verb and resource: 'Create a remote HTTP/OAuth workspace alias by creating a new local folder or git repo under a configured allowed root.' It clearly distinguishes this from read-only siblings like workspace_list/workspace_get and from workspace_register_existing_repo, which implies registering an existing repo rather than creating a new one.

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 excludes stdio/local provider path access and states required privileges (LLM_GATEWAY_WORKSPACE_ADMIN=1, OAuth workspace:admin). It does not explicitly name workspace_register_existing_repo as the alternative for existing repos, but 'creating a new local folder or git repo' and the exclusion of local callers provide clear routing.

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