Read-only access to the bRAInZ knowledge base. Exposes tools for searching, querying, and reading library items and digest pages.
Server exposes 8 read-only tools with clear verb-noun naming (search, list_*, get_*). All tools have descriptions and input schemas are visible in server.py. However, descriptions vary in quality, some are verbose and include guidance (search, get_item) while others are minimal (list_categories, health). Parameter descriptions are present but inconsistent; several lack detail on constraints or expected formats. Output schemas are not explicitly documented in the code. No error handling guidance visible. All tools are read-only (low risk), but composition could be tighter, list_library and search overlap in intent.
Get the full content of a Digest page.
Get the full content of a library item by its ID. Use this after search to read the complete text of a result before synthesizing an answer. The content field contains the full markdown of the item.
Check bRAInZ status and get basic stats (total items, categories, LLM provider).
List all categories in the library with item counts.
List all Digest pages (curated reference notes).
List items in the bRAInZ library with optional filtering.
Minimal descriptions on discovery tools (list_categories, list_tags, health). 'List all categories in the library with item counts' lacks guidance on when to call this vs search, and what the LLM should do with the results.
Output schemas not documented in code. Tools return JSON but LLMs cannot see the structure of results (e.g., what fields are in a search result, what does health return). This forces LLMs to guess at response shape.
search and list_library both retrieve library items with filtering. Overlap in intent creates ambiguity, LLM must reason which to call. Consider consolidating or clarifying when each is preferred.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 53 | <=2025-11-25 | v2 |
List the most common tags in the library.
Search the bRAInZ library and return matching items. This is the correct tool for research questions, topic exploration, and building answers from library content. Use search to find relevant items, then call get_item to read their full content, and synthesize the answer yourself. Do NOT call ask_brainz for these tasks. Returns ranked results with item_id, title, category, URL, and a short snippet. Use the item_id with get_item to retrieve the full content of any result.
Parameter descriptions lack constraint details. 'top_k' has no min/max bounds; 'limit' and 'offset' lack guidance on valid ranges. LLMs may pass invalid values (e.g., top_k=10000).
No error handling guidance visible. If search returns no results, or get_item fails with 404, the code does not show recovery hints for the LLM (e.g., 'Try a broader query' or 'Item may have been deleted').