br8n defines 3 read-only tools with clear, action-verb names (brain_list, brain_read, brain_search) and concise descriptions (avg 155 chars, within baseline 194). All tools have input schemas with Zod validation and proper type annotations. Tool annotations (readOnlyHint, idempotentHint, openWorldHint) are correctly applied. However, parameter descriptions are minimal or absent: brain_list has no input schema at all (empty {}), brain_read's 'path' param lacks format/constraint guidance, and brain_search's 'limit' param lacks min/max documentation in the description text (only in Zod). Output schemas are not documented, LLMs cannot predict the structure of returned JSON. Error handling is absent: no guidance on path traversal failures, missing files, or invalid search queries. No pagination guidance for brain_search despite potentially large result sets.

• Add explicit parameter descriptions to brain_read: 'path (string, required): Relative path inside the brain (e.g., decisions/2026-03-change-orders.md). Must not contain .. or escape the root. Max 500 chars.'
• Document brain_search limit in description: 'limit (number, optional, 1-200, default 50): Maximum results to return. Refine your query if results are truncated at the limit.'
• Add output schema documentation as a comment or separate schema field. E.g., 'Returns: Array of {rel: string, line: number, text: string} objects, capped at limit.'
• Enhance error messages with recovery hints. E.g., 'Path outside brain root. Call brain_list() to see available files.' This guides LLM self-correction.
• Add a note to brain_list description: 'Returns all markdown files (.md, .markdown, .txt) in the brain, sorted by path. Use brain_search() to find content by keyword.'