kg_search

FIND an artefact by its name, friendly id or uuid with artefactMetadataOnly:true. This works in every organisation, with or without the knowledge graph. Without that flag the tool ANSWERS questions from inside the content (facts, themes, relationships) through the knowledge modes below, which need the organisation's knowledge graph switched on: where it is off, those calls are refused with a message saying so. The knowledge modes will not reliably find a thing by its title.

FIND (artefactMetadataOnly:true): matches title, friendly id and uuid, never document content, across documents, whiteboards, plans, tasks, improvements and compliance frameworks that the caller can open and the organisation has switched on. Ignores mode. Narrow it with artefactTypes, projectId or workspaceId; page with offset. Returns { artefacts: [{ result_type, id, friendly_id, title, snippet, document_id, project_id, href }], total }. To search inside document bodies use listDocuments (full-content grep).

KNOWLEDGE MODES (need the knowledge graph; pass projectId or workspaceId). PICK THE MODE THAT FITS THE QUERY:

• mode='local' (default): for SPECIFIC factual questions ("what does section 15 say about deposits?", "who is the Chief Counsel?"). Searches individual passages of the content by wording and by meaning. Returns precise excerpts with citations.

• mode='global': for THEMATIC / OVERVIEW / SUMMARY questions ("what are the main themes", "give me an overview of the project", "what topics does this cover"). Returns summaries of the communities (groups of closely related entities) found in the content, plus curated wiki pages. Far better than 'local' for big-picture queries, because each summary already draws on many passages. ALWAYS PREFER over 'local' when the user asks for themes / summary / overview / topic landscape.

• mode='graph': for RELATIONSHIP questions ("what's connected to entity X?", "who cites Section 5?"). Returns the entities connected to the one you name, and how they are related; depth sets how many links to follow. Pass query OR srcEntityId.

• mode='path': for CONNECTION questions ("how does X relate to Y?"). Returns up to five of the shortest chains of relationships between two entities, each step saying how it relates to the one before, with a one-line summary; or, when there is none, a message saying why. Pass srcEntityId AND dstEntityId (both in the same project); depth is the most steps a chain may have.

• mode='ppr': for MULTI-HOP discovery ("what's relevant to X, even indirectly?"). Starts from the entities closest to the query and follows their relationships outwards, giving more weight to links people authored than to links inferred from text. Best when 'local' returns too few results and the answer means following several relationships in a row.

Quick decision tree:

• User wants to FIND a named artefact ("the GTM plan", "DOC-123", a uuid) → artefactMetadataOnly:true
• User asks for an overview/summary/themes → 'global'
• User asks a specific question with a clear answer → 'local'
• User asks 'how is X connected to Y' → 'path' (with both entity IDs)
• User asks 'what's near entity X' → 'graph' (with srcEntityId)
• 'local' returned nothing useful and the question is broad → retry with 'ppr'

DATED FACTS: a knowledge-mode response also carries datedFacts for the entities the query names: what holds now by default, what held on a day with asOf, or the whole history with history:true, each fact with its dates, how it ended if it has, and its sources. Prefer them for "who owns X now", "what was X in March", "when did X change".