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

Goes well past the destructiveHint annotation: it discloses that an audit row (`dependency.deleted`) is written, that a missing edge surfaces as `dependency_not_found` rather than a silent success, and details the `close_outcome_link_required` refusal including the direction-specific conditions (last `duplicates` edge FROM, last `supersedes` edge TO) and the remediation. This is behavior an agent could not infer from annotations or schema.

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?

Front-loads purpose, then alternatives, then error semantics in short paragraphs — good ordering with no filler sentences. It is somewhat long, and the final refusal paragraph is dense, but every clause conveys operationally relevant information.

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 three-parameter destructive mutation with no output schema, the description covers the mutation's side effect, the failure modes, and the precondition that blocks deletion. The only light gap is that it does not say what a successful return looks like beyond the audit row, but with no output schema required that is minor.

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 coverage is 100%, so the baseline would be 3, but the description adds real meaning beyond the schema: the three parameters act as a composite key for one edge, and direction is semantically load-bearing (duplicates counts FROM, supersedes counts TO). It also notes the match must be exact — a partial tuple yields `dependency_not_found`.

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?

States a specific verb and resource ("Remove a typed dependency edge") and pins down what identifies the target — the composite (fromId, toId, type). It also positions itself against siblings by calling itself the inverse of skein_dep_add, so the agent can distinguish it without reading other schemas.

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?

Gives an explicit when-to-use (cleanup after a mistaken edge or a relationship that no longer holds) and an explicit when-not-to with the named alternative: "To MOVE a parent-child edge ... use skein_reparent instead ... skein_dep_remove only deletes." That is the exact routing decision an agent needs.

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