Provides intent-based tools for querying and analyzing the Sakila sample database, including film search, customer management, rental operations, revenue analysis, and inventory tracking without exposing underlying database schema.
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., "@Sakila MCP Server search for action movies starring Tom Hanks"
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.
MySQL（Sakilaデータベース）にアクセスするMCPサーバーのPython実装です。
このプロジェクトは、Model Context Protocol (MCP) を使用して、LLM（Claude等）からSakilaデータベースに自然言語でアクセスできるようにします。
Intent-Based API設計を採用し、データベーススキーマを非公開としながら、ビジネス意図ベースの18種類のツールを提供します。
┌─────────────────┐ ┌─────────────────┐
│ ユーザー │ 自然言語 │ Claude (LLM) │
│ (Human) │ ─────────────────────► │ 意図理解 │
└─────────────────┘ └────────┬────────┘
│ ツール選択
▼
┌─────────────────┐ MCP Protocol ┌─────────────────┐
│ Claude Desktop │ ◄────────────────────► │ MCP Server │
│ (Host) │ stdio transport │ (Python) │
└─────────────────┘ └────────┬────────┘
│ SQL生成・実行
│ aiomysql
▼
┌─────────────────┐
│ MySQL 8.0 │
│ (Sakila DB) │
└─────────────────┘スキーマ非公開: テーブル構造、カラム名、FK関係は一切公開しない
ビジネス意図ベース: 「映画を検索する」「顧客詳細を取得する」などの意図に対応
セキュリティ重視: パラメータ化クエリ、入力検証、エラーメッセージ制御
Related MCP server: MCP-Driven Data Management System
ツール名 | 機能 | 主要パラメータ |
| 映画検索（タイトル、カテゴリ、レーティング、俳優名） | title, category, rating, actor_name, limit |
| 映画詳細取得（出演者・在庫情報含む） | title |
| カテゴリ一覧取得 | なし |
| 在庫・貸出状況確認 | title, store_id |
ツール名 | 機能 | 主要パラメータ |
| 顧客検索 | name, email, store_id, active_only |
| 顧客詳細取得（住所・履歴サマリー含む） | customer_id or email |
ツール名 | 機能 | 主要パラメータ |
| レンタル履歴取得 | customer_id, status |
| 延滞一覧取得 | store_id, days_overdue |
ツール名 | 機能 | 主要パラメータ |
| 人気映画ランキング | period, category, store_id, limit |
| 売上サマリー | group_by, store_id, period |
| 店舗統計 | store_id |
| 俳優の出演作品一覧 | actor_name |
ツール名 | 機能 | 主要パラメータ |
| 優良顧客ランキング | metric (rentals/spending), period, limit |
| 顧客セグメント分析 | なし（自動分類） |
| 顧客アクティビティ分析 | period |
ツール名 | 機能 | 主要パラメータ |
| 在庫回転率分析 | store_id, category |
| カテゴリ別パフォーマンス | period, store_id |
| 低稼働作品一覧 | days_not_rented, store_id |
git clone <repository-url>
cd sakila-mcp-servercp .env.example .env
# 必要に応じて .env を編集docker compose up -d初回起動時、Sakilaデータベースが自動的にインポートされます（約1-2分）。
uv syncuv run sakila-mcp~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または適切な設定ファイルに以下を追加：
{
"mcpServers": {
"sakila": {
"command": "uv",
"args": ["--directory", "/path/to/sakila-mcp-server", "run", "sakila-mcp"]
}
}
}Claude Desktopで以下のような質問ができます。
「アクション映画を検索して」
「PG-13の映画を5本教えて」
「Tom Hanksが出演している映画は？」
「映画'ACADEMY DINOSAUR'の詳細を教えて」
「Smithという名前の顧客を検索して」
「顧客ID 1番の詳細情報を見せて」
「アクティブな顧客だけを検索して」
「顧客ID 1番のレンタル履歴を見せて」
「延滞している顧客は誰？」
「店舗1の延滞状況を確認して」
「今月の人気映画ランキングを教えて」
「カテゴリ別の売上サマリーを見せて」
「店舗ごとの統計を比較して」
「優良顧客TOP10は？」
「在庫回転率が低い映画は？」
「カテゴリ別のパフォーマンスを分析して」
「30日以上レンタルされていない映画を教えて」
# リント
uv run ruff check .
# リント（自動修正）
uv run ruff check --fix .
# フォーマット
uv run ruff format .
# フォーマットチェック
uv run ruff format --check .# 全テスト実行
uv run pytest
# ユニットテストのみ（DB不要）
uv run pytest -m "not integration"
# 統合テストのみ（DB起動後）
uv run pytest -m integration
# カバレッジ付き
uv run pytest --cov=sakila_mcp --cov-report=term-missing項目 | 値 |
Host | localhost |
Port | 3306 |
Database | sakila |
User | sakila_user |
Password | sakila_pass |
パラメータ化クエリ: すべてのユーザー入力は%sプレースホルダー経由
入力検証: 許可値リストによるバリデーション
rating: G, PG, PG-13, R, NC-17
store_id: 1, 2
period: all_time, last_month, last_week
等
数値制限: limitは最大50件
フィールド制限: 返却JSONは必要フィールドのみ
エラーメッセージ: SQLエラー詳細は非公開
sakila-mcp-server/
├── CLAUDE.md # 開発ガイド（Claude Code用）
├── README.md # セットアップ手順（本ファイル）
├── docker-compose.yml # MySQL 8.0 + Sakila自動セットアップ
├── init/
│ └── 01-init-sakila.sh # Sakila DB 初期化スクリプト
├── pyproject.toml # 依存関係・ツール設定
├── .env.example # 環境変数テンプレート
├── sakila_mcp/
│ ├── __init__.py
│ └── server.py # MCPサーバー本体（18ツール実装）
└── tests/
├── __init__.py
├── conftest.py # 共通fixtures
└── test_server.py # サーバーテスト（43テスト）CLAUDE.md - 開発者向け詳細ガイド（アーキテクチャ、コーディング規約、テストパターン）
docs/SAKILA_DATABASE.md - Sakilaデータベース概要
docs/MCP_IMPLEMENTATION_PATTERNS.md - MCP実装パターンガイド
MIT
映画の在庫・貸出状況を確認します。
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | 映画タイトル | |
| store_id | No | 店舗ID（省略時は全店舗） |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. While 'checking' implies a read-only operation, it doesn't explicitly state whether this requires authentication, has rate limits, returns real-time vs cached data, or what format the output takes. For a tool with zero annotation coverage, this leaves significant behavioral gaps.
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 a single, efficient sentence in Japanese that directly states the tool's purpose without any unnecessary words. It's appropriately sized and front-loaded with the core functionality, making it easy for an agent to parse quickly.
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 annotations, no output schema, and multiple sibling tools with overlapping domains, the description is insufficiently complete. It doesn't explain what 'availability' means in this context (inventory count, rental status, both?), doesn't differentiate from similar tools, and provides no behavioral context. For a tool in a crowded namespace, more contextual information would be helpful.
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 100%, with both parameters clearly documented in the schema itself. The description doesn't add any parameter information beyond what's already in the schema (title and store_id with enum values). With complete schema coverage, the baseline score of 3 is appropriate as the description doesn't compensate but doesn't need to.
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 as 'checking film availability/inventory/rental status' (映画の在庫・貸出状況を確認します), which is a specific verb+resource combination. However, it doesn't distinguish this from sibling tools like 'get_film_details' or 'search_films' that might also provide film-related information, so it doesn't fully differentiate from alternatives.
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 no guidance on when to use this tool versus alternatives like 'get_film_details', 'search_films', or other sibling tools. There's no mention of prerequisites, specific use cases, or exclusions, leaving the agent to infer usage context from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
俳優の出演作品一覧を取得します。
| Name | Required | Description | Default |
|---|---|---|---|
| actor_name | 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 of behavioral disclosure. It only states the basic action without details on permissions, rate limits, response format, or pagination. For a read operation with no annotation coverage, this is a significant gap in 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 a single, efficient sentence in Japanese that directly states the tool's purpose. It's front-loaded and wastes no words, though it could benefit from more detail given the lack of annotations and output schema.
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 of a read operation with no annotations and no output schema, the description is incomplete. It doesn't explain what the return values look like (e.g., list format, fields included) or any behavioral traits like error handling. This makes it inadequate for full agent 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 schema description coverage is 100%, with the parameter 'actor_name' documented as allowing partial matches. The description doesn't add any extra meaning beyond this, such as examples or edge cases. With high schema coverage, the baseline score of 3 is appropriate as the schema handles the parameter documentation adequately.
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: '俳優の出演作品一覧を取得します' translates to 'Get a list of an actor's filmography.' This specifies the verb (get) and resource (actor's filmography). However, it doesn't distinguish from siblings like 'get_film_details' or 'search_films,' which might also involve actors, so it lacks explicit differentiation.
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 no guidance on when to use this tool versus alternatives. It doesn't mention when to use it over 'search_films' for actor-related queries or 'get_film_details' for specific film data, nor does it specify any prerequisites or exclusions. This leaves the agent without context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
カテゴリ別パフォーマンス分析を行います。
| Name | Required | Description | Default |
|---|---|---|---|
| period | No | 集計期間（デフォルト: all_time） | all_time |
| store_id | No | 店舗ID |
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 only states the tool 'analyzes' category performance, but doesn't describe what the analysis includes (e.g., metrics like sales, rentals, or trends), whether it's a read-only operation, any rate limits, or what the output format looks like. For a tool with no annotations, this is a significant gap in 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 a single, efficient sentence in Japanese (カテゴリ別パフォーマンス分析を行います), which translates to 'Performs category performance analysis.' It is front-loaded with the core purpose and has zero wasted words, making it highly concise and well-structured for its minimal content.
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 of a performance analysis tool with no annotations and no output schema, the description is incomplete. It doesn't explain what 'performance' means, what metrics are returned, or how the analysis is structured. Without this context, users lack essential information to understand the tool's behavior and outputs, 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.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with clear documentation for both parameters ('period' and 'store_id'), including enums and defaults. The description adds no additional meaning beyond what the schema provides, such as explaining how these parameters affect the analysis. However, since schema coverage is high (>80%), the baseline score of 3 is appropriate, as the schema adequately handles parameter semantics.
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 states the tool performs 'category performance analysis' (カテゴリ別パフォーマンス分析を行います), which is a clear purpose. However, it lacks specificity about what 'performance' entails (e.g., sales, rentals, revenue) and doesn't distinguish it from sibling tools like 'list_categories' or 'get_revenue_summary', making it somewhat vague. The verb 'analyzes' is appropriate but could be more precise.
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 no guidance on when to use this tool versus alternatives. It doesn't mention any context, prerequisites, or exclusions, such as how it differs from 'list_categories' (which might list categories without performance data) or 'get_revenue_summary' (which might provide overall revenue without category breakdown). Without such information, users must infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
顧客アクティビティ分析を行います。新規・アクティブ・休眠顧客の割合を確認できます。
| Name | Required | Description | Default |
|---|---|---|---|
| period | No | 分析期間 | last_month |
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 performs analysis and returns percentage breakdowns, but doesn't describe output format, data freshness, rate limits, authentication needs, or potential side effects. For a tool with no annotations, this is a significant gap in transparency, as the agent lacks critical 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 concise and front-loaded, with two sentences that directly state the purpose and key capability. There's no wasted text or redundancy. However, it could be slightly more structured by explicitly listing the three customer types (new, active, dormant) for clarity, but it's still efficient.
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 of an analysis tool with no annotations and no output schema, the description is incomplete. It doesn't explain what the output looks like (e.g., a report, percentages, time-series data), how the analysis is computed, or any limitations. For a tool that likely returns structured data, this leaves the agent unprepared to interpret results effectively.
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 no parameter semantics beyond what the input schema provides. The schema has 100% coverage with a clear enum for 'period' (all_time, last_month, last_week) and a default. The description doesn't explain what these periods mean in the context of activity analysis or how they affect results. Since schema coverage is high, the baseline is 3, but no extra value is added.
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: '顧客アクティビティ分析を行います。新規・アクティブ・休眠顧客の割合を確認できます。' (Performs customer activity analysis. You can check the percentage of new, active, and dormant customers.) This specifies the verb ('analyzes') and resource ('customer activity'), and distinguishes it from siblings like get_customer_details (details) or get_customer_segments (segments). However, it doesn't explicitly differentiate from get_customer_rentals or get_top_customers, which might overlap in analyzing customer behavior, so it's not a perfect 5.
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 no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, context, or exclusions. For example, it doesn't clarify if this is for high-level summaries versus detailed breakdowns, or how it compares to get_customer_segments or get_top_customers. The lack of usage context leaves the agent guessing about appropriate scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
顧客の詳細情報（住所、レンタル統計含む）を取得します。
| Name | Required | Description | Default |
|---|---|---|---|
| customer_id | No | 顧客ID | |
| No | メールアドレス（customer_idがない場合） |
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. While '取得します' (get/retrieve) implies a read operation, there's no information about authentication requirements, rate limits, error conditions, response format, or whether this is a real-time query versus cached data. For a tool with no annotation coverage, this leaves significant behavioral gaps.
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 extremely concise - a single Japanese sentence that efficiently communicates the core functionality. It's front-loaded with the main purpose and includes the scope (address, rental statistics) without unnecessary elaboration. Every word earns its place.
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 tool with no annotations, no output schema, and multiple sibling tools in the same domain, the description is insufficient. It doesn't explain what format the details come in, how comprehensive they are, whether this includes historical data, or how it differs from other customer tools. The agent would struggle to use this effectively without additional context.
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%, so the schema already documents both parameters (customer_id and email) with their descriptions. The tool description doesn't add any parameter-specific information beyond what's in the schema, nor does it explain the relationship between the two parameters or which takes precedence. 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: '取得します' (get/retrieve) '顧客の詳細情報' (customer details) including '住所、レンタル統計含む' (address, rental statistics included). It specifies the resource (customer details) and scope (including address and rental statistics), but doesn't explicitly differentiate from sibling tools like get_customer_activity or get_customer_rentals.
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 no guidance on when to use this tool versus alternatives. With multiple customer-related tools available (get_customer_activity, get_customer_rentals, get_customer_segments, search_customers), there's no indication of when this detailed view is appropriate versus those other tools, nor any prerequisites or exclusions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
顧客のレンタル履歴を取得します。
| Name | Required | Description | Default |
|---|---|---|---|
| customer_id | Yes | 顧客ID | |
| status | No | レンタル状態 | all |
| limit | No | 取得件数 |
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 but provides minimal information. It states what the tool does but doesn't mention whether it's a read-only operation, what permissions might be required, whether there are rate limits, or what format the rental history data will be returned in. For a tool with 3 parameters and no annotations, this is insufficient behavioral 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 a single, efficient sentence that states exactly what the tool does without any wasted words. It's appropriately sized for a straightforward retrieval tool and gets directly to the point with no unnecessary elaboration.
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 read operation with good schema coverage but no annotations and no output schema, the description is minimally adequate. It tells the agent what the tool does but leaves important behavioral questions unanswered. The combination of clear purpose, complete parameter documentation in the schema, and concise description makes it functional but not comprehensive.
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 100% description coverage, with all parameters clearly documented in Japanese. The tool description doesn't add any additional parameter information beyond what's already in the schema. According to the scoring rules, when schema_description_coverage is high (>80%), the baseline is 3 even with no param info in the description.
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 ('取得します' - get/retrieve) and resource ('顧客のレンタル履歴' - customer rental history), making the purpose immediately understandable. It doesn't explicitly differentiate from sibling tools like 'get_customer_activity' or 'get_customer_details', but the specific focus on rental history is clear enough to avoid confusion.
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 no guidance on when to use this tool versus alternatives. With siblings like 'get_customer_activity' and 'get_customer_details' available, there's no indication of how this tool differs in scope or when it should be preferred over those other customer-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
顧客セグメント分析を行います。利用頻度・金額で顧客を自動分類します。
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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. While it states what the tool does (analysis/classification), it doesn't describe important behavioral aspects: whether this is a read-only operation, what format the output takes, whether it requires specific permissions, or how the classification algorithm works. For a tool with zero annotation coverage, this is insufficient.
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 extremely concise - just two Japanese sentences that directly state the tool's purpose and classification method. Every word earns its place with zero wasted text. The structure is front-loaded with the core purpose immediately stated.
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 annotations, no output schema, and the description's limited scope, this is incomplete for a data analysis tool. The description explains what the tool does but not what it returns, how results are structured, or any behavioral constraints. For a tool that presumably returns customer segmentation data, more context about output format and analysis characteristics would be helpful.
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 tool has 0 parameters with 100% schema description coverage, so the baseline is 4. The description appropriately doesn't discuss parameters since none exist, and it focuses on the tool's core functionality instead.
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: '顧客セグメント分析を行います' (performs customer segment analysis) and specifies the classification criteria ('利用頻度・金額で顧客を自動分類します' - automatically classifies customers by usage frequency and amount). This is specific about the verb (analyze/classify) and resource (customers), though it doesn't explicitly distinguish from sibling tools like 'get_customer_activity' or 'get_customer_details'.
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 no guidance on when to use this tool versus alternatives. With multiple customer-related sibling tools (get_customer_activity, get_customer_details, get_customer_rentals, search_customers, get_top_customers), there's no indication of when this segmentation analysis is appropriate versus other customer data retrieval tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
映画の詳細情報（出演者、カテゴリ、在庫状況含む）を取得します。
| Name | Required | Description | Default |
|---|---|---|---|
| title | 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 states this is a retrieval operation ('取得します'), implying it's likely read-only, but doesn't explicitly confirm this or mention any authentication requirements, rate limits, error conditions, or what happens if the film isn't found. The description adds minimal behavioral context beyond the basic purpose.
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 a single, efficient sentence that communicates the core purpose and scope without unnecessary words. It's appropriately sized for a simple retrieval tool and front-loads the essential information. Every element of the sentence contributes meaning.
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 retrieval tool with no annotations and no output schema, the description is insufficiently complete. It doesn't describe what the return format looks like (structure of the detailed information), whether it returns a single result or multiple, error handling, or any behavioral constraints. Given the complexity of returning detailed film information with multiple data points, more context would be helpful for the 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?
Schema description coverage is 100% (the single parameter 'title' has a clear description in Japanese), so the baseline is 3. The tool description doesn't add any parameter-specific information beyond what's in the schema - it doesn't explain format expectations, examples, or constraints for the title parameter. The description's mention of what details are retrieved doesn't directly relate to parameter semantics.
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 ('取得します' - get/retrieve) and resource ('映画の詳細情報' - film details), specifying what information is included ('出演者、カテゴリ、在庫状況含む' - including cast, category, inventory status). It distinguishes from siblings like 'check_film_availability' (which might only check availability) and 'search_films' (which likely returns a list rather than detailed information). However, it doesn't explicitly differentiate from 'get_actor_filmography' or 'get_category_performance' which focus on different aspects.
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 no guidance on when to use this tool versus alternatives. It doesn't mention when to choose this over 'search_films' (which might return multiple films with less detail) or 'check_film_availability' (which might focus only on inventory). There's no context about prerequisites, timing, or exclusions for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
在庫回転率分析を行います。作品ごとの在庫効率を確認できます。
| Name | Required | Description | Default |
|---|---|---|---|
| store_id | No | 店舗ID（省略時は全店舗） | |
| category | No | カテゴリで絞り込み |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It states the tool performs analysis and allows checking efficiency, implying a read-only operation, but doesn't clarify if it requires specific permissions, what the output format looks like, whether it's paginated, or any rate limits. For an analytics tool with zero annotation coverage, this leaves significant gaps in understanding how it behaves.
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 with two sentences that directly state the tool's function and scope. It's front-loaded with the main purpose and avoids unnecessary details. However, it could be slightly more structured by explicitly mentioning it's a read operation or linking to sibling tools.
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 has no annotations, no output schema, and moderate complexity (analytics with two parameters), the description is incomplete. It doesn't explain what 'inventory turnover analysis' entails (e.g., metrics like turnover ratio, time periods), how results are returned, or any limitations. For an analytics tool, this leaves the agent guessing about output format and behavioral context.
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%, with both parameters ('store_id' and 'category') well-documented in the schema. The description adds no additional parameter information beyond what's in the schema, such as explaining how 'category' relates to inventory turnover or providing examples. Baseline 3 is appropriate when the 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 as '在庫回転率分析を行います' (performs inventory turnover analysis) and specifies it allows checking inventory efficiency per work/film. This is a specific verb+resource combination, though it doesn't explicitly differentiate from sibling tools like 'get_category_performance' or 'get_store_stats' which might overlap in inventory-related analytics.
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 no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'get_category_performance' or 'get_store_stats' that might provide related metrics, nor does it specify prerequisites or exclusions for usage. The agent must infer context from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
延滞中のレンタル一覧を取得します。
| Name | Required | Description | Default |
|---|---|---|---|
| store_id | No | 店舗ID（省略時は全店舗） | |
| days_overdue | No | N日以上延滞（デフォルト: 0） | |
| limit | No | 取得件数（デフォルト20） |
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 only states what the tool does (get overdue rentals) without mentioning any behavioral traits like whether it's read-only, if it requires specific permissions, rate limits, or what the output format might be. For a tool with zero annotation coverage, this is a significant gap.
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 a single, efficient sentence in Japanese that directly states the tool's purpose without any unnecessary words. It is appropriately sized and front-loaded, making it easy to understand at a glance.
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 of a tool with 3 parameters and no output schema or annotations, the description is incomplete. It doesn't cover behavioral aspects, usage context, or output details, leaving gaps that could hinder an AI agent's ability to use the tool effectively. This is inadequate for a tool with multiple parameters and no structured support.
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 100% description coverage, with all parameters well-documented in the schema itself (e.g., store_id, days_overdue, limit with defaults). The description adds no additional meaning beyond what the schema provides, such as explaining parameter interactions or usage examples. With high schema coverage, the baseline score of 3 is appropriate.
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 purpose: '延滞中のレンタル一覧を取得します' (Get a list of overdue rentals). It specifies the verb (get/取得) and resource (overdue rentals/延滞中のレンタル). However, it doesn't explicitly differentiate from sibling tools like 'get_customer_rentals' or 'get_customer_activity', which might also involve rental data, so it doesn't reach the highest 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 no guidance on when to use this tool versus alternatives. It doesn't mention any context, prerequisites, or exclusions, such as how it differs from other rental-related tools like 'get_customer_rentals' or 'search_films'. This leaves the agent without clear usage instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
人気映画ランキングを取得します。
| Name | Required | Description | Default |
|---|---|---|---|
| period | No | 集計期間 | all_time |
| category | No | カテゴリで絞り込み | |
| store_id | No | 店舗ID | |
| limit | No | 取得件数 |
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 only states what the tool does ('get popular film rankings') without detailing aspects like authentication requirements, rate limits, error handling, or the format of returned data. For a tool with no annotations and no output schema, this is a significant gap in 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 a single, clear sentence in Japanese that directly states the tool's purpose without unnecessary words. It's front-loaded with the core action and resource, making it efficient and easy to parse. There's no wasted verbiage, earning a top score for 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 (4 parameters, no annotations, no output schema), the description is incomplete. It lacks details on behavioral traits, output format, and usage context. While the schema covers parameters well, the overall tool understanding is insufficient for an agent to invoke it confidently without additional context or assumptions.
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 no parameter-specific information beyond what's in the input schema, which has 100% coverage with descriptions for all parameters (e.g., 'period' with enum values, 'category' for filtering). Since schema description coverage is high, the baseline score is 3, as the schema adequately documents parameters without needing extra details in the description.
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: '人気映画ランキングを取得します' translates to 'Get popular film rankings.' This specifies the verb ('get') and resource ('popular film rankings'), making the purpose unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'get_top_customers' or 'get_category_performance,' which also retrieve rankings but for different entities.
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 no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'search_films' or 'get_film_details' that might serve related purposes, nor does it specify prerequisites or contexts where this tool is preferred. The lack of usage guidelines leaves the agent to infer based on tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
売上サマリーを取得します。
| Name | Required | Description | Default |
|---|---|---|---|
| group_by | No | 集計単位 | store |
| store_id | No | 店舗で絞り込み |
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/retrieve), which implies a read-only operation, but doesn't clarify permissions, rate limits, data freshness, or what the output looks like. For a tool with no annotations and no output schema, this minimal description is inadequate for understanding behavioral traits.
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 a single, efficient sentence in Japanese with no wasted words. It's appropriately sized for a simple tool, though it could be more informative. The structure is straightforward, but it lacks front-loading of critical details that would help an agent.
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 with enums), no annotations, and no output schema, the description is incomplete. It doesn't explain the tool's role among siblings, behavioral constraints, or output format. For a revenue summary tool with potential overlap with other stats tools, more context is needed to guide effective 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?
The input schema has 100% description coverage with clear enum values and defaults, so the baseline is 3. The tool description adds no parameter information beyond what's in the schema—it doesn't explain how 'group_by' and 'store_id' interact or provide usage examples. This meets the minimum viable level given the schema's completeness.
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 '売上サマリーを取得します' (Get revenue summary) is a tautology that essentially restates the tool name 'get_revenue_summary' in Japanese. It provides a verb+resource but lacks specificity about what kind of revenue summary or how it differs from sibling tools like 'get_store_stats' or 'get_category_performance'. The purpose is clear at a basic level but doesn't distinguish from alternatives.
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 no guidance on when to use this tool versus alternatives. There are multiple sibling tools that might overlap (e.g., 'get_store_stats', 'get_category_performance'), but the description doesn't mention any context, prerequisites, or exclusions. This leaves the agent guessing about appropriate use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
店舗の統計情報を取得します。
| Name | Required | Description | Default |
|---|---|---|---|
| store_id | No | 店舗ID（省略時は全店舗） |
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 only states the action ('取得します' - get) without detailing what '統計情報' (statistics) includes, whether it's read-only, requires permissions, has rate limits, or what the output format might be. This leaves significant gaps in understanding 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence in Japanese that directly states the tool's purpose without any unnecessary words. It's front-loaded and appropriately sized for its content, making it 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 complexity of a statistical tool with no annotations and no output schema, the description is incomplete. It doesn't specify what statistics are returned, their format, or any behavioral traits like data freshness or aggregation methods. This makes it inadequate for an agent to fully understand how to use the tool effectively.
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 100% description coverage, with the parameter 'store_id' well-documented in the schema itself (including type, enum values, and a note that omitting it returns all stores). The description adds no additional parameter information, but with high schema coverage and only one optional parameter, the baseline is appropriately high as the schema handles the semantics effectively.
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 '店舗の統計情報を取得します' (Get store statistics) states a clear verb ('取得します' - get) and resource ('店舗の統計情報' - store statistics), providing a basic purpose. However, it doesn't differentiate from sibling tools like 'get_revenue_summary' or 'get_category_performance' that might also provide statistical information, making it somewhat 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.
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, exclusions, or specific contexts for usage, leaving the agent with no explicit or implied direction on tool selection among the many sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
優良顧客ランキングを取得します。
| Name | Required | Description | Default |
|---|---|---|---|
| metric | No | ランキング基準 | spending |
| period | No | 集計期間 | all_time |
| limit | No | 取得件数 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It only states what the tool does ('get rankings') without mentioning any behavioral traits such as whether it's read-only (likely, but not confirmed), performance characteristics, authentication needs, rate limits, or what the output format looks like. For a tool with no annotation coverage, this leaves significant gaps in understanding how it behaves.
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 a single, efficient sentence in Japanese that directly states the tool's purpose without unnecessary words. It's appropriately sized for a simple retrieval tool, though it could be more front-loaded with key details if expanded. There's no wasted verbiage, making it 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 complexity (3 parameters, no output schema, no annotations), the description is incomplete. It doesn't explain what the output looks like (e.g., list of customers with scores), how rankings are calculated, or behavioral aspects like safety and performance. Without annotations or output schema, the description should provide more context to compensate, but it falls short, leaving the agent with insufficient information for optimal 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 100%, with clear descriptions for all parameters (metric, period, limit) including enums and defaults. The description adds no additional meaning beyond what the schema provides—it doesn't explain parameter interactions, ranking algorithms, or edge cases. With high schema coverage, the baseline score of 3 is appropriate as the 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 '優良顧客ランキングを取得します' (Get top customer rankings) states a clear verb ('取得します' - get) and resource ('優良顧客ランキング' - top customer rankings), but it's somewhat vague about what constitutes 'top' and doesn't distinguish from sibling tools like get_customer_activity, get_customer_details, or get_customer_segments. It provides basic purpose but lacks specificity about ranking criteria beyond what the schema reveals.
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 no guidance on when to use this tool versus alternatives. With siblings like get_customer_activity (activity tracking), get_customer_details (individual details), and get_customer_segments (segmentation), there's no indication that this tool is specifically for ranking customers by metrics like rentals or spending over time periods. Usage is implied only through the tool name and description, not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
低稼働作品一覧を取得します。長期間レンタルされていない作品を特定できます。
| Name | Required | Description | Default |
|---|---|---|---|
| days_not_rented | No | N日以上レンタルなし（デフォルト: 30） | |
| store_id | No | 店舗ID |
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 states the tool retrieves a list and identifies films not rented for a long time, but doesn't disclose behavioral traits such as whether it's read-only, if it requires specific permissions, rate limits, or what the output format looks like. For a tool with no annotation coverage, this leaves significant gaps in understanding its 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 concise and front-loaded, consisting of two sentences that directly state the purpose and key functionality. There is no wasted language, and it efficiently communicates the core intent without unnecessary 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 moderate complexity (2 parameters, no output schema, no annotations), the description is minimally adequate. It covers the purpose but lacks details on usage guidelines, behavioral transparency, and output expectations. With no output schema, the description should ideally hint at return values, but it doesn't, leaving room for improvement.
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 100% description coverage, with clear documentation for both parameters (days_not_rented and store_id). The description adds no additional parameter semantics beyond what's in the schema, such as explaining the impact of the days_not_rented threshold or store_id selection. Baseline 3 is appropriate as the 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: '低稼働作品一覧を取得します' (get a list of underperforming films) and specifies the criteria: '長期間レンタルされていない作品を特定できます' (identify films not rented for a long period). This is a specific verb+resource combination, though it doesn't explicitly differentiate from siblings like 'get_popular_films' or 'get_inventory_turnover' beyond the underperforming focus.
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 no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'get_popular_films' for contrast, prerequisites for use, or scenarios where it's most applicable. The user must infer usage from the purpose alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
利用可能な映画カテゴリの一覧を取得します。
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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 retrieves a list, implying a read-only operation, but doesn't address potential behaviors like pagination, rate limits, authentication needs, or error handling. For a tool with zero annotation coverage, this is a significant gap in 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 a single, clear sentence in Japanese that directly states the tool's function without any fluff. It's appropriately sized and front-loaded, making it efficient and easy to parse.
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 (0 parameters, no output schema, no annotations), the description is adequate but minimal. It covers the basic purpose but lacks details on usage context, behavioral traits, or output format, which could be helpful for an agent despite the low 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?
The tool has 0 parameters, and the input schema has 100% description coverage (though empty). The description doesn't need to add parameter details, so it meets the baseline for this case. It implies no filtering or inputs are required, which aligns with the 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: '利用可能な映画カテゴリの一覧を取得します' (Get a list of available movie categories). It specifies the verb (取得します/get) and resource (映画カテゴリ/movie categories). However, it doesn't explicitly differentiate from siblings like 'get_category_performance' or 'search_films', which prevents 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 no guidance on when to use this tool versus alternatives. It doesn't mention when to choose it over sibling tools like 'get_category_performance' or 'search_films', nor does it specify any prerequisites or exclusions. This leaves the agent with minimal contextual direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
顧客を検索します。名前、メール、店舗で絞り込みできます。
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | 顧客名（部分一致） | |
| No | メールアドレス（部分一致） | ||
| store_id | No | 店舗ID | |
| active_only | No | アクティブ顧客のみ | |
| limit | No | 取得件数 |
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 searches customers with filtering, but lacks details on permissions, rate limits, pagination, or response format. For a search tool with 5 parameters and no output schema, this leaves significant gaps in understanding how the tool behaves operationally.
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 and front-loaded, stating the core purpose in the first phrase. It uses only two sentences with no wasted words, making it efficient. A score of 5 is reserved for exceptional cases with perfect structure, but this is very good.
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 (5 parameters, no annotations, no output schema), the description is insufficient. It doesn't explain return values, error handling, or behavioral constraints. For a search tool that likely returns lists of customers, more context is needed to guide effective use, especially with sibling tools that might overlap in functionality.
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 mentions filtering by name, email, and store, which aligns with three of the five parameters. However, schema description coverage is 100%, meaning the schema already documents all parameters thoroughly. The description adds minimal value beyond the schema, so it meets the baseline score of 3 for high schema 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 tool's purpose as 'search customers' (顧客を検索します) and mentions filtering capabilities by name, email, and store. It's specific about the verb (search) and resource (customers), but doesn't explicitly distinguish it from sibling tools like get_customer_details or get_customer_activity, which is why it doesn't reach a score of 5.
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 no guidance on when to use this tool versus alternatives. It mentions filtering capabilities but doesn't specify scenarios, prerequisites, or exclusions. For example, it doesn't clarify if this is for broad searches versus specific lookups, or how it differs from get_customer_details for individual customer queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
映画を検索します。タイトル、カテゴリ、レーティング、俳優名などで絞り込みできます。
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | 映画タイトル（部分一致） | |
| category | No | カテゴリ名 | |
| rating | No | レーティング | |
| actor_name | No | 出演俳優名（部分一致） | |
| release_year | No | 公開年 | |
| limit | 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 mentions filtering capabilities but doesn't disclose important behavioral traits: whether results are paginated, what format they return, if there are rate limits, authentication requirements, or performance characteristics. For a search tool with 6 parameters and no annotations, this leaves significant gaps in understanding how it behaves.
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 concise - just two sentences that directly state the tool's purpose and filtering capabilities. It's front-loaded with the main function. There's no wasted text, though it could potentially benefit from slightly more structure or bullet points for the filter list.
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 search tool with 6 parameters, no annotations, and no output schema, the description is insufficient. It doesn't explain what the search returns (film objects? just titles?), how results are ordered, whether there's pagination, or any error conditions. The combination of missing behavioral context and lack of output information creates significant gaps for an agent trying to use this tool effectively.
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%, so the schema already documents all 6 parameters thoroughly. The description lists the same filter fields (title, category, rating, actor name) that appear in the schema, adding no additional semantic meaning beyond what's already in parameter descriptions. This meets the baseline for high schema 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 tool's purpose: 'search films' with filtering by title, category, rating, actor name, etc. It specifies the verb ('search') and resource ('films'), but doesn't explicitly differentiate from sibling tools like 'search_customers' or 'get_popular_films' which might have overlapping functionality. The purpose is clear but lacks sibling differentiation.
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 no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'get_film_details' for single films or 'get_popular_films' for curated lists. There's no context about prerequisites, limitations, or when this search is preferred over other film-related tools.
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.0check_film_availabilityget_actor_filmographyget_category_performanceget_customer_activityget_customer_detailsget_customer_rentalsget_customer_segmentsget_film_detailsget_inventory_turnoverget_overdue_rentalsget_popular_filmsget_revenue_summaryget_store_statsget_top_customersget_underperforming_filmslist_categoriessearch_customerssearch_filmsEach tool has a clearly distinct purpose targeting specific resources and actions, such as checking film availability, getting actor filmography, analyzing category performance, or retrieving customer details. There is no overlap or ambiguity between tools; for example, 'get_customer_details' and 'get_customer_rentals' serve different functions without confusion.
All tool names follow a consistent verb_noun pattern, primarily using 'get_' or 'search_' prefixes followed by descriptive nouns, with minor variations like 'check_' and 'list_' that still maintain readability. There are no deviations in style, such as mixing camelCase or snake_case, ensuring predictability across the set.
With 18 tools, the count is slightly high but reasonable for a Sakila database server covering films, customers, rentals, and analytics. It includes essential operations like search, retrieval, and analysis, though it might benefit from consolidation in areas like analytics to reduce potential complexity.
The tool set provides comprehensive coverage for the Sakila domain, including CRUD-like operations (e.g., search and get details for films and customers), rental management (e.g., overdue rentals), and advanced analytics (e.g., performance, segments, turnover). There are no obvious gaps; agents can handle full workflows from browsing to analysis without dead ends.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Ask questions in plain language, get answers from your business database. No SQL required.
Ask business questions in plain English. Get instant answers from your database, no SQL needed.
Ask data questions in natural language. Get SQL, insights, and charts from your databases.
GibsonAI MCP server: manage your databases with natural language
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Mo3g4u/mcp-server-sample'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
