Connect related-but-unlinked brain cards (densify the graph)

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

With no annotations, the description carries the full behavioral burden and does so richly: dry run produces a before→projected orphan receipt, apply:true draws 'only additive, removable arrows' and reports a measured after count, and it 'NEVER archives or rewrites cards'. It further discloses that dismissals are logged to a machine-local provenance sidecar with nothing extra written into the brain file — exactly the side-effect detail an agent needs.

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 primary use case (orphan repair) is front-loaded, then scope:'all', then the reconcile-dismissal path — a logical ordering. It is dense and long for a single paragraph, but nearly every clause carries distinct operational information, so little is wasted.

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 seven-parameter tool with no output schema and no annotations, the description covers dry-run vs apply semantics, return receipts, side-effect boundaries, scope selection, and the cross-tool dismissal workflow. An agent has everything required to call it correctly without further 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?

Schema coverage is 100%, so the schema already documents all seven parameters and a 3 would be the floor. The description adds genuine meaning beyond it: the 0.55 semantic threshold and its shared-tags + [[mentions]] fallback when the on-device model is absent, plus the permanence of a not_contradiction dismissal. It stops short of covering max/canvas behavior, so not a 5.

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 opening states a specific verb+resource ('Repairs orphaned decision/milestone cards ... by proposing genuinely related unlinked pairs') and immediately differentiates the two scopes. It also names the sibling tool it complements (brain_reconcile) and the role it plays against it, so an agent can separate it from adjacent graph tools without opening a schema.

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?

Explicit when-to-use is given for both modes: scope:'orphans' (default) for repair, scope:'all' for 'deliberate whole-graph densification'. It also states a concrete alternative use case — passing pairs:[{fromId,toId}] with relationship:'not_contradiction' to DISMISS a brain_reconcile false-positive. Nothing about routing is left to inference.

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