The Spix MCP server defines 13 tools with complete JSON Schema input definitions and brief descriptions. All tools have properly typed parameters with constraints (enums, ranges). However, descriptions are uniformly terse (10-40 chars), lacking the WHEN/WHY/HOW context required by LLMs for tool selection. Parameter descriptions exist but are often minimal. Output schemas are not documented. Error handling is absent, no recovery guidance or actionable error messages. No tool annotations (readOnlyHint/destructiveHint/idempotentHint) despite risk classification in metadata. Naming follows verb_noun convention consistently and is clear. The server lacks composition patterns (e.g., no batch variants, no multi-step helpers). Security is reasonable (API key via env var, no secrets in params), but permission gates and audit trails are not visible in the provided code.
Descriptions uniformly terse (10-40 chars). Fall far short of 50-200 char baseline for LLM optimization. Examples: 'Create a new call or SMS playbook' (36 chars), 'List playbooks' (14 chars), 'Delete a playbook' (17 chars). Missing context on WHEN/WHY to call each tool, prerequisites, and return value guidance.
Output schemas not documented in tool definitions. LLMs cannot infer response structure, fields, or downstream chaining requirements. E.g., spix_playbook_create returns a playbook object but the structure is undocumented, does it return playbook_id, voice_id, status, created_at, etc.?
Expand every tool description to 80 - 200 characters. Template: 'ACTION what the tool does. WHEN to call it (prerequisite, relation to other tools). RETURN what structure/fields are available.' Example: 'Create a new call or SMS playbook with voice settings, goals, and rules. Call after listing available voices/languages. Returns playbook_id, status, and created_at for follow-up management.'
Document output schemas for all tools. For each tool, specify: response type (object, array), key fields, field types, and which fields enable downstream chaining. E.g., spix_playbook_list returns: { playbooks: [{id, name, type, status, created_at}], total_count, next_cursor }.
Add tool annotations. Mark read-only tools (spix_playbook_list, spix_playbook_show, list_voices, list_languages, list_emotions, spix_playbook_rule_list) with readOnlyHint=true. Mark destructive tool (spix_playbook_delete) with destructiveHint=true. Mark idempotent tools (pause/resume on already-paused/resumed playbook) with idempotentHint=true.
Add error handling guidance to tool descriptions and/or response documentation. E.g., spix_playbook_delete: 'May fail if playbook has active campaigns. Check playbook status (via spix_playbook_show) before deleting. On error, receive error_code and recovery suggestion (e.g., pause campaigns first, then retry).'
Enhance parameter descriptions with constraints and examples. E.g., 'language: Language code (2-letter ISO 639-1, e.g., en, es, fr, de). Determines voice options returned by spix_playbook_voice_list and TTS default.'
No error handling guidance. Tool definitions do not indicate what errors might occur, which are retryable, or what the LLM should do on failure. E.g., spix_playbook_delete could fail if the playbook is in use, but no recovery path is documented. Violates recovery-guide pattern.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite risk metadata in evaluation data. Metadata indicates spix_playbook_delete is DESTRUCTIVE, spix_playbook_create is WRITE, etc., but these are not exposed in tool definitions. LLMs cannot distinguish safe vs risky tools without explicit annotation.
Parameter descriptions minimal or absent in many tools. E.g., spix_playbook_language_list has no input schema properties documented; spix_playbook_emotion_list empty input. Even described params like 'type' in spix_playbook_create lack detail on how playbook type affects downstream behavior.
spix_playbook_list offers pagination (cursor, limit) but does not document total count or next_cursor in response schema. Agents cannot determine if more results exist without response inspection. Violates paginated-result pattern.
Composition gaps: no batch variants for tools agents might call in loops (e.g., add multiple rules to a playbook requires N sequential spix_playbook_rule_add calls). Wastes tokens and latency. No helper to create+activate a playbook in one call.
spix_playbook_rule_add
Add a spix_playbook_rule_add_batch tool accepting an array of rules to reduce N sequential calls to 1. Or enrich spix_playbook_create to accept initial rules as optional parameter.
Document playbook_id parameter behavior across tools. Clarify: is playbook_id optional with a default (as shown in tools.py session validation), or required? If optional, which tools apply default and which don't? Make this explicit in each tool description.
Add pagination metadata to spix_playbook_list response documentation: clarify if next_cursor is present only when more results exist, and how to determine end-of-list. Specify default limit and max page size.
Validate inputs early and return structured errors. E.g., if voice_id is invalid, return { error: 'invalid_voice_id', valid_voices: [...] } so LLM can self-correct without manual lookup.
Consider adding a spix_playbook_create_and_activate helper if the two-step create→update pattern is common, to reduce agent friction and token spend.