Skip to main content
Glama
Peacho97

librarian-mcp

by Peacho97

librarian_guide

Registers session intent and exclusions to steer worker queries toward relevant code and prevent cross-project bleed; updates replace prior guidance and reset clears it.

Instructions

For the coordinating session, before delegating to workers: register this session's intent so every worker's librarian_brief / librarian_ask / librarian_discuss is steered by it (their answers show the guidance version). Freeform intent about code/projects only - never client names, emails, health, or personal data (the engine rejects PII). Replaced on every call (version bumps); expires after 6h. reset=true clears it first (reset with empty text = just clear). Re-guide per phase.

exclude: path prefixes/substrings, project names, or catalog entry ids the librarian must NOT serve this session. They are hard-filtered on the engine before the model sees them, and librarian_locate hits are filtered too. Use it to stop cross-project bleed, e.g. another app's UI palette/layout leaking into a worker's build (["apps/other-app", "legacy-service"]). Max 40 items, 200 chars each. expect: one line (<=500 chars) predicting the effect this guidance should have on worker output; workers quote the guidance footer in their report, and the coordinator compares that against this prediction. Replace-on-write: every call replaces text, exclude AND expect, so a call without exclude clears the exclusions. caller is an optional caller label; leave it empty.

Input Schema

NameRequiredDescriptionDefault
textYes
resetNo
callerNo
expectNo
excludeNo

Output 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?

With no annotations, the description carries the full burden and does so: replace-on-write semantics, version bumping on every call, 6h expiry, reset-with-empty-text behavior, engine-side PII rejection, and hard filtering before the model sees excluded content. These are exactly the behavioral traits an agent needs before mutating shared state.

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 core purpose, then organized into per-parameter blocks that are easy to scan. The replace-on-write rule is stated twice (once in the intro, again at the end for `exclude`/`expect`), which is mild redundancy but defensible given the destructive implication.

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?

An output schema exists so return values need no explanation, and the description covers the remaining risk surface: scoping constraints, PII limits, expiry, reset, and cross-project bleed prevention. Nothing an agent needs in order to call this correctly is missing.

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

Parameters5/5

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

Schema coverage is 0%, so the description must compensate and it does for every parameter: `text` (freeform, code/projects only, PII rejected), `exclude` (path prefixes/substrings/project names/catalog ids, hard-filtered, max 40 items at 200 chars, with a concrete example), `expect` (one line, <=500 chars, compared against worker reports), `reset`, and `caller`.

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 and resource ('register this session's intent') and explains its downstream effect on named siblings (librarian_brief / librarian_ask / librarian_discuss). An agent can distinguish this from the sibling tools without opening any 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?

Explicit about when: 'For the coordinating session, before delegating to workers' and 'Re-guide per phase.' It also names the alternatives that consume the guidance, so the agent knows this is the setup step rather than a query tool.

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