Skip to main content
Glama
IBazylchuk

Paparats: Local Semantic Code Search

by IBazylchuk
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Record Lesson

arch_record_lesson
Idempotent

Record a codebase rule the agent must follow next time, capturing the user's correction and the situation it applies to. Use it so future sessions avoid repeating the same non-obvious mistake.

Instructions

Record a lesson — a rule the agent should follow next time. Use when the user corrects a non-obvious mistake of yours, OR when you accept an unusual approach that would surprise a future reader. Skip typos, parser errors, and facts trivially visible in code.

Belongs here (arch) vs. agent-side memory (auto-memory / CLAUDE.md / AGENTS.md):

  • arch (this tool) — rules about the code: contracts, boundaries, patterns, API shape, type invariants, framework gotchas, schema/migration constraints, security rules tied to the codebase. Examples: "GraphQL admin mutations require a non-null ID and a corresponding picker query", "Always preserve createdAt on re-upsert", "Run integration tests against a real database, not mocks".

  • agent-side memory (not here) — rules about the user's workflow or how to collaborate with them: preferred commit style, branch naming, when to ask vs act, formatting preferences. Those live in auto-memory or a CLAUDE.md / AGENTS.md file — not in arch.

  • Heuristic: if a new engineer joining the codebase would need it → write it here. If only this specific user needs it → it's agent-side memory.

Three fields, each markdown:

  • rule: one imperative sentence (the rule).

  • why: 1-3 sentences with the incident — quote the user verbatim when possible.

  • when: one sentence describing the situation in which the rule applies. The server runs a similarity gate; possible outcomes:

  • created: a new lesson was written.

  • updated: a near-duplicate already existed — its updatedAt was bumped (confirmation signal). Refine the existing card if your wording was better.

  • similar: a related lesson exists — nothing is written. Decide whether to refine the existing or write a clearly distinct one.

Input Schema

NameRequiredDescriptionDefault
whyYes1-3 sentences. The incident or reason. Quote the user verbatim if they corrected you.
ruleYesOne imperative sentence — the rule itself. E.g. "Always preserve createdAt on re-upsert."
whenYesOne sentence describing the situation in which this rule applies. Future-you must be able to recognise it.
groupYesTarget group
scopeNoglobal
projectNoOptional. Project this lesson is scoped to (same value the indexer uses in `payload.project`). Omit for lessons that apply across all projects in the group.
evidenceNoOptional commit hash, PR link, or short quote backing the lesson.
severityNoinfo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.3/5.0
Behavior5/5

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true), it discloses the server-side similarity gate and its three outcomes (created/updated/similar), which is precisely the behavior an agent needs to interpret the result — and it is consistent with idempotentHint=true. It also implicitly sets expectations about what gets written and what the agent should do on a `similar` result.

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-loaded with the purpose, then cleanly structured with headings and a bulleted routing rule; almost every line carries decision-relevant content. The three field definitions partially duplicate the input schema's own parameter descriptions, which is the only wasted space.

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

Completeness4/5

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

With 8 params, 4 required, and no output schema, the description compensates well by documenting the three possible outcomes in place of a return schema. The remaining gap is operational: `group`, `scope`, and `severity` semantics are never explained, which matters for a tool whose scoping determines where the lesson lands.

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

Parameters3/5

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

Schema coverage is 75%, so the baseline is 3, and the description largely restates the schema for rule/why/when (adding only "each markdown"). It adds nothing about the undocumented parameters — `group` ("Target group" in the schema too), `scope`, and `severity` — so an agent must guess what a group is and what scope/severity change.

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

Purpose4/5

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

The first sentence gives a concrete verb and resource ("Record a lesson — a rule the agent should follow next time") and even defines what a lesson is. It sharply distinguishes arch from external agent-side memory files, but never distinguishes itself from the sibling record tools arch_record_component and arch_record_decision, leaving that routing to the agent's inference.

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 explicit triggers ("user corrects a non-obvious mistake", "you accept an unusual approach that would surprise a future reader") and explicit exclusions ("Skip typos, parser errors, and facts trivially visible in code"). The arch-vs-agent-memory section with a "new engineer joining the codebase" heuristic routes borderline cases decisively.

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