Second Brain MCP server has 15 tools with significant quality gaps. Tool naming is moderately clear (verb-based: list, create, update, remove, switch, accept, find, rename, resolve), averaging ~20 characters. Descriptions exist for all tools (range 45-150 chars) but many are generic and lack context on when to use them or what happens on failure. Input schemas are visible but sparse: only 7 of 15 tools have documented parameters with types and descriptions; 8 tools have no visible input schema at all. Output schemas are completely undocumented, callers have no guidance on what fields to expect. Error handling is absent from all tool definitions, no recovery guidance, no categorization of retryable vs fatal errors. Parameter descriptions lack constraints (e.g., no enum for role values despite them being role, no format specs for IDs). Tool composition is reasonable (each tool does one thing), but critical chaining information is missing, e.g., createAgent returns an API key but no agent_id, forcing an extra listAgents call to identify the created agent. Security-relevant tools (createAgent, createInvitation, updateMemberRole, removeMember) lack permission annotations and scope declarations. Baseline for production tools expects 100% tool descriptions (achieved here) and 100% parameter descriptions (only ~47% achieved). Average parameter annotation length in this server is ~35 chars vs production baseline of 72 chars.

• Document output schemas for all 15 tools. For each, specify field names, types (string, number, object, array), and required fields. Example: listAgents should return {agents: [{id, name, scopes, active, createdAt, updatedAt}], total: number}.
• Add comprehensive parameter descriptions with constraints for all 7 tools with input schemas. For enum params (role, status), explicitly list valid values in the description. For IDs, specify format (UUID, slug, numeric). Example: 'role (required): Team role for invited member. Must be one of: owner, admin, member.'
• Expand tool descriptions from ~50 chars to 100-150 chars. Include: WHAT the tool does, WHEN to call it (prerequisites, dependencies), and WHAT it returns. Example for renameTeam: 'Rename the current active team. Requires team_admin or owner role. Returns the updated team with new name and slug. Note: team slug does not change, only display name. Use this before creating resources under a new team name.'
• Add error handling notes to 5 write tools (createAgent, createInvitation, updateMemberRole, removeMember, acceptInvitation). Document expected errors: 'On 409 Conflict: email already invited or member already exists. On 403 Forbidden: insufficient permissions. On 404 NotFound: invitation/user/team not found, verify IDs match your context.'
• Add scope/permission annotations to security-critical tools. Use a 'permissions' field in tool definition. Examples: createAgent requires ['write:agents']; removeMember requires ['write:team', 'read:team']; renameTeam requires ['write:team']. This enables least-privilege agent config.