Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Insight Digger MCP list all available data sources and show me the structure of the sales database"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Enterprise-grade Model Context Protocol (MCP) system for data analysis with Claude Desktop integration.
This project provides a sophisticated 3-layer MCP architecture designed for enterprise environments:
MCP Bridge ↔ MCP Client Flask API (Custom HTTP REST endpoints)
MCP Client Flask API ↔ MCP Server subprocess (Standard MCP protocol)
MCP Server ↔ Backend Data API (HTTP calls to enterprise backend)
🔐 Dynamic JWT Authentication: 14-day JWT tokens with session management
🧠 Intelligent Caching: Parameter caching and auto-injection for efficient workflows
📋 Workflow Guidance: LLM-optimized tool orchestration with conversation management
👥 Multi-User Support: Centralized service with session isolation
🏢 Enterprise Integration: Compatible with existing authentication and monitoring systems
Related MCP server: MCP JSON Database Server
For end users who want to use Claude Desktop with Insight Digger:
npx @sandsiv/data-narrator-mcpAdd to your Claude Desktop configuration file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"data-narrator": {
"command": "npx",
"args": ["-y", "@sandsiv/data-narrator-mcp@1.0.0"],
"env": {
"MCP_CLIENT_URL": "https://your-mcp-service.com"
}
}
}
}Note: The MCP_CLIENT_URL environment variable is optional. By default, the system will use Sandsiv's hosted MCP service. Only provide this variable if you're deploying your own version of the data-narrator-mcp service.
Authenticate first: Use the setup_authentication tool with your API URL and JWT token
Start analysis: Begin with list_sources to see available data
Follow the workflow: The system guides you through multi-step analysis processes
For custom integrations or testing:
# Install dependencies
./scripts/setup/install_dependencies.sh
# Activate virtual environment
source venv/bin/activate
# Start the Flask API service
npm run dev:flask
# OR
python src/python/scripts/start_flask_api.py# Initialize session
curl -X POST http://localhost:5000/init \
-H "Content-Type: application/json" \
-d '{"session_id": "test-session", "apiUrl": "https://your-api.com", "jwtToken": "your-jwt"}'
# Get available tools
curl -X POST http://localhost:5000/tools \
-H "Content-Type: application/json" \
-d '{"session_id": "test-session"}'
# Call a tool
curl -X POST http://localhost:5000/call-tool \
-H "Content-Type: application/json" \
-d '{"session_id": "test-session", "tool": "list_sources", "params": {}}'Python 3.8+
Node.js 18+ (for NPX bridge)
Access to Insight Digger backend API
# Clone the repository
git clone <repository-url>
cd insight_digger_mcp
# Install all dependencies
./scripts/setup/install_dependencies.sh --dev
# Activate virtual environment
source venv/bin/activate
# Run tests
npm test
# OR separately:
npm run test:python
npm run test:nodejs# Start your MCP client service
npm run dev:flask
# In another terminal, test the bridge
npm run dev:bridge
# Use the MCP Inspector or Claude Desktop to testLifetime: 14 days
Refresh: Through the main platform web UI (outside MCP scope)
Validation: Bridge handles expired tokens by requesting re-authentication
Single Session: One active session per bridge instance
Session ID: UUID generated for each bridge startup
Isolation: Multiple Claude Desktop instances use separate sessions
The system provides LLM-optimized tools for:
📊 Data Source Discovery: list_sources, get_source_structure
⚙️ Analysis Configuration: prepare_analysis_configuration
🚀 Execution: execute_analysis_from_config
📈 Results: Interactive dashboards and summaries
Parameter Injection: Previously fetched data automatically included in subsequent calls
Workflow Memory: System remembers source selections, configurations, and analysis state
Efficiency: LLM doesn't need to repeat large data structures between steps
Authentication Errors: Clear guidance for JWT/URL validation failures
Tool Errors: Contextual error messages from backend systems
Session Errors: Automatic cleanup and re-authentication prompts
MCP_CLIENT_URL: URL of the MCP Client Flask API service
INSIGHT_DIGGER_API_URL: Backend API URL (configured in MCP server layer)
The MCP Server (mcp_server.py) connects to your backend API using configuration provided during the /init call.
docs/mcp_bridge_implementation_guide.md - Detailed bridge architecture
docs/integration_guide.md - Integration patterns
docs/mcp_client_development_plan.md - Client development guide
docs/mcp_server_development_plan.md - Server development guide
# Install as systemd service (Linux)
sudo cp data-narrator-mcp.service /etc/systemd/system/
sudo systemctl enable data-narrator-mcp
sudo systemctl start data-narrator-mcp# Build and publish the bridge package
npm version patch
npm publish --access publicService logs: journalctl -u data-narrator-mcp -f
Bridge logs: Console output in Claude Desktop
Session tracking: All sessions logged with UUIDs
✅ Status: Ready for external publication
🔐 Security: Comprehensive credential validation implemented
📊 Performance: Optimized with session reuse and direct validation
Immediate credential validation during /init endpoint
Session reuse optimization - no redundant validation calls
Proper HTTP status codes (401 for auth failures, 500 for server errors)
Input validation for API URLs and JWT tokens
Resource efficiency - MCP servers created only for valid credentials
5-second timeout for validation requests
JWT Tokens: Never logged or stored permanently
Session Isolation: Proper cleanup prevents cross-session data leakage
HTTPS Required: All production communications must use HTTPS
Enterprise Auth: Integrates with existing authentication systems
Immediate Auth Feedback: Invalid credentials rejected in <5 seconds
Resource Protection: No MCP instances created for invalid credentials
See SECURITY.md for detailed security documentation.
For issues or questions:
Check the documentation in the docs/ folder
Review the service logs for error details
Verify JWT token validity and API connectivity
Ensure MCP Client service is running and accessible
MIT License - See LICENSE file for details.
🔒 [Requires Authentication] Analyzes data from all charts and returns detailed insights. This is the final analytical step. 🔄 Auto-Cached: 'chartData' is automatically provided from get_charts_data step, 'question' from the workflow, and 'apiUrl'/'jwtToken' from authentication. You typically don't need to provide any parameters for this tool. After receiving the insights, you MUST synthesize them into a final report for the user. Your report should:
Start with a brief summary that directly answers the user's original question.
Follow the previously generated analysis strategy, using insights to address each point.
Support findings with specific data points and note any limitations.
Present the full analysis in markdown format, and include the 'dashboardUrl' at the end.
⚠️ Please authenticate first by calling the setup_authentication tool above. This tool will become fully functional after authentication.
| Name | Required | Description | Default |
|---|---|---|---|
| chartData | Yes | ||
| question | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does well: it discloses authentication requirements ('🔒 [Requires Authentication]'), caching behavior ('🔄 Auto-Cached'), workflow dependencies (data from other tools), and post-call requirements (synthesizing insights into a report). It doesn't mention rate limits, error conditions, or performance characteristics, but provides substantial behavioral context beyond basic functionality.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately front-loaded with purpose and key constraints, but includes extensive post-call instructions (4 bullet points on report synthesis) that belong in workflow documentation rather than tool description. While some context is useful, the report formatting requirements are overly prescriptive and verbose for a tool description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-parameter tool with no annotations and no output schema, the description provides good authentication and workflow context but lacks details on return values (only mentions 'detailed insights' without format), error handling, and the 'apiUrl'/'jwtToken' mentioned in caching note (not in schema). The post-call report instructions partially compensate but don't fully address output expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains that 'chartData' is 'automatically provided from get_charts_data step' and 'question' is 'from the workflow', clarifying their sources and typical non-requirement for manual provision. However, it doesn't detail the structure of 'chartData' (an object with additionalProperties) or format expectations for 'question', leaving some semantic gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'analyzes data from all charts and returns detailed insights' with a specific verb ('analyzes') and resource ('data from all charts'), distinguishing it from siblings like 'get_charts_data' (data retrieval) or 'create_dashboard' (visualization creation). However, it doesn't explicitly differentiate from 'analyze_source_structure' which might have overlapping analytical functions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: it states this is 'the final analytical step' (positioning in workflow), mentions prerequisites ('⚠️ Please authenticate first'), specifies when parameters are typically not needed ('You typically don't need to provide any parameters'), and references sibling tools for required data ('chartData' from 'get_charts_data', authentication from 'setup_authentication').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
🔒 [Requires Authentication] Fetches and analyzes the structure of a given data source. This is a key step after selecting a source. 🔄 Auto-Cached: apiUrl and jwtToken are automatically provided from authentication. Only provide the 'sourceId' parameter (from the previous list_sources step). Returns detailed column analysis to help formulate analytical questions.
⚠️ Please authenticate first by calling the setup_authentication tool above. This tool will become fully functional after authentication.
| Name | Required | Description | Default |
|---|---|---|---|
| sourceId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full burden. It discloses key behavioral traits: authentication requirement ('Requires Authentication'), auto-caching of parameters ('🔄 Auto-Cached'), and that it's a read operation (implied by 'fetches and analyzes'). However, it lacks details on rate limits, error handling, or specific output format, which could enhance transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded, starting with key info (authentication, purpose) and using emojis for emphasis. However, some redundancy exists (e.g., repeating authentication instructions), and it could be more streamlined without losing essential details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (analysis operation), lack of annotations, and no output schema, the description is somewhat complete but has gaps. It covers authentication, usage context, and parameter guidance but lacks details on return values (e.g., what 'detailed column analysis' includes) and potential side effects, which would improve completeness for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage and 1 parameter, the description compensates well by explaining that 'sourceId' is 'from the previous list_sources step' and that only this parameter should be provided. This adds meaningful context beyond the schema, though it could specify the format or constraints of 'sourceId' for full clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'fetches and analyzes the structure of a given data source' and mentions it 'returns detailed column analysis,' which specifies the verb (fetch and analyze) and resource (data source structure). It distinguishes from siblings like 'list_sources' by focusing on analysis rather than listing, though it could be more explicit about how it differs from tools like 'analyze_charts' or 'generate_config.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool: 'after selecting a source' and 'Please authenticate first by calling the `setup_authentication` tool above.' It also mentions an alternative ('list_sources' for selecting a source) and prerequisites, providing clear guidance on context and exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
🔒 [Requires Authentication] Create dashboard configuration from question, column analysis, and strategy. This is a granular step in the analysis workflow. 🔄 Auto-Cached: 'question', 'columnAnalysis', and 'strategy' are automatically provided from previous steps. You typically don't need to provide any parameters for this tool.
⚠️ Please authenticate first by calling the setup_authentication tool above. This tool will become fully functional after authentication.
| Name | Required | Description | Default |
|---|---|---|---|
| columnAnalysis | Yes | ||
| question | Yes | ||
| strategy | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key traits: authentication requirements ('🔒 [Requires Authentication]'), caching behavior ('🔄 Auto-Cached'), and workflow integration ('granular step in the analysis workflow'). It doesn't mention rate limits, error handling, or response format, but covers essential operational aspects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with key information: authentication requirement, purpose, and caching behavior. Every sentence adds value—no wasted words. The use of emojis and formatting (bold, warnings) enhances readability without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (3 parameters, nested objects, no output schema, no annotations), the description does a good job covering authentication, workflow role, and parameter sourcing. However, it lacks details on what the tool returns or how errors are handled. For a creation tool with no output schema, explaining the result would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It mentions the three parameters ('question', 'columnAnalysis', 'strategy') and states they're 'automatically provided from previous steps' and 'typically don't need to be provided.' This adds context about parameter sourcing but doesn't explain what each parameter represents or their expected formats, leaving significant gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Create dashboard configuration from question, column analysis, and strategy.' It specifies the verb ('create') and resource ('dashboard configuration'), and distinguishes it from siblings like 'create_dashboard' by focusing on configuration rather than the dashboard itself. However, it doesn't explicitly differentiate from 'generate_config', which might be similar.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool: 'This is a granular step in the analysis workflow' and 'You typically don't need to provide any parameters for this tool.' It also specifies prerequisites: 'Please authenticate first by calling the `setup_authentication` tool above.' This clearly defines the context and exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
🔒 [Requires Authentication] Create a dashboard from config, source structure, and API settings. This is a granular step in the analysis workflow. 🔄 Auto-Cached: 'markdownConfig' is provided from create_configuration step, 'sourceStructure' from analyze_source_structure, and 'apiUrl'/'jwtToken' from authentication. You typically don't need to provide any parameters for this tool.
⚠️ Please authenticate first by calling the setup_authentication tool above. This tool will become fully functional after authentication.
| Name | Required | Description | Default |
|---|---|---|---|
| markdownConfig | Yes | ||
| sourceStructure | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively adds context: it discloses authentication requirements ('Requires Authentication'), caching behavior ('Auto-Cached'), and workflow dependencies. It doesn't cover all potential behavioral traits (e.g., error handling or rate limits), but it provides significant operational context beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized but not optimally structured. It uses emojis and formatting (e.g., '🔒', '⚠️') for emphasis, which adds visual clutter. The information is front-loaded with key points, but the sentences could be more streamlined; for example, the authentication warning is repeated in different forms. It earns its place but lacks polish.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (2 required parameters, nested objects, no output schema, and no annotations), the description is fairly complete. It covers purpose, usage, dependencies, and behavioral aspects like authentication and caching. However, it doesn't explain the return values or potential errors, which would enhance completeness for a tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description must compensate. It adds meaning by explaining that 'markdownConfig' is from 'create_configuration' and 'sourceStructure' from 'analyze_source_structure,' and notes that parameters are typically auto-cached and not manually provided. This clarifies the semantics and usage of the parameters, though it doesn't detail their internal structure or validation rules.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Create a dashboard from config, source structure, and API settings.' It specifies the verb ('Create') and resource ('dashboard'), and distinguishes it from siblings like 'create_configuration' by mentioning it's a 'granular step in the analysis workflow.' However, it doesn't fully differentiate from all siblings (e.g., 'generate_config' or 'generate_strategy'), keeping it from a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidelines: it states 'You typically don't need to provide any parameters for this tool' due to auto-caching, names the prerequisite tool 'setup_authentication' with a warning to authenticate first, and mentions dependencies on outputs from 'create_configuration' and 'analyze_source_structure.' This clearly defines when and how to use the tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
🔒 [Requires Authentication] Generate dashboard config (markdown) from question and source structure. 🔄 Auto-Cached: 'sourceStructure' is automatically provided from analyze_source_structure step. 'apiUrl' and 'jwtToken' are provided from authentication. Only provide the 'question' parameter from the user. Returns: dict (markdown configuration).
⚠️ Please authenticate first by calling the setup_authentication tool above. This tool will become fully functional after authentication.
| Name | Required | Description | Default |
|---|---|---|---|
| question | Yes | ||
| sourceStructure | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does well: it discloses authentication requirements ('🔒 **[Requires Authentication]**'), caching behavior ('🔄 Auto-Cached'), and that it returns a 'dict (markdown configuration).' It doesn't mention rate limits, error handling, or side effects, but covers key behavioral aspects for a tool with no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with key information (authentication, purpose) but includes some redundancy (e.g., repeating authentication instructions) and could be more streamlined. Sentences like 'Returns: dict (markdown configuration).' are brief, but overall it's moderately efficient with room for improvement in structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (2 parameters, nested objects, no output schema, no annotations), the description is fairly complete: it covers purpose, prerequisites (authentication), parameter context, and return type. It lacks details on error cases or exact output structure, but for a tool with no annotations or output schema, it provides sufficient context for basic use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains that 'sourceStructure' is 'automatically provided from analyze_source_structure step' and that 'Only provide the 'question' parameter from the user,' adding context about parameter origins and usage. However, it doesn't detail the structure or format of 'sourceStructure' or what 'question' should contain, leaving gaps in parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Generate dashboard config (markdown) from question and source structure.' It specifies the verb ('generate'), resource ('dashboard config'), and output format ('markdown'), though it doesn't explicitly differentiate from siblings like 'create_configuration' or 'create_dashboard'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: it states '⚠️ **Please authenticate first** by calling the `setup_authentication` tool above' and mentions that 'sourceStructure' is auto-cached from 'analyze_source_structure' step, while 'apiUrl' and 'jwtToken' come from authentication. It also specifies 'Only provide the 'question' parameter from the user,' clarifying what inputs are needed versus automated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
🔒 [Requires Authentication] Generate analysis strategy for a question and column analysis. This is a granular step in the analysis workflow. 🔄 Auto-Cached: 'columnAnalysis' is automatically provided from the previous analyze_source_structure step. Only provide the 'question' parameter from the user.
⚠️ Please authenticate first by calling the setup_authentication tool above. This tool will become fully functional after authentication.
| Name | Required | Description | Default |
|---|---|---|---|
| columnAnalysis | Yes | ||
| question | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It successfully communicates several important behavioral traits: the authentication requirement (🔒 **[Requires Authentication]**), the auto-caching behavior ('🔄 Auto-Cached': 'columnAnalysis' is automatically provided from the previous analyze_source_structure step), and the functional dependency on authentication ('This tool will become fully functional after authentication'). This provides meaningful context beyond what a basic description would include.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and well-structured with clear visual markers (🔒, 🔄, ⚠️) that help scanning. Each sentence adds value: authentication requirement, purpose, workflow context, parameter guidance, and authentication reminder. While slightly repetitive on authentication, the repetition serves as emphasis rather than waste. The information is front-loaded with the most critical details first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (workflow step with dependencies), no annotations, 0% schema coverage, and no output schema, the description does an excellent job of providing necessary context. It explains the tool's place in a workflow, its dependencies, authentication requirements, and parameter handling. The main gap is the lack of information about what the generated strategy actually contains or looks like, but this is somewhat mitigated by the tool's name and purpose being clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage and 2 parameters, the description adds significant value. It explains that 'columnAnalysis' is 'automatically provided from the previous analyze_source_structure step' and that users should 'Only provide the 'question' parameter from the user.' This clarifies the source and handling of each parameter, which is crucial information not present in the bare schema. The description effectively compensates for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Generate analysis strategy for a question and column analysis' with the specific verb 'generate' and resource 'analysis strategy'. It distinguishes this as 'a granular step in the analysis workflow', which helps differentiate it from sibling tools like analyze_charts or create_dashboard. However, it doesn't explicitly contrast with the most similar sibling (generate_config).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: it states this is 'a granular step in the analysis workflow' and specifies that 'columnAnalysis' is automatically provided from the previous analyze_source_structure step. It also gives clear authentication prerequisites: 'Please authenticate first by calling the setup_authentication tool above.' This tells the agent exactly when to use this tool and what must happen first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
🔒 [Requires Authentication] Fetch data for multiple charts. This step is granular. 🔄 Auto-Cached: 'chartConfigs' is automatically provided from the create_dashboard step, and 'apiUrl'/'jwtToken' from authentication. You typically don't need to provide any parameters for this tool. Returns a summary of fetched charts (chart names). The full data is cached for the next step.
⚠️ Please authenticate first by calling the setup_authentication tool above. This tool will become fully functional after authentication.
| Name | Required | Description | Default |
|---|---|---|---|
| chartConfigs | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key traits: authentication requirements ('🔒 [Requires Authentication]'), caching behavior ('🔄 Auto-Cached'), parameter handling ('automatically provided'), and output behavior ('Returns a summary... The full data is cached for the next step'). This covers critical operational aspects beyond basic functionality.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded with key information (authentication, purpose, caching). It uses formatting (bold, emojis) for emphasis, but includes some redundancy (e.g., repeating authentication instructions) and could be slightly more streamlined without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (involves authentication, caching, and dependencies), no annotations, and no output schema, the description is largely complete. It covers purpose, prerequisites, behavioral traits, and parameter context. However, it lacks details on error handling, rate limits, or the exact format of the returned summary, which could be useful for full contextual understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 1 parameter with 0% description coverage, and the description compensates well. It explains that 'chartConfigs' is 'automatically provided from the create_dashboard step' and that 'You typically don't need to provide any parameters,' clarifying the parameter's source and usage context. However, it doesn't detail the structure or content of 'chartConfigs' (e.g., what it contains), leaving some ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Fetch data for multiple charts' and 'Returns a summary of fetched charts (chart names).' It specifies the verb (fetch) and resource (data for charts), but doesn't explicitly distinguish it from sibling tools like 'analyze_charts' or 'create_dashboard' beyond mentioning the caching relationship with 'create_dashboard.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: it states 'You typically don't need to provide any parameters for this tool' due to auto-caching, specifies prerequisites ('Please authenticate first by calling the `setup_authentication` tool'), and indicates the tool's dependency on 'create_dashboard' for 'chartConfigs.' This clearly defines when and how to use it versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
🔒 [Requires Authentication] List available data sources. This is typically the FIRST interactive step in data analysis. Ask user to provide a search term to filter the sources. 🔄 Auto-Cached: apiUrl and jwtToken are automatically provided from your authentication session. Only provide 'search', 'page', and 'limit' parameters as needed. Ask the user for a source name to search first. Returns: {{'count': int, 'data': [{'id': str, 'title': str, 'type': str, 'updated': str, 'numberOfColumns': int}]}}.
⚠️ Please authenticate first by calling the setup_authentication tool above. This tool will become fully functional after authentication.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| page | No | ||
| search | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and discloses key behavioral traits: authentication requirement ('Requires Authentication'), auto-caching behavior ('🔄 Auto-Cached'), and guidance to ask users for search terms. It doesn't mention rate limits or error handling, but covers essential operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose and authentication requirements, but contains some redundancy (e.g., 'Ask user to provide a search term' and 'Ask the user for a source name to search first') and could be more streamlined. The emojis and formatting help readability but add visual clutter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter tool with no annotations and no output schema, the description provides good context: authentication prerequisites, parameter guidance, and detailed return format. It lacks information about error cases or rate limits, but covers the essential operational flow adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by explaining parameter usage: 'search' for filtering sources, 'page' and 'limit' for pagination, and clarifies that 'apiUrl and jwtToken are automatically provided'. It doesn't detail default values or constraints, but adds meaningful context beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('List') and resource ('available data sources'), and distinguishes it from siblings by emphasizing it's the 'FIRST interactive step in data analysis' rather than analysis or configuration tools like 'analyze_charts' or 'create_configuration'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('typically the FIRST interactive step in data analysis') and when not to use ('Please authenticate first by calling the `setup_authentication` tool above'), with clear prerequisites and named alternatives for authentication.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Setup authentication credentials for Sandsiv+ Insight Digger. This must be called FIRST before any analysis tools become available. Requires your API URL and JWT token.
About This System:
System: Sandsiv+ Insight Digger (Enterprise Data Analysis Platform)
Purpose: Transform business questions into interactive dashboards and AI-powered insights using Sandsiv+ data sources
When to Use This System:
User wants to analyze data from Sandsiv+ platform
User asks about business metrics, KPIs, or data trends
User needs to create dashboards or data visualizations
User mentions Sandsiv+, data analysis, or business intelligence
User wants to explore available data sources
User has analytical questions about their business data
Capabilities:
Connect to Sandsiv+ data sources securely
Analyze data structure and recommend visualization strategies
Generate interactive dashboards with multiple chart types
Extract AI-powered insights from data patterns
Support complex multi-step analytical workflows
Provide comprehensive analytical reports
Workflow: 7-step process: Authentication → Source Discovery → Structure Analysis → Strategy Planning → Configuration → Dashboard Creation → Insight Generation
| Name | Required | Description | Default |
|---|---|---|---|
| apiUrl | Yes | Your Sandsiv+ API base URL (e.g., https://your-domain.sandsiv.com) | |
| jwtToken | Yes | Your JWT authentication token for the Sandsiv+ platform |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses that this tool enables subsequent analysis tools and requires API URL and JWT token, which is useful context. However, it lacks details on error handling, token expiration, security implications, or what happens on repeated calls. For an authentication setup tool with zero annotation coverage, more behavioral disclosure would be expected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is excessively long and poorly structured for a simple authentication tool. Most content describes the broader system capabilities and workflow rather than focusing on the specific tool. The first two sentences contain the essential information, while the remaining sections (About This System, When to Use This System, Capabilities, Workflow) are unnecessary verbosity that doesn't help the agent use this specific tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-parameter authentication tool with no annotations and no output schema, the description provides adequate context about its prerequisite role and parameters. However, it lacks information about what the tool returns (success/failure indicators, session tokens, error messages) and doesn't address important authentication concerns like token refresh or security best practices. The completeness is minimal but sufficient for basic usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, providing clear documentation for both parameters (apiUrl and jwtToken). The description mentions these parameters but doesn't add significant meaning beyond what the schema already states. It doesn't explain parameter relationships, validation rules, or provide examples beyond the schema's URL example. Baseline 3 is appropriate when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Setup authentication credentials for Sandsiv+ Insight Digger.' It specifies the exact action (setup) and resource (authentication credentials) with platform context. It distinguishes itself from siblings by being the mandatory first step before any analysis tools become available.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: 'This must be called FIRST before any analysis tools become available.' It clearly indicates when to use this tool (as the initial authentication step) and implicitly when not to use it (after authentication is already established or for non-Sandsiv+ related tasks). The 'When to Use This System' section further contextualizes the broader platform usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
🔒 [Requires Authentication] Validate API settings by testing the connection to the external data API. 🔄 Auto-Cached: apiUrl and jwtToken are automatically provided from your authentication session - you typically don't need to provide these parameters. Args: apiUrl (str), jwtToken (str). Returns: {{'status': 'success'|'error', 'error': str (if status == 'error')}}.
⚠️ Please authenticate first by calling the setup_authentication tool above. This tool will become fully functional after authentication.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key traits: authentication requirement ('🔒 **[Requires Authentication]**'), auto-caching behavior ('🔄 Auto-Cached': apiUrl and jwtToken are automatically provided from your authentication session'), and return format ('Returns: {{'status': 'success'|'error', 'error': str (if status == 'error')}}'). It doesn't mention rate limits or error handling details, but covers essential operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized but could be more front-loaded. It starts with authentication requirements and auto-caching details before stating the core purpose. The sentences earn their place by providing necessary context, but the structure could be improved by leading with the tool's primary function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (authentication-dependent validation), no annotations, and no output schema, the description does well by covering authentication prerequisites, auto-caching behavior, and return format. It doesn't explain potential error scenarios or validation criteria in depth, but provides enough context for basic usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so the baseline is 4. The description adds value by explaining that 'apiUrl and jwtToken are automatically provided from your authentication session - you typically don't need to provide these parameters,' which clarifies why the schema shows no required parameters despite mentioning args. This semantic context helps the agent understand the parameter flow.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Validate API settings by testing the connection to the external data API.' It specifies the verb 'validate' and the resource 'API settings' with the specific action of testing connection. However, it doesn't explicitly differentiate from sibling tools like 'setup_authentication' or 'create_configuration' beyond mentioning the authentication prerequisite.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: '⚠️ **Please authenticate first** by calling the `setup_authentication` tool above. This tool will become fully functional after authentication.' It names the prerequisite tool and specifies when this tool should be used (after authentication), which is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0analyze_chartsanalyze_source_structurecreate_configurationcreate_dashboardgenerate_configgenerate_strategyget_charts_datalist_sourcessetup_authenticationvalidate_settingsScored across 10 tools
Most tools have distinct purposes aligned with a clear 7-step workflow, but there is some overlap between create_configuration and generate_config that could cause confusion. Both tools generate dashboard configurations, with create_configuration being described as a 'granular step' and generate_config as generating 'markdown configuration', making their boundaries unclear. Other tools like analyze_charts, analyze_source_structure, and list_sources are well-differentiated.
The naming follows a mostly consistent verb_noun pattern (e.g., analyze_charts, list_sources, generate_strategy), but there are inconsistencies like setup_authentication (verb_noun) vs. validate_settings (verb_noun, but 'settings' is plural and less specific) and create_configuration vs. generate_config (different verbs for similar actions). While readable, these deviations reduce overall consistency.
With 10 tools, the count is well-scoped for the server's purpose of transforming business questions into dashboards and insights. Each tool corresponds to a step in the described 7-step workflow, such as authentication, source discovery, and insight generation, ensuring that every tool earns its place without being excessive or insufficient.
The tool set provides complete coverage for the data analysis workflow, from authentication (setup_authentication) to insight generation (analyze_charts). It includes all necessary steps like source listing, structure analysis, strategy planning, configuration, dashboard creation, and data fetching, with no obvious gaps. The tools support the full lifecycle, enabling agents to execute end-to-end analyses without dead ends.
AI-powered corporate learning platform — manage courses, users, and insights via Claude.
Query your warehouse or a CSV with Claude/ChatGPT over MCP, governed by table-level ACL + audit.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
Enterprise AI Control Plane: governance, guardrails, spend tracking, compliance & smart routing.
