Skip to main content
Glama
enesjakozh
susheel

Synapse MCP Server

by susheel
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

Synapse MCP サーバー

Synapse エンティティ (データセット、プロジェクト、フォルダー、ファイル、テーブル) を注釈とともに公開し、OAuth2 認証をサポートするモデル コンテキスト プロトコル (MCP) サーバー。

概要

このサーバーは、モデルコンテキストプロトコル（MCP）を介してSynapseエンティティとそのアノテーションにアクセスするためのRESTful APIを提供します。これにより、以下のことが可能になります。

  • Synapseで認証する

  • IDでエンティティを取得する

  • 名前でエンティティを取得する

  • エンティティの注釈を取得する

  • エンティティの子を取得する

  • さまざまな基準に基づいてエンティティをクエリする

  • Synapseテーブルのクエリ

  • Croissant メタデータ形式でデータセットを取得する

Related MCP server: Reactome MCP Server

インストール

# Clone the repository
git clone https://github.com/SageBionetworks/synapse-mcp.git
cd synapse-mcp

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e .

PyPIからのインストール

# Install from PyPI
pip install synapse-mcp

使用法

サーバーの起動

python server.py --host 127.0.0.1 --port 9000

これにより、デフォルトのポート (9000) で MCP サーバーが起動します。

CLIの使用

# Start the server using the CLI
synapse-mcp --host 127.0.0.1 --port 9000 --debug

コマンドラインオプション

usage: server.py [-h] [--host HOST] [--port PORT] [--debug]

Run the Synapse MCP server with OAuth2 support

options:
  -h, --help       show this help message and exit
  --host HOST      Host to bind to
  --port PORT      Port to listen on
  --debug          Enable debug logging
  --server-url URL Public URL of the server (for OAuth2 redirect)

テストの実行

# Run all tests with coverage
./run_tests.sh

# Or run pytest directly
python -m pytest

サーバーのテスト

python examples/client_example.py

認証方法

環境変数

