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.

10 tools

Knowledge graph

Entities, observations and relations: the durable knowledge surface.

add_observations

Write · Ordinary

Appends observations to existing entities. The everyday way to grow what is known about people, vendors, and topics without touching entity identity.

Full documentation →

Arguments, result and boundaries
Arguments
Required: `observations`. - `observations`. Note: Each entry needs entityName plus a contents string list. Non-string contents are skipped; absent contents still refresh the entity timestamp.
Result
JSON object with added (newly added plus revived count) and observation_ids.
Boundaries
Unknown entities and entities outside the caller's project grants are silently skipped with zero contribution, so callers cannot probe foreign projects by name. Operates only inside the caller's profile boundary.
Lifecycle
Each addition records an audit/history event. Duplicate text is skipped by content identity; re-adding retired text revives the same observation identity with its original creation evidence intact.
Errors
observations must be an array; entries need a string entityName. Unknown arguments are rejected (strict validator). Failures add nothing (atomic).
Example
```json { "observations": [ { "contents": [ "Now offers same-day turnaround." ], "entityName": "Acme Print" } ] } ``` Result shape: ```json { "added": 1, "observation_ids": [ "<uuid>" ] } ```

create_entities

Write · Ordinary

Creates entities in the knowledge graph, each with a name, type, and optional observations, project, aliases, and visibility. Names are unique: a repeated name resolves to the existing identity rather than duplicating it.

Full documentation →

Arguments, result and boundaries
Arguments
Required: `entities`. - `entities`. Note: Each entry needs name and entityType; observations is a string list, aliases a free-form list, project a tag. Untagged creation needs an explicit untagged grant.
Result
JSON object with created (newly created plus revived count), total_requested, entity_ids (one per resolved entity), and observation_ids (for observations added by this call).
Boundaries
Every entry needs the write grant for its project, and the whole batch fails closed on the first denied entry. Duplicate names belonging to foreign projects answer entity name already exists, never revealing their content.
Lifecycle
Creations record an audit/history event each. A repeated name revives the same identity when retired (void stamps stay as last-void evidence) or reuses the live one, still accepting new observations, aliases, and project backfill on this call. Duplicate observation text is skipped by content identity.
Errors
entities must be an array; entries need string name and entityType. Unknown arguments are rejected (strict validator). Denied projects fail the whole batch with nothing half-applied (atomic).
Example
```json { "entities": [ { "entityType": "vendor", "name": "Acme Print", "observations": [ "Local print shop on High Street." ], "project": "shared-ops" } ] } ``` Result shape: ```json { "created": 1, "entity_ids": [ "<uuid>" ], "observation_ids": [ "<uuid>" ], "total_requested": 1 } ```

create_relations

Write · Ordinary

Creates typed relations between entities, such as depends-on or produces. Relations only ever join two visible, live entities.

Full documentation →

Arguments, result and boundaries
Arguments
Required: `relations`. - `relations`. Note: Each entry needs from, to (entity names), and relationType. Entries with a missing endpoint are silently skipped.
Result
JSON object with created (newly created plus revived count), total_requested, and relation_ids.
Boundaries
Both endpoints must be live and visible under the caller's project grants; anything else is silently skipped with zero contribution, so callers cannot probe foreign content by name. Operates only inside the caller's profile boundary.
Lifecycle
Each creation records an audit/history event. Duplicate triples are skipped; re-creating a retired triple revives the same relation identity with its history preserved.
Errors
relations must be an array; entries need string from, to, and relationType. Unknown arguments are rejected (strict validator). Failures create nothing (atomic).
Example
```json { "relations": [ { "from": "Acme Print", "relationType": "supplies", "to": "Paul Pack" } ] } ``` Result shape: ```json { "created": 1, "relation_ids": [ "<uuid>" ], "total_requested": 1 } ```

delete_entities

Write · Ordinary

Retires named entities from the active knowledge graph. Despite the name, nothing is physically deleted: this is a lifecycle transition (active to voided) covered by the no-delete invariant. Re-creating the same name revives the same entity identity.

Full documentation →

Arguments, result and boundaries
Arguments
Required: `entityNames`. - `entityNames`. Note: Names that are unknown, already retired, or outside the caller's project scope are silently skipped and contribute zero to the deleted count; there is no error for unmatched names.
Result
JSON object with deleted (count of entities retired by this call).
Boundaries
Scope is enforced per entity: content outside the caller's project grants is silently skipped, never denied loudly, so callers cannot probe foreign projects by name. Operates only inside the caller's profile boundary.
Lifecycle
Records an audit/history event per entity, then marks it void with voided_at/voided_by stamps. Observations, relations, and aliases are NOT cascaded: they stay in place, resolve as absent while the entity is void, and revive independently. Re-creating an entity with the same name revives the original identity (void stamps retained as last-void evidence; history lives in the audit trail).
Errors
entityNames must be an array of strings (validation error otherwise). Unknown arguments rejected. The operation fails atomically (zero partial voids). deleted: 0 with no error means nothing matched or nothing was visible.
Example
```json { "entityNames": [ "Stale Vendor" ] } ``` Result shape: ```json { "deleted": 1 } ``` A later create_entities with name Stale Vendor revives the same identity rather than duplicating it.

delete_observations

Write · Ordinary

Retires exact observation texts from named entities. Despite the name, nothing is physically removed: this is a lifecycle transition (active to voided) covered by the no-delete invariant, and re-adding the text revives the same identity.

Full documentation →

Arguments, result and boundaries
Arguments
Required: `deletions`. - `deletions`. Note: Each entry needs entityName plus an observations string list matched by exact text. Unknown entities, unknown texts, and non-string items are silently skipped with zero contribution.
Result
JSON object with deleted (count of observations retired by this call).
Boundaries
Scope is enforced per entity: content outside the caller's project grants is silently skipped, never denied loudly, so callers cannot probe foreign projects by name. Operates only inside the caller's profile boundary.
Lifecycle
Records an audit/history event per retired observation, then marks it void with voided stamps. Re-adding the same text revives the original identity (creation evidence untouched; history lives in the audit trail).
Errors
deletions must be an array; entries need a string entityName. Unknown arguments are rejected (strict validator). The operation fails atomically (zero partial voids). deleted 0 with no error means nothing matched or nothing was visible.
Example
```json { "deletions": [ { "entityName": "Acme Print", "observations": [ "Now offers same-day turnaround." ] } ] } ``` Result shape: ```json { "deleted": 1 } ```

delete_relations

Write · Ordinary

Retires named relations from the knowledge graph. Despite the name, nothing is physically removed: this is a lifecycle transition (active to voided) covered by the no-delete invariant, and re-creating the triple revives the same identity.

Full documentation →

Arguments, result and boundaries
Arguments
Required: `relations`. - `relations`. Note: Each entry needs from, to (entity names), and relationType, matched exactly. Unknown endpoints and non-matching triples are silently skipped with zero contribution.
Result
JSON object with deleted (count of relations retired by this call).
Boundaries
Scope is enforced per endpoint: triples touching content outside the caller's project grants are silently skipped, never denied loudly, so callers cannot probe foreign projects by name. Operates only inside the caller's profile boundary.
Lifecycle
Records an audit/history event per retired relation, then marks it void with voided stamps. Re-creating the same triple revives the original identity (history lives in the audit trail).
Errors
relations must be an array; entries need string from, to, and relationType. Unknown arguments are rejected (strict validator). The operation fails atomically (zero partial voids). deleted 0 with no error means nothing matched or nothing was visible.
Example
```json { "relations": [ { "from": "Acme Print", "relationType": "supplies", "to": "Paul Pack" } ] } ``` Result shape: ```json { "deleted": 1 } ```

open_nodes

Read · Ordinary

Opens named entities with their observations plus the relations that run directly between the opened set. The precise read when the names are already known.

Full documentation →

Arguments, result and boundaries
Arguments
Required: `names`. - `names`. Note: Entity names to open. Non-string entries are skipped; unknown or out-of-scope names are silently omitted.
Result
JSON object with entities (name, entityType, observations in order, project included only when set) and relations (from, to, relationType) limited to edges with both endpoints in the opened set (only computed when two or more open).
Boundaries
Names outside the caller's project grants read as missing and contribute nothing, so callers cannot probe foreign projects by name. Operates only inside the caller's profile boundary.
Lifecycle
Pure read of live content; retired entities and observations resolve as absent. A best-effort access note is recorded alongside the read and never affects the returned content.
Errors
names must be an array (validation error otherwise). Unknown arguments are rejected (strict validator). No match is an empty result, not an error.
Example
```json { "names": [ "Acme Print", "Paul Pack" ] } ``` Result shape: ```json { "entities": [ { "entityType": "vendor", "name": "Acme Print", "observations": [ "Local print shop on High Street." ], "project": "shared-ops" } ], "relations": [] } ```

