docmancer

Official

Overview Schema Source Related Servers Discussions Admin

search_evidence

Read-onlyIdempotent

Semantically search local evidence files—memory, instructions, rules—written by coding agents, and retrieve relevance-scored excerpts with source paths.

Instructions

READ-ONLY: semantic search over the raw evidence index, meaning the memory, instruction, and rule files that other coding agents already wrote on this machine and that docmancer harvested. Runs entirely locally against the embedding index; no network call, no cost. Use it to find what an agent originally recorded, with a relevance score and the file it came from. Not for curated memory you or an agent deliberately wrote: that lives in a separate tree, so use search_memory for it, or ask_memory to get both at once. Parameters: query is the natural-language text to match; limit caps the number of results (default 8); include_history adds superseded evidence to the active evidence; expand_relations adds items linked to a direct match. Returns a list of objects with score, excerpt, source_path, scope, kind, lifecycle_state, and a docmancer://record/ record_uri. Returns [] when nothing matches.

Input Schema

TableJSON Schema

Name	Required	Description
`limit`	No	Maximum number of matching results to return. Defaults are tool-specific.
`query`	Yes	Natural-language terms to search for in the local memory or documentation index.
`include_history`	No	When true, include historical or superseded memory evidence in addition to active evidence.
`expand_relations`	No	When true, include related memory items alongside direct matches.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.9.13Aug 5, 2026

TDQS

A4.9/5.0

Behavior5/5

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

The description adds substantial behavioral context beyond the annotations: it runs entirely locally with no network call or cost, returns [] when nothing matches, and describes the return object fields including record_uri. It also explains the semantic difference between raw evidence and curated memory. These details are not in the annotations and align with the readOnly/idempotent hints.

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

Conciseness5/5

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

The description is front-loaded with the READ-ONLY label and core purpose, then efficiently covers scope, alternatives, parameters, and return format. Every sentence adds value and there is no repetition or fluff. Despite being long, it remains structured and scannable.

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?

Given the tool's complexity (4 parameters, 1 required, output schema, and sibling tools), the description is complete. It explains the source index, local execution, parameter semantics, return object fields, and empty-result behavior. With the annotations also provided, an agent has everything needed to invoke it correctly.

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?

Although schema coverage is 100%, the description goes slightly beyond by specifying the default limit of 8, clarifying that include_history adds 'superseded' evidence, and expand_relations adds 'items linked to a direct match.' It also describes the expected return structure, which helps an agent understand parameter effects. Baseline was 3, but the added clarification justifies a 4.

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?

The description clearly states 'semantic search over the raw evidence index' and specifies that it searches memory, instruction, and rule files harvested by docmancer. It distinguishes the tool from siblings by explicitly contrasting with search_memory and ask_memory, making the purpose and resource unambiguous.

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?

The description explicitly says 'Not for curated memory you or an agent deliberately wrote: that lives in a separate tree, so use search_memory for it, or ask_memory to get both at once.' This provides clear when-to-use and when-not-to-use guidance and names specific alternatives, making it easy for an agent to select the correct tool.

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