Skip to main content
Glama
IBazylchuk

Paparats: Local Semantic Code Search

by IBazylchuk
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Architecture Context

arch_context
Read-only

Retrieves relevant components, decisions, and lessons for a question or touched files, helping agents check architectural memory before non-trivial code changes.

Instructions

Retrieve architectural memory relevant to a question or set of touched files. Returns three card kinds, each with an updated-at age stamp:

  • Components: what parts the system is made of.

  • Decisions: why they were built that way.

  • Lessons: rules that survived previous mistakes — each rule comes with why (incident context) and when (when to apply) continuation bullets. Superseded and deprecated cards are hidden by default. Cards older than 90 days are prefixed with ⚠ stale — verify them against the current code before acting. Call this BEFORE any non-trivial change. Returns an init hint when the arch layer is empty.

Each kind has its own independent top-N budget — a verbose decision bucket can't starve components. Pass limits: { component, decision, lesson } to override the per-kind cap (default 5 each, max 50; 0 suppresses the kind). When you pass project, cards whose payload matches that project also get a small additive rank boost (~one calibrated tier) so short global cards don't drown out longer project-scoped ones on raw cosine — globals stay visible but no longer dominate. When you suspect ranking issues, prefer arch_list for ground-truth enumeration.

Input Schema

NameRequiredDescriptionDefault
groupNoSpecific group, or omit to query all known groups
limitsNoPer-kind result limits — components, decisions, and lessons each get their own top-N so a verbose decision bucket cannot starve components out of the output. Default is 5 per kind. Set a kind to 0 to suppress it entirely.
projectNoScope results to a single project inside the group (same value the indexer uses as `payload.project` on code chunks). Components are filtered hard — a component without `project=X` is dropped. Decisions and lessons are filtered soft — cards with `project=X` OR no `project` field pass through, so globally-scoped guidance still surfaces. Omit to query the whole group.
questionYesQuestion, or comma-separated list of files being touched
min_scoreNoDrop hits whose cosine similarity is below this threshold. Default 0.45. Lower it (e.g. 0.30) when the arch memory is sparse and you want broader recall; raise it (e.g. 0.60) when you only want high-confidence matches.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.9/5.0
Behavior5/5

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

The annotations already declare a safe read-only, closed-world operation. The description adds substantial behavior beyond annotations: hidden superseded/deprecated cards, `⚠ stale` prefixes for cards older than 90 days, an init hint on empty architecture memory, independent per-kind budgets, and project-based rank boosting.

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 core purpose and return shape, then uses compact bullets and short paragraphs for behavior, staleness, limits, project ranking, and the sibling alternative. Despite its length, each sentence conveys operative guidance for invoking or interpreting the tool.

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?

For a complex retrieval tool with five parameters, nested `limits`, no output schema, and read-only annotations, the description covers return kinds, staleness handling, empty-layer behavior, per-kind limits, project ranking, and when to prefer `arch_list`. Nothing essential for correct invocation appears missing.

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 100%, so the schema already documents all parameters thoroughly. The description still adds meaning beyond the schema for `limits` and `project`, including the default/max behavior, the ability to suppress a kind with 0, and the project-scoped rank boost; it does not add much for `group` or `min_score`, but those are fully covered in the schema.

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 states a specific verb and resource: retrieve architectural memory relevant to a question or touched files. It enumerates the three returned card kinds and explicitly distinguishes this tool from `arch_list` when ground-truth enumeration is needed, so an agent can identify its role without opening the schema.

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?

It gives an explicit trigger - call this BEFORE any non-trivial change - and names `arch_list` as the alternative when ranking issues are suspected. It also explains when stale cards require verification, which is actionable usage guidance rather than merely implied context.

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