Docflow List Workspaces

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

With no annotations, the description carries the transparency burden. It discloses the endpoint, implies a non-mutating list operation, notes the account-access scope, and enumerates the returned fields. It omits pagination and side-effect details, but this is adequate for a simple read-list tool.

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?

Two compact sentences: the first states the operation and endpoint, the second lists return fields. There is no filler or redundancy.

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?

The endpoint, scope, and returned fields are clear, and an output schema exists. However, the undocumented enterprise_id parameter is material to making correct calls, and there is no guidance on choosing this over related workspace tools. Adequate but with a clear gap.

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 0% and the description never mentions the only parameter, enterprise_id. An agent cannot determine whether enterprise_id filters the results, whether it is required, or what the default of 0 means. The description adds no parameter meaning.

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 names a specific verb and resource ('List all workspaces'), gives the exact endpoint, and the 'all' scope distinguishes it from singular workspace tools like docflow_get_workspace. An agent can clearly tell what this 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 makes the context clear: use this when you need all workspaces accessible to the current account. It does not explicitly contrast it with alternatives like docflow_get_workspace, but the scope is stated well enough to avoid confusion.

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