サーバーは次の環境変数をサポートしています。

  • HOST : バインドするホスト（デフォルト: 127.0.0.1）

  • PORT : リッスンするポート（デフォルト: 9000）

  • MCP_TRANSPORT : 使用するトランスポートプロトコル（デフォルト: stdio）

    • stdio : ローカル開発に標準入出力を使用する

    • sse : クラウド展開に Server-Sent Events を使用する

  • MCP_SERVER_URL : サーバーの公開URL (デフォルト: mcp://127.0.0.1:9000)

    • OAuth2リダイレクトとサーバー情報に使用されます

サーバーは次の 2 つの認証方法をサポートしています。

  1. 認証トークン: Synapse認証トークンを使用して認証する

  2. OAuth2 : SynapseのOAuth2サーバーを使用して認証する

APIエンドポイント

サーバー情報

  • GET /info - サーバー情報を取得する

ツール

  • GET /tools - 利用可能なツールの一覧

  • POST /tools/authenticate - Synapseで認証する

  • POST /tools/get_oauth_url - OAuth2認証URLを取得する

  • POST /tools/get_entity - IDまたは名前でエンティティを取得する

  • POST /tools/get_entity_annotations - エンティティの注釈を取得する

  • POST /tools/get_entity_children - コンテナエンティティの子エンティティを取得します

  • POST /tools/query_entities - さまざまな基準に基づいてエンティティをクエリする

  • POST /tools/query_table - Synapse テーブルをクエリする

リソース

  • GET /resources - 利用可能なリソースを一覧表示する

  • GET /resources/entity/{id} - IDでエンティティを取得する

  • GET /resources/entity/{id}/annotations - エンティティのアノテーションを取得する

  • GET /resources/entity/{id}/children - エンティティの子を取得する

  • GET /resources/query/entities/{entity_type} - タイプ別にエンティティをクエリする

  • GET /resources/query/entities/parent/{parent_id} - 親IDでエンティティをクエリする

  • GET /resources/query/entities/name/{name} - 名前でエンティティをクエリする

  • GET /resources/query/table/{id}/{query} - SQLのような構文でテーブルをクエリする

OAuth2エンドポイント

  • GET /oauth/login - Synapse OAuth2 ログインページにリダイレクトします

  • GET /oauth/callback - Synapse からの OAuth2 コールバックを処理する

例

認証

サーバーを使用するには、実際の Synapse 資格情報で認証する必要があります。

import requests

# Authenticate with Synapse
response = requests.post("http://127.0.0.1:9000/tools/authenticate", json={
    "email": "your-synapse-email@example.com",
    "password": "your-synapse-password"
})
result = response.json()
print(result)

# Alternatively, you can authenticate with an API key
response = requests.post("http://127.0.0.1:9000/tools/authenticate", json={
    "api_key": "your-synapse-api-key"
})

OAuth2認証

1. リダイレクトフロー（ブラウザベース）

ユーザーを OAuth ログイン URL に誘導します。

http://127.0.0.1:9000/oauth/login?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI

2. APIベースのフロー

プログラムで使用する場合は、まず認証 URL を取得します。

import requests

# Get OAuth2 authorization URL
response = requests.post("http://127.0.0.1:9000/tools/get_oauth_url", json={
    "client_id": "YOUR_CLIENT_ID",
    "redirect_uri": "YOUR_REDIRECT_URI"
})
auth_url = response.json()["auth_url"]
# Redirect user to auth_url

エンティティの取得

import requests

# Get an entity by ID
response = requests.get("http://127.0.0.1:9000/resources/entity/syn123456")  # Replace with a real Synapse ID
entity = response.json()
print(entity)

エンティティアノテーションの取得

import requests

# Get annotations for an entity
response = requests.get("http://127.0.0.1:9000/resources/entity/syn123456/annotations")  # Replace with a real Synapse ID
annotations = response.json()
print(annotations)

エンティティのクエリ

import requests

# Query for files in a project
response = requests.get("http://127.0.0.1:9000/resources/query/entities/parent/syn123456", params={  # Replace with a real Synapse ID
    "entity_type": "file"
})
files = response.json()
print(files)

テーブルのクエリ

import requests

# Query a table
table_id = "syn123456"  # Replace with a real Synapse table ID
query = "SELECT * FROM syn123456 LIMIT 10"  # Replace with a real Synapse table ID
response = requests.get(f"http://127.0.0.1:9000/resources/query/table/{table_id}/{query}")
table_data = response.json()
print(table_data)

Croissant形式でデータセットを取得する

import requests
import json

# Get public datasets in Croissant format
response = requests.get("http://127.0.0.1:9000/resources/croissant/datasets")
croissant_data = response.json()

# Save to file
with open("croissant_metadata.json", "w") as f:
    json.dump(croissant_data, f, indent=2)

展開

ドッカー

Docker を使用してサーバーを構築および実行できます。

# Build the Docker image
docker build -t synapse-mcp .

# Run the container
docker run -p 9000:9000 -e SYNAPSE_OAUTH_CLIENT_ID=your_client_id -e SYNAPSE_OAUTH_CLIENT_SECRET=your_client_secret -e SYNAPSE_OAUTH_REDIRECT_URI=your_redirect_uri synapse-mcp
docker run -p 9000:9000 -e MCP_TRANSPORT=sse -e MCP_SERVER_URL=mcp://your-domain:9000 synapse-mcp

フライアイオー

fly.io にデプロイします。

# Install flyctl
curl -L https://fly.io/install.sh | sh

# Login to fly.io
flyctl auth login

# Launch the app
flyctl launch

# Set OAuth2 secrets
flyctl secrets set SYNAPSE_OAUTH_CLIENT_ID=your_client_id
flyctl secrets set SYNAPSE_OAUTH_CLIENT_SECRET=your_client_secret
flyctl secrets set SYNAPSE_OAUTH_REDIRECT_URI=https://your-app-name.fly.dev/oauth/callback
flyctl secrets set MCP_TRANSPORT=sse
flyctl secrets set MCP_SERVER_URL=mcp://your-app-name.fly.dev:9000

# Deploy
flyctl deploy

Claude Desktopとの統合

この Synapse MCP サーバーを Claude Desktop と統合すると、Claude が会話の中で Synapse データに直接アクセスして操作できるようになります。

セットアップ手順

  1. まず、リポジトリのクローンを作成し、要件をインストールします。

# Clone the repository
git clone https://github.com/susheel/synapse-mcp.git
cd synapse-mcp

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e .

  1. Synapse MCP サーバーを使用するように Claude Desktop を構成します。

    • クロードデスクトップを開く

    • Claude メニューをクリックし、「設定...」を選択します。

    • 左側のバーにある「開発者」をクリックします

    • 「設定の編集」をクリックします

    • mcpServersセクションに次の構成を追加します。

"synapse-mcp": {
  "command": "python",
  "args": [
    "/path/to/synapse-mcp/server.py",
    "--host", "127.0.0.1",
    "--port", "9000"
  ]
}

  1. 設定ファイルを保存し、Claude Desktopを再起動します。

  2. クロードとの会話でSynapseデータを使用できるようになりました。例えば：

    • 「SynapseからID syn123456のエンティティを取得する」

    • 「Synapse プロジェクト syn123456 内のすべてのファイルをクエリする」

    • 「Synapseエンティティsyn123456の注釈を取得する」

貢献

貢献を歓迎します！お気軽にプルリクエストを送信してください。

ライセンス

マサチューセッツ工科大学

Available Tools

7 tools
get_datasets_as_croissantB

Get public datasets in Croissant metadata format.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.2/5.0
Behavior2/5

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 states the tool retrieves public datasets, implying a read-only operation, but doesn't clarify aspects like authentication requirements, rate limits, or what 'public' entails. More context on behavior is needed for safe invocation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that directly states the tool's purpose without any unnecessary words. It's front-loaded and appropriately sized for a simple tool with no parameters.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (0 parameters, output schema provided), the description is adequate but minimal. It lacks details on behavioral traits and usage context, which could be important for an agent to operate effectively, especially without annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

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 no parameter documentation is needed. The description doesn't add parameter details, but this is acceptable given the schema's completeness, aligning with the baseline for zero parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Get') and resource ('public datasets in Croissant metadata format'), making the purpose immediately understandable. However, it doesn't differentiate this tool from its siblings (like get_entity or query_entities), which might also retrieve data but in different formats or scopes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention any prerequisites, context for use, or comparisons to sibling tools, leaving the agent to infer usage based on the name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_entityB

Get a Synapse entity by ID.

ParametersJSON Schema
NameRequiredDescriptionDefault
entity_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool 'Get[s]' an entity, implying a read operation, but doesn't specify whether it's safe, requires authentication, has rate limits, or what happens if the ID is invalid. For a tool with zero annotation coverage, this leaves critical behavioral traits undisclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise—a single sentence with no wasted words. It's front-loaded with the core purpose, making it easy to parse. Every word earns its place, and there's no redundancy or unnecessary elaboration.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (one parameter) and the presence of an output schema (which handles return values), the description is minimally complete. However, it lacks context about Synapse entities and doesn't differentiate from siblings, leaving gaps in understanding when and how to use it effectively. It's adequate but with clear room for improvement.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds meaning by specifying that the 'entity_id' parameter is used to retrieve a Synapse entity, which clarifies the parameter's purpose beyond the schema's basic 'Entity Id' title. With 0% schema description coverage and only one parameter, this minimal addition is sufficient to compensate, earning a baseline 4 for adequate coverage in this simple case.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the tool's purpose ('Get a Synapse entity by ID'), which is clear but vague. It specifies the verb 'Get' and resource 'Synapse entity', but doesn't explain what a Synapse entity is or distinguish it from sibling tools like 'get_entity_children' or 'get_entity_annotations'. The purpose is understandable but lacks specificity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. With siblings like 'query_entities', 'search_entities', and 'get_entity_children', it's unclear whether this is for retrieving a single entity by exact ID versus other lookup methods. No context, exclusions, or prerequisites are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_entity_annotationsC

Get annotations for an entity.

ParametersJSON Schema
NameRequiredDescriptionDefault
entity_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states 'Get annotations' but doesn't clarify if this is a read-only operation, what permissions might be required, how the annotations are formatted, or if there are rate limits. The description is too minimal to provide meaningful behavioral 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.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, straightforward sentence with no wasted words. It's front-loaded and efficiently conveys the core action, though it could be more informative without sacrificing brevity. The structure is clear but minimal.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has an output schema (which likely defines the return values), the description doesn't need to explain outputs. However, with 1 parameter, 0% schema coverage, and no annotations, the description is too sparse—it doesn't provide enough context about the entity or annotations to be fully helpful. It's minimally adequate but leaves significant gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the schema provides no parameter descriptions. The description doesn't add any meaning to the 'entity_id' parameter beyond what's implied by the tool name. It doesn't explain what an entity ID is, its format, or where to obtain it, failing to compensate for the lack of schema documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the action ('Get') and target ('annotations for an entity'), which is clear but vague. It doesn't specify what type of annotations or what an 'entity' refers to in this context. While it distinguishes from siblings like 'get_entity' or 'query_entities', it lacks specificity about the resource being retrieved.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, such as needing a valid entity ID, or differentiate from siblings like 'get_entity' (which might retrieve entity metadata) or 'query_entities' (which might search for entities). There's no explicit when/when-not or alternative tool recommendations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_entity_childrenB

Get child entities of a container entity.

ParametersJSON Schema
NameRequiredDescriptionDefault
entity_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action ('Get') but does not reveal whether this is a read-only operation, if it requires specific permissions, what the output format is, or any rate limits. This leaves significant gaps for an agent to understand the tool's behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence with no wasted words. It is appropriately sized and front-loaded, efficiently conveying the core purpose without unnecessary elaboration.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (1 parameter) and the presence of an output schema, the description is minimally adequate. However, with no annotations and sibling tools present, it lacks context on usage and behavioral traits, making it incomplete for optimal agent decision-making.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

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, so the description must compensate. It clarifies that 'entity_id' refers to a 'container entity', adding meaning beyond the schema's minimal 'Entity Id' title. This is sufficient for the single parameter, though it could be more detailed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the verb ('Get') and resource ('child entities of a container entity'), which clarifies the basic purpose. However, it does not distinguish this tool from sibling tools like 'get_entity' or 'query_entities', leaving ambiguity about when to use this specific tool versus others for retrieving entity-related data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. With sibling tools such as 'get_entity', 'query_entities', and 'search_entities' available, there is no indication of context, prerequisites, or exclusions to help an agent choose appropriately.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

query_entitiesD

Query entities based on various criteria.

ParametersJSON Schema
NameRequiredDescriptionDefault
annotationsNo
entity_typeNo
nameNo
parent_idNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

D1.7/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. However, it offers no information about what the tool does beyond 'query'—such as whether it's read-only, destructive, requires authentication, has rate limits, or what the output looks like. This is inadequate for a tool with 4 parameters and no annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise—a single sentence with no wasted words. It's front-loaded and to the point, though this brevity comes at the cost of clarity and completeness. Every word earns its place, but the place is insufficient for the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (4 parameters, 0% schema coverage, no annotations, and multiple sibling tools), the description is severely incomplete. It doesn't explain what 'entities' are, how querying works, what the parameters do, or how this differs from similar tools. While an output schema exists, the description provides no context to interpret it, making it inadequate for effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, meaning none of the 4 parameters (annotations, entity_type, name, parent_id) are documented in the schema. The description adds no semantic information about these parameters—it doesn't explain what they mean, how they're used, or what values are acceptable. This fails to compensate for the complete lack of schema documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose2/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Query entities based on various criteria' is vague and tautological. It restates the tool name 'query_entities' without specifying what 'entities' are, what 'query' means operationally, or what 'various criteria' entail. It doesn't distinguish this tool from siblings like 'search_entities' or 'get_entity', leaving the purpose ambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There are no usage guidelines provided. The description doesn't indicate when to use this tool versus alternatives like 'search_entities' or 'get_entity', nor does it mention any prerequisites, context, or exclusions. This leaves the agent with no guidance on tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

query_tableC

Query a Synapse table.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
table_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.4/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden but offers no behavioral details. It doesn't disclose if this is a read-only operation, requires authentication, has rate limits, affects data, or what the response entails (e.g., format, pagination). This leaves critical behavioral traits unknown.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with no wasted words, making it appropriately sized and front-loaded. It directly states the tool's function without unnecessary elaboration.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (querying a database table), no annotations, 0% schema coverage, and an output schema (which helps but isn't described), the description is incomplete. It lacks essential context such as query language, permissions, or behavioral traits, making it inadequate for effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

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 but adds no parameter semantics. It doesn't explain what 'query' and 'table_id' represent (e.g., query syntax, table identifier format), leaving both parameters undocumented beyond their titles in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Query a Synapse table' states the action (query) and resource (Synapse table), which provides a basic purpose. However, it's vague about what 'query' entails (e.g., SQL-like queries, filtering, aggregation) and doesn't distinguish it from sibling tools like 'query_entities' or 'search_entities', leaving ambiguity in scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives such as 'query_entities' or 'search_entities'. The description lacks context about prerequisites, typical use cases, or exclusions, offering no help in tool selection among siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_entitiesC

Search for Synapse entities.

ParametersJSON Schema
NameRequiredDescriptionDefault
entity_typeNo
parent_idNo
search_termYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.6/5.0
Behavior2/5

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 only states the action ('Search') without detailing permissions, rate limits, pagination, or what constitutes a 'Synapse entity'. This leaves significant gaps in understanding the tool's behavior and constraints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with no wasted words. It is appropriately sized and front-loaded, making it easy to parse quickly, though this conciseness comes at the cost of detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (3 parameters, 0% schema coverage, no annotations) and the presence of an output schema, the description is incomplete. It lacks essential context such as parameter meanings, usage scenarios, and behavioral traits, making it inadequate for effective tool selection and invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the schema provides no parameter details. The description adds no information about parameters like 'entity_type', 'parent_id', or 'search_term', failing to compensate for the lack of schema documentation. This leaves all three parameters semantically unclear.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Search for Synapse entities' clearly states the verb ('Search') and resource ('Synapse entities'), providing a basic purpose. However, it lacks specificity about what 'Synapse entities' are and doesn't differentiate from sibling tools like 'query_entities' or 'get_entity', making it vague in context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives such as 'query_entities' or 'get_entity'. There is no mention of context, exclusions, or prerequisites, leaving the agent with no usage direction beyond the basic action.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 7 tool updatesv1.0.0
    • First observedget_datasets_as_croissant
    • First observedget_entity
    • First observedget_entity_annotations
    • First observedget_entity_children
    • First observedquery_entities
    • First observedquery_table
    • First observedsearch_entities
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

C2.9/5.0

Scored across 7 tools

Disambiguation4/5

Most tools have distinct purposes targeting different Synapse operations, but query_entities and search_entities could cause some confusion as both involve finding entities. The descriptions help differentiate them, with query_entities focusing on structured criteria and search_entities on broader search, but overlap exists.

Naming Consistency5/5

Tool names follow a highly consistent verb_noun pattern throughout, using snake_case uniformly. All tools start with a clear verb (get, query, search) followed by a specific noun, making them predictable and easy to understand.

Tool Count5/5

With 7 tools, this server is well-scoped for interacting with Synapse entities and datasets. Each tool serves a distinct function in the domain, such as retrieving entities, annotations, children, datasets, and querying/searching, without being overly sparse or bloated.

Completeness4/5

The tool set covers core read and query operations for Synapse entities and datasets effectively, including retrieval, annotation access, and searching. A minor gap exists in write operations (e.g., create, update, delete entities), but agents can likely work around this for many use cases.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers