search_concepts

Search the concepts. Keyword search over concepts’ titles, descriptions, tags, IDs, and bodies, across every tree or some. Every term must match. Filter by types, tags, statuses, or trust tiers: a concept passes a filter with any of its values, and must pass every filter given. An empty query lists every concept that passes the filters. Read-only.

Parameters

Parameter	Type	Required	Description
query	string	Yes	Keywords; may be empty when filtering.
trees	list of strings	No	The trees’ slugs, as list_trees gives them (not their names). Only these trees; omit for every tree.
types	list of strings	No	Only concepts of any of these types (case-insensitive).
tags	list of strings	No	Only concepts with any of these tags (case-insensitive).
statuses	list of draft | stable | deprecated	No	Only concepts with any of these statuses.
trustTiers	list of unverified | machine-confirmed | human-reviewed	No	Only concepts with any of these trust tiers.
limit	integer, 1–50	No	Default 10.

Returns

One JSON object (see All tools):

Field	Type	Always	Description
total	number	Yes	How many concepts match, before limit.
url	string	Yes	This search in OKForest, with every match.
results	list of objects	Yes	The best matches, best first.
results[].id	string	Yes	The concept’s ID: its tree’s slug, a colon, and its path without .md.
results[].tree	string	Yes	The slug of the tree it’s in.
results[].path	string	Yes	Its file’s path in the tree.
results[].url	string	Yes	The concept’s page in OKForest.
results[].type	string	No	Its type, when it has one.
results[].title	string	No	Its title, when it has one.
results[].description	string	No	Its description, when it has one.
results[].tags	list of strings	Yes	Its tags.
results[].status	draft | stable | deprecated	Yes	Its lifecycle status; stable when it gives none.
results[].stale	boolean	Yes	Whether it’s past its stale_after date.
results[].trustTier	unverified | machine-confirmed | human-reviewed	Yes	How it has been verified, from its verified entries.
results[].score	number	Yes	How well it matches: title matches count most, then tags and description.
results[].snippet	string	No	A line of its body containing a search term, when one does.
unreadTrees	list of strings	Yes	The slugs of trees that couldn’t be read, so their concepts are missing.

Example

Asked “What do we know about our retail customers?”, an assistant might call search_concepts with:

Arguments

{
  "query": "retail",
  "trees": [
    "company"
  ],
  "types": [
    "Customer"
  ]
}

On OKForest’s test Forest (Acme’s made-up company knowledge), it returns:

Result

{
  "total": 1,
  "url": "https://app.okforest.ai/@/3f2b8c1e-9a4d-4c7b-8e2f-6d1a0b5c9e7f/-/search?q=retail&tree=company&type=Customer",
  "results": [
    {
      "id": "company:customers/acme-corp",
      "path": "customers/acme-corp.md",
      "type": "Customer",
      "title": "Acme Corp",
      "description": "Our largest retail customer.",
      "tags": [
        "customer",
        "retail"
      ],
      "status": "stable",
      "trustTier": "human-reviewed",
      "stale": false,
      "score": 7,
      "snippet": "Acme Corp buys our retail analytics plan. Their main competitor of ours",
      "tree": "company",
      "url": "https://app.okforest.ai/@/3f2b8c1e-9a4d-4c7b-8e2f-6d1a0b5c9e7f/company/customers/acme-corp"
    }
  ],
  "unreadTrees": []
}