memory_submit

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

With no annotations provided, the description carries the full burden and does so well: it discloses the local commit on the current branch, that outbox originals are moved out (a destructive/relocating side effect), that branches are never created, and that push/PR commands are only printed and require explicit approval. It also notes environment availability (MCP server and CLI, but not the opencode native plugin), which prevents a class of false invocations.

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 core action is front-loaded and the side-effect/approval constraints follow in logical order; almost every clause earns its place. The trailing parenthetical about CLI/plugin support is useful but slightly tangles the structure, and the block is denser than it needs to be for a single sentence per idea.

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 3-parameter mutation tool with no annotations and no output schema, the description covers side effects, approval gates, and even what gets printed to the user. It is nearly complete; it omits failure/conflict behavior (e.g., what happens if an id is unknown or the working tree is dirty), which is the remaining 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 100%, so the schema already documents ids, base, and branch, including the approval constraint on branch. The description mostly restates the branch constraint rather than adding syntax, ordering, or format detail. Baseline 3 is appropriate when structured fields do the heavy lifting.

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 ("Move outbox drafts into the repo memory dir for review") and enumerates the exact steps of the chain: copy in as proposed, commit locally, move outbox originals out. It is clearly a submit/publish operation. It does not, however, explicitly contrast itself with close siblings like memory_propose or memory_promote, so an agent must infer which tool owns a given draft lifecycle stage.

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 gives concrete conditions for the risky parameter ("pass branch= only with the user's explicit approval for the full chain") and states what is never done automatically (branch creation, push, PR). This is strong conditional guidance. It stops short of naming an alternative tool to use when the user has not yet drafted or approved, so no explicit sibling routing.

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