Agent Brain MCP exposes 16 tools with consistent naming (verb_noun pattern) and complete input schemas. All tools have descriptions (avg 85 chars, within baseline 34-392). However, descriptions are terse and lack context for LLM selection, most are single-sentence statements without WHEN/WHY guidance. Output schemas are not documented in the provided source. Error handling is minimal; no recovery guidance or actionable error messages visible. Tool composition is sound (single responsibility), but descriptions do not explain dependencies (e.g., index_folder must complete before search_documents works). Parameter descriptions are present but sparse, many lack format/constraint details. No evidence of pagination support for list_* tools despite potential for large result sets.

• Expand tool descriptions to 100-200 chars, adding WHEN/WHY context. E.g., 'Search documents using hybrid search (semantic + BM25). Use when you need both keyword and semantic relevance. Returns ranked chunks with scores. Call explain_result() to understand why a chunk ranked high.'
• Document output schemas for all tools. Specify return fields, types, and which fields are required for chaining (e.g., index_folder returns job_id, which get_job and wait_for_job require).
• Add pagination to list_jobs and list_folders: accept limit (1-100, default 20) and offset/cursor parameters; return total_count and next_cursor in response.
• For destructive operations, add a dry_run parameter or return a preview of what will be deleted before confirming. E.g., remove_folder could return 'Will delete 1,250 chunks from /path/to/folder' before confirm=true.
• Enhance parameter descriptions with format/constraint details. E.g., 'timeout_seconds: integer, 1-3600 seconds (default 300)' and 'folder_path: absolute or relative path to a directory containing documents'.