This server provides MCP tools to query and analyze social media datasets stored in DuckDB. Key capabilities include:
Dataset discovery (list_data_queries): List all available datasets with row counts and date ranges. Call this first to get valid query_id values.
Schema inspection (describe_data_query): Get a dataset's schema, row count, date range, and sample rows.
Metric summaries (get_metric_summary): Compute aggregate metrics (post count, total/average engagement) and distributions (sentiment, platform, brand, category) with optional filters.
Keyword search (search_posts): Case-insensitive keyword/phrase search across text and searchable columns, with optional filters for platform, brand, sentiment, category, and date range (up to 100 results).
Post detail retrieval (get_posts_by_ids): Fetch full details for up to 50 specific posts by their IDs.
Ranked posts (get_ranked_posts): Retrieve posts ranked by engagement, likes, comments, shares, or recency, with optional filters (up to 100 results).
VOC search (search_voc): Search Voice of Customer posts by keyword and/or sentiment across main text and summary columns, returning top results by engagement.
Safe SQL execution (safe_query): Run SELECT-only SQL queries directly against dataset tables, with dangerous keyword blocking and automatic LIMIT enforcement (max 500 rows).
Click on "Install 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., "@syncly-dataset-mcp what datasets are available?"
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.
JSON/JSONL 소셜 데이터셋을 Claude Desktop에서 MCP tool로 질의하기 위한 로컬 PoC.
구조: JSON/JSONL → DuckDB → Python MCP 서버 → Claude Desktop
도구 | 설명 |
| 등록된 데이터셋 목록·행 수·날짜 범위 반환. 항상 이 도구를 먼저 호출 |
| 스키마, 행 수, 날짜 범위, 샘플 행 반환 |
| 수치 집계 (post_count, engagement_sum 등) + 분포 (sentiment_distribution 등) |
| 키워드·필터 복합 검색. text/summary/searchable_columns 대상 ILIKE |
| ID 목록으로 포스트 상세 조회 (최대 50건) |
| engagement_count 등 지표 기준 랭킹 포스트 반환 |
| VOC 검색: 텍스트+summary 검색, sentiment 필터, 감성별 상위 포스트 |
| SELECT 전용 SQL 직접 실행 (안전장치 포함) |
get_metric_summary)종류 | 이름 |
스칼라 |
|
분포 |
|
기본값 (metrics 미지정 시): post_count, engagement_sum, avg_engagement, sentiment_distribution, platform_distribution
Related MCP server: motherduck-mcp
도구 | 설명 |
| 기간별 지표 변화·증감률 (주간/월간 비교) |
| 언급 빈도 상위 엔티티 (브랜드, 제품, 카테고리) |
| 엔티티 간 감성 비교 |
| 상위 키워드·해시태그·반복 표현 추출 |
| 인플루언서·파워유저 순위 |
| 엔티티별 VOC 블록 요약 |
| 연관 엔티티 탐색 |
| summary 컬럼 기반 시맨틱 검색 |
| 엔티티 시맨틱 검색 |
| 포스트 상세 (메타데이터·특징) |
| 포스트 피처 분석 (감성 스코어, 주제 등) |
syncly-dataset-mcp/
├── config/
│ └── datasets.yaml # 데이터셋 등록 허용 목록 (여기서 관리)
├── data/
│ ├── raw/ # 원본 JSONL 파일 보관 위치
│ │ └── sample_social_posts.jsonl
│ └── duckdb/
│ └── syncly_datasets.duckdb # 자동 생성, git 제외
├── docs/
│ └── data-prep-prompt.md # 새 데이터 전처리 에이전트 프롬프트
├── src/syncly_dataset_mcp/ # MCP 서버 소스
└── tests/원본 데이터 전처리 적재 분석
CSV / JSON array → JSONL 변환 → DuckDB 적재 → Claude에서 질의
스키마 다를 수 있음 에이전트 활용 ingest CLI이 저장소에서 실제 업무 데이터셋은 로컬 전용 파일로 등록합니다.
GitHub에 올라가는 기본 파일: config/datasets.yaml
로컬에서만 쓰는 실제 데이터셋 등록 파일: config/datasets.local.yaml
로컬에서만 쓰는 실제 원본 데이터: data/raw/*.jsonl
로컬에서만 생성되는 DuckDB: data/duckdb/syncly_datasets.duckdb
config/datasets.local.yaml, sample을 제외한 data/raw/*.jsonl, data/duckdb/*는 .gitignore 대상입니다. MCP 서버는 datasets.yaml을 먼저 읽고, 같은 폴더에 datasets.local.yaml이 있으면 함께 병합합니다. 같은 dataset id가 있으면 local 파일이 우선합니다.
# 1. 파일 배치
cp my_data.jsonl data/raw/
# 2. 로컬 전용 config/datasets.local.yaml에 등록
cat >> config/datasets.local.yaml <<'YAML'
datasets:
my_dataset:
title: "My private dataset"
source_path: "data/raw/my_data.jsonl"
table: "my_dataset"
format: "jsonl"
text_column: "text"
id_column: "id"
YAML
# 3. 적재
uv run syncly-dataset-ingest --dataset my_dataset
# 4. Claude Desktop 새 대화에서 확인
# list_data_queries → describe_data_query → get_metric_summarydocs/data-prep-prompt.md에 있는 에이전트 프롬프트를 활용합니다.
docs/data-prep-prompt.md 전체 복사
Claude 대화에 붙여넣고 원본 데이터 샘플 (100~200행) 추가
Claude가 다음을 반환함:
전처리 Python 스크립트
datasets.yaml 설정 블록
컬럼 매핑 분석
스크립트 실행 → data/raw/ 에 JSONL 저장
datasets.yaml 업데이트 후 적재
# 적재는 항상 DROP → 재생성이므로 그냥 재실행하면 됨
uv run syncly-dataset-ingest --dataset my_datasetdatasets.yaml에서 해당 블록을 삭제하면 MCP tool에서 접근 불가.
DuckDB 테이블은 남지만 tool이 차단함. 완전 삭제 원할 경우:
rm data/duckdb/syncly_datasets.duckdb
uv run syncly-dataset-ingest --dataset all # 남은 데이터셋 재적재_registry는 lazy-load라 서버 재시작 없이 새 대화만 열면 됩니다.
적재 완료 후 Claude Desktop에서 새 대화 열기
list_data_queries 호출 → 새 데이터셋 확인
Python 3.11+
uv 설치
curl -LsSf https://astral.sh/uv/install.sh | shgit clone <이 저장소>
cd syncly-dataset-mcp
uv sync원본 데이터 스키마가 다른 경우 →
docs/data-prep-prompt.md참고
config/datasets.yaml에 데이터셋을 등록합니다.
datasets:
social_posts:
title: "소셜 포스트 데이터"
source_path: "data/raw/social_posts.jsonl"
table: "social_posts"
format: "jsonl" # 'jsonl' 또는 'json'
text_column: "text" # 메인 텍스트 컬럼
id_column: "id"
date_column: "created_at"
summary_column: "summary" # 요약 컬럼 (optional, search_voc에 활용)
searchable_columns:
- text
- summary
- author_name
- brand
- product
- platform
dimensions: # 필터 허용 컬럼
- platform
- brand
- sentiment
- category
entity_columns: # 엔티티 분석 대상
- brand
- product
- category
metrics: # 수치 집계 대상 컬럼
- engagement_count
- like_count
- comment_count
- share_countuv run syncly-dataset-ingest --dataset social_posts전체 데이터셋 적재:
uv run syncly-dataset-ingest --dataset allOS | 경로 |
macOS |
|
Windows |
|
{
"mcpServers": {
"syncly-dataset": {
"command": "uv",
"args": [
"--directory",
"/ABSOLUTE/PATH/TO/syncly-dataset-mcp",
"run",
"syncly-dataset-mcp"
],
"env": {
"SYNCLY_DB_PATH": "/ABSOLUTE/PATH/TO/syncly-dataset-mcp/data/duckdb/syncly_datasets.duckdb",
"SYNCLY_CONFIG_PATH": "/ABSOLUTE/PATH/TO/syncly-dataset-mcp/config/datasets.yaml"
}
}
}
}현재 경로 확인:
pwd
# 예: /Users/yourname/projects/syncly-dataset-mcpClaude Desktop을 완전히 종료 후 재시작하고 새 대화에서 연결을 확인하세요.
사용 가능한 데이터 쿼리 목록 보여줘→ list_data_queries 호출
social_posts 데이터셋의 스키마와 샘플 데이터를 보여줘→ describe_data_query(query_id="social_posts")
소셜 포스트 전체 지표 요약해줘→ get_metric_summary(query_id="social_posts") → post_count, engagement_sum, sentiment/platform 분포
BrandA의 부정 포스트 수와 engagement 합계를 알려줘→ get_metric_summary(filters={"brand":"BrandA","sentiment":"negative"}, metrics=["post_count","engagement_sum"])
배송 관련 포스트 찾아줘→ search_posts(text_query="배송")
BrandB의 2024년 3월 이후 부정 포스트를 engagement 높은 순으로 보여줘→ get_ranked_posts(filters={"brand":"BrandB","sentiment":"negative","date_from":"2024-03-01"})
고객 불만 VOC 중 engagement 상위 포스트 5개를 보여줘→ search_voc(sentiment="negative", limit=5)
환불 관련 VOC를 찾아줘→ search_voc(query="환불")
post_012, post_022의 상세 내용을 보여줘→ get_posts_by_ids(query_id="social_posts", post_ids=["post_012","post_022"])
SELECT brand, COUNT(*), AVG(engagement_count) FROM social_posts GROUP BY brand→ safe_query(query_id="social_posts", sql="SELECT ...")
안전장치 | 동작 |
SELECT 전용 | DROP/DELETE/UPDATE/INSERT/CREATE/ALTER/INSTALL/LOAD 등 차단 |
자동 LIMIT | LIMIT 없는 쿼리에 자동으로 |
최대 반환 행 | 500행 초과 불가 |
ID 조회 제한 |
|
랭킹/검색 제한 | 최대 100행 |
데이터셋 허용 목록 |
|
민감 컬럼 마스킹 |
|
uv 절대경로를 사용해 보세요:
which uv # 예: /Users/yourname/.local/bin/uv{
"command": "/Users/yourname/.local/bin/uv",
"args": ["--directory", "/path/to/project", "run", "syncly-dataset-mcp"]
}서버 직접 실행으로 오류 확인:
cd /path/to/syncly-dataset-mcp
uv run syncly-dataset-mcpClaude Desktop 로그 확인:
tail -f ~/Library/Logs/Claude/mcp*.log데이터 적재가 필요합니다:
uv run syncly-dataset-ingest --dataset social_posts환경변수로 경로를 직접 지정하세요:
SYNCLY_CONFIG_PATH=/absolute/path/to/datasets.yaml uv run syncly-dataset-mcpClaude Desktop을 완전히 종료 후 재시작
새 대화에서 시도 (기존 대화 세션이 서버 프로세스를 재사용하지 않음)
claude_desktop_config.json에 SYNCLY_DB_PATH, SYNCLY_CONFIG_PATH env 설정 확인
Describe a data query: schema, row count, date range, and sample rows.
Args: query_id: Dataset ID from list_data_queries
| Name | Required | Description | Default |
|---|---|---|---|
| query_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions the tool returns schema, row count, date range, and sample rows, but does not discuss any potential side effects, permissions, or rate limits. It is adequate but not thorough.
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 very concise, using a clear format: a one-line summary followed by a bullet for the argument. Every sentence provides necessary information without wasted words.
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 simplicity (1 parameter, no output schema), the description is essentially complete. It explains the return values and the parameter. However, it could benefit from mentioning potential error cases or output format details.
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 description adds significant context to the sole parameter query_id by specifying it is a 'Dataset ID from list_data_queries', which explains its origin and role. This compensates for the 0% schema description coverage.
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 verb 'describe' and resource 'data query', listing what it returns (schema, row count, date range, sample rows). It distinguishes itself from sibling tools like list_data_queries and safe_query by its specific function.
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 tells the user that query_id comes from list_data_queries, implying when to use it. However, it does not explicitly mention when not to use or alternative tools, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compute metric summaries for a dataset.
Scalar metrics: post_count, engagement_sum, avg_engagement, like_sum, comment_sum, share_sum Distribution metrics: sentiment_distribution, platform_distribution, brand_distribution, category_distribution
When metrics is omitted, returns the default set: post_count, engagement_sum, avg_engagement, sentiment_distribution, platform_distribution.
Args: query_id: Dataset ID from list_data_queries metrics: List of metric names to compute (default: all 5 standard metrics) filters: Optional filters dict. Keys: platform, brand, sentiment, category, date_from (ISO date), date_to (ISO date)
| Name | Required | Description | Default |
|---|---|---|---|
| query_id | Yes | ||
| metrics | No | ||
| filters | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the metrics computed, default set, and filter keys. However, it does not describe return format or performance implications, but is still adequate for a compute tool.
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 with a clear purpose, list, and arguments, but could be slightly more concise. It is front-loaded and every sentence adds value.
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 no output schema, the description explains parameters and default behavior well. It lacks detail on return format, but for a summary tool with clear metric names, it is fairly complete.
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 description explains each parameter beyond the schema: query_id as dataset ID, metrics as list with defaults, and filters with specific keys. This compensates for the 0% schema description coverage and adds significant semantic value.
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 computes metric summaries for a dataset, listing specific scalar and distribution metrics, which distinguishes it from sibling tools that retrieve posts or describe queries.
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 explains what the tool does and its default behavior when metrics is omitted, but does not explicitly state when to use this tool versus alternatives like get_posts_by_ids or search_posts. Usage is implied but not directly contrasted.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve full post details for a list of post IDs (max 50).
Returns found posts and a list of any IDs not found.
Args: query_id: Dataset ID from list_data_queries post_ids: List of post ID strings to retrieve (max 50)
| Name | Required | Description | Default |
|---|---|---|---|
| query_id | Yes | ||
| post_ids | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses max 50 posts, returns found posts and not-found IDs. Implies read-only by using 'Retrieve'. Could be more explicit about idempotency or side effects, but adequate.
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?
Three short sentences, purpose front-loaded, Args section clear. No fluff. Efficient communication.
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 no output schema or annotations, description covers key aspects: input, limit, return structure (found posts and not-found IDs). Could mention error handling or order, but sufficient for a simple retrieval tool.
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 coverage 0%, so description compensates well. Explains query_id as 'Dataset ID from list_data_queries' and post_ids as 'List of post ID strings to retrieve (max 50)'. Adds meaningful context beyond schema types.
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?
Clearly states the verb 'Retrieve full post details' for a specific resource (list of post IDs by ID). Includes max limit and return format. Distinct from sibling tools like search_posts which are query-based.
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?
Implies usage when you have specific post IDs, but no explicit when-to-use or when-not-to-use compared to alternatives like search_posts. Only constraint is max 50 IDs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return posts ranked by a metric or recency (max 100, descending).
Args: query_id: Dataset ID from list_data_queries rank_by: Metric to rank by. One of: engagement_count, like_count, comment_count, share_count, created_at filters: Dict with optional keys: platform, brand, sentiment, category, date_from, date_to limit: Max results, up to 100
| Name | Required | Description | Default |
|---|---|---|---|
| query_id | Yes | ||
| rank_by | No | engagement_count | |
| filters | No | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses ranking direction, limit, and the need for a query_id. However, it does not explain behavioral traits like idempotency, error handling, or whether results are paginated, leaving gaps for a read-like operation.
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 the main purpose and uses a structured args list. It is efficient but slightly verbose with blank lines. Overall, it earns its length without being overly wordy.
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 presence of an output schema, the description need not detail return values. It covers core functionality, parameters, and a prerequisite. Minor omissions like error cases or pagination details prevent a perfect score.
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% description coverage, but the description fully compensates by explaining each parameter: query_id's source, rank_by's options, filters' keys, and limit's maximum. This adds critical semantic meaning beyond the bare schema types.
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 returns posts ranked by a metric or recency, with specific constraints (max 100, descending). It is a specific verb+resource pair, but does not explicitly differentiate from sibling tools like search_posts.
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?
No guidance on when to use this tool versus siblings such as search_posts or safe_query. The description implies a prerequisite (query_id from list_data_queries) but lacks explicit when-to-use or when-not-to-use instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available data queries (datasets) with row counts and date ranges.
Always call this first to discover query_id values for subsequent tools.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should fully disclose behavior. It mentions the output includes row counts and date ranges but does not state if the operation is read-only, if there are pagination limits, or if any side effects exist. Adequate but lacks some 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?
Two sentences with no redundant words. The first sentence states action and output, the second provides critical usage guidance. Highly concise and well-structured.
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 simplicity (no parameters, no output schema), the description adequately covers purpose and usage. However, it could be more complete by clarifying the exact return format or handling of empty results, but overall sufficient for discovery.
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?
No parameters are defined, so schema coverage is 100%. The description is not required to add parameter info. Baseline score of 4 is appropriate as there is no missing detail.
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 action (list all available data queries) and the output (row counts and date ranges). It also indicates the tool's role as a discovery tool for sequel queries, distinguishing it from sibling tools that operate on a specific query_id.
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 'Always call this first to discover query_id values for subsequent tools.' This gives clear directive on when and why to use the tool, and implies it should be used before tools that require a query_id.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a SELECT-only SQL query against a dataset table.
Safety: DROP/DELETE/UPDATE/INSERT/CREATE/ALTER/INSTALL/LOAD and other dangerous keywords are blocked. LIMIT is auto-applied if missing (max 500 rows).
Args: query_id: Dataset ID (for validation context) sql: A SELECT SQL query, e.g. "SELECT id, sentiment FROM social_posts LIMIT 10" limit: Max rows to return (capped at 500)
| Name | Required | Description | Default |
|---|---|---|---|
| query_id | Yes | ||
| sql | Yes | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description covers safety restrictions and auto-limit. However, it omits details about return format, error handling, and performance impacts, leaving some behavioral aspects unclear.
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 tightly written with a clear purpose upfront, followed by safety details and a concise parameter list. Every sentence contributes essential information without redundancy.
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 query tool with 3 parameters and an output schema, the description covers safety, usage, and parameters. It does not explain return values, but the output schema likely fills that gap. Overall adequate for the tool's complexity.
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?
Despite 0% schema description coverage, the description explains each parameter in plain language: query_id for context, sql with an example, and limit with a cap. This fully compensates for the schema's lack of descriptions.
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 it executes a SELECT-only SQL query against a dataset table, distinguishing it from sibling tools like describe_data_query or get_metric_summary by specifying the exact operation and scope.
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 lists blocked keywords and auto-applied LIMIT, giving clear constraints. While it does not directly compare to alternatives, the context of blocked operations provides implicit guidance for when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search posts by keyword and/or filters. Returns posts with text snippets.
Searches across text column and all searchable columns (ILIKE, case-insensitive). Either text_query or filters (or both) must be provided.
Args: query_id: Dataset ID from list_data_queries text_query: Keyword or phrase to search (e.g. "배송 지연") filters: Dict with optional keys: platform, brand, sentiment, category, date_from (ISO date string), date_to (ISO date string) limit: Max results, up to 100
| Name | Required | Description | Default |
|---|---|---|---|
| query_id | Yes | ||
| text_query | No | ||
| filters | No | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It explains the case-insensitive ILIKE search across text and searchable columns, and describes what the tool returns (posts with text snippets). It could mention more about error handling or if it is read-only, but overall it is fairly transparent.
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 with a clear summary followed by an args list. It is concise and only includes relevant information, though the phrase 'Searches across text column and all searchable columns (ILIKE, case-insensitive)' could be slightly more succinct.
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 that an output schema exists, the description does not need to explain return values. It covers the input parameters sufficiently and includes usage constraints. However, it omits any mention of error conditions or performance considerations, which would make it more complete.
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 provides detailed explanations for all four parameters, including the meaning of query_id, text_query, filters (with optional keys like platform, brand, sentiment, category, date range), and limit. This adds significant value 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 that the tool searches posts by keyword and/or filters and returns text snippets. It specifies the search mechanism (ILIKE, case-insensitive across columns). However, it does not explicitly differentiate from sibling tools like search_voc or get_ranked_posts, so it loses a point.
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?
It indicates that either text_query or filters must be provided, which is a useful guideline. However, it does not provide when to use this tool versus alternatives (e.g., search_voc for different search behavior), nor does it mention any prerequisites or limitations beyond the limit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Voice of Customer posts by keyword and/or sentiment.
Searches both main text and summary columns (if available). When only sentiment is provided (no query), returns top posts by engagement.
Args: query_id: Dataset ID from list_data_queries query: Keyword to search in post text and summaries sentiment: Filter sentiment: "positive", "negative", or "neutral" filters: Additional filters: platform, brand, category, date_from, date_to limit: Max results, up to 100
| Name | Required | Description | Default |
|---|---|---|---|
| query_id | Yes | ||
| query | No | ||
| sentiment | No | ||
| filters | No | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It describes search behavior and special sentiment-only mode, but does not explicitly state read-only nature or other traits like rate limits or auth requirements. Output schema exists but not described.
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 concise: a brief introductory sentence followed by a clear bulleted list of arguments. No redundant information.
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 output schema exists, return values need not be explained. The description covers parameters, special mode, and limit. Missing examples and error info, but overall adequate for a search tool.
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%, but the description adds meaningful explanations for all 5 parameters, including the list of filter fields and the source for query_id. This compensates well for the missing schema descriptions.
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 it searches Voice of Customer posts by keyword and/or sentiment, and specifies it searches both main text and summary columns. However, it does not explicitly distinguish from sibling tools like search_posts, which could overlap.
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?
Provides specific guidance: when only sentiment is provided (no query), it returns top posts by engagement. Missing explicit when-not-to-use or alternatives, but the special case is helpful.
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. Dates show when Glama detected each change.
v0.1.0describe_data_queryget_metric_summaryget_posts_by_idsget_ranked_postslist_data_queriessafe_querysearch_postssearch_vocEach tool serves a distinct purpose: listing queries, describing datasets, computing metrics, retrieving posts by ID, ranking posts, executing SQL, searching by keyword, and searching for Voice of Customer. There is no overlap in functionality.
Most tools follow a consistent verb_noun pattern (e.g., list_data_queries, get_posts_by_ids, search_posts). However, 'safe_query' deviates from the pattern (adjective_noun), and the use of 'search_voc' instead of 'search_voice_of_customer' is slightly inconsistent.
8 tools is an ideal number for a dataset analytics MCP server. Each tool covers a necessary operation: discovering datasets, describing schema, computing metrics, retrieving posts, ranking, custom SQL, and two search methods. No tool feels redundant or missing.
The tool set covers the main analytics use cases: listing, describing, retrieving, searching, and computing metrics. Custom SQL via safe_query fills gaps for advanced aggregations. However, there is no tool for creating or modifying datasets, which is acceptable for a read-only analytics server.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Query, join, profile, clean and convert CSV/JSON/Parquet with server-side DuckDB over MCP.
Query your warehouse or a CSV with Claude/ChatGPT over MCP, governed by table-level ACL + audit.
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Remote data science agents for Snowflake, Databricks & BigQuery in Claude/Cursor via MCP
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/rimmade/syncly-dataset-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
