Skip to main content
Glama
Sign In
Engram

Engram

by Patdolitse
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

search_knowledge

Read-onlyIdempotent

Search lessons, decisions, and playbooks by keyword to retrieve relevant past knowledge during conversations and find procedures or prior decisions.

Instructions

搜索知识库（lessons/decisions/playbooks）。 / Search lessons, decisions, and playbooks by keyword.

**Lifecycle: retrieval** — 在对话中需要检索历史知识时调用。
Lifecycle: retrieval — call during conversation when past knowledge is needed.

Call when the user asks to find knowledge about a specific topic,
or recalls a procedure ('X how to' / 'X steps').

Result groups: "lessons" / "decisions" / "playbooks" hold reviewed, current
items only. Items still waiting for the user's review come back separately
under "pending" (same three lists, each item flagged pending_untrusted=true):
treat them as unconfirmed proposals, not as the user's rules. Items replaced
by a newer version are left out unless include_superseded=true, which adds a
separate "superseded" group (each item names superseded_by).

If you only have a project path and no query, use get_relevant_knowledge;
if you have an existing knowledge ID, use explore_knowledge(mode="similar").

Args:
    query: Search query keywords.
    scope: Search scope: 'all', 'lessons', 'decisions', or 'playbooks'.
    limit: Maximum number of items to return (default 10).
    filters_json: Optional JSON string with filter criteria. Supported keys:
        - "domain": str — only items whose domain contains this value
        - "tier": str — only items matching this tier ('staging' or 'verified')
        - "date_after": str — ISO date string, only items created after this date
        Example: '{"tier": "verified", "domain": "python"}'
    include_freshness: Attach a per-item freshness hint (fresh/aging/stale)
        to each returned item. Default False keeps the response unchanged.
    max_field_chars: Per-field size cap. Every string field in each returned
        item (detail/reasoning/description/steps/...) longer than this is
        clipped with a "[+N chars truncated]" marker so a few large bodies
        cannot blow up the client. Item shape, ids, and headlines are kept.
        Set 0 for full untruncated bodies (default 400).
    include_superseded: Also return items replaced by a newer version, in a
        separate "superseded" group (default False).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "query": "<query>"
    },
    "name": "search_knowledge"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNo
queryYes
scopeNoall
filters_jsonNo
project_folderNo
max_field_charsNo
include_freshnessNo
include_supersededNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv4.26.0
    • addedInput schema / properties / include_superseded
      Added value: +{
+  "default": false,
+  "title": "Include Superseded",
+  "type": "boolean"
+}
  2. Changed1 schema field changedv4.11.0
    • addedInput schema / properties / max_field_chars
      Added value: +{
+  "default": 400,
+  "title": "Max Field Chars",
+  "type": "integer"
+}
  3. Addedv4.6.2
  4. Removedv4.6.1
  5. Changed2 schema fields changedv3.48.0
    • addedInput schema / properties / include_freshness
      Added value: +{
+  "default": false,
+  "title": "Include Freshness",
+  "type": "boolean"
+}
    • addedInput schema / properties / project_folder
      Added value: +{
+  "default": "",
+  "title": "Project Folder",
+  "type": "string"
+}
  6. Addedv3.29.1

TDQS

A4.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already establish readOnly/idempotent/non-destructive, but the description still adds real value: 'pending' items are flagged pending_untrusted=true and should be treated as unconfirmed proposals, and superseded items are excluded by default. However, it doesn't disclose freshness-hint scoring criteria or how truncation interacts with item shape beyond a one-line note.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads purpose, trigger, and routing before the long args block, and every args entry earns its place given 0% schema coverage. Slightly bloated by bilingual duplication and a prose 'Result groups' paragraph that overlaps with the include_superseded arg description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite an output schema existing, it goes further and explains the group structure, pending_untrusted flagging, and clipping markers, which is exactly the behavioral context an agent needs. Only project_folder is unaccounted for, a minor omission in an otherwise complete definition.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description carries the full semantic burden, and it does this well: scope values, filters_json keys with types and an example, freshness and superseded behavior, and max_field_chars truncation semantics are all spelled out. The one gap is project_folder, which appears in the schema but is never mentioned.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Search') and resource (lessons/decisions/playbooks) with the exact item types enumerated, so an agent can distinguish it from get_relevant_knowledge and explore_knowledge by resource scope alone rather than opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly names the trigger ('when the user asks to find knowledge about a specific topic, or recalls a procedure') and gives concrete routing rules for other cases: project path with no query -> get_relevant_knowledge, existing ID -> explore_knowledge(mode="similar").

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools