nope-mcp — Open Educational Resources search

Grounded passage search (RAG) scoped by a spell

search_passages

Read-onlyIdempotent

THE DEFAULT TOOL FOR QUESTION-SHAPED QUERIES ("wie/warum/was hilft bei X?", "how do I…?"): retrieves the best-matching fulltext passages from the corpus and returns them with citations (source resource, page, heading, source URL) — answer the user FROM the passages and cite each source. (For discovery intent — "finde/empfiehl Materialien" — use search_content instead, or afterwards to offer browsable links.) Keep question topic-only. Ranking is hybrid keyword+vector, so phrase the question as a topical statement that names the subject and the target group ("Friedenserziehung in der Grundschule: Einstieg in das Thema Frieden mit Kindern"), not as the user's literal sentence ("Wie kann ich …?"). Results are capped at two passages per document; a passage with only a snippet and no text has no fulltext yet — say so instead of guessing. Educational-resource passages come only from openly licensed resources (CC0, Public Domain, CC BY, CC BY-SA); other content types are not license-filtered. Scope is required but simple: with no source restriction from the user, pass the content kinds (e.g. kinds:[30142] for educational resources, [30040,30041] for publications, [30023] for articles). Route source restrictions ("nur Content von X") into the scope parameters: a metadata publisher (most organisations — resolve_publisher finds the exact spelling) goes into search as a QUOTED field filter, e.g. search:'publisher.name:"LEHRE LADEN"' (unquoted multi-word names match nothing); a Nostr signing account (resolve_author → pubkey) goes into authors. A published grimoire spell (kind 777, nevent or event id) can replace inline scope entirely; the response carries the canonical spell for whatever scope was used — publish it (e.g. via grimoire) to make the scope reusable. Spells may use $me/$contacts; they resolve to the calling user (pass me if the transport is anonymous). Fails rather than widening scope: an empty scope, unreachable relay (relay_unreachable — tell the user to retry), or unreachable index is a typed error, never a silently unscoped search.

Input Schema

TableJSON Schema

Name	Required	Description
`me`	No	Who $me refers to (npub or hex). Defaults to the calling identity.
`tag`	No	Inline scope: one tag filter, e.g. {letter:"h", values:["<community-pk>"]}.
`kinds`	No	Inline scope: content kinds (e.g. 30142).
`limit`	No	Passages to return (1-25, default 10).
`since`	No	Inline scope: absolute Unix seconds or relative (7d, 1mo, now).
`spell`	No	Published spell: nevent, note id, or 64-hex event id.
`until`	No	Inline scope: absolute Unix seconds or relative.
`relays`	No	Relay selection (list_relays set), by full URL or short name (e.g. "oersi", "sodix"). First mapped relay is used.
`search`	No	Inline scope: NIP-50 term selecting the EVENTS in scope (distinct from question). Supports field filters; quote multi-word values: publisher.name:"LEHRE LADEN".
`authors`	No	Inline scope: Nostr event-author pubkeys (hex/npub/$me/$contacts) — resolve names via resolve_author. NOT for metadata publishers; those go into `search`.
`question`	Yes	The question or topic to find grounding passages for.

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 3, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already cover read-only/idempotent/non-destructive, but the description adds substantial behavior the annotations do not: results capped at two passages per document, snippet-only passages lacking fulltext, license filtering only for educational resources, and typed failure modes ('Fails rather than widening scope'). It also discloses the $me/$contacts resolution and the canonical-spell return value.

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 classification ('THE DEFAULT TOOL FOR QUESTION-SHAPED QUERIES') and every sentence carries operational content for an 11-param tool. It is dense — a single long paragraph heavy with parentheticals — which costs some readability, but there is little wasted text.

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, 11-param tool with no output schema, the description covers what is returned (passages with citations: source resource, page, heading, source URL), how to answer from results, scope construction, spell substitution, and error behavior. 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?

Schema coverage is 100% and the schema already documents the search/authors split, so much of the routing advice is reinforcement. However, the description adds genuinely new guidance absent from the schema — 'Keep `question` topic-only' and phrasing it as a topical statement rather than the user's literal sentence — plus concrete kinds examples. It adds value beyond the schema, though not dramatically.

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?

Opens with a specific verb+resource ('retrieves the best-matching fulltext passages from the corpus') and a clear scope statement ('THE DEFAULT TOOL FOR QUESTION-SHAPED QUERIES'). It explicitly distinguishes itself from search_content by intent (question-shaped vs discovery), so an agent can pick between siblings without opening either 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?

States when to use it (question-shaped queries like 'wie/warum/was hilft bei X?'), when to use the alternative ('For discovery intent — use search_content instead, or afterwards to offer browsable links'), and how to route source restrictions into scope params. Prerequisites like the required-but-simple scope and the relay_unreachable retry path are spelled out.

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

All nope-mcp — Open Educational Resources search tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.