Skip to content
SHAMPOO

Tool catalogue

107 documented tools.

Derived from the canonical SHAMPOO tool documentation (the same source the implementation is gated against), so these pages and the software cannot drift apart.

5 tools

Links

Connections between tasks and the entities they concern.

get_entity_tasks

Read · Ordinary

Lists every live task linked to one knowledge-graph entity. The reverse view of get_task_links, useful for seeing all work touching a person, vendor, or topic.

Full documentation →

Arguments, result and boundaries
Arguments
Required: `entity_name`. - `entity_name`.
Result
JSON object with entity_name and tasks, each carrying id, title, status, priority, section, link_type, score (or null), and linked_at (or null).
Boundaries
The entity must be visible under the caller's project grants, and linked tasks are filtered to the caller's grants as well. An unknown or invisible entity answers Entity not found; an empty grant set reads as an empty task list.
Lifecycle
Pure read over live links; removed links resolve as absent.
Errors
Missing or non-string entity_name is rejected by validation. Unknown arguments are rejected (strict validator). Unlike get_task_links, an unknown name is an error, not an empty list.
Example
```json { "entity_name": "Acme Print" } ``` Result shape: ```json { "entity_name": "Acme Print", "tasks": [ { "id": "<uuid>", "link_type": "manual", "linked_at": "<iso-8601>", "score": null, "status": "not_started", "title": "Draft Paul pack README" } ] } ```

get_task_links

Read · Ordinary

Lists every live knowledge-graph entity linked to one task. The read side of the manual linking workflow.

Full documentation →

Arguments, result and boundaries
Arguments
Required: `task_id`. - `task_id`.
Result
JSON object with task_id and links, each carrying entity_id, entity_name, entity_type, link_type, score (or null), and created_at (or null).
Boundaries
The task and the linked entities must all be visible under the caller's project grants. An invisible task reads as an empty link list, never a denial; a malformed id answers Task not found.
Lifecycle
Pure read over live links and live entities; removed links and retired entities resolve as absent.
Errors
Missing or non-string task_id is rejected by validation. Unknown arguments are rejected (strict validator).
Example
```json { "task_id": "<uuid>" } ``` Result shape: ```json { "links": [ { "created_at": "<iso-8601>", "entity_name": "Acme Print", "entity_type": "vendor", "link_type": "manual", "score": null } ], "task_id": "<uuid>" } ```

link_task_entity

Write · Ordinary

Creates a manual link between a task and a knowledge-graph entity. Manual links always win: an existing auto-discovered link for the pair is upgraded rather than duplicated.

Full documentation →

Arguments, result and boundaries
Arguments
Required: `task_id`, `entity_name`. - `task_id`. - `entity_name`.
Result
JSON object with the decision record (decision_id, task_id, entity_id, entity_name, decision accepted, score, rank_at_decision, model_version, label_progress) plus link_type (manual) and created_at for the link.
Boundaries
Both the task and the entity must be visible under the caller's project grants. An invisible task answers Task not found; an unknown or invisible entity answers Entity not found; neither leaks the other side.
Lifecycle
Records an accepted manual decision and creates (or revives and upgrades) the link in one atomic unit, clearing any prior removal marker for the pair. Re-linking an existing manual link refreshes it rather than duplicating it.
Errors
Missing task_id or entity_name is rejected by validation. Unknown arguments are rejected (strict validator). Unknown or out-of-scope endpoints answer not-found. Failures link nothing (atomic).
Example
```json { "entity_name": "Acme Print", "task_id": "<uuid>" } ``` Result shape: ```json { "created_at": "<iso-8601>", "decision": "accepted", "decision_id": "<uuid>", "entity_name": "Acme Print", "link_type": "manual", "task_id": "<uuid>" } ```

suggest_task_links

Read · Ordinary

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.

Full documentation →

Arguments, result and boundaries
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
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
```json { "limit": 5, "task_id": "<uuid>" } ``` Result shape: ```json { "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" } ```

unlink_task_entity

Write · Ordinary

Removes a task-entity link while keeping the removal itself as durable evidence. Removing a silent high-confidence link additionally records an explicit human rejection, so the pair stays suppressed and becomes a real evaluation label.

Full documentation →

Arguments, result and boundaries
Arguments
Required: `task_id`, `entity_name`. - `task_id`. - `entity_name`.
Result
JSON object with removed (boolean). Removing a silent high-confidence link instead returns removed true with decision_recorded rejected and the decision_id. A missing link or an invisible task returns removed false, not an error.
Boundaries
The entity must be visible under the caller's project grants or the call answers Entity not found. An invisible task reads as removed false so task existence never leaks.
Lifecycle
Marks the link removed with removal stamps and preserves a removal marker carrying the prior link detail; re-linking later revives the edge and clears the marker with its own stamps. A rejected auto-discovered link cannot resurface silently. Nothing is ever physically removed.
Errors
Missing task_id or entity_name is rejected by validation. Unknown arguments are rejected (strict validator). An unknown or out-of-scope entity answers Entity not found.
Example
```json { "entity_name": "Acme Print", "task_id": "<uuid>" } ``` Result shape: ```json { "removed": true } ```