Skip to main content
Glama

pitfalls

Before starting a task, search recorded pitfalls and decisions to avoid repeating known errors and read the prevention notes.

Instructions

작업을 시작하기 전에 호출하라: 주제와 관련해 과거에 기록된 교훈(learning)과 의사결정(decision)을 찾아준다. 같은 실수를 반복하지 않기 위한 사전 점검 도구다.

topic에는 하려는 작업을 자연어로 (예: "pgvector 인덱스 마이그레이션", "Slack export 파싱"). 결과가 있으면 반드시 get_document로 예방책을 읽어라. 대체된(superseded) 노트는 제외된다. stale=true 표시는 참조 코드가 그 후 변경되어 재검증이 필요하다는 뜻 — 내용을 그대로 믿지 말고 현재 코드와 대조하라. project: 스코프 이름 (토큰에 기본 프로젝트가 있으면 자동 적용, 전체는 "*"). 결과의 project는 그 노트가 기록된 프로젝트(null=팀 공용) — 다른 프로젝트의 노트는 하향되고 other_project=true로 표시된다. 증상이 같아도 프로젝트가 다르면 원인이 다를 수 있으니 그대로 적용하지 말고 현재 프로젝트에서 재확인하라.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
limitNo
topicYes
projectNo

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
resultYes

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 description discloses the tool's behavior regarding superseded notes, staleness re-validation, and cross-project applicability. It also explains that results from other projects should not be applied as-is, giving agents a clear understanding of limitations.

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 concise yet informative, with each sentence adding meaningful guidance. It is well-structured despite being a single block, covering purpose, usage, parameter semantics, and result interpretation efficiently.

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?

The description fully explains the tool's context, including the meaning of result flags and the need to verify against current project code. It also directs to get_document for detailed precautions, making the tool's usage complete for an agent.

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?

Topic and project parameters are well explained with examples and default behavior, but the limit parameter is not described. However, limit is a common and intuitive parameter with a default, so the slight gap is acceptable.

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 the tool finds past lessons and decisions related to a topic and serves as a pre-check to avoid repeating mistakes. It distinguishes from sibling tools like search by focusing on pitfalls and explicitly directing to get_document for precautions.

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 provides explicit guidance to call this tool before starting work and explains how to interpret results, including the meaning of stale and other_project flags. It also instructs to read precautions via get_document, offering clear next steps.

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