Skip to main content
Glama

查飞书用户

feishu_user_lookup
Read-only

Looks up Feishu users by email, mobile number, or open_id, returning open_id and name so you can identify a colleague or get the target needed to message or mention them.

Instructions

用邮箱、手机号或 open_id 查飞书用户,返回 open_id 与名字。使用场景:手上只有同事邮箱/手机号,需要 open_id 才能私聊或 @ 他;或者拿到 open_id 后想确认这人是谁。用法优先级:给了 open_id 就查这一个人的详情(名字、邮箱、手机号最全);否则按 emails / mobiles 批量查(两个都给会各查一次);都不给会直接报错说明用法。重要:查到记录但 open_id 为空,说明该邮箱/手机号不在本企业通讯录(或不在应用可见范围内),这不是 bug,也不能拿它当发送目标。拿到 open_id 后可以直接作为 feishu_send_text 的 target 单聊这个人。前置条件:应用需要通讯录权限(如 contact:user.id:readonly),且用户在应用可见范围内。只读。

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "feishu_user_lookup"
  }
}

Input Schema

NameRequiredDescriptionDefault
emailsNo要查的邮箱列表(批量),例如 ["a@b.com"]。
mobilesNo要查的手机号列表(批量),带不带 +86 都试一下。
open_idNo已知 open_id(ou_ 开头)时直接查单个用户详情,优先级最高,给了就不走批量查询。

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.1

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already declare readOnlyHint and openWorldHint, and the description still adds real behavioral context: a record with an empty open_id means the user is outside the tenant directory or app visibility scope and must not be used as a send target, plus the required contact:user.id:readonly scope. It stops short of describing result ordering or how partial batch failures are surfaced, which keeps it off a 5.

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?

It is front-loaded with purpose, then scenarios, then the priority rule, then the failure caveat and prerequisites — a sensible order with no filler sentences. It runs long for a 3-parameter tool, and the precedence rule is stated twice (in 用法优先级 and again in the schema's open_id description), which is the only real redundancy.

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

Completeness5/5

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

For a read-only lookup with no output schema and full schema coverage, everything an agent needs is present: call precedence, the empty-open_id interpretation, permission prerequisites, and how to chain into feishu_send_text. Nothing material is left to inference.

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?

Schema coverage is 100%, so the per-parameter text already carries the basics and 3 would be the baseline. The description still adds genuine semantics the schema does not: open_id takes precedence over the batch arrays, and supplying both emails and mobiles results in two separate lookups rather than one merged query.

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

Purpose5/5

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

The opening sentence names a specific verb (查/查飞书用户) and enumerates the exact input keys (邮箱、手机号、open_id) plus what is returned (open_id 与名字). It is immediately distinguishable from siblings like feishu_members or feishu_chats because it is keyed on personal identifiers rather than chat/doc IDs.

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

Usage Guidelines5/5

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

Gives explicit scenarios (only have a colleague's email/phone and need open_id to DM or @ them; or have an open_id and want to confirm identity) and an explicit priority rule: open_id first for single-user detail, otherwise batch by emails/mobiles, otherwise an error. It also names the downstream tool (feishu_send_text) the result feeds into.

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