Skip to main content
Glama
enesjakozh
RayanZaki

MCP Google Contacts Server

by RayanZaki
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

📇 MCP Google 通讯录服务器

提供 Google 通讯录功能的机器对话协议 (MCP) 服务器，允许 AI 助手管理联系人、搜索您组织的目录以及与 Google Workspace 交互。

✨ 特点

  • 列出并搜索 Google 通讯录

  • 创建、更新和删除联系人

  • 搜索 Google Workspace 目录

  • 查看“其他联系人”（与您互动过但尚未添加的人）

  • 访问您单位中的 Google Workspace 用户

Related MCP server: MCP Google Contacts Server

🚀 安装

📋 先决条件

  • Python 3.12 或更高版本

  • 具有联系人访问权限的 Google 帐户

  • 启用 People API 的 Google Cloud 项目

  • 用于访问 Google API 的 OAuth 2.0 凭据

🧪 使用 uv（推荐）

  1. 如果尚未安装 uv，请安装它：

    pip install uv

  2. 克隆存储库：

    git clone https://github.com/rayanzaki/mcp-google-contacts-server.git
cd mcp-google-contacts-server

  3. 创建虚拟环境并安装依赖项：

    uv venv
source .venv/bin/activate
uv pip install -r requirements.txt

📦使用 pip

  1. 克隆存储库：

    git clone https://github.com/rayanzaki/mcp-google-contacts-server.git
cd mcp-google-contacts-server

  2. 安装依赖项：

    pip install -r requirements.txt

🔑 身份验证设置

服务器需要 Google API 凭据才能访问您的联系人。您有以下几种选择：

🔐 选项 1：使用 credentials.json 文件

  1. 创建 Google Cloud 项目并启用 People API

  2. 创建 OAuth 2.0 凭据（桌面应用程序类型）

  3. 下载 credentials.json 文件

  4. 将其放置在以下位置之一：

    • 本项目的根目录

    • 您的主目录（~/google-contacts-credentials.json）

    • 使用--credentials-file参数指定其位置

🔐 选项 2：使用环境变量

设置以下环境变量：

  • GOOGLE_CLIENT_ID ：您的 Google OAuth 客户端 ID

  • GOOGLE_CLIENT_SECRET ：您的 Google OAuth 客户端密钥

  • GOOGLE_REFRESH_TOKEN ：您帐户的有效刷新令牌

🛠️ 使用方法

🏃‍♂️ 基本启动

python src/main.py
# or
uv run src/main.py

这将使用默认的 stdio 传输启动服务器。

⚙️ 命令行参数

争论

描述

默认值

--transport

要使用的传输协议（ stdio或http ）

stdio

--host

HTTP 传输的主机

localhost

--port

HTTP 传输端口

8000

--client-id

Google OAuth 客户端 ID（覆盖环境变量）

-

--client-secret

Google OAuth 客户端密钥（覆盖环境变量）

-

--refresh-token

Google OAuth 刷新令牌（覆盖环境变量）

-

--credentials-file

Google OAuth credentials.json 文件的路径

-

📝 示例

从 HTTP 传输开始：

python src/main.py --transport http --port 8080

使用特定的凭证文件：

python src/main.py --credentials-file /path/to/your/credentials.json

直接提供凭证：

python src/main.py --client-id YOUR_CLIENT_ID --client-secret YOUR CLIENT_SECRET --refresh-token YOUR_REFRESH_TOKEN

🔌 与 MCP 客户端集成

要将此服务器与 MCP 客户端（如 Anthropic 的 Claude 和 Cline）一起使用，请将其添加到您的 MCP 配置中：

{
  "mcpServers": {
    "google-contacts-server": {
      "command": "uv",
      "args": [
         "--directory",
         "/path/to/mcp-google-contacts-server",
         "run",
        "main.py"
      ],
      "disabled": false,
      "autoApprove": []
    }
  }
}

🧰 可用工具

该 MCP 服务器提供以下工具：

工具

描述

list_contacts

列出所有联系人或按姓名过滤

get_contact

通过资源名称或电子邮件获取联系人

create_contact

创建新联系人

update_contact

更新现有联系人

delete_contact

按资源名称删除联系人

search_contacts

按姓名、电子邮件或电话号码搜索联系人

list_workspace_users

列出您组织目录中的 Google Workspace 用户

search_directory

在 Google Workspace 目录中搜索人员

get_other_contacts

从“其他联系人”部分检索联系人

🔍 详细工具描述

📋 list_contacts

列出您的所有 Google 联系人或按姓名过滤。

参数：

  • name_filter （可选）：按名称过滤联系人的字符串

  • max_results （可选）：返回的最大联系人数量（默认值：100）

例子：

list_contacts(name_filter="John", max_results=10)

👤 get_contact

检索有关特定联系人的详细信息。

参数：

  • identifier ：资源名称（people/*）或联系人的电子邮件地址

例子：

get_contact("john.doe@example.com")
# or
get_contact("people/c12345678901234567")

➕ create_contact

在您的 Google 通讯录中创建新联系人。

参数：

  • given_name ：联系人的名字

  • family_name （可选）：联系人的姓氏

  • email （可选）：联系人的电子邮件地址

  • phone （可选）：联系人的电话号码

例子：

create_contact(given_name="Jane", family_name="Smith", email="jane.smith@example.com", phone="+1-555-123-4567")

✏️ update_contact

使用新信息更新现有联系人。

参数：

  • resource_name ：联系资源名称（people/*）

  • given_name （可选）：更新后的名字

  • family_name （可选）：更新后的姓氏

  • email （可选）：更新后的电子邮件地址

  • phone （可选）：更新后的电话号码

例子：

update_contact(resource_name="people/c12345678901234567", email="new.email@example.com")

🗑️ delete_contact

从您的 Google 通讯录中删除联系人。

参数：

  • resource_name ：要删除的联系人资源名称 (people/*)

例子：

delete_contact(resource_name="people/c12345678901234567")

🔍 search_contacts

按姓名、电子邮件或电话号码搜索您的联系人。

参数：

  • query ：在联系人中查找的搜索词

  • max_results （可选）：返回的最大结果数（默认值：10）

例子：

search_contacts(query="john", max_results=5)

🏢 list_workspace_users

列出您组织目录中的 Google Workspace 用户。

参数：

  • query （可选）：用于查找特定用户的搜索词

  • max_results （可选）：返回的最大结果数（默认值：50）

例子：

list_workspace_users(query="engineering", max_results=25)

🔭 search_directory

对您组织的 Google Workspace 目录执行有针对性的搜索。

参数：

  • query ：搜索词以查找特定目录成员

  • max_results （可选）：返回的最大结果数（默认值：20）

例子：

search_directory(query="product manager", max_results=10)

👥 get_other_contacts

从“其他联系人”部分检索联系人 - 与您互动但尚未添加到联系人中的人。

参数：

  • max_results （可选）：返回的最大结果数（默认值：50）

例子：

get_other_contacts(max_results=30)

🔒 权限

首次运行服务器时，您需要通过 Google 进行身份验证并授予访问联系人所需的权限。身份验证流程将引导您完成此过程。

❓ 故障排除

  • 🔐 身份验证问题：确保您的凭据有效并具有必要的范围

  • ⚠️ API 限制：请注意 Google People API 配额限制

  • 📝 日志：检查控制台输出中的错误消息和调试信息

👥 贡献

欢迎贡献代码！欢迎提交 Pull 请求。

📄 许可证

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。

Available Tools

9 tools
create_contactB

Create a new contact.

    Args:
        given_name: First name of the contact
        family_name: Last name of the contact
        email: Email address of the contact
        phone: Phone number of the contact
ParametersJSON Schema
NameRequiredDescriptionDefault
given_nameYes
family_nameNo
emailNo
phoneNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.1/5.0
Behavior2/5

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

With no annotations provided, the description carries full burden for behavioral disclosure. While 'Create' implies a write operation, the description doesn't address permissions needed, whether duplicates are allowed, what happens on failure, or what the output contains. This leaves significant behavioral questions unanswered.

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 appropriately concise with a clear purpose statement followed by parameter documentation. The Args section is well-structured and easy to parse. Minor formatting issues with indentation slightly detract from perfect structure.

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 this is a write operation with no annotations and 4 parameters, the description provides adequate parameter semantics but lacks behavioral context. The presence of an output schema means the description doesn't need to explain return values, but it should address more about the creation operation's behavior and constraints.

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 provides clear parameter documentation in the Args section, explaining what each parameter represents. With 0% schema description coverage, this documentation fully compensates by adding essential semantic meaning beyond the bare schema. Only minor formatting issues prevent a perfect score.

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 verb ('Create') and resource ('contact'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'update_contact' or specify what makes this creation operation unique versus alternatives.

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 like 'update_contact' or 'search_contacts'. There's no mention of prerequisites, constraints, or typical use cases for creating versus other contact operations.

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

delete_contactC

Delete a contact by resource name.

    Args:
        resource_name: Contact resource name (people/*) to delete
ParametersJSON Schema
NameRequiredDescriptionDefault
resource_nameYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.9/5.0
Behavior2/5

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

With no annotations provided, the description carries full burden but only states the action ('Delete') without disclosing critical behavioral traits such as whether deletion is permanent, requires specific permissions, has side effects, or what happens on success/failure. This is inadequate for a destructive operation.

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 appropriately sized with two sentences: one for the purpose and one for the parameter. It's front-loaded with the main action, though the parameter section could be more integrated. No wasted words.

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?

For a destructive tool with no annotations, 0% schema coverage, and an output schema (which helps but isn't described), the description is incomplete. It lacks behavioral context, error handling, and usage guidance, making it insufficient for safe agent invocation.

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

Parameters3/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. It adds the parameter name and clarifies it's a 'Contact resource name (people/*)', providing basic semantics beyond the schema's title. However, it doesn't explain format details or validation rules, leaving gaps.

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 verb ('Delete') and resource ('a contact'), making the purpose unambiguous. However, it doesn't differentiate from sibling tools like 'update_contact' or 'create_contact' beyond the obvious action difference, missing explicit sibling distinction.

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 like 'update_contact' or 'create_contact', nor any context about prerequisites or exclusions. The description only states what it does, not when it's appropriate.

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

get_contactB

Get a contact by resource name or email.

    Args:
        identifier: Resource name (people/*) or email address of the contact
ParametersJSON Schema
NameRequiredDescriptionDefault
identifierYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.1/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 retrieves a contact but doesn't describe what happens if the contact isn't found (e.g., error handling), authentication needs, rate limits, or the format of the output. For a read operation with zero annotation coverage, 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.

Conciseness4/5

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

The description is appropriately sized and front-loaded, with the core purpose stated clearly in the first sentence. The additional parameter explanation is concise and directly relevant. There's no wasted text, though the structure could be slightly improved by integrating the parameter details more seamlessly.

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 (single parameter, read operation) and the presence of an output schema, the description is somewhat complete but has gaps. It covers the basic purpose and parameter semantics adequately, but without annotations, it lacks behavioral details like error handling. The output schema likely explains return values, reducing the burden on the description.

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 meaningful context beyond the input schema, which has 0% description coverage. It explains that the 'identifier' parameter can be either a resource name (people/*) or an email address, clarifying the two valid input types. This compensates well for the schema's lack of detail, though it doesn't specify format constraints or examples.

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 tool's purpose: 'Get a contact by resource name or email.' It specifies the verb ('Get') and resource ('contact'), and distinguishes it from siblings like list_contacts or search_contacts by focusing on retrieving a single contact. However, it doesn't explicitly differentiate from get_other_contacts, which might have overlapping functionality.

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 list_contacts, search_contacts, and get_other_contacts, there's no indication of when this specific retrieval method is preferred, such as for known identifiers versus broader searches. It lacks context on prerequisites or exclusions.

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

get_other_contactsB

Retrieve contacts from the 'Other contacts' section.

    Other contacts are people you've interacted with but haven't added to your contacts list.
    These often include email correspondents that aren't in your main contacts.
    
    Args:
        max_results: Maximum number of results to return (default: 50)
ParametersJSON Schema
NameRequiredDescriptionDefault
max_resultsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.3/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. It states this is a retrieval operation, implying read-only behavior, but doesn't disclose other behavioral traits such as authentication requirements, rate limits, pagination, error handling, or what the output contains. The description adds minimal 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.

Conciseness4/5

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

The description is appropriately sized with three sentences: the first states the purpose, the second explains 'Other contacts', and the third documents the parameter. It's front-loaded with the main action, and each sentence adds value without redundancy. Minor improvements could include more structured formatting.

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 one parameter and an output schema exists, the description covers the basics but lacks depth. It explains what 'Other contacts' are and documents the parameter, but without annotations, it misses behavioral context like safety or performance traits. The output schema likely handles return values, so completeness is adequate but not thorough.

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?

With 0% schema description coverage, the description compensates by documenting the single parameter 'max_results' with its default value and purpose. This adds meaningful semantics beyond the schema, which only provides the title and type. However, it doesn't specify constraints like minimum/maximum values or format details.

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 verb 'retrieve' and the resource 'contacts from the Other contacts section', with additional context explaining what 'Other contacts' are. However, it doesn't explicitly differentiate from sibling tools like list_contacts or search_contacts, which likely retrieve different contact sets.

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

Usage Guidelines3/5

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

The description implies usage by explaining that 'Other contacts' are people interacted with but not in the main contacts list, suggesting this tool is for retrieving that specific subset. However, it doesn't provide explicit guidance on when to use this versus alternatives like list_contacts or search_contacts, nor does it mention any prerequisites or exclusions.

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

list_contactsB

List all contacts or filter by name.

    Args:
        name_filter: Optional filter to find contacts by name
        max_results: Maximum number of results to return (default: 100)
ParametersJSON Schema
NameRequiredDescriptionDefault
name_filterNo
max_resultsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.1/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 full burden for behavioral disclosure. It mentions filtering and pagination (via max_results), but doesn't cover important aspects like whether this requires authentication, rate limits, sorting behavior, error conditions, or what happens when no matches are found. For a listing 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.

Conciseness4/5

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

The description is appropriately concise with a clear purpose statement followed by parameter explanations. The two-sentence structure is efficient, though the formatting with extra whitespace could be cleaner. Every sentence adds value without redundancy.

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 handles return values), 2 parameters with good description coverage, and no complex annotations, the description is reasonably complete for a basic listing tool. However, it lacks guidance on sibling tool differentiation and some behavioral context that would be helpful for an agent making informed decisions.

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?

With 0% schema description coverage, the description fully compensates by explaining both parameters: 'name_filter' as an optional filter for contacts by name, and 'max_results' as the maximum number of results with its default value. This adds meaningful context beyond the bare schema, though it doesn't specify exact matching behavior (exact vs. partial, case sensitivity).

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 tool's purpose: 'List all contacts or filter by name.' This specifies the verb ('List') and resource ('contacts') with optional filtering. However, it doesn't explicitly differentiate from sibling tools like 'search_contacts' or 'get_other_contacts,' which likely have overlapping functionality.

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 'search_contacts' and 'get_other_contacts' available, there's no indication of when this listing/filtering approach is preferred over those other methods. The description only states what the tool does, not when to choose it.

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

list_workspace_usersB

List Google Workspace users in your organization's directory.

    This tool allows you to search and list users in your Google Workspace directory,
    including their email addresses and other information.
    
    Args:
        query: Optional search term to find specific users (name, email, etc.)
        max_results: Maximum number of results to return (default: 50)
ParametersJSON Schema
NameRequiredDescriptionDefault
queryNo
max_resultsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.1/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. While it mentions the tool 'allows you to search and list users' and describes parameters, it doesn't cover important behavioral aspects like authentication requirements, rate limits, pagination behavior, error conditions, or what specific user information beyond email addresses is returned. For a directory listing tool with zero annotation coverage, this leaves significant gaps in understanding how the tool behaves.

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 appropriately sized and well-structured with clear sections. The purpose is stated upfront, followed by additional context, then parameter explanations. While slightly verbose with some redundancy ('list' appears twice in the opening), each sentence adds value and there's no wasted text. The parameter documentation is neatly formatted.

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 that an output schema exists (so return values are documented elsewhere), the description covers the basic purpose and parameters adequately. However, for a directory listing tool with no annotations and multiple sibling tools, it should provide more context about when to use it versus alternatives and more behavioral transparency about how it operates. The parameter explanations help compensate for the 0% schema coverage.

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?

With 0% schema description coverage, the description compensates well by explaining both parameters: 'query' is described as 'Optional search term to find specific users (name, email, etc.)' and 'max_results' as 'Maximum number of results to return (default: 50)'. This adds meaningful context beyond the bare schema, clarifying the query scope and default value. However, it doesn't specify format constraints or validation rules.

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 tool's purpose: 'List Google Workspace users in your organization's directory' with the verb 'list' and resource 'Google Workspace users'. It specifies the scope ('your organization's directory') and mentions what information is included ('email addresses and other information'). However, it doesn't explicitly differentiate from sibling tools like 'search_directory' or 'list_contacts', which appear to be related directory/search tools.

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 like 'search_directory', 'list_contacts', and 'search_contacts' available, there's no indication of when this specific workspace user listing tool is appropriate versus those other directory/contact tools. The description only states what the tool does, not when to choose it.

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

search_contactsB

Search contacts by name, email, or phone number.

    Args:
        query: Search term to find in contacts
        max_results: Maximum number of results to return (default: 10)
ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
max_resultsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.2/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 searches contacts but doesn't mention important behavioral aspects like whether it's read-only, requires authentication, has rate limits, returns paginated results, or what happens on errors. For a search tool with zero annotation coverage, this leaves significant gaps.

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 appropriately sized and front-loaded with the core purpose in the first sentence. The parameter explanations are brief and directly relevant. There's no wasted text, and the structure is clear and efficient.

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 that there's an output schema (which handles return values), the description covers the basic purpose and parameters adequately. However, for a search tool with no annotations and multiple sibling tools, it lacks context about behavioral traits and usage differentiation, making it only minimally complete.

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 meaningful context beyond the input schema. While schema description coverage is 0%, the description explains that 'query' searches 'by name, email, or phone number' and that 'max_results' has a default of 10. This compensates well for the lack of schema descriptions, though it doesn't cover all possible parameter nuances.

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 tool's purpose: 'Search contacts by name, email, or phone number.' This specifies the verb (search), resource (contacts), and searchable fields. However, it doesn't explicitly differentiate from sibling tools like 'list_contacts' or 'search_directory', which would be needed for 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.

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 like 'list_contacts', 'get_contact', or 'search_directory'. It mentions what the tool does but gives no context about appropriate use cases, prerequisites, or exclusions.

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

search_directoryB

Search for people specifically in the Google Workspace directory.

    This performs a more targeted search of your organization's directory.
    
    Args:
        query: Search term to find specific directory members
        max_results: Maximum number of results to return (default: 20)
ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
max_resultsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.3/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 mentions 'more targeted search' which hints at specificity, but doesn't describe important behaviors like authentication requirements, rate limits, pagination, error handling, or what constitutes a 'targeted' search. For a search tool with zero annotation coverage, this leaves significant gaps in understanding how it operates.

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 well-structured and appropriately sized. It starts with the core purpose, adds context about the search type, and then provides parameter details in a clear format. Every sentence adds value, though the 'more targeted search' phrase could be more specific to earn a perfect score.

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 that there's an output schema (which handles return values) and only 2 parameters with good description coverage, the description is reasonably complete for a search tool. However, the lack of annotations means important behavioral aspects like authentication, rate limits, and error handling aren't addressed, and the relationship to sibling tools isn't clarified, leaving some contextual gaps.

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 meaningful context for both parameters beyond what the schema provides. It explains that 'query' is a 'Search term to find specific directory members' and 'max_results' has a 'default: 20', which clarifies their purpose and usage. Since schema description coverage is 0%, the description effectively compensates by providing this essential parameter information.

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 tool's purpose: 'Search for people specifically in the Google Workspace directory.' It specifies the verb ('search'), resource ('people'), and scope ('Google Workspace directory'), making it easy to understand what the tool does. However, it doesn't explicitly differentiate from sibling tools like 'search_contacts' or 'list_workspace_users', 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.

Usage Guidelines3/5

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

The description provides some implied usage context by mentioning 'more targeted search' and specifying the directory scope, which suggests it's for organizational directory searches rather than general contacts. However, it lacks explicit guidance on when to use this tool versus alternatives like 'search_contacts' or 'list_workspace_users', and doesn't mention any prerequisites or exclusions.

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

update_contactC

Update an existing contact.

    Args:
        resource_name: Contact resource name (people/*)
        given_name: Updated first name
        family_name: Updated last name
        email: Updated email address
        phone: Updated phone number
ParametersJSON Schema
NameRequiredDescriptionDefault
resource_nameYes
given_nameNo
family_nameNo
emailNo
phoneNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.9/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 this is an update operation, implying mutation, but doesn't mention permissions, reversibility, error handling, or rate limits. The description adds minimal behavioral context beyond the basic action, which is insufficient for a mutation tool without annotations.

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 front-loaded with the core purpose in the first sentence, followed by a structured parameter list. It avoids unnecessary fluff, though the parameter explanations are minimal and could be more informative without sacrificing brevity.

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 complexity (mutation with 5 parameters), no annotations, and an output schema (which reduces the need to describe return values), the description is partially complete. It covers the basic action and parameters but lacks critical context like usage guidelines, behavioral details, and parameter nuances, making it adequate but with clear gaps.

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

Parameters3/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. It lists all 5 parameters with brief explanations (e.g., 'Updated first name'), adding some meaning beyond the schema's titles. However, it doesn't clarify format expectations (e.g., email validation) or the implications of null values, leaving gaps in parameter understanding.

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 verb ('Update') and resource ('an existing contact'), making the purpose immediately understandable. However, it doesn't differentiate this tool from its siblings like 'create_contact' or 'delete_contact' beyond the basic action, missing explicit comparison that would warrant 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.

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 like 'create_contact' or 'delete_contact'. It lacks context about prerequisites (e.g., needing an existing contact resource) or exclusions, leaving the agent to 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.

Tool Schema Changelog

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

  1. 9 tool updates
    • First observedcreate_contact
    • First observeddelete_contact
    • First observedget_contact
    • First observedget_other_contacts
    • First observedlist_contacts
    • First observedlist_workspace_users
    • First observedsearch_contacts
    • First observedsearch_directory
    • First observedupdate_contact
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

A3.5/5.0

Scored across 9 tools

Disambiguation4/5

Most tools have distinct purposes, but there is some potential confusion between list_contacts, search_contacts, and search_directory. The descriptions clarify that search_directory targets Google Workspace directory specifically, while search_contacts is broader, but an agent might initially struggle to choose between them for certain queries. The other tools (create, delete, get, update, get_other_contacts, list_workspace_users) are clearly differentiated.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern with snake_case (e.g., create_contact, list_contacts, search_directory). The naming is predictable and readable throughout, with no deviations in style or convention.

Tool Count5/5

With 9 tools, this server is well-scoped for managing Google Contacts. It covers core CRUD operations (create, get, update, delete), listing and searching contacts, and includes specialized tools for other contacts and workspace users, which is appropriate for the domain without being overwhelming.

Completeness5/5

The tool surface provides complete coverage for the Google Contacts domain. It includes all essential CRUD operations (create, get, update, delete), multiple ways to retrieve contacts (list, search, get_other_contacts), and extends to workspace directory functionality. There are no obvious gaps that would hinder agent workflows.

Maintenance

ActivityInactive
ResponsivenessUnresponsive

Resources

Related MCP Connectors

Related MCP Servers

Appeared in Searches