Orchestrator/bahn/db-planet-mcp-server/docs/tool-overview.md

DB Planet MCP Server — Tool Overview

29 tools across 9 components. Each tool maps to one or more Haiilo API endpoints.

---

1. Search (3 tools)

Tool	API Endpoint	What it does
Search_FullText	GET /api/search?term=	Keyword search across all content. Returns metadata (id, type, excerpt).
Search_QuickEntity	GET /api/quick-entity-search?term=	Fast entity lookup by name (users, workspaces, pages, events).
Search_Grouped	GET /api/search/grouped?term=	Same as FullText but results grouped by content type.

Example user queries:

• "Find articles about sustainability on DB Planet"
• "Search for GenAI content"
• "Is there a workspace called Innovation Hub?"
• "Find the Town Hall event"

Limitations:

• Keyword matching only, not semantic search. Short queries (1-2 words) work best.
• LLMs sometimes wrap queries in quotes — we strip them automatically.

---

2. Workspace Management (5 tools)

Tool	API Endpoint	What it does
Workspace_List	GET /api/workspaces	List workspaces. memberOnly=true filters for user's own workspaces (client-side pagination + filter).
Workspace_Get	GET /api/workspaces/{id}	Get workspace details by UUID or slug.
Workspace_GetMembers	GET /api/workspaces/{id}/members	Get member list for a workspace.
Workspace_Join	PUT /api/workspaces/{id}/users/join	Join a workspace.
Workspace_Create	POST /api/workspaces	Create a new workspace. Auto-sets current user as admin.

Example user queries:

• "What workspaces am I a member of?" → Workspace_List(memberOnly=true)
• "Show me the Innovation Hub workspace" → Search_QuickEntity → Workspace_Get
• "Who are the members of the BahnGPT workspace?" → Workspace_GetMembers
• "Join the Digital Transformation workspace" → Search_QuickEntity → Workspace_Join
• "Create a workspace called Q1 Planning" → Workspace_Create

Limitations:

• API has no server-side membership filter — memberOnly paginates all workspaces client-side.
• API defaults to 20 results per page.

---

3. News (1 tool)

Tool	API Endpoint	What it does
News_GetFeed	GET /web/blog/newsfeed	Get news articles from subscribed pages. Filters: published/scheduled/drafts, date range.

Example user queries:

• "What are the latest news on DB Planet?"
• "Show me articles from January 2026"
• "Are there any draft articles?"

Limitations:

• ⚠️ Returns 404 on staging — endpoint doesn't exist in staging environment.
• Only returns articles from pages the authenticated user is subscribed to.

---

4. People (4 tools)

Tool	API Endpoint	What it does
People_GetMe	GET /api/users/me	Get current user's profile.
People_Get	GET /api/users/{id}	Get a user's profile by UUID.
People_List	GET /api/users	List all users with pagination.
People_Search	GET /api/users/chooser/search?term=&types=user	Search users by name only.
People_GetManaged	GET /api/users/{id}/managed	Get all users that a given user manages (direct reports).

Example user queries:

• "Show me my DB Planet profile" → People_GetMe
• "Find Alexandra on DB Planet" → People_Search
• "How many users are on DB Planet?" → People_List
• "Who does Alexandra manage?" → People_Search + People_GetManaged

Limitations:

• People_Search only matches by name — cannot search by department, job title, or expertise.
• properties.department exists on profiles but is not queryable and often null on staging.
• No "find people in department X" capability via the API.

---

5. Events (4 tools)

Tool	API Endpoint	What it does
Event_Get	GET /api/events/{id}	Get event details by UUID.
Event_GetMemberships	GET /api/events/{id}/memberships	Get attendee list. Only works if showParticipants is enabled.
Event_UpdateStatus	PUT /api/events/{id}/status	Update attendance: ATTENDING, NOT_ATTENDING, TENTATIVE.
Event_Create	POST /api/events	Create a new event. Auto-sets current user as host/admin.

Example user queries:

• "Show me details about the Town Hall event" → Search_QuickEntity → Event_Get
• "Who is attending the Innovation Workshop?" → Event_GetMemberships
• "Register me for the team building event" → Event_UpdateStatus(status=ATTENDING)
• "Decline the Friday meeting" → Event_UpdateStatus(status=NOT_ATTENDING)
• "Create a team event on May 15th at Frankfurt HQ" → Event_Create

Limitations:

• No "list all events" endpoint — must use Search_QuickEntity to find events by name.
• Event_GetMemberships returns 404 if the event has showParticipants=false.

---

6. Social (4 tools)

Tool	API Endpoint	What it does
Social_GetComments	GET /api/comments?targetId=&targetType=	Get comments on an entity.
Social_PostComment	POST /api/comments	Post a comment. Auto-sets current user as author.
Social_GetLikes	GET /api/like-targets/{type}/{id}/likes	Get like count and list.
Social_ToggleLike	POST /api/like-targets/{type}/{id}/likes/{userId}	Like or unlike content.

Example user queries:

• "Show me comments on the latest blog post" → Search_FullText → Social_GetComments
• "How many likes does the sustainability article have?" → Social_GetLikes
• "Like the welcome post" → People_GetMe + Search_FullText → Social_ToggleLike
• "Comment 'Great work!' on the team update" → Search_FullText → Social_PostComment

Limitations:

• Valid targetTypes: blog-article, timeline-item, wiki-article only. Events are NOT supported.
• Requires content UUID — must search first to find it.
• ToggleLike requires the user's UUID (from People_GetMe).

---

7. Notifications (3 tools)

Tool	API Endpoint	What it does
Notification_List	GET /api/notifications	List notifications. Filter by category: ACTIVITY, DISCUSSION.
Notification_GetStatus	GET /api/notifications/status	Get unseen notification count.
Notification_MarkSeen	PUT /api/notifications/action/mark-seen	Mark notifications as seen. Optional category filter.

Example user queries:

• "Do I have unread notifications?" → Notification_GetStatus
• "Show me my activity notifications" → Notification_List(category=ACTIVITY)
• "Show me discussion notifications" → Notification_List(category=DISCUSSION)
• "Mark all notifications as read" → Notification_MarkSeen

Limitations:

• Category parameter may be required (API returns error without it on some environments).

---

8. Pages (4 tools)

Tool	API Endpoint	What it does
Page_List	GET /api/pages	List all pages.
Page_Get	GET /api/pages/{id}	Get page details by UUID or slug.
Page_GetMembers	GET /api/pages/{id}/members	Get page members/admins.
Page_Create	POST /api/pages	Create a new page. Auto-sets current user as admin.

Example user queries:

• "What pages are available on DB Planet?" → Page_List
• "Show me the HR Department page" → Search_QuickEntity → Page_Get
• "Who manages the Innovation page?" → Page_GetMembers
• "Create a page for the sustainability initiative" → Page_Create

Limitations:

• ⚠️ Page_Create returns 404 on staging — endpoint doesn't exist in staging environment.

---

9. Content (1 tool)

Tool	API Endpoint	What it does
Content_GetFull	Various widget endpoints	Fetch full rendered content by ID and type. Supports: blog-article, wiki-article, page, workspace, app, timeline-item.

Example user queries:

• "Show me the full text of that article" → Content_GetFull (after search)
• "Read the wiki page about onboarding" → Search_FullText → Content_GetFull

Limitations:

• Requires appId for blog and wiki articles (available from Search_FullText results).
• Uses internal widget layout endpoints — may break if Haiilo changes layout naming.

---

Summary

Component	Tools	Status
Search	3	✅ Working
Workspaces	5	✅ Working
News	1	⚠️ 404 on staging
People	5	✅ Working (name search only)
Events	4	✅ Working
Social	4	✅ Working
Notifications	3	✅ Working
Pages	4	✅ Working (Create 404 on staging)
Content	1	✅ Working
Total	30