read_graph

Read · Ordinary

Reads the visible knowledge graph as a paged snapshot: entities with their observations plus the relations between them. The broad orientation read when exploring what is known.

Full documentation →

Arguments, result and boundaries
Arguments
Optional: `limit`, `offset`. - `limit`. Note: Page size (default 500). - `offset`. Note: Starting position in name order.
Result
JSON object with entities (name, entityType, project which is always present and null when unset, observations), relations (from, to, relationType), total (visible live entity count), and has_more.
Boundaries
Only live entities and relations visible under the caller's project grants are included; both relation endpoints must be visible. No visible scope reads as an empty snapshot with total 0, never a denial.
Lifecycle
Pure read of live content; retired entries resolve as absent. A best-effort access note is recorded alongside the read and never affects the returned content.
Errors
Unknown arguments and bad types are rejected (strict validator).
Example
```json { "limit": 10, "offset": 0 } ``` Result shape: ```json { "entities": [ { "entityType": "vendor", "name": "Acme Print", "observations": [ "Local print shop on High Street." ], "project": "shared-ops" } ], "has_more": false, "relations": [], "total": 1 } ```

search_by_project

Read · Ordinary

Searches the knowledge graph strictly inside one named project. A substring candidate pool is re-ranked with multi-signal scoring, so every hit is guaranteed in-project rather than merely boosted toward it.

Full documentation →

Arguments, result and boundaries
Arguments
Required: `query`, `project`. - `query`. - `project`.
Result
JSON object with entities (name, entityType, project echoing the request argument, observations, _score), the echoed query, and the echoed project. An out-of-scope project returns entities [] with the echoes intact.
Boundaries
The named project must be granted to the caller; anything else reads as an empty result, never a denial. Only live entities and live observations in that project are pooled and returned. Operates only inside the caller's profile boundary.
Lifecycle
Pure read of live content; ranking leaves no trace. Contrast search_nodes, whose project hint is affinity-only and currently unused on its path.
Errors
Missing or non-string query or project is rejected by validation. Unknown arguments are rejected (strict validator).
Example
```json { "project": "shared-ops", "query": "same-day print" } ``` Result shape: ```json { "entities": [ { "_score": 0.8, "entityType": "vendor", "name": "Acme Print", "observations": [ "Now offers same-day turnaround." ], "project": "shared-ops" } ], "project": "shared-ops", "query": "same-day print" } ```

search_nodes

Read · Ordinary

Searches the knowledge graph by free text and packs the best evidence per entity under a wire budget. Returns ranked entities with short observation windows plus an accounting block describing coverage and calibration.

Full documentation →

Arguments, result and boundaries
Arguments
Required: `query`. Optional: `budget`, `project`. - `query`. Note: Free text; a blank query lists the first 50 entities by name instead of matching. - `budget`. Note: Wire-character budget for packing (default 16000); over-budget entities stop the pack and report truncated. - `project`. Note: Accepted but currently unused on this path: it does not narrow or boost the ranking.
Result
JSON object with entities (name, entityType, observations as evidence windows, project when set, _evidence_status), the echoed query, and _accounting (entities_considered, entities_returned, observations_returned, truncated, budget_wire_chars, wire_chars, status, degraded, jump when measurable, refills, query_status, meaningful_terms, stopword_list).
Boundaries
Candidates, one-hop neighbours, and observations are all gated to the caller's project grants; foreign content never enters the pool or the expansion. Operates only inside the caller's profile boundary.
Lifecycle
Pure read of live content with scope-gated one-hop expansion. A best-effort access note is recorded alongside the read and never affects the returned content.
Errors
Missing or non-string query is rejected by validation. Unknown arguments and bad types are rejected (strict validator).
Example
```json { "budget": 16000, "query": "same-day print" } ``` Result shape: ```json { "_accounting": { "entities_considered": 1, "entities_returned": 1, "observations_returned": 1, "status": "OK", "truncated": false }, "entities": [ { "_evidence_status": "found", "entityType": "vendor", "name": "Acme Print", "observations": [ "Now offers same-day turnaround." ] } ], "query": "same-day print" } ```