Click on "Deploy 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., "@ZenTao MCP Server show me my active bugs assigned to me"
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.
一个基于 MCP 的 ZenTao RESTful API v1 适配器，自动处理 token，提供通用调用工具和资源索引。
Token 自动获取/缓存：自动登录获取 Token，支持强制刷新，所有请求自动带 Token 头。
通用调用：直接调用禅道 RESTful v1 任意接口（GET/POST/PUT/DELETE/PATCH）。
项目与产品：列出与当前账号相关的项目；按关键字搜索产品。
缺陷处理：
查询分配给我的缺陷（支持按产品、关键字、状态过滤，获取下一个待处理项）。
查看缺陷详情（附带步骤中的图片链接提取）。
统计缺陷数量（总数/活跃）。
将缺陷标记为已解决（resolve，默认 resolution=fixed）。
资源索引：zentao://endpoints（接口概览）、zentao://config（环境配置检查）、zentao://projects（我的项目）。
Related MCP server: ZenTao MCP Server
# 全局安装
npm install -g @makun111/zentao-mcp-server安装后由 MCP 客户端通过 API/stdio 调用，无需手动启动。
git clone git@github.com:Immmmmmortal1/zantao.git
cd zantao
npm install用于本地开发/调试。如需环境文件，可将
.env.example复制为.env并填写参数。需要手动验证时可运行npm start。
ZENTAO_BASE_URL：禅道服务地址，形如 https://xxx.com
ZENTAO_ACCOUNT：登录账号
ZENTAO_PASSWORD：登录密码
ZENTAO_TOKEN：可选，已有 token；如果未提供会自动通过 /tokens 获取
在 zsh 中配置环境变量示例：
echo 'export ZENTAO_BASE_URL="https://example.com/zentao/"' >> ~/.zshrc
echo 'export ZENTAO_ACCOUNT="你的账号"' >> ~/.zshrc
echo 'export ZENTAO_PASSWORD="你的密码"' >> ~/.zshrc
source ~/.zshrc在 MCP 客户端的配置文件中添加以下片段即可通过 npx 直接运行本服务：
# Zentao MCP server (stdio, npm)
[mcp_servers.zentao_server]
type = "stdio"
command = "npx"
args = ["-y", "@makun111/zentao-mcp-server"]get_token(forceRefresh?)：调用 POST /api.php/v1/tokens 获取 token，默认缓存。
call(path, method?, query?, body?, forceTokenRefresh?)：调用任意 RESTful 接口，自动注入 Token 头。path 可写 /projects 或 projects/1。
zentao://endpoints：RESTful v1 主要接口概览。
zentao://config：当前环境变量是否已设置（不包含敏感值）。
在任意支持 MCP 的客户端中调用对应工具：
获取 token：{ "tool": "get_token" }
列出部门：{ "tool": "call", "arguments": { "path": "/departments", "method": "GET" } }
创建项目：{ "tool": "call", "arguments": { "path": "/projects", "method": "POST", "body": { "name": "Demo Project", "code": "DEMO" } } }
查询分配给我的缺陷：{ "tool": "getMyBugs", "arguments": { "productId": 1, "status": "active" } }
Call any ZenTao RESTful API endpoint (api.php/v1). Automatically injects Token header. Paths accept leading slash or relative.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Relative path, e.g. /projects or projects/1 | |
| method | No | HTTP verb | GET |
| query | No | Query params object | |
| body | No | JSON body | |
| forceTokenRefresh | No | Refresh token before request |
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 adds useful context: automatic Token header injection, path format flexibility (leading slash or relative), and token refresh capability via the forceTokenRefresh parameter. However, it lacks details on error handling, rate limits, authentication requirements beyond token injection, or response formats, leaving gaps for a general-purpose API tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise and front-loaded, consisting of two sentences that efficiently convey the tool's core functionality and key features (API calling, token injection, path flexibility). Every sentence earns its place with no wasted words, making it easy to understand 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 the tool's complexity as a general-purpose API caller with 5 parameters, no annotations, and no output schema, the description is incomplete. It covers basic purpose and some behavioral traits but lacks details on error handling, response structure, or advanced usage scenarios. While concise, it does not fully compensate for the missing structured data, 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?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal value beyond the schema by implying path format flexibility and token refresh behavior, but it does not explain parameter interactions or provide additional semantic context. 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: 'Call any ZenTao RESTful API endpoint (api.php/v1).' It specifies the verb ('Call'), resource ('ZenTao RESTful API endpoint'), and scope ('any'), distinguishing it from sibling tools that perform specific operations like getBugDetail or markBugResolved. The mention of automatic Token header injection adds specificity.
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 clear context for usage by indicating it's for ZenTao RESTful API endpoints and handles token injection automatically. However, it does not explicitly state when to use this tool versus the more specific sibling tools (e.g., getBugDetail for bug details), nor does it mention exclusions or prerequisites. The guidance is implied but not comprehensive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get bug detail by ID; also extracts image URLs from steps HTML into stepsImages.
| Name | Required | Description | Default |
|---|---|---|---|
| bugId | Yes | Bug ID (required) |
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 extracting image URLs, which adds some context beyond a simple read operation, but fails to describe critical traits like whether it's read-only, requires authentication, handles errors, or returns structured data. For a tool with no annotation coverage, this leaves significant gaps in understanding its 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 highly concise and front-loaded, consisting of a single sentence that efficiently conveys the core functionality and an additional feature. Every word earns its place, with no redundant information, making it easy 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 the lack of annotations and output schema, the description is incomplete for a tool that performs data retrieval and processing. It doesn't explain what 'bug detail' includes, how image extraction works, or the format of the response. For a tool with no structured output documentation, more context is needed to understand its full behavior and results.
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 'bugId' clearly documented as a required number. The description adds no additional parameter details beyond implying the ID is used to fetch bug details. Since the schema does the heavy lifting, the baseline score of 3 is appropriate, as the description doesn't enhance parameter understanding but doesn't detract either.
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 bug detail by ID' specifies the verb (get) and resource (bug detail), and 'extracts image URLs from steps HTML into stepsImages' adds a specific processing feature. However, it doesn't explicitly differentiate from sibling tools like 'getMyBug' or 'getNextBug', which likely also retrieve bug details, preventing 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 prerequisites, such as needing a valid bug ID, or compare it to siblings like 'getMyBug' (which might filter by user) or 'getBugStats' (which might provide aggregated data). Without such context, users must infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get counts of bugs assigned to me under a product (total and active).
| Name | Required | Description | Default |
|---|---|---|---|
| productId | Yes | Product ID (required) | |
| activeOnly | No | If true, only active count is returned |
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 returns counts (total and active), which is useful, but lacks details on permissions (e.g., if it requires authentication), rate limits, error handling, or response format. For a tool with no annotations, this is a significant gap, earning a 2 as it provides basic output info but misses critical 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 that front-loads key information ('Get counts of bugs assigned to me under a product') and adds necessary detail ('total and active'). There is no wasted text, making it appropriately sized and well-structured for quick understanding, earning a 5 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 tool's moderate complexity (2 parameters, no output schema, no annotations), the description is minimally adequate. It covers the basic purpose and output types (counts), but lacks details on return values, error cases, or integration with siblings. Without annotations or output schema, more context on behavior would improve completeness, resulting in a 3 for being functional but incomplete.
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 documentation for both parameters (productId as required number, activeOnly as optional boolean with default). The description adds marginal value by implying the product context and active/total counts, but doesn't explain parameter interactions or semantics beyond what the schema provides. Baseline is 3 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 with a specific verb ('Get counts') and resource ('bugs assigned to me under a product'), including scope details ('total and active'). It distinguishes from siblings like getBugDetail (detailed info) or getMyBugs (list bugs), but doesn't explicitly name alternatives. This earns a 4 for clear purpose without explicit 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 implies usage context by specifying 'bugs assigned to me under a product,' suggesting it's for personal bug statistics in a product context. However, it doesn't provide explicit guidance on when to use this tool versus alternatives like getMyBugs (which might list bugs rather than count them) or markBugResolved (for updates). No exclusions or prerequisites are mentioned, resulting in a 3 for implied usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the first active bug assigned to me in a product (by productName). Returns full bug detail.
| Name | Required | Description | Default |
|---|---|---|---|
| productName | Yes | Product name to match (required) | |
| keyword | No | Keyword filter on bug title | |
| status | No | Status filter (e.g., active) | |
| allStatuses | No | Include non-active bugs |
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 that it returns 'full bug detail,' which adds some context about the output. However, it doesn't describe key behaviors such as what 'active' means (e.g., status definitions), how 'first' is determined (e.g., by creation date, priority), authentication requirements, error handling, or rate limits. For a read operation with no annotation coverage, this leaves significant gaps 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 concise and front-loaded, consisting of a single sentence that states the core purpose and output. It avoids unnecessary words and gets straight to the point. However, it could be slightly more structured by separating usage notes or behavioral details, but as is, it's efficient with minimal waste.
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 (4 parameters, no output schema, no annotations), the description is partially complete. It covers the basic purpose and output but lacks details on behavioral traits, parameter interactions, and comparison to siblings. Without annotations or output schema, more context on how the tool behaves and what it returns would improve completeness, 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.
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 4 parameters thoroughly. The description adds minimal value beyond the schema: it mentions 'productName' as required and implies filtering by 'active' status, but doesn't explain parameter interactions (e.g., how 'status' and 'allStatuses' relate) or provide additional semantics. With high schema coverage, the baseline is 3, and the description doesn't significantly enhance understanding.
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 the first active bug assigned to me in a product (by productName). Returns full bug detail.' It specifies the verb ('Get'), resource ('bug'), and scope ('assigned to me', 'first active', 'in a product'). However, it doesn't explicitly differentiate from siblings like 'getMyBugs' (plural) or 'getBugDetail', which might retrieve multiple bugs or any bug respectively, leaving some ambiguity.
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 implies usage context: it's for retrieving a single active bug assigned to the user in a specific product. However, it doesn't provide explicit guidance on when to use this tool versus alternatives like 'getMyBugs' (for multiple bugs) or 'getBugDetail' (for a specific bug by ID), nor does it mention prerequisites or exclusions. The usage is clear but lacks comparative direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List bugs assigned to me under a product. Defaults to active bugs only.
| Name | Required | Description | Default |
|---|---|---|---|
| productId | Yes | Product ID (required) | |
| keyword | No | Keyword filter on bug title | |
| status | No | Status filter (e.g., active) | |
| allStatuses | No | Include non-active bugs | |
| limit | No | Max items |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions default behavior ('Defaults to active bugs only'), which adds some context, but fails to disclose critical behavioral traits such as whether this is a read-only operation, if it requires authentication, any rate limits, pagination details, or what the output format looks like. This leaves significant gaps for an AI agent to understand how to handle the tool effectively.
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 with a single sentence that front-loads the core purpose and includes a key behavioral note. Every word earns its place, making it efficient and easy to parse without any wasted text.
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 5 parameters, no annotations, and no output schema, the description is incomplete. It lacks details on behavioral aspects like authentication needs, error handling, or return values, which are crucial for an AI agent to use the tool correctly in a real-world context. The high parameter count and absence of structured support make this description insufficient.
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 input schema already documents all parameters thoroughly. The description adds minimal value by implying filtering on 'active bugs' (related to 'status' and 'allStatuses'), but doesn't provide additional semantics beyond what's in the schema, such as explaining interactions between parameters or usage examples.
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 ('List') and resource ('bugs assigned to me under a product'), making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'getBugDetail' or 'searchProducts', which would require mentioning unique aspects like personal assignment filtering.
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 implies usage by specifying 'assigned to me' and 'Defaults to active bugs only', which suggests context for when to use it (e.g., for personal bug tracking). However, it doesn't provide explicit guidance on when to choose this tool over alternatives like 'getBugStats' or 'searchProducts', nor does it mention any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the next active bug assigned to me under a product (first match).
| Name | Required | Description | Default |
|---|---|---|---|
| productId | Yes | Product ID (required) | |
| keyword | No | Keyword filter on bug title | |
| status | No | Status filter (e.g., active) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions 'next active bug' and 'first match', which hints at ordering and filtering behavior, but does not disclose critical details like how 'next' is determined (e.g., by priority, creation date), whether it's read-only or has side effects, or what happens if no bugs match. This leaves significant gaps for a tool with mutation potential (e.g., marking bugs as viewed).
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 front-loads the core purpose ('Get the next active bug assigned to me under a product') and adds clarifying detail ('first match') without any wasted words. Every part 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?
Given no annotations and no output schema, the description is incomplete for a tool that likely returns bug data. It does not explain what 'next' means operationally, what data is returned, or error handling (e.g., if no bugs exist). For a tool with potential behavioral complexity, this leaves the agent under-informed.
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 fully documents the three parameters (productId, keyword, status). The description adds no additional parameter semantics beyond implying that productId is used for 'under a product' and status might default to 'active'. 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 specific action ('Get'), resource ('next active bug'), and scope ('assigned to me under a product (first match)'). It distinguishes from siblings like getBugDetail (detailed view), getMyBug (specific bug), and getMyBugs (multiple bugs) by emphasizing the 'next' and 'first match' 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 implies usage context ('assigned to me', 'under a product') but does not explicitly state when to use this tool versus alternatives like getMyBugs (for multiple bugs) or searchProducts (for product discovery). No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a token via POST /tokens using env ZENTAO_ACCOUNT/PASSWORD. Caches in-memory.
| Name | Required | Description | Default |
|---|---|---|---|
| forceRefresh | No | Ignore cached token |
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 effectively describes key traits: it performs a POST request (implying a write operation), requires specific environment variables for authentication, and caches tokens in-memory. It also hints at the 'forceRefresh' parameter's purpose. However, it lacks details on error handling, rate limits, or token expiration, which could be important for an authentication tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded and highly concise, consisting of a single sentence that efficiently conveys the action, method, authentication, and caching. Every word earns its place, with no redundant information, making it easy 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 the tool's complexity (authentication with caching) and no annotations or output schema, the description is somewhat complete but has gaps. It covers the main action, authentication method, and caching, but lacks details on response format, error cases, or how the token is used by sibling tools. For a tool that likely provides critical auth tokens, more context on integration would be beneficial.
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 'forceRefresh' parameter documented as 'Ignore cached token'. The description adds value by mentioning caching ('Caches in-memory'), which contextualizes the parameter's purpose. Since there is only one parameter and schema coverage is high, the description compensates well, but it could explicitly link 'forceRefresh' to the caching behavior for clarity.
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 specific action ('Fetch a token') and the resource ('via POST /tokens'), distinguishing it from sibling tools like 'getBugDetail' or 'searchProducts' that handle different resources. It specifies the authentication method ('using env ZENTAO_ACCOUNT/PASSWORD') and caching behavior, making the purpose explicit and distinct.
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 implies usage context by mentioning authentication via environment variables and caching, suggesting this tool is for obtaining tokens needed for other operations. However, it does not explicitly state when to use it versus alternatives (e.g., whether other tools require tokens) or provide exclusions, leaving some guidance gaps.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List projects related to the current account (PM/PO/QD/RD/assigned/team).
| Name | Required | Description | Default |
|---|---|---|---|
| keyword | No | Filter by project name keyword | |
| limit | No | Max items |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('List projects') but lacks details on permissions, rate limits, pagination, or output format. This is inadequate for a tool that likely involves data retrieval and filtering.
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 front-loads the core purpose without unnecessary words. It directly communicates the tool's function and scope, making it easy 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 and no output schema, the description is incomplete. It covers the basic purpose but lacks crucial behavioral context (e.g., how results are returned, error handling) and doesn't compensate for the absence of structured metadata, making it insufficient for reliable tool invocation.
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 ('keyword' for filtering by name and 'limit' for max items). The description adds no additional parameter semantics beyond what the schema provides, meeting 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 verb ('List') and resource ('projects'), specifying they are 'related to the current account' with role-based context (PM/PO/QD/RD/assigned/team). This provides a specific scope, though it doesn't explicitly distinguish from sibling tools like 'searchProducts', which might overlap in functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives is provided. The description implies usage for listing account-related projects but doesn't mention when to choose this over sibling tools like 'searchProducts' or 'getMyBugs', leaving the agent without clear differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark a bug as resolved (resolution=fixed).
| Name | Required | Description | Default |
|---|---|---|---|
| bugId | Yes | Bug ID (required) | |
| comment | No | Resolution comment |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('Mark a bug as resolved') but doesn't clarify permissions needed, whether the change is reversible, error handling, or side effects. This is inadequate for a mutation tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste, front-loading the core action. It's appropriately sized for the tool's complexity and doesn't include unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations, no output schema, and incomplete behavioral context, the description is insufficient. It lacks details on permissions, reversibility, response format, or error cases, making it inadequate for safe and 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?
Schema description coverage is 100%, so the schema already documents both parameters ('bugId' and 'comment'). The description implies the tool applies to a bug but doesn't add syntax, format, or contextual details beyond what the schema provides, meeting the baseline for high 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 action ('Mark a bug as resolved') and specifies the resolution type ('resolution=fixed'), which distinguishes it from other resolution states. However, it doesn't explicitly differentiate from potential sibling tools like 'call' or other bug-related operations beyond the provided list.
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, prerequisites, or exclusions. It lacks context about whether it should be used after investigation, testing, or in specific workflows, leaving usage ambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search products by keyword; returns a short list of products.
| Name | Required | Description | Default |
|---|---|---|---|
| keyword | No | Keyword to match product name | |
| limit | No | Max items |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool returns 'a short list of products,' but lacks details on permissions, rate limits, error handling, or what 'short' means (e.g., pagination, default behavior). This is a significant gap for a search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and front-loaded: two clauses that directly state the action and outcome with zero wasted words. Every sentence earns its place by covering core functionality efficiently.
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 low complexity (2 parameters, no output schema, no annotations), the description is minimally complete but lacks depth. It covers the basic purpose and return type but misses behavioral context needed for effective use, such as result format or limitations.
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 ('keyword' and 'limit') adequately. The description adds no additional meaning beyond implying keyword matching, aligning with 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 products by keyword; returns a short list of products.' It specifies the verb ('Search'), resource ('products'), and scope ('by keyword'), but does not differentiate from siblings (none are product-related).
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 no prerequisites, exclusions, or comparisons to sibling tools (which are unrelated to products), leaving usage context implied at best.
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.
v1.0.0callget_tokengetBugDetailgetBugStatsgetMyBuggetMyBugsgetNextBuglistMyProjectsmarkBugResolvedsearchProductsScored across 10 tools
The tools have clear distinctions in most cases, but there is some overlap between getMyBug, getMyBugs, and getNextBug, which all retrieve bugs assigned to the user with slight variations in scope (single vs. list vs. next). Additionally, call is a generic tool that could potentially duplicate functionality of specific tools like getBugDetail or markBugResolved, creating ambiguity in tool selection for agents.
Naming conventions are inconsistent: tools use a mix of camelCase (getBugDetail, getMyBug) and snake_case (get_token, markBugResolved), with no clear pattern. Verb usage varies, such as 'get' for retrieval and 'mark' for updates, but the inconsistency in casing and structure reduces predictability and readability.
With 10 tools, the count is well-scoped for a ZenTao bug tracking and project management server. It covers core operations like bug retrieval, resolution, project listing, and token management, providing a balanced set without being overwhelming or too sparse for the domain.
The tool set covers essential workflows for bug management (e.g., get, list, resolve) and project/product access, with minor gaps such as missing tools for creating bugs or updating bug details beyond resolution. However, the generic call tool can potentially fill these gaps, making the surface reasonably complete for typical agent tasks.
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.
Track stories, organize sprints, and manage project workflows across your team
Create and manage MeisterTask projects, tasks, and notes from your AI assistant.
Read tickets, contacts, companies, agents and groups; create, update and reply to tickets.
