maket_workspace

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

With no annotations provided, the description carries the full burden. It discloses the lock's blocking behavior, that list_messages returns all pending messages across docs and workspace, and that ack_messages drops the specified ids. The action-by-action semantics are clearly stated.

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 front-loaded with the primary usage distinction, then uses a concise action-by-action table format. No superfluous sentences; every line adds needed operational detail.

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 multi-action tool without an output schema, the description covers each action's behavior, lists prerequisites, and indicates return expectations (e.g., JSON for list_messages). The alternative tool for other operations is provided, rounding out the context.

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 descriptions, and the tool description reinforces action-specific parameter usage (e.g., doc required for focus/state/lock, omitted for list_messages; locked toggle behavior). This adds value by summarizing the action-to-parameter mapping, although most details exist in the schema.

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 specifically that it handles session-level interactions with the live workspace, then enumerates six concrete actions. It also differentiates itself from the sibling maket_doc tool for persistent CRUD, making its scope unmistakable.

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 opening 'When to use' sentence defines the tool's context and explicitly directs persistent document CRUD to maket_doc. Each action is described with its trigger and expected effect, leaving no ambiguity about when to invoke it.

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