mcp-brain has three tools with complete input schemas and basic descriptions, but falls significantly short of production quality. Tool names follow verb-noun conventions (read_graph, create_entities, create_relations), which is positive. However, parameter descriptions are entirely absent, none of the 6 input parameters across the three tools have descriptions explaining what they control or what formats are expected. Tool descriptions are generic and lack specificity about when to use each tool or what downstream dependencies exist. The schema for create_entities and create_relations are well-formed with proper type hierarchies, but the complete lack of parameter-level documentation violates critical pattern requirements. Output schemas are not documented anywhere. Error handling is minimal, no recovery guidance, no error categorization, no validation of the entity_type or relation_type enums. The entities array in create_entities accepts arbitrary strings for entity_type and relation_type with no enum constraint, inviting hallucinated values from LLMs. No idempotency hints provided for write operations, making retries risky. The read_graph tool takes no parameters but its output schema is undocumented, the LLM has no way to know what structure it returns. Security is concerning: there are no permission checks or audit trails, and the Supabase credentials are loaded from environment variables but the tool definitions include no mention of what data access they grant.

• Add descriptions to all input parameters. For 'entities' in create_entities: 'An array of entity objects. Each must have: name (string, unique identifier for this entity), entity_type (string, category such as person|organization|event), observations (array of strings, facts or attributes about this entity).'
• Add descriptions for 'relations' in create_relations: 'from' (string, the name of the source entity), 'to' (string, the name of the target entity), 'relation_type' (string, the relationship kind such as knows|works_for|owns|created_by).'
• Document output schemas. For read_graph: 'Returns {entities: [{name, entity_type, observations, created_at, updated_at}], relations: [{from, to, relation_type, created_at, updated_at}]}'. This enables LLMs to extract and chain data.
• Add enum constraints for entity_type and relation_type. Define a fixed list of valid values (e.g. entity_type: enum ['person', 'organization', 'place', 'event'] or allow custom with constraint 'alphanumeric, max 50 chars'). Document in parameter descriptions.
• Add idempotent hints via tool annotations (toolAnnotations feature). For create_entities and create_relations, set idempotentHint=true and document that duplicate names are deduplicated or upserted, not duplicated.
• Add error recovery guidance. For example, if create_entities fails with 'Duplicate entity name', respond: 'Entity with this name already exists. Call read_graph to find the existing entity ID, then call create_relations to connect it to other entities instead.'