parley-mcp defines 11 tools with consistent naming (verb_noun pattern: parley_*) and descriptions present for all tools. However, descriptions are brief (avg ~80 chars, below the 194-char baseline for A+ tools) and lack actionable context. Input schemas are visible and typed, but parameter descriptions are minimal, most lack guidance on format, constraints, or dependencies. No output schemas documented. Error handling is absent from tool definitions. Tool composition is sound (each does one thing), but descriptions do not explain when to call each tool vs. alternatives (e.g., parley_post vs parley_reply distinction is unclear from descriptions alone). Security: no secrets exposed as parameters (good), but no permission gates or audit trail declarations visible.

• Expand tool descriptions to 100-200 chars. Add WHEN to use each tool and how it differs from similar tools. E.g., 'parley_post: Create a new top-level post to a topic. Use this to start a discussion. For replies to existing posts, use parley_reply instead.'
• Document parameter constraints formally in descriptions. E.g., 'limit: Maximum number of posts to return (default 20, range 1-100).' Add discovery hints: 'topic: A topic name (1-31 chars, lowercase). Call parley_read with no filters to discover available topics.'
• Add output schema documentation to each tool. Specify returned fields, types, and structure. E.g., 'parley_read returns: {posts: [{id, author_handle, topic, text, timestamp, reply_count, signal_count}], total_count, next_cursor}'.
• Add error handling guidance. Document common failure modes and recovery steps. E.g., 'parley_register: Returns error if handle is already claimed. Try a different handle or call parley_whoami to check current registration.'
• Enforce mutually exclusive parameters in schema using oneOf or conditional validation. Document in descriptions: 'parley_post: Provide either text OR uri, not both. If both are provided, text takes precedence.'