suggest_task_links

Category: links
Access: read
Audience: ordinary (an ordinary user normally calls this directly)

Purpose

Suggests entities that may relate to a task using one versioned pairwise scorer (exact name and alias, full-text, project, provenance, graph and meta-path, temporal, plus vector and community signals). Suggestions only: links are never created here.

Arguments

Required: task_id.

Optional: include_vector, limit.

task_id.
include_vector. Note: Accepted and echoed; the current output always carries a null vector rank and a null community run.
limit. Note: Caps the returned suggestions (default 5).

Result

JSON object with task_id, model_version (explainable-pairwise-v1), include_vector, community_run (null), suggestions (entity_id, entity_name, entity_type, score, signals with raw, weights, and contributions, reasons, matched_aliases, shared_keywords, fts_rank, vector_rank, existing_decision, rank), candidate_count, accept_tool (link_task_entity), and undo_auto_tool (unlink_task_entity).

Boundaries

The task must be visible under the caller's project grants; anything else answers task not found (lowercase shape). Candidates and their evidence are drawn only from content the caller may see.

Lifecycle / side effects

Pure read; scoring creates no links and records no decisions. Accepting a suggestion is a separate link_task_entity call.

Errors

Missing task_id is rejected by validation. Bad limit or include_vector types are rejected (strict validator). Unknown or out-of-scope tasks answer task not found.

Example

{
  "limit": 5,
  "task_id": "<uuid>"
}

Result shape:

{
  "accept_tool": "link_task_entity",
  "candidate_count": 1,
  "community_run": null,
  "include_vector": false,
  "model_version": "explainable-pairwise-v1",
  "suggestions": [
    {
      "entity_name": "Acme Print",
      "rank": 1,
      "reasons": [
        "name_match"
      ],
      "score": 0.75
    }
  ],
  "task_id": "<uuid>",
  "undo_auto_tool": "unlink_task_entity"
}