memory_graph_provenance_reconcile

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

With no annotations, the description carries the full burden and does so: it discloses the default action, what detach destroys vs retains, the limited scope of retire/restore (visibility only, history preserved), required prerequisites, dryRun preview semantics, the mutation side effects (graph/index update + audit entry), and the error conditions (invalid, missing, stale, wrong-project, conflicting).

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-loaded with purpose and dense with information; every sentence earns its place by covering action behavior, requirements, side effects, and errors. It is a single unbroken block, which hurts scannability slightly, but is appropriately sized for 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 complex, multi-action mutation tool with no output schema, the description is thorough: it covers prerequisites, per-action behavior, dry-run preview, side effects, and even the return shape ({success,action,project,dryRun,changedTargets,results} plus auditId and per-target before/after). Nothing an agent needs to call it correctly is missing.

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 80%, so the schema already documents most parameters; the description adds genuine semantics beyond it, notably that action defaults to detach and that target sources are review evidence rather than replacement relation support. It stops short of syntax-level detail, so 4 rather than 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?

States a specific verb+resource ('Correct exact graph targets in one project') with scope qualifiers and names three sibling tools it is not (memory_graph_query for inspection, memory_graph_upsert for adding relationships, memory_graph_purge for physical deletion). An agent can distinguish this reconcile tool from its graph siblings without opening any 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?

Explicitly routes the agent: 'Use memory_graph_query to inspect targets and memory_graph_upsert to add supported relationships; memory_graph_purge physically deletes a project graph.' It also clarifies per-action selection (detach default vs retire/restore) and when-required conditions (expectedUpdatedAt, review evidence, live endpoints).

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