workspace.write

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

The description goes far beyond the annotations, disclosing specific field prohibitions (never revision_id, depends_on_refs, ref), the mark lifecycle state machine (ACTIVE before CLOSED/ARCHIVED after RETRACTED/SUPERSEDED), and that PROPLEM is reserved for workspace.open. It also clarifies that all content remains AGENT_RECORDED/UNVERIFIED and that focus references are limited to finding cards, providing deep behavioral transparency.

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?

Despite its length, the description is dense and front-loaded with the most important directive, and every sentence adds a distinct constraint or clarification. The canonical example at the end consolidates the rules into a usable pattern, making the size justified by the tool's complexity.

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 9 parameters, no output schema, and complex lifecycle rules, the description is thoroughly complete: it covers prerequisites (workspace_id, branch_id, base_revision), all payload sections, field naming restrictions, focus behavior, and the invalidating-state transitions. An agent has everything needed to invoke the tool correctly without further documentation.

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?

Although the schema provides descriptions for every parameter, the description adds critical cross-parameter semantics: the flat arguments rule, the base_revision vs revision_id distinction, the client_ref naming convention, and the rules for linking refs within the same batch. The canonical example shows exactly how to combine findings, attempts, and focus, which the schema alone does not convey.

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 establishes that workspace.write is the direct tool for appending workspace data, listing the exact top-level fields and explicitly distinguishing it from capability.describe. The name combined with 'Direct tool. Do not call capability.describe.' and the detailed batch structure 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?

It explicitly warns against calling capability.describe and provides clear workflow guidance: append at an exact base revision, use flat arguments, never send verification fields. The canonical batch example gives a concrete template for typical usage, and the constraints on references and state transitions serve as strong when-to-use/never-do guidance.

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