The server defines two tools with moderately good naming (verb_noun convention) and detailed parameter schemas. However, descriptions are functional but generic, output schemas are not documented, and error handling lacks recovery guidance. The complex nested schemas for create_cohort show effort, but the tools lack actionable error messages and the server lacks essential quality patterns for production use.
Tools (2)
create_cohortwriteauthsource verified72/100
Create a PostHog cohort (static or dynamic) based on person properties OR user behavior (events/actions). Provide either propertyGroups OR behavioralFilters.
list_cohorts includes a dummy 'random_string' parameter that serves no purpose. Violates single-responsibility and confuses LLMs about what input is actually needed.
Error handling absent. No guidance for LLMs on failure modes: What if PostHog API is unreachable? What if a cohort name already exists? What if propertyGroups AND behavioralFilters are both provided?
create_cohort description does not clarify mutual exclusivity of propertyGroups and behavioralFilters. LLMs will pass both unless explicitly told not to, causing ambiguous failures.
create_cohort
Recommendations
Document output schema for list_cohorts: return structure should include cohort_id, name, description, is_static, created_at, updated_at, and member_count. Include example: {"cohorts": [{"id": "123", "name": "Power Users", "is_static": false, "member_count": 1250}]}
Remove the dummy 'random_string' parameter from list_cohorts. Change input schema to an empty object {}.
Enhance create_cohort description: 'Create a PostHog cohort (static or dynamic) based on person properties OR user behavior. Provide either propertyGroups (based on user attributes) OR behavioralFilters (based on events/actions), but not both. Returns the new cohort's ID and a link to the PostHog dashboard.'
Add validation error handling: Return structured errors like {"error": "Missing required credentials", "code": "MISSING_POSTHOG_KEY", "recovery": "Set POSTHOG_HOST and POSTHOG_API_KEY environment variables and retry."} for auth failures, {"error": "Cohort name already exists", "code": "DUPLICATE_NAME", "recovery": "Choose a unique name or update the existing cohort."} for duplicates, and {"error": "Both propertyGroups and behavioralFilters provided", "code": "AMBIGUOUS_INPUT", "recovery": "Provide either propertyGroups OR behavioralFilters, not both."} for mutual exclusivity violations.
No rate limiting, timeout handling, or permission gates documented. Agents running in loops could overwhelm PostHog API or inadvertently create cohorts without user awareness.
create_cohort's description does not mention prerequisites: What permissions are required? Must the user own the PostHog project? What happens if the API key is invalid?
create_cohort
Update create_cohort description to include: 'Requires valid PostHog API credentials (POSTHOG_API_KEY, POSTHOG_HOST, POSTHOG_PROJECT_ID). Static cohorts capture a snapshot of users at creation time; dynamic cohorts update continuously as user properties change.'
Add per-parameter validation hints in create_cohort schema: For 'name', specify max length (e.g., 255 chars) and disallowed characters. For 'operator' in propertyConditionSchema, document valid operators: 'exact', 'icontains', 'is_not', 'regex', 'gt', 'lt', 'is_date_after', 'is_date_before', 'matches', 'not_matches'. For 'time_value', specify min=1, max=365.
Implement dry-run or confirmation pattern for create_cohort since it modifies state: Accept an optional 'preview' parameter that returns the cohort definition and estimated member count WITHOUT creating. This prevents accidental cohort creation.
Add timeout handling: Specify that calls to external PostHog API have a 30-second timeout. If exceeded, return {"error": "PostHog API request timed out", "code": "TIMEOUT", "recovery": "PostHog service may be slow. Wait a moment and retry, or check https://status.posthog.com/